Story: Codegen Model Dashboard
Table of Contents
This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Build a JavaScript dashboard in projects/ores.org-js/ that visualises the
structure of the MASD codegen model — the ~127 org-mode entity/config files,
their types, and the cross-references between them — so that a developer can
orient themselves in the codegen model without reading every file.
The existing knowledge-graph visualiser shows all documents and is unusable for this purpose; the agile dashboard PoC (sprint 20) proved the pattern. This story delivers the same idea for codegen: a focused, purpose-built view over a well-typed subset of the org corpus.
Design principles:
- Filtered scope — show only org-mode files that carry information to the code generator (types listed in the inventory below). All other documents are excluded.
- Colour by type — follow Object Modeling in Color conventions: each MASD type family gets a distinct hue so the graph reads at a glance.
- UML-inspired layout — borrow UML class-diagram conventions (stereotypes, compartments, relationship arrows) to show containment and cross-references between entity files.
- Mustache source preview — org files that tangle Mustache templates (the
literate template docs created in sprint 20) surface in the sidebar with
their raw
.mustachesource shown in a collapsible pane. (Rendered HTML output is not feasible client-side: no data context is available ingraphdata.json.) - Deployable identically to the agile dashboard — serves from GitHub Pages
and a local dev server; data sourced from
graphdata.jsonor a codegen-specific JSON slice.
Codegen input org-file inventory (from task Improve meta-model for codegen input org files)
Entity / model types:
| MASD type | Count | Compass type | Primary output |
|---|---|---|---|
ores.codegen.entity |
75 | entity_org |
C++ domain class + SQL table + Qt UI |
ores.codegen.module |
12 | — | Index grouping entity docs for a namespace |
ores.codegen.lookup_entity |
12 | lookup_entity |
SQL artefact table (batch-loaded, no UI) |
ores.codegen.table |
10 | table |
SQL DDL only (reference-data tables) |
ores.codegen.field_group |
7 | field_group |
C++ struct fragment composed into entities |
ores.codegen.junction |
7 | junction |
SQL join table + C++ struct + repository |
ores.codegen.service_registry |
1 | service_registry |
SQL GRANT scripts + shell var declarations |
Generator-config types:
| MASD type | File | Description |
|---|---|---|
ores.codegen.facet_catalogue |
facet_catalogue.org | Profile → facet → template/output mapping |
ores.codegen.component_catalogue |
component_catalogue.org | Component name → discovery roots |
ores.codegen.modeline_catalogue |
modeline.org | Editor modeline strings per language |
Literate template types (org files tangling to Mustache templates; require HTML preview):
| Type | Location | Description |
|---|---|---|
| Literate Mustache templates | projects/ores.codegen/library/templates/*.org |
One org file per template; tangles to .mustache |
Status
| Field | Value |
|---|---|
| State | ABANDONED |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Requirements re-captured as two inbox stories. |
| Last touched | 2026-06-12 |
Acceptance
- A dashboard page loads in a browser (GitHub Pages and
file:/// local dev server) and shows the codegen model as an interactive graph. - Nodes are coloured by MASD type following Object Modeling in Color conventions; a legend maps colour → type.
- Clicking a node shows document details (type, description, incoming and outgoing org-roam links).
- Generator-config nodes (facet_catalogue, component_catalogue, modeline_catalogue) are visually distinguished from entity model nodes.
- Template org files (
projects/ores.codegen/library/templates/) surface in the sidebar as linked chips; clicking one opens a collapsible pane with the raw Mustache source. (Rendered HTML output requires a data context not present ingraphdata.jsonand is out of scope.) - Only codegen-relevant org files appear (filtered by
#+type:to the inventory above); general knowledge and agile documents are excluded. - Data is sourced from a codegen-specific JSON slice of
graphdata.json(or the full graph pre-filtered client-side); no additional backend required. - The dashboard deploys via the same
ores-deploy-web-appsmechanism as the agile dashboard. - A brief written design note covers: colour mapping rationale, layout algorithm chosen, any limitations discovered, and recommended follow-ups.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Codegen Model Dashboard | DONE | 2026-06-11 | 2026-06-11 | Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR. |
| Brainstorm and design the codegen model dashboard | DONE | 2026-06-11 | 2026-06-11 | Brainstorm design decisions: type → colour mapping, layout algorithm, template preview approach, and data pipeline from graphdata.json. |
| Implement the Codegen Model Dashboard | DONE | 2026-06-11 | 2026-06-12 | Build the codegen dashboard JavaScript app in projects/ores.org-js/codegen/: d3-force graph with OMC colour coding, sidebar panel, Mustache source preview, and deploy via ores-deploy-web-apps. |
Decisions
Colour mapping (OMC-based)
Each MASD type is assigned a colour following Object Modeling in Color conventions. See task Brainstorm and design for full rationale.
| MASD type | OMC archetype | Colour | Hex |
|---|---|---|---|
ores.codegen.entity |
Party/Place/Thing | Green | #2da44e |
ores.codegen.field_group |
Part of thing (structural) | Teal | #1abc9c |
ores.codegen.lookup_entity |
Description/Catalog | Blue | #0075ca |
ores.codegen.table |
Description/Catalog (SQL) | Steel blue | #4a90d9 |
ores.codegen.junction |
Moment-Interval (relationship event) | Pink | #e05c8a |
ores.codegen.service_registry |
Infrastructure config | Orange | #d93b00 |
ores.codegen.module |
Organisational grouping | Gray | #8b949e |
ores.codegen.facet_catalogue |
Generator meta-config | Purple | #7c3aed |
ores.codegen.component_catalogue |
Generator meta-config | Purple | #7c3aed |
ores.codegen.modeline_catalogue |
Generator meta-config | Purple | #7c3aed |
OMC Yellow (Role) has no equivalent in the codegen type system and is omitted. The three purple types share the same hex; the legend must render them as a single entry ("Generator config ×3") to avoid implying they are distinct.
Layout algorithm
Decision: force-directed using d3-force (via CDN, no bundler) with a custom
type-cluster force — forceX / forceY pull same-type nodes into loose clusters,
giving OMC colour regions visible structure without strict hierarchy.
forceCollide prevents overlap (radius must account for node width when
UML-style boxes are used).
Three alternatives were assessed (d3-force, dagre hierarchical, radial/type-ring). d3-force was chosen because: 127 nodes are small enough for interactive force simulation; type-cluster hints give enough visual structure; it mirrors the existing knowledge-graph app; and it requires no bundler.
UML visual conventions (stereotypes, compartment lines, arrow-head styles) are deferred to the implementation task — they are a node/edge rendering concern separate from the layout algorithm. Non-determinism is mitigated by seeding initial positions from type-cluster targets rather than random positions.
Template HTML preview
Template org files (projects/ores.codegen/library/templates/) are not
first-class graph nodes. They surface only as linked chips inside the sidebar
of whichever entity/config node holds a link to them.
Sidebar behaviour (all nodes):
- Sidebar panel — type badge (colour-coded), title, description, and incoming/outgoing link chips; "View page" link to the published HTML.
- Template source pane — for template org files, the sidebar adds a
collapsible
<pre>block with raw Mustache source extracted from#+begin_src mustache…#+end_srcin thecontentfield.
No iframe needed — all content is already in graphdata.json.
Data pipeline
Decision: client-side filtering from the shared graphdata.json. No separate
codegendata.json build step.
Filter approach: parse #+type: from each level-0 node's content field using
/^#\+type:\s*(\S+)/m (identical to the agile dashboard), keep only nodes whose
type is in the CODEGEN_TYPES set, then filter links to those with both endpoints
retained. Result: 127 nodes, 75 links — instantaneous (~4% of corpus).
A dedicated codegendata.json slice can be added later as a CMake target if the
full graph grows to the point where load time matters.
Out of scope
- Editing org-mode files from the dashboard.
- Showing non-codegen documents (use the existing knowledge-graph visualiser for the full corpus).
- C++ source-file dependency graphs.
- Real-time / live reload from disk (static JSON snapshot is sufficient).