Architecture overview
This system is a local repository helper for safer AI-assisted code planning.
The architecture is intentionally simple:
- the codebase is scanned and indexed locally
- structural and reference data are stored in a local SQLite database
- Python services read that database and compute context or risk
- an MCP server exposes those services
- an AI agent calls the tools before proposing or making changes
- a human approves the plan before implementation starts
Main components
1. Repository scanner
The scanner walks the local repository and finds supported source files.
Responsibilities:
- validate repo root
- ignore junk directories
- keep only supported files
- derive repo-relative paths
- derive file URIs
- derive module paths
- compute file hashes and metadata
- store RepoRecord and FileRecord
Output:
- local file inventory in SQLite
2. AST extraction layer
The AST layer parses Python files and extracts structural graph data.
Responsibilities:
- create module nodes
- create class nodes
- create function and method nodes
- create contains edges
- create imports edges
- create inherits edges
- store declaration ranges and symbol metadata
Output:
- structural graph stored in SQLite
3. Graph storage layer
The graph storage layer is the persistence and query foundation.
Responsibilities:
- upsert nodes
- upsert edges
- replace one file’s graph state cleanly
- query by node ID
- query by qualified name
- query incoming and outgoing edges
- query parent and child relationships
Output:
- durable local graph in SQLite
4. Context builder
The context builder reads graph data and assembles a useful symbol-centered view.
Responsibilities:
- load one symbol
- find parent symbol
- find child symbols
- load incoming and outgoing edges
- compute structural summary
- compute freshness summary
- compute confidence summary
- expose reference summary placeholder or actual values
Output:
- SymbolContext
5. LSP reference enrichment
This layer adds semantic usage information that AST alone cannot provide well enough.
Responsibilities:
- choose the best declaration position for a symbol
- ask the Python language server for references
- map returned locations back to internal symbols
- create references edges
- derive referenced_by through reverse queries
- compute reference counts and spread
Output:
- reference graph enrichment in SQLite
6. Risk engine
The risk engine turns graph facts into deterministic risk outputs.
Responsibilities:
- inspect targets
- inspect references
- inspect cross-file and cross-module impact
- inspect public-surface heuristics
- inspect inheritance involvement
- inspect freshness and confidence
- emit issue codes
- compute score
- compute decision
Output:
- machine-friendly risk result
7. MCP server
The MCP server exposes deterministic tools to an agent.
Responsibilities:
- register tools
- validate inputs
- call internal graph, context, reference, and risk services
- return structured outputs
- return structured errors
Output:
- a tool interface the agent can query safely
8. Watch mode
Watch mode keeps the local graph fresh while files change.
Responsibilities:
- observe file changes
- debounce noisy events
- update changed file metadata
- re-extract AST structure
- replace file graph
- invalidate stale references
- keep the graph fresh enough for later MCP calls
Output:
- fresher local SQLite graph over time
9. Agent workflow layer
This is not a database or server layer.
It is the real operating workflow.
Responsibilities:
- draft plan
- call MCP tools
- revise the plan from deterministic findings
- wait for human approval
- only then begin implementation
Output:
- safer human-gated coding workflow
Data flow
The data flow should look like this:
- Local repo files are scanned.
- File records are stored in SQLite.
- AST extraction builds structural nodes and edges.
- Structural graph is stored in SQLite.
- LSP enrichment adds
referencesedges. - Context and risk services read from SQLite and compute higher-level outputs.
- MCP tools expose those outputs to the agent.
- The agent uses those outputs before proposing or making code changes.
- The human approves before implementation.
Short version:
Local repo
-> Scanner
-> AST extraction
-> SQLite graph
-> Context / LSP / Risk services
-> MCP tools
-> Agent
-> Human approval
-> Implementation
