Graph Model

Overview

Synapses builds a relational graph from your codebase. The graph consists of nodes (code entities) connected by edges (relationships). This graph powers context carving, impact analysis, and all code intelligence features.

Node Types

Code Entities

Type	Description	Example
`function`	Functions and procedures	`ValidateToken()`
`method`	Struct/class methods	`(s *Server) Start()`
`struct`	Struct definitions	`type Config struct`
`interface`	Interface definitions	`type Handler interface`
`variable`	Variables and constants	`const MaxRetries = 3`
`file`	Source files (root containers)	`auth.go`
`package`	Language packages/modules	`internal/auth`

Synthetic Nodes

Type	Description	Source
`route`	HTTP/RPC routes	Injected by route heuristic pass

Documentation Nodes

Type	Description
`section`	Markdown heading (ATX `#` through `######`)

Knowledge Nodes

Type	Description
`concept`	Abstract ideas (e.g., “token bucket”, “eventual consistency”)
`entity`	Real-world entities (people, organizations, products)
`artifact`	Documents, specs, standards (RFC 7519, GDPR Article 17)
`decision`	Architectural/design decisions (from ADRs)

Node Properties

Node {
  ID          string    // Stable UUID v4
  Type        string    // One of the types above
  Name        string    // Entity name
  Package     string    // Language package
  File        string    // Absolute file path
  Line        int       // Source line number
  Exported    bool      // Public/exported?
  StableID    string    // UUID preserved across renames
  Provenance  string    // "user-authored" | "generated" | "vendored" | "external"
  Domain      string    // "code" | "infra" | "api" | "docs" | "issues" | "knowledge"
  Metadata    map       // Flexible attributes (churn, coverage, cpu_pct, confidence)
}

Edge Types

Code Edges

Type	Weight	Description
`CALLS`	1.0	Function calls another function
`DATA_FLOWS`	0.95	Data dependency chain (source → sink)
`IMPLEMENTS`	0.9	Type implements an interface
`HANDLES`	0.9	Route → handler function (synthetic)
`EMBEDS`	0.85	Struct embeds another struct
`DEPENDS_ON`	0.8	Package dependency
`IMPORTS`	0.7	Module/package import
`EXPORTS`	0.5	Exported symbol
`DEFINES`	0.15	File → entity containment

Documentation Edges

Type	Weight	Description
`CONTAINS`	0.15	Document → section containment
`EXPLAINS`	0.7	Documentation section → code entity
`DOCUMENTED_BY`	0.6	Code entity → documentation section
`LINKS_TO`	0.3	Cross-document markdown links

Cross-Domain Edges

Type	Weight	Description
`DEPLOYS`	0.75	Code → infrastructure resource
`CONSUMES`	0.75	Code → API endpoint/service
`CONFIGURED_BY`	0.65	Code → config resource
`DOCUMENTS`	0.65	Docs → code (broader than EXPLAINS)
`MENTIONS`	0.55	Synthetic name-match edges (0.0-1.0 confidence)
`MANUAL`	0.5	User-defined via `link_entities`

Knowledge Edges

Type	Weight	Description
`CONTRADICTS`	0.6	Conflicting information
`CAUSED_BY`	0.5	Effect → cause relationship
`INSTANCE_OF`	0.4	Specific → general type
`RELATES_TO`	0.3	Generic fallback relationship

Storage

The graph is stored in SQLite with these key tables:

nodes: All graph nodes with properties
edges: All relationships (from_id, to_id, type)
manual_edges: User-created edges via link_entities
edge_learned_weights: Weight adjustments from agent feedback
call_sites: Unresolved call sites for deferred resolution
node_embeddings: Vector embeddings for semantic search
nodes_fts: FTS5 full-text search index

The graph is also kept in memory for fast traversal, with an optional FlatGraph (SoA layout) for cache-friendly PPR computation.