docs(archify): add CodeGraph architecture and query-handling diagrams
Two self-contained interactive diagrams under docs/archify/, each with its source spec and browser-evidence receipt. - codegraph-architecture: the extraction -> resolution -> query -> context pipeline, the local-first engine boundary, and the MCP / CLI / viewer consumption surfaces. 16 cited source references verified at the indexed revision. - codegraph-explore-nl-query: how codegraph_explore turns a natural-language query into symbols (parseQuery, flowTokens), resolves them to nodes with exact-only matching and overload disambiguation, finds the call path among them, and assembles a budgeted answer. Validation: both pass showcase validation with 9/9 artifact checks and no composition errors or warnings, and visual-check reports no viewport overflow at 1440x900, 1600x1000, 1920x1080, and 2048x1320.
This commit is contained in:
@@ -0,0 +1,393 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"diagram_type": "architecture",
|
||||
"meta": {
|
||||
"title": "CodeGraph Architecture",
|
||||
"locale": "en",
|
||||
"quality_profile": "showcase",
|
||||
"repository": {
|
||||
"url": "https://github.com/colbymchenry/codegraph",
|
||||
"provider": "github",
|
||||
"link_mode": "web",
|
||||
"revision": "3ed73bc127323e63153bf6ec8354afa82ce36aaf"
|
||||
},
|
||||
"views": [
|
||||
{
|
||||
"id": "indexing",
|
||||
"label": "Indexing a repository",
|
||||
"focus": [
|
||||
"repo",
|
||||
"watcher",
|
||||
"orchestrator",
|
||||
"sqlite"
|
||||
],
|
||||
"note": "Source files become symbols, edges and files in one local SQLite index."
|
||||
},
|
||||
{
|
||||
"id": "resolution-and-query",
|
||||
"label": "Resolution and query",
|
||||
"focus": [
|
||||
"sqlite",
|
||||
"resolver",
|
||||
"graph",
|
||||
"context"
|
||||
],
|
||||
"note": "Stored symbols are resolved into a graph, then traversed into context."
|
||||
},
|
||||
{
|
||||
"id": "consumption",
|
||||
"label": "Consumption surfaces",
|
||||
"focus": [
|
||||
"context",
|
||||
"mcp",
|
||||
"cli",
|
||||
"viewer",
|
||||
"agents"
|
||||
],
|
||||
"note": "One engine, three read-only surfaces, with MCP as the agent path."
|
||||
}
|
||||
]
|
||||
},
|
||||
"layout": {
|
||||
"mode": "grid",
|
||||
"cols": 6,
|
||||
"cellW": 175,
|
||||
"cellH": 64,
|
||||
"gapX": 25,
|
||||
"gapY": 54
|
||||
},
|
||||
"components": [
|
||||
{
|
||||
"id": "repo",
|
||||
"type": "external",
|
||||
"label": "Source Codebase",
|
||||
"sublabel": "any supported language",
|
||||
"row": 0,
|
||||
"col": 0,
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "watcher",
|
||||
"type": "backend",
|
||||
"label": "File Watcher",
|
||||
"sublabel": "native FS events",
|
||||
"row": 1,
|
||||
"col": 1,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/sync/watcher.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "orchestrator",
|
||||
"type": "backend",
|
||||
"label": "Extraction",
|
||||
"sublabel": "tree-sitter AST",
|
||||
"tag": "29 wasm grammars",
|
||||
"row": 0,
|
||||
"col": 1,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/extraction/tree-sitter.ts"
|
||||
},
|
||||
{
|
||||
"path": "src/extraction/parse-worker.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "sqlite",
|
||||
"type": "database",
|
||||
"label": "SQLite Index",
|
||||
"sublabel": "nodes · edges · files",
|
||||
"tag": "WAL + FTS5",
|
||||
"row": 0,
|
||||
"col": 2,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/db/schema.sql"
|
||||
},
|
||||
{
|
||||
"path": "src/db/sqlite-adapter.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "resolver",
|
||||
"type": "backend",
|
||||
"label": "Reference Resolver",
|
||||
"sublabel": "imports · names · frameworks",
|
||||
"row": 0,
|
||||
"col": 3,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/resolution/import-resolver.ts"
|
||||
},
|
||||
{
|
||||
"path": "src/resolution/name-matcher.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "graph",
|
||||
"type": "backend",
|
||||
"label": "Graph Query",
|
||||
"sublabel": "callers · callees · impact",
|
||||
"row": 0,
|
||||
"col": 4,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/graph/queries.ts"
|
||||
},
|
||||
{
|
||||
"path": "src/graph/traversal.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "context",
|
||||
"type": "backend",
|
||||
"label": "Context Builder",
|
||||
"sublabel": "markdown / JSON",
|
||||
"row": 0,
|
||||
"col": 5,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/context/index.ts"
|
||||
},
|
||||
{
|
||||
"path": "src/context/formatter.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "viewer",
|
||||
"type": "frontend",
|
||||
"label": "Browser Viewer",
|
||||
"sublabel": "read-only JSON API",
|
||||
"row": 1,
|
||||
"col": 3,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/ui-server/index.ts"
|
||||
},
|
||||
{
|
||||
"path": "ui/src/App.svelte"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "cli",
|
||||
"type": "backend",
|
||||
"label": "CLI",
|
||||
"sublabel": "init · index · query",
|
||||
"row": 1,
|
||||
"col": 4,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/bin/codegraph.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "mcp",
|
||||
"type": "backend",
|
||||
"label": "MCP Server",
|
||||
"sublabel": "codegraph_explore · node",
|
||||
"row": 1,
|
||||
"col": 5,
|
||||
"sources": [
|
||||
{
|
||||
"path": "src/mcp/tools.ts"
|
||||
},
|
||||
{
|
||||
"path": "src/mcp/server-instructions.ts"
|
||||
}
|
||||
],
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "agents",
|
||||
"type": "external",
|
||||
"label": "AI Agents",
|
||||
"sublabel": "Claude Code · Cursor · Codex",
|
||||
"row": 2,
|
||||
"col": 5,
|
||||
"size": [
|
||||
145,
|
||||
64
|
||||
]
|
||||
}
|
||||
],
|
||||
"boundaries": [
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "CodeGraph engine — local-first, no server",
|
||||
"wraps": [
|
||||
"orchestrator",
|
||||
"sqlite",
|
||||
"resolver",
|
||||
"graph",
|
||||
"context"
|
||||
]
|
||||
}
|
||||
],
|
||||
"connections": [
|
||||
{
|
||||
"id": "repo-to-orchestrator",
|
||||
"from": "repo",
|
||||
"to": "orchestrator",
|
||||
"label": "source files",
|
||||
"variant": "emphasis",
|
||||
"labelAt": [
|
||||
213,
|
||||
158
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "watcher-to-orchestrator",
|
||||
"from": "watcher",
|
||||
"to": "orchestrator",
|
||||
"label": "incremental sync",
|
||||
"variant": "dashed"
|
||||
},
|
||||
{
|
||||
"id": "orchestrator-to-sqlite",
|
||||
"from": "orchestrator",
|
||||
"to": "sqlite",
|
||||
"label": "parsed symbols & edges",
|
||||
"labelAt": [
|
||||
413,
|
||||
158
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "sqlite-to-resolver",
|
||||
"from": "sqlite",
|
||||
"to": "resolver",
|
||||
"label": "stored symbols",
|
||||
"labelAt": [
|
||||
613,
|
||||
158
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "resolver-to-graph",
|
||||
"from": "resolver",
|
||||
"to": "graph",
|
||||
"label": "resolved edges",
|
||||
"labelAt": [
|
||||
740,
|
||||
158
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "graph-to-context",
|
||||
"from": "graph",
|
||||
"to": "context",
|
||||
"label": "traversal results",
|
||||
"labelAt": [
|
||||
940,
|
||||
158
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "context-to-mcp",
|
||||
"from": "context",
|
||||
"to": "mcp",
|
||||
"label": "context payload",
|
||||
"labelAt": [
|
||||
1113,
|
||||
158
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "context-to-cli",
|
||||
"from": "context",
|
||||
"to": "cli",
|
||||
"label": "markdown / JSON",
|
||||
"variant": "dashed"
|
||||
},
|
||||
{
|
||||
"id": "graph-to-viewer",
|
||||
"from": "graph",
|
||||
"to": "viewer",
|
||||
"label": "read-only JSON API",
|
||||
"variant": "dashed"
|
||||
},
|
||||
{
|
||||
"id": "agents-to-mcp",
|
||||
"from": "agents",
|
||||
"to": "mcp",
|
||||
"label": "MCP tool calls"
|
||||
}
|
||||
],
|
||||
"cards": [
|
||||
{
|
||||
"dot": "cyan",
|
||||
"title": "Deterministic extraction",
|
||||
"items": [
|
||||
"Symbols and edges come from the AST, never LLM summaries",
|
||||
"29 tree-sitter grammars, with heavy parsing off the main thread",
|
||||
"Re-indexing the same source produces the same graph"
|
||||
]
|
||||
},
|
||||
{
|
||||
"dot": "emerald",
|
||||
"title": "One local index",
|
||||
"items": [
|
||||
"SQLite with WAL and FTS5 under .codegraph/",
|
||||
"Node's built-in node:sqlite — no native build step",
|
||||
"Per project, and it never leaves the machine"
|
||||
]
|
||||
},
|
||||
{
|
||||
"dot": "violet",
|
||||
"title": "Graph to answer",
|
||||
"items": [
|
||||
"Import, name, framework and dynamic-dispatch resolution",
|
||||
"Callers, callees, impact radius and named-symbol flow",
|
||||
"Three read-only surfaces: MCP server, CLI, browser viewer"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user