Documentation

The graph engine is the heart of CodeAtlas. It maintains a live, typed representation of every repository, service, module, API, and datastore, and streams incremental diffs to downstream agents.

Architecture

Ingestion, resolution, and projection run as three cooperating passes over a persistent, content-addressed store. Each pass produces a versioned snapshot that downstream agents can subscribe to.

type Node = {
  id: string
  kind: "repo" | "service" | "module" | "api" | "database" | "infra" | "ai"
  version: number
  hash: string
}

interface GraphEngine {
  scan(repo: Repository): Promise<Snapshot>
  diff(from: Snapshot, to: Snapshot): Diff
  subscribe(cb: (d: Diff) => void): Unsubscribe
}

Guarantees

• Snapshots are immutable and content-addressed.
• Diffs are minimal and reversible.
• Subscribers observe events at-least-once, with per-node ordering.

Copilot suggestion: introduce a projection cache keyed on (snapshot, agent)to avoid re-computing agent-specific views. Estimated 34% reduction in P95 planning latency.

Related