Architecture
Knowledge Graph splits cleanly into a control plane and a data plane. Fontana keeps heavy processing (parsing, chunking, embedding, extraction, and graph writes) in a dedicated data plane so your workspace UI stays responsive no matter how large a corpus you load.
- Source files (VFS)
- Jobs, prefs, budgets
- Ontology draft / publish
- ACL / namespace allow-lists
- PARSE / INDEX / EMBED / EXTRACT
- Hybrid search, outline, navigate
- MCP server (`/mcp`) + S2S HTTP
Convex never runs KG processing. It watches jobs and reports status; `kg-engine` owns every parse, chunk, embed, extract, and graph write against FalkorDB.
Control plane
Section titled “Control plane”The control plane owns everything that is reactive and operator-facing:
| Responsibility | What it holds |
|---|---|
| Source files | Your original document bytes on Fontana Files, with each processing step’s record beside them |
| Configuration | Ingest settings per namespace and folder, retrieval preferences, and the cost ledger |
| Ontology | Draft and published ontology JSON, with version hashes |
| Access control | Namespace allow-lists per agent, and the reactive Flow UI state |
Data plane
Section titled “Data plane”The per-workspace Knowledge Graph engine owns ingestion and retrieval:
- Ingestion: every processing step (PARSE, NER, EMBED, RESOLVE, INDEX) keeps its own record per file in the engine’s own store and runs again only when its input changed. There is no queue to lose: a restart picks up from those records, and an empty store means one more pass over the files, not lost data. See Processing lanes.
- Retrieval: hybrid search, outline navigation, and entity navigation are available through MCP for agents and through KG Studio in the product UI. See Retrieval and MCP.
- Status: each step keeps one status file per namespace in the engine’s store. KG Studio reads status, parsed documents and extracted graphs from the engine under your read permissions, so status never passes through the control plane and nothing is written into your files.
Derived graph store
Section titled “Derived graph store”Every namespace has one property graph that holds every derived artifact: chunks with provenance and embeddings, the document outline tree, typed entities and relationships, evidence mentions, and vector plus full-text indexes on the same nodes. There is no split between “chunks in one store and entities in another”. See Graph overlays for how one graph supports four different retrieval views.
Your original files stay on the workspace filesystem (the source of truth for bytes); the graph store holds only what Fontana derives from them.
Per-workspace isolation and backup
Section titled “Per-workspace isolation and backup”Each workspace has its own graph database and Knowledge Graph engine. Backups and volume snapshots include derived graph data alongside your other workspace volumes, so a restore brings back your graph, chunk text, and vectors together with the rest of your workspace state. If a restore omits that volume, the graph is empty until you re-ingest from your source files, which remain on the workspace file store regardless.
Namespaces, folders, and documents
Section titled “Namespaces, folders, and documents”Knowledge Graph documents are organised in three levels: a namespace (top-level corpus boundary), a slash-path folder within that namespace, and individual documents addressed by path.
Each agent searches only the namespaces you assign it in Admin → Agents. Retrieval and relationship expansion stay inside those boundaries, which keeps regulated corpora segregated and agent answers focused on the domain you intend.