Navegador

navegador / docs / architecture / overview.md
Source Blame History 202 lines
ce0374a… lmata 1 # Architecture Overview
ce0374a… lmata 2
ce0374a… lmata 3 ## Design philosophy
ce0374a… lmata 4
ce0374a… lmata 5 Navegador is built around a single observation: **code structure and business knowledge are both graph-shaped, and they belong in the same graph.**
ce0374a… lmata 6
ce0374a… lmata 7 Most context tools for AI agents handle one or the other — either they parse code (AST tools, code search) or they surface docs (RAG over wikis, ADR files). Navegador stores both in the same property graph and connects them with typed edges. An agent asking "what does `process_payment` do?" gets back not just the function signature and call graph, but the business rules that govern it and the architectural decision that shaped its design — in a single structured query.
ce0374a… lmata 8
ce0374a… lmata 9 ---
ce0374a… lmata 10
89816aa… lmata 11 ## Architecture layers
ce0374a… lmata 12
ce0374a… lmata 13 ```
ce0374a… lmata 14 ┌──────────────────────────────────────────────────────────────────┐
89816aa… lmata 15 │ INTELLIGENCE LAYER │
89816aa… lmata 16 │ LLM providers (Anthropic · OpenAI · Ollama) │
89816aa… lmata 17 │ Semantic search · NLP queries · Doc generation │
89816aa… lmata 18 ├──────────────────────────────────────────────────────────────────┤
89816aa… lmata 19 │ ANALYSIS LAYER │
89816aa… lmata 20 │ Impact · Trace · Churn · Deadcode · Cycles · Testmap │
89816aa… lmata 21 │ Diff · Rename · Communities · Blast radius │
89816aa… lmata 22 ├──────────────────────────────────────────────────────────────────┤
ce0374a… lmata 23 │ KNOWLEDGE LAYER │
ce0374a… lmata 24 │ │
ce0374a… lmata 25 │ Domain ──BELONGS_TO── Concept ──RELATED_TO── Rule │
ce0374a… lmata 26 │ │ │ │ │
ce0374a… lmata 27 │ └──BELONGS_TO── Decision GOVERNS │ │
ce0374a… lmata 28 │ │ ↓ │
ce0374a… lmata 29 │ DECIDED_BY── Person (code nodes) │
ce0374a… lmata 30 │ │
ce0374a… lmata 31 │ WikiPage ──DOCUMENTS── Concept │
ce0374a… lmata 32 │ │
ce0374a… lmata 33 ├──────────────── ANNOTATES / GOVERNS / IMPLEMENTS ────────────────┤
ce0374a… lmata 34 │ │
ce0374a… lmata 35 │ CODE LAYER │
ce0374a… lmata 36 │ │
ce0374a… lmata 37 │ Repository ──CONTAINS── File ──CONTAINS── Class │
ce0374a… lmata 38 │ │ │ │
ce0374a… lmata 39 │ CONTAINS DEFINES │
ce0374a… lmata 40 │ ↓ ↓ │
ce0374a… lmata 41 │ Function ──CALLS── Function │
89816aa… lmata 42 │ │ │ │
89816aa… lmata 43 │ DECORATES─Decorator TESTS──TestFn │
ce0374a… lmata 44 │ │ │
ce0374a… lmata 45 │ IMPORTS── Import │
89816aa… lmata 46 ├──────────────────────────────────────────────────────────────────┤
89816aa… lmata 47 │ ENRICHMENT LAYER │
89816aa… lmata 48 │ Framework metadata (Django · FastAPI · React · Rails · Spring) │
89816aa… lmata 49 │ VCS (Git · Fossil) · CODEOWNERS · ADRs · OpenAPI · GraphQL │
89816aa… lmata 50 ├──────────────────────────────────────────────────────────────────┤
89816aa… lmata 51 │ STORE LAYER │
89816aa… lmata 52 │ FalkorDB (falkordblite SQLite local / Redis cluster) │
ce0374a… lmata 53 └──────────────────────────────────────────────────────────────────┘
ce0374a… lmata 54 ```
ce0374a… lmata 55
ce0374a… lmata 56 ### Code layer
ce0374a… lmata 57
89816aa… lmata 58 Populated automatically by `navegador ingest`. Contains the structural facts extracted from source code across 13 languages: which functions exist, what they call, which classes inherit from which, what decorators are applied. Supports incremental ingestion (content hashing), watch mode, and parallel processing. This layer changes whenever code changes; re-ingest is the refresh mechanism.
ce0374a… lmata 59
ce0374a… lmata 60 ### Knowledge layer
ce0374a… lmata 61
89816aa… lmata 62 Populated by humans (via `navegador add`) or semi-automatically (via wiki, Planopticon, ADR, OpenAPI, and PM ingestion). Contains the *why*: business concepts, architectural rules, recorded decisions, domain ownership, and documentation. This layer changes slowly and deliberately.
89816aa… lmata 63
89816aa… lmata 64 ### Enrichment layer
89816aa… lmata 65
89816aa… lmata 66 Framework enrichers run after AST parsing to add framework-specific metadata — Django model field types, FastAPI route paths, React component display names, etc. VCS adapters (Git, Fossil) provide blame, history, and churn data. CODEOWNERS files are parsed to populate `Person`→`File` ownership edges.
89816aa… lmata 67
89816aa… lmata 68 ### Analysis layer
89816aa… lmata 69
89816aa… lmata 70 Graph analysis commands operate over the populated code and knowledge layers without additional ingestion. They run Cypher traversals for impact analysis, cycle detection, dead code detection, test mapping, and community detection.
89816aa… lmata 71
89816aa… lmata 72 ### Intelligence layer
89816aa… lmata 73
89816aa… lmata 74 NLP and LLM commands (`navegador ask`, `navegador semantic-search`, `navegador docs`) use configurable LLM providers (Anthropic, OpenAI, Ollama) to answer natural language queries grounded in graph data.
ce0374a… lmata 75
ce0374a… lmata 76 ### Cross-layer edges
ce0374a… lmata 77
ce0374a… lmata 78 | Edge | Meaning | Direction |
ce0374a… lmata 79 |---|---|---|
ce0374a… lmata 80 | `ANNOTATES` | A knowledge node describes a code node | Concept/Rule → Function/Class/File |
ce0374a… lmata 81 | `GOVERNS` | A rule applies to a code node | Rule → Function/Class |
ce0374a… lmata 82 | `IMPLEMENTS` | A code node implements a concept or interface | Function/Class → Concept/Interface |
ce0374a… lmata 83 | `DOCUMENTS` | A wiki page documents a concept or code node | WikiPage → Concept/Function/Class |
ce0374a… lmata 84
ce0374a… lmata 85 These edges are created explicitly via `navegador annotate` or inferred during wiki/Planopticon ingestion when names match.
ce0374a… lmata 86
ce0374a… lmata 87 ---
ce0374a… lmata 88
ce0374a… lmata 89 ## FalkorDB as the store
ce0374a… lmata 90
ce0374a… lmata 91 Navegador uses [FalkorDB](https://www.falkordb.com/) — a property graph database with a Cypher query interface.
ce0374a… lmata 92
ce0374a… lmata 93 | Environment | Backend | Install |
ce0374a… lmata 94 |---|---|---|
ce0374a… lmata 95 | Local dev | `falkordblite` (SQLite) | Included in `pip install navegador` |
ce0374a… lmata 96 | Production / team | FalkorDB on Redis | `pip install "navegador[redis]"` |
ce0374a… lmata 97
ce0374a… lmata 98 Both backends implement the same `GraphStore` interface. The query path is identical; only the connection setup differs. The SQLite backend uses an embedded engine — no daemon, no port, just a `.db` file.
ce0374a… lmata 99
ce0374a… lmata 100 ---
ce0374a… lmata 101
ce0374a… lmata 102 ## Ingestion pipeline
ce0374a… lmata 103
ce0374a… lmata 104 ```
89816aa… lmata 105 Source code (13 languages via tree-sitter)
ce0374a… lmata 106 │
ce0374a… lmata 107 ▼
8fe1420… lmata 108 tree-sitter parser (per-language grammar)
89816aa… lmata 109 + incremental parsing (LRU cache, content hashing)
89816aa… lmata 110 + parallel ingestion (worker pool)
ce0374a… lmata 111 │
ce0374a… lmata 112 ▼
ce0374a… lmata 113 AST visitor (extract nodes + relationships)
89816aa… lmata 114 │
89816aa… lmata 115 ▼
89816aa… lmata 116 Framework enrichers (Django · FastAPI · React · Rails · Spring · Laravel · …)
89816aa… lmata 117 │
89816aa… lmata 118 ▼
89816aa… lmata 119 Graph diffing (only write changed nodes/edges)
ce0374a… lmata 120 │
ce0374a… lmata 121 ▼
ce0374a… lmata 122 GraphStore.merge_node / create_edge
ce0374a… lmata 123 │
ce0374a… lmata 124 ▼
ce0374a… lmata 125 FalkorDB (SQLite or Redis)
ce0374a… lmata 126 ```
ce0374a… lmata 127
ce0374a… lmata 128 ```
ce0374a… lmata 129 Human curation (navegador add)
ce0374a… lmata 130 Wiki pages (navegador wiki ingest)
ce0374a… lmata 131 Planopticon output (navegador planopticon ingest)
89816aa… lmata 132 ADRs (navegador adr ingest)
89816aa… lmata 133 OpenAPI / GraphQL schemas (navegador api ingest)
89816aa… lmata 134 PM issues (navegador pm ingest --github)
89816aa… lmata 135 External deps (navegador deps ingest)
89816aa… lmata 136 Submodules (navegador submodules ingest)
ce0374a… lmata 137 │
ce0374a… lmata 138 ▼
89816aa… lmata 139 KnowledgeIngester / WikiIngester / PlanopticonIngester / …
ce0374a… lmata 140 │
ce0374a… lmata 141 ▼
ce0374a… lmata 142 GraphStore.merge_node / create_edge
ce0374a… lmata 143 │
ce0374a… lmata 144 ▼
ce0374a… lmata 145 FalkorDB (same database)
ce0374a… lmata 146 ```
ce0374a… lmata 147
ce0374a… lmata 148 All ingesters write to the same graph. There is no separate code database and knowledge database.
ce0374a… lmata 149
ce0374a… lmata 150 ---
ce0374a… lmata 151
89816aa… lmata 152 ## Query and analysis path
ce0374a… lmata 153
ce0374a… lmata 154 ```
ce0374a… lmata 155 User / agent
ce0374a… lmata 156 │
89816aa… lmata 157 ▼ CLI command, MCP tool call, or Python SDK
89816aa… lmata 158 navegador context / function / explain / search / impact / trace / ...
ce0374a… lmata 159 │
ce0374a… lmata 160 ▼
89816aa… lmata 161 ContextLoader / AnalysisEngine (builds Cypher query)
ce0374a… lmata 162 │
ce0374a… lmata 163 ▼
89816aa… lmata 164 GraphStore.query(cypher) ← MCP: query validation + complexity check
ce0374a… lmata 165 │
ce0374a… lmata 166 ▼
ce0374a… lmata 167 FalkorDB (SQLite or Redis)
ce0374a… lmata 168 │
ce0374a… lmata 169 ▼
89816aa… lmata 170 ContextBundle / AnalysisResult (structured result)
ce0374a… lmata 171 │
ce0374a… lmata 172 ▼
ce0374a… lmata 173 JSON / Markdown / rich terminal output
ce0374a… lmata 174 ```
ce0374a… lmata 175
89816aa… lmata 176 `ContextLoader` handles context retrieval commands (`function`, `class`, `explain`, etc.). `AnalysisEngine` handles graph analysis commands (`impact`, `trace`, `deadcode`, `cycles`, `churn`, `testmap`). Both construct Cypher queries, fetch results from `GraphStore`, and return structured output. The CLI formats output for the terminal; the MCP server returns JSON; the Python SDK returns typed Python objects.
89816aa… lmata 177
89816aa… lmata 178 ---
89816aa… lmata 179
89816aa… lmata 180 ## Cluster architecture
89816aa… lmata 181
89816aa… lmata 182 For team and CI environments, navegador supports a cluster mode backed by a shared Redis graph:
89816aa… lmata 183
89816aa… lmata 184 ```
89816aa… lmata 185 Multiple agents / CI runners
89816aa… lmata 186 │
89816aa… lmata 187 ▼
89816aa… lmata 188 navegador (each instance)
89816aa… lmata 189 │
89816aa… lmata 190 ▼
89816aa… lmata 191 ┌────────────────────────────────────────┐
89816aa… lmata 192 │ Shared Redis │
89816aa… lmata 193 │ ├── FalkorDB graph (shared state) │
89816aa… lmata 194 │ ├── Pub/sub (event broadcast) │
89816aa… lmata 195 │ ├── Task queue (ingest jobs) │
89816aa… lmata 196 │ ├── Sessions (agent state) │
89816aa… lmata 197 │ ├── Checkpoints (long-running tasks) │
89816aa… lmata 198 │ └── Observability (metrics, traces) │
89816aa… lmata 199 └────────────────────────────────────────┘
89816aa… lmata 200 ```
89816aa… lmata 201
89816aa… lmata 202 Configure with `[cluster]` in `.navegador/config.toml`. See [Configuration](../getting-started/configuration.md) for details.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button