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 the unified workspace filesystem, plus processing stage metadata |
| Jobs and registry | The ingest queue, namespace statistics, ingest mode, retrieval preferences, and 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 stage (PARSE, INDEX, NER, EMBED) runs as an independent, prioritized queue. 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: the engine reports job progress back to the control plane in small batches, so UI updates scale with status changes, not with chunk volume.
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.