Architecture

Mercatorgraph is three app services plus Postgres. Agents only ever reach the MCP server; the worker is the only writer; the viewer is for humans.

Two write paths

Rebuilds are heavy and rare; annotations/comments are light and frequent. They never mix.

Query path (the hot path)

Derived vs contributed knowledge

The single most important rule:

• Derived = Graphify output (graph.json, report). Rebuildable, versioned on the volume, overwritten every build.
• Contributed = annotations + comments. Durable, in Postgres, overlaid at query time. Never written into graph.json — otherwise it is lost on every rebuild.