Back to posts

Graph Platform
System Design

ontology-governed data engineering · hardcoded services · agent-assisted development
00 — Graph Foundations
Why a Graph Database, and What Makes It Different
If you're coming from relational databases (PostgreSQL, SQL Server, MySQL), this section maps the concepts you already know to their graph equivalents — and explains what a graph makes possible that a relational schema doesn't.
SQL
Neo4j
Table
->
Label
Row
->
Node
Column
->
Property
Foreign Key / JOIN
->
Typed Relationship
DDL Schema
->
Ontology
SQL
->
Cypher
View / Materialized View
->
Subgraph
Relational (SQL)
Table
Row
Column
Foreign Key / JOIN
DDL Schema
SQL
View / Materialized View
⇄
Graph (Neo4j)
Label
Node
Property
Relationship (typed, directional)
Ontology
Cypher
Subgraph
Graph Concept What It Means Why It Matters Here
Node A single entity — a customer, product, order, store, supplier, or inventory record. Equivalent to a row, but it exists independently without needing a table to belong to. Every data entity in the platform is a governed node
Relationship A typed, directional connection between two nodes — (:Customer)-[:PLACED]→(:Order). Unlike a foreign key, the relationship is a first-class object with its own properties. Relationships make purchases, fulfillment, inventory, and supplier paths explicit
Traversal Following chains of relationships across the graph. "Find products bought by customers who also bought this item." In SQL this can become a chain of joins across orders, order lines, customers, products, and stores. In a graph, that path is the query shape. This is why the graph exists — the queries it makes easy
Cypher Neo4j's query language. Uses ASCII-art pattern syntax: MATCH (a)-[:CONNECTS_TO]->(b). The equivalent of SQL for graph databases. Entity Parser registers every query against the ontology
Ontology Goes beyond a DDL schema. Defines not just what types of nodes/relationships exist, but their semantic meaning, valid combinations, cardinality rules, and constraints. A schema says "this column is an integer." An ontology says "an Order contains one or more Products, and each line item carries quantity and price metadata." The ontology is the contract everything in this platform enforces
Subgraph A subset of the full graph — a partition defined by labels, relationships, or access rules. Different services or roles see different subgraphs of the same database. Access Control controls who sees which subgraph
Schema Change Cascading In SQL, renaming a column breaks queries that reference it — but the blast radius is usually one table. In a graph, changing a relationship type can break traversal patterns across many connected node types. The impact is non-linear. The query registry exists to make this impact visible before deployment
When to use a graph
Relational databases excel when your data fits cleanly into tables and your queries are predictable. Graph databases excel when the connections between things are the point — when you need to traverse relationships dynamically, ask "what's connected to this, and what's connected to that," or model domains where relationship types are as important as the entities themselves. Retail data is a good fit when the useful questions cross customers, orders, products, stores, inventory, promotions, and suppliers. The value is in the path, not just the row.
01 — Data Pipeline
Ingestion → Governance → Graph
How does data get into the graph? What validates it before it's stored? How is graph shape enforced?
Data enters from retail systems, passes through entity parsing and ontology validation, and lands in Neo4j as governed graph structures. The ingestion path is hardcoded, deterministic, and testable. The ontology is the contract; nothing persists without conforming to it.
IN
Upstream Sources
POS transactions Product catalog Inventory updates
→
EP
Entity Parser
Entity extraction Ontology-bound typing Query registration
→
GV
Graph Validator
Validation engine Large-scale batch validation Conformance gate
→
G
Neo4j Graph
Governed nodes Typed relationships Query-ready
No LLMs in production services
Ingestion, validation, and graph writes run as hardcoded services. No model inference, prompt chain, or generated behavior sits in the production data path. LLMs are useful in development and validation tooling, but the deployed graph pipeline runs as deterministic code.
02 — Architecture Layers
Stack Composition
What technologies make up the stack? Where does access control live? How is the ontology positioned in the architecture?
Five layers from interface to infrastructure. The ontology layer sits between compute and storage — it's the governance boundary. The environment metadata layer manages who can access what, enforcing least-privilege by role across the graph.
Interface
Ontology Editor Visual schema editor Database API consumers
Compute
API services Database API Entity Parser Graph Validator
Ontology
Schema definitions Validation rules Relationship constraints Entity type registry Query registry
Environment
Graph users Privileges Roles Service permissions Subgraph access policies
Infrastructure
Neo4j AWS Lambda EC2 Athena CloudWatch Route 53
03 — Platform Services
Hardcoded Service Responsibilities
What does each service do? Why are they separate? How is access control enforced?
Each service owns a single concern and runs hardcoded logic with well-defined inputs, outputs, and ontology bindings. No LLM is responsible for production ingestion, validation, access control, or graph writes.
Entity Parser
Entity extraction from raw data, bound to ontology types. Every query that reads or writes to the graph is registered — connected to the ontology so you can trace which queries are impacted by any schema change. This is the query registry.
Graph Validator
Batch validation engine. Scans large graph volumes across the full graph, checking every node and relationship against current ontology definitions. Produces conformance reports and flags drift. The equivalent of running a schema-wide integrity check — but for a graph.
Access Control
Manages graph users, privileges, roles — represented as data in the graph itself. Controls access to subgraph partitions by service responsibility. Principle of least-privilege by role — each service sees only the data its responsibilities require.
Database API
Service layer exposing governed graph operations. All reads and writes pass through ontology-aware endpoints with RBAC enforcement from the Access Control service. Consumers never interact with raw Neo4j directly — the API is the only door.
04 — Query Registry
Ontology-Connected Impact Analysis
What happens when the schema changes? How do you know which queries break? Why is graph schema change harder than SQL?
Every registered query is linked to the ontology entities and relationships it touches. When a schema changes, you query the ontology and immediately identify every affected query. In a relational database, renaming a column breaks queries on one table. In a graph, changing a relationship type can cascade across traversal patterns that span many node types — the blast radius is non-linear. The query registry makes this visible before deployment, not after.
Schema Change
via Ontology Editor
→
Ontology Lookup
which entities changed?
→
Query Registry
which queries touch these?
→
Impacted Queries
flagged for review
Why this matters
In a graph with thousands of registered queries across multiple services, a property rename or relationship type change could silently break production reads in ways you won't see until traversals return empty results. The query registry connects every access pattern to the ontology definition it depends on. The ontology doesn't just govern the data — it governs the access patterns.
05 — Development Workflow
Where Coding Agents Fit
Where do LLMs belong in this system? What does the engineer review? How does business context reach the agent? Where do LLM validation tools fit?
Coding agents (OpenCode, Claude Code, Codex) support development inside dev containers. They connect to platform services through MCP, including MCP access to the Database API. The engineer provides business context, stewards the feature branch, and reviews tests before trusting implementation.
1
Issue Triggers Workspace
An issue (feature or bugfix) triggers a dev container. The engineer has their coding agent (OpenCode, Claude Code) with MCP integration to the Database API, GitHub, and file system edit tools.
2
Engineer Provides Context
Business context comes from two sources: the database through MCP/Database API, and transcribed meeting recordings. The engineer synthesizes goals, constraints, and domain intent before directing the agent.
3
Tests First — The Primary Review Point
The engineer guides the agent with word-form requirements and asks it to generate tests. The engineer reviews those tests as the executable specification. The agent should not invent tests on its own; the test suite has to reflect the actual requirement before implementation proceeds.
4
Code Until Tests Pass
Once tests are approved, the agent implements code against the specification. The code itself is secondary to the tests: if the tests are right and the implementation passes, line-by-line review matters less, especially for internal walled-in applications. Security still gets reviewed regardless.
5
E2E Validation + Merge
The engineer runs end-to-end validation, checks security, and merges after the change is verified across relevant integration paths.
MCP Connections
Database API — query/write to the governed graph from the coding agent
GitHub — access repos, issues, PRs, code review
File system — edit tools on the codebase within the dev container
Query Validator
Query Validator validates Cypher queries against multiple LLMs. It is a development and validation tool, not a production graph pipeline service. That distinction matters: LLMs can help test and review query behavior before deployment, while production ingestion and graph writes stay hardcoded.
06 — Monitoring & Alarms
Agent-Assisted Observability
How are services monitored at runtime? Where do alarm thresholds come from?
Services need proper runtime monitoring with statistical alarms. Coding agents add value here — not in production, but in configuring production monitoring. Agents review the codebase, suggest performance metrics, and generate alarm definitions. These get reviewed and deployed as static config.
Agent-Suggested Alarms
Coding agent reviews service code and proposes: latency thresholds, error rate triggers, throughput anomalies, memory/CPU bounds. Engineer reviews and adjusts — then deploys as static CloudWatch config. The agent isn't monitoring anything at runtime.
Statistical Baselines
Agents analyze historical CloudWatch data via Athena to suggest appropriate thresholds rather than guessing. Alarm bounds based on actual p95/p99 distributions, not arbitrary numbers. Modified as services evolve.
Runtime Stack
CloudWatch metrics + alarms · Athena historical query · Lambda function monitoring · EC2 instance health — all static config, no LLM inference in the monitoring path.
07 — Orchestration
Ontology as Central Nervous System
How do schema changes propagate? What's the human interface to the ontology? How do services stay in sync?
The Ontology Editor is the human interface to the ontology. Changes propagate downstream — Graph Validator picks up new rules, Entity Parser aligns extraction and updates the query registry, and Access Control re-evaluates access policies. Everything reacts to the ontology.
ONTOLOGY
single source of truth
↑ Ontology Editor
Visual schema editor. Engineers define and modify the ontology directly. Changes commit to the schema registry and propagate to downstream services.
↓ Entity Parser
Reads current ontology at extraction time. Schema changes immediately update entity typing and the query registry — impacted queries are flagged for review.
↓ Graph Validator
Schema changes automatically become new validation rules in the next scan cycle. Drift from previous definitions surfaces in conformance reports.
↓ Access Control
Ontology changes may affect which subgraphs exist and which roles need access. Access policies are re-evaluated against updated schema definitions.
Graph Validator drift reports → Editor review → ontology update → re-validate → query registry impact check
08 — Comparison
Multi-Agent Dev Pipeline vs. Ontology-Governed Platform
How does this compare to the 7-agent factory pattern? Are these approaches competing or complementary?
Multi-agent development workflows split implementation into specialized phases with written specifications and human checkpoints. That pattern addresses development process control. This platform addresses production data governance, service boundaries, and ontology enforcement. They operate at different layers.
7-Agent Dev Pipeline
Use it when: you need to break a feature into research, requirements, implementation, and review steps
Input: issue text, meeting notes, acceptance criteria, existing code, and engineer guidance
Output: specs, tests, implementation patches, review notes, and follow-up tasks
Best checkpoint: review the generated tests before trusting generated code
Where it stops: it does not enforce graph shape, permissions, query safety, or runtime data quality
Main risk: a wrong assumption can become a wrong spec, then a wrong implementation
Ontology-Governed Platform
Use it when: graph data must stay consistent as schemas, access rules, and services change
Input: ontology definitions, ingestion records, registered queries, roles, and subgraph policies
Output: governed nodes, typed relationships, validation reports, query impact lists, and access decisions
Best checkpoint: run ontology validation and query-impact checks before deploying schema changes
Where it stops: it does not write features for you; it constrains what deployed services can persist or read
Main risk: an unregistered query or unvalidated schema change can create invisible graph drift
Complementary, not competing
A multi-agent development workflow can build features for a platform like this when generated work passes review, tests, and deployment controls. The workflow governs how software changes are produced. The platform governs how production graph data is modeled, validated, accessed, and monitored.
09 — Design Philosophy
Build Robust Systems With Agent Support
Where are LLMs appropriate? Which paths stay hardcoded?
Production data systems need explicit service boundaries. Use LLMs where their outputs can be reviewed before deployment: test generation, query validation, monitoring suggestions, and prototyping. Keep ingestion, validation, access control, and graph writes hardcoded.
Agents Support Development
Coding agents help draft code, generate tests from requirements, suggest monitoring thresholds, prototype features, and review codebases. Their outputs are reviewed before they affect production systems.
Hardcoded Runtime Paths
Production data pipelines, validation engines, access control, and scheduled processing jobs run as hardcoded services. These paths should not depend on model inference or generated behavior at runtime.
LLMs Belong Around the System
Query Validator, coding agents, and monitoring threshold suggestions are useful because they operate before deployment or outside the load-bearing data path. They improve engineering leverage without making the graph pipeline depend on dynamic model output.