All docs

Code Graph

The architecture diagram on every Daisi Git commit: a derived project graph, plus an optional overlay.

Open Code Graph

  1. On the commit

    Every commit page has an Architecture panel. Components sit in lanes (Apps, Services, Domain, Data, and others) and dependencies are edges. The graph is computed for that commit, so history shows the architecture as it was then. Added components are green, removed ones are red ghosts, and components touched by the commit’s files are amber. Open a repository on Daisi Git and pick a commit to see it.

  2. Two layers

    The derived base is computed from the code in that commit’s tree. It stays correct without a file to maintain. The overlay is an optional delta committed at .dg/code-graph/code-graph-overlay.json. It annotates the base: external systems, descriptions, lane assignments, and hidden noise.

  3. What gets derived

    For .NET repositories, Daisi Git scans the tree for .csproj files. One node per project, one edge per ProjectReference. A reference that resolves outside the repository becomes an external node. No build or checkout is involved, so it works for any historical commit. Lanes come from the project name’s last segment: *.Web is Apps, *.Services is Services, *.Core is Domain, *.Data is Data, *.SDK is Clients, *Tests is Tests. If the name does not match, projects nothing depends on go to Apps and projects that depend on nothing go to Domain. The overlay can reassign any lane. Graphs are cached by commit SHA — computed on push for the default branch, or the first time a commit page is opened.

  4. The folder

    On the first push to the default branch, Daisi Git seeds .dg/code-graph when it is missing, as a commit authored by daisi-git. code-graph-overlay.json starts as a no-op. code-graph-instructions.md points at this guide so an agent in the repo can find the current schema.

  5. Overlay schema

    The overlay is a delta, not a full graph. Operations are keyed by node id and merged onto the derived base when the page renders. lanes lists columns left to right; listed lanes come first and any other lane still in use is appended. nodes.add creates nodes, usually external systems. id is required and lane defaults to External. Adding an id that already exists updates the fields you provide. nodes.update is a partial update: label, lane, description, kind. nodes.hide drops those nodes and their edges. edges.add needs both ends to exist after the node operations. kind is ref (default), data, queue, http, or a custom name; anything other than ref draws as a dashed flow edge. edges.hide removes an edge written as fromId->toId.

    {
  "version": 1,
  "mode": "overlay",
  "lanes": ["Apps", "Services", "Data", "External"],
  "nodes": {
    "add": [
      { "id": "ext:cosmos", "label": "Cosmos DB", "lane": "External", "kind": "external" },
      { "id": "ext:queue",  "label": "Storage Queue", "lane": "External", "kind": "external" }
    ],
    "update": {
      "proj:MyApp.Worker": { "description": "Queue-driven background processor" },
      "proj:MyApp.Shared": { "lane": "Domain" }
    },
    "hide": ["proj:MyApp.DevTools"]
  },
  "edges": {
    "add": [
      { "from": "proj:MyApp.Data",   "to": "ext:cosmos", "kind": "data" },
      { "from": "proj:MyApp.Worker", "to": "ext:queue",  "kind": "queue" }
    ],
    "hide": ["proj:MyApp.Web->proj:MyApp.Shared"]
  }
}

  6. Node ids

    A derived project is proj:<ProjectName>, the csproj filename without the extension, such as proj:MyApp.Services. An external reference derived from a project reference is ext:<Name>. Overlay nodes can use any id; ext: is the convention for systems outside the codebase. A lane exists because something names it.

  7. Stale entries and replace mode

    An operation whose node is gone from the derived base — a renamed project, for example — is skipped, and the commit page shows a stale overlay entries hint. The graph stays correct; only that annotation is dropped. Repositories with no derivable base can set mode to replace and author the whole graph: nodes.add and edges.add define it, and the derived base is ignored.

  8. For agents

    When a change adds a component, an external dependency (database, queue, API), or a new data flow, update .dg/code-graph/code-graph-overlay.json in the same commit. Do not describe projects and project references the derived graph already shows. The overlay is only what static analysis cannot see. Keep a description to one sentence.

WorkflowsBroski

Reviewed October 2026.