Architecture

Synaptic is a Rust workspace: 25 library crates under crates/* plus the synaptic CLI under bin/. The workspace uses edition 2021 and a pinned Rust 1.96 toolchain, with dependencies centralized in the root Cargo.toml.

The pipeline

A normal extract run flows through these stages:

detect  ->  extract  ->  graph build  ->  cluster + analyze  ->  output
                                   \-> (optional) semantic pass

1. detect - walk the directory, classify files, apply ignore rules, and skip sensitive files. See Extraction.
2. extract - run tree-sitter (or a regex extractor) per file to produce nodes and edges. Results are cached per file so unchanged files skip re-parsing. See Languages.
3. graph build - assemble nodes/edges into a graph, resolve symbols across files, and deduplicate.
4. cluster + analyze - detect communities, compute betweenness and god nodes, find import cycles and surprising connections. See Analysis and Reports.
5. output - write graph.json and the report, visualizations, and exports. See Output Formats.

The optional semantic pass (--semantic) sends documents and papers to an LLM to add concept nodes and to break ties during dedup. See Semantic Analysis.

Querying and serving read graph.json back; they do not re-extract. See Querying and MCP Server.

Crates

Crate	Responsibility
synaptic-core	The shared data contract: NodeId, FileType, Confidence, Node, Edge, Hyperedge, the graph.json node-link DTO, id generation, and schema validation
synaptic-detect	File discovery, classification, ignore handling (.synapticignore / .gitignore), manifest building, and sensitive-file detection
synaptic-extract	Tree-sitter (and regex) extractors that turn source files into core nodes/edges; languages gated behind lang-* features; per-file AST cache
synaptic-graph	Graph assembly: build, symbol resolution, dedup (MinHash/LSH), clustering and community detection, betweenness, analysis
synaptic-semantic	The LLM semantic pass: documents and papers to concept nodes, plus the optional dedup tiebreaker
synaptic-llm	Pluggable LLM client layer: provider registry with env auto-detect, response cache, JSON repair, token-budget chunking, adaptive retry
synaptic-query	Query (IDF-scored subgraph retrieval), shortest path, node explanation, and reverse impact
synaptic-output	Output writers: graph.json, HTML viewers, SVG, GraphML, Cypher, DOT, Mermaid call-flow, D3 tree, Obsidian, wiki, and live database push
synaptic-report	The GRAPH_REPORT.md generator
synaptic-ingest	External-source ingestion: URL (SSRF-guarded), MCP config, Cargo, Postgres, SCIP, office, media
synaptic-server	The MCP server (read-only graph and PR tools) over stdio and HTTP, plus a small REST surface
synaptic-prs	Graph-aware PR dashboard: classification, CI rollup, blast radius, conflict grouping
synaptic-incremental	Changed-files rebuild engine plus git integration (hooks, merge driver, watch, concurrency lock)
synaptic-workspace	Multi-repo / monorepo federation: member discovery, namespacing, cross-repo resolution, global store, merge-graphs
synaptic-skillgen	Generates and installs the host-assistant integration: the Claude skill file + .claude/settings.json hooks, the always-on instruction blocks (AGENTS.md/GEMINI.md/etc.), and the Codex MCP server + SessionStart hook config (project .codex/ or global ~/.codex/)
synaptic-synql	The SYNQL query engine: a small Cypher-inspired language over the graph (kind/visibility/loc/fan-in-out, variable-length paths, count(...)), used by synaptic search and the structural_search tool
synaptic-history	Time-travel diff: builds the graph at a git revision in a throwaway worktree (cached per commit) and diffs two revisions (synaptic diff, time_travel_diff)
synaptic-refactor	Safe-refactor plans (rename/move/extract) for an agent to apply, plus post-edit graph-invariant verification
synaptic-predict	Change forecasting: blast radius, at-risk tests, public-API risk, change-risk score, co-change, and the analytic edit forecast (synaptic predict)
synaptic-sandbox	Speculative execution: apply a change in a throwaway worktree and run the at-risk tests + a build/type-check (synaptic speculate)
synaptic-eval	Forecast evaluation: the prediction ledger and the replay calibration harness (synaptic eval replay)
synaptic-readiness	Static port/readiness auditor: ranks graph-linked framework stubs, sentinel returns, placeholders, generated-resource noise, and project metadata for synaptic audit readiness / readiness_audit
synaptic-sqlaudit	SQL performance & security auditor: a rule engine over a SQL-aware graph (columns, indexes, RLS policies, grants, code-to-SQL edges) powering synaptic sql audit/advise and the audit_sql / advise_sql MCP tools
bin/synaptic	The CLI that wires the crates into commands

Data model

The graph is a node-link structure serialized to graph.json (NetworkX-compatible shape).

• Nodes have an id, a label, a file_type (one of code, document, paper, image, rationale, concept), and a source_file. Optional fields include source_location, community, and repo (for federated graphs).
• Edges (serialized under links) have a source, target, relation (for example calls, imports, imports_from, inherits, implements, references, contains, depends_on, reads_from, shadows), and a confidence of EXTRACTED, INFERRED, or AMBIGUOUS. Cross-repo edges are flagged with cross_repo. Semantic edge identity also includes optional context (so GET and POST couplings between the same nodes remain distinct). When several extraction sites produce the same semantic edge, the typed source_file / source_location remain the primary site and additional distinct sites are retained in the flattened sites array.
• Resource nodes (file_type: document, tagged _node_type: resource) index data/resource files (data JSON, .mcmeta) one node per file — never one per key. Reference-like strings inside them bind to the file, resource (by path-derived logical id ns:path), or code symbol they name via a references edge, and a generated resource that duplicates a source one at the same logical path gets a shadows edge. This is framework-agnostic (a Minecraft ResourceLocation is one instance of the logical-id shape) and on by default (extract --no-resources to skip). Because they are ordinary nodes with edges, affected and query_graph span code and resources.

The exact JSON shape and every export format are documented in Output Formats.

Determinism

Extraction parallelizes across files but collects results in a stable order, so graph.json is byte-identical for the same input regardless of thread scheduling. Community numbers are assigned deterministically (community 0 is the largest) and kept stable across incremental rebuilds.

Where to go next

• Configuration knobs and files: Configuration
• Building, testing, and CI: Development