city.json
The code city: one flat, sorted, JSON-shaped tree. No classes, no cycles, no Maps — it must survive JSON.stringify unchanged and arrive intact in a browser. Written by city; the same shape with an extra replay block is written by replay and by history --city.
Field names are those of CityModel in packages/city/src/city.ts.
Top level
| Field | Type | Meaning |
|---|---|---|
kind | string | always codegraph.city/1 |
generatedBy | string | always @codegraph/city |
view | ViewDescriptor | {name, filters} — the view the city was built under |
corpus | {name, roots, repository?} | display name, the model roots verbatim, and the union’s repository facts when every model that carries one agrees |
conventions | object | what the renderer may assume; see below |
bindings | ResolvedBinding[] | the legend in machine form, one entry per bound channel |
districts | District[] | sorted by id |
buildings | Building[] | sorted by id |
arrows | Arrow[] | type-level dependencies, sorted by (from, to) |
districtArrows | Arrow[] | module-level dependencies between districts, from the analyzer’s fold at level: "module" under the same view |
roles | {framework, values} | present only with --framework: which framework spoke and the distinct roles it assigned, sorted |
diagnostics | CityDiagnostics | what the transform left out |
layout | ResolvedLayout | present only after --layout |
bounds | Bounds | present only after --layout: the whole ground plane |
replay | CityReplay | present only in a replay city |
conventions
| Field | Value | Meaning |
|---|---|---|
arrowAttachment | "roof" | arrows attach at the roof of each building, at both ends |
heightAxis | "y" | height grows along this axis |
groundPlane | "xz" | the plane the districts tile |
units | "city" | abstract city units — not metres, not pixels; only ratios mean anything |
bindings[] — ResolvedBinding
| Field | Type | Meaning |
|---|---|---|
channel | "height" | "footprint" | |
metric | string | the resolved metric name (loc, sum:cyclomatic, …) |
unit | string | what one unit of the value is, for the legend |
describe | string | the metric source’s own one-line description |
scale | "linear" | "sqrt" | "log" | |
range | {min, max} | the dimension given to the smallest and largest measured value |
domain | {min, max} | observed across the buildings that had a value; absent when none did |
unmeasured | integer | buildings the model could not measure on this channel |
See City metrics.
districts[] — District
| Field | Type | Meaning |
|---|---|---|
id | EntityId | the module’s rendered id |
name | string | undefined | |
kind | string | the entity kind, verbatim from the model |
isStub | boolean | |
identity | {lang, module, symbol, disambiguator?} | symbol is empty exactly when the element IS the module |
parent | EntityId | the nearest ancestor module that is itself a district, when the model declares module containment; never derived from the id or the name |
buildings | EntityId[] | sorted; every building whose type folds into this module |
footprintDemand | number | total base area its buildings occupy, in city units² |
bounds | {x, y, width, depth} | after --layout |
buildings[] — Building
| Field | Type | Meaning |
|---|---|---|
id | EntityId | |
name | string | undefined | |
kind | string | the entity kind, verbatim: class, interface, enum… |
isStub | boolean | |
district | EntityId | |
identity | {lang, module, symbol, disambiguator?} | |
source | {file, span?} | the anchor, for source links; absent when the model anchors nothing (stubs) |
role | string | the architectural role a framework profile assigns, with --framework; absent means the framework says nothing about it, never “plain” |
height | number | along the height axis |
footprint | {width, depth} | base rectangle |
metrics | Record<string, number | null> | raw measurements by metric name — the bound channels plus anything --carry asked for; null means the model does not say |
attributes | {name, type?, value?}[] | sorted by name; empty for stubs and memberless types, never absent |
operations | {signature, parameters?}[] | sorted by signature; a parameter is {name, type?} |
owner | {name, share} | dominant author of the element’s file, replay cities only and only when a history was joined |
position | {x, y} | after --layout: minimum corner of the footprint, absolute in city coordinates |
arrows[] and districtArrows[] — Arrow
| Field | Type | Meaning |
|---|---|---|
from, to | EntityId | |
count | integer | base edges aggregated into this arrow |
kinds | EdgeKind[] | sorted |
provenances | Provenance[] | sorted |
inferred | boolean | true when at least one base edge is not declared — precomputed so the renderer cannot get the rule wrong |
crossDistrict | boolean | true when the endpoints stand in different districts; trivially true on districtArrows |
feedback | boolean | true when this dependency is in the minimum feedback set of its strongly connected component at its own fold level |
Buildings reference their district and districts list their buildings: both directions are stored in the artifact even though one is derivable, because a renderer walks both ways per frame. This is not the interchange model, where inverse indexes are never serialized.
diagnostics — CityDiagnostics
| Field | Type | Meaning |
|---|---|---|
unplacedBuildings | EntityId[] | types whose module the model does not give; excluded, sorted |
droppedArrows | integer | arrows dropped because an endpoint was not placed |
selfArrows | integer | type-level self-dependencies, excluded |
droppedDistrictArrows | integer | district arrows dropped because an endpoint module is not a district here |
selfDistrictArrows | integer | module-level self-dependencies, excluded — internal cohesion, not an arrow |
unmeasured | Record<string, number> | per metric name, how many buildings the model could not measure |
fold | {unfoldableEntities, droppedEdges, foldedEdges} | passed through from the fold that produced the buildings |
layout — ResolvedLayout
| Field | Value on the default run | Meaning |
|---|---|---|
algorithm | "shelf-rows" | |
order | "area-desc,id-asc" | |
buildingGap | 2 | street kept open between two buildings of one district |
districtPadding | 3 | sidewalk between a district’s border and its outermost buildings |
districtGap | 6 | avenue kept open between two districts |
replay — CityReplay
Present in a replay city only.
| Field | Type | Meaning |
|---|---|---|
clock | "commits" | "revisions" | what a tick IS: every commit of a mined history, or the sampled revisions of a temporal store |
ticks | {hash, time, author, fix?}[] | chronological; time is unix seconds |
series | Record<string, [tick, height, heat?][]> | building id → sparse keyframes. A keyframe holds until the next one; before the first the building does not exist (height 0), and height 0 later means the element is deleted |
coChange | {a, b, support, confidence}[] | logical-coupling arcs between buildings, mined from history — an INFERENCE, never a dependency. Absent when no history was joined |
Excerpt
codegraph city fixtures/java/expected/model.jsonl --layout, trimmed to one district, one building and one arrow of each kind:
{
"kind": "codegraph.city/1",
"generatedBy": "@codegraph/city",
"view": { "name": "all", "filters": [] },
"corpus": { "name": "src", "roots": ["fixtures/java/src"] },
"conventions": { "arrowAttachment": "roof", "heightAxis": "y", "groundPlane": "xz", "units": "city" },
"bindings": [
{ "channel": "height", "metric": "loc", "unit": "source lines",
"describe": "Lines the type's own source anchor spans (end - start + 1).",
"scale": "linear", "range": { "min": 1, "max": 40 }, "domain": { "min": 4, "max": 51 },
"unmeasured": 18 },
{ "channel": "footprint", "metric": "members", "unit": "entities",
"describe": "Base entities that folded into the building, the type included.",
"scale": "sqrt", "range": { "min": 2, "max": 20 }, "domain": { "min": 1, "max": 22 },
"unmeasured": 0 }
],
"districts": [
{ "id": "java:com.megacorp.ledger", "name": "com.megacorp.ledger", "kind": "package",
"isStub": true,
"identity": { "lang": "java", "module": "com.megacorp.ledger", "symbol": "" },
"buildings": ["java:com.megacorp.ledger/LedgerClient"],
"footprintDemand": 4,
"bounds": { "x": 46, "y": 84.673, "width": 8, "depth": 8 } }
],
"buildings": [
{ "id": "java:com.acme.order.adapter/LedgerAdapter", "name": "LedgerAdapter", "kind": "class",
"isStub": false, "district": "java:com.acme.order.adapter",
"identity": { "lang": "java", "module": "com.acme.order.adapter", "symbol": "LedgerAdapter" },
"source": { "file": "com/acme/order/adapter/LedgerAdapter.java", "span": [6, 15] },
"height": 5.979, "footprint": { "width": 8.029, "depth": 8.029 },
"metrics": { "loc": 10, "members": 5 },
"attributes": [{ "name": "trail", "type": "AuditTrail" }],
"operations": [
{ "signature": "<init>()", "parameters": [] },
{ "signature": "post(java.lang.Object)",
"parameters": [{ "name": "document", "type": "Object" }] }
],
"position": { "x": 24.013, "y": 28 } }
],
"arrows": [
{ "from": "java:com.acme.order.adapter/LedgerAdapter",
"to": "java:com.megacorp.ledger/LedgerClient",
"count": 1, "kinds": ["inheritance"], "provenances": ["declared"],
"inferred": false, "crossDistrict": true, "feedback": false }
],
"districtArrows": [
{ "from": "java:com.acme.order", "to": "java:com.acme.order.legacy",
"count": 2, "kinds": ["invocation", "reference"], "provenances": ["declared"],
"inferred": false, "crossDistrict": true, "feedback": false }
],
"diagnostics": {
"unplacedBuildings": ["java:com.acme.order.adapter/AuditTrail", "java:com.acme.order/Invoice"],
"droppedArrows": 2, "selfArrows": 12,
"droppedDistrictArrows": 0, "selfDistrictArrows": 3,
"unmeasured": { "loc": 18, "members": 0 },
"fold": { "unfoldableEntities": 10, "droppedEdges": 11, "foldedEdges": 177 }
},
"layout": { "algorithm": "shelf-rows", "order": "area-desc,id-asc",
"buildingGap": 2, "districtPadding": 3, "districtGap": 6 },
"bounds": { "x": 0, "y": 0, "width": 85.55, "depth": 96.673 }
}Why the city is a model rather than a picture: The city is a model.
Last updated on