Story: System model readability
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Transform the System Model from a flat component inventory into a readable architecture document that a newcomer can understand top-to-bottom. Add a narrative introduction and layer blurbs explaining the role and rationale of each architectural layer, and convert component listings into scannable tables.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Complete. |
| Waiting on | Nothing. |
| Next | — |
| Last touched | 2026-05-28 |
Acceptance
- A newcomer reading the system model from top to bottom can explain what each layer does and why the system is organised this way.
- Each layer heading is preceded by a 1–2 paragraph blurb describing the layer's role, the kind of components it contains, and its dependency rules.
- Component inventories use tables (Component | Description | Dependencies) instead of bare bullet lists.
- The Database Isolation section is preserved and remains accurate.
- All id-links are valid; frontmatter
#+updatedis refreshed.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Rewrite system model with layer blurbs and component tables | DONE | 2026-05-26 | 2026-05-26 | Add narrative introduction, layer blurbs, and table-based component inventories to system_model.org. |
| Add component id-links and architectural cross-references to system model | DONE | 2026-05-26 | 2026-05-26 | Wire all unlinked Qt plugin component rows to their component_overview.org via id-links; add cross-references to key architectural docs (workspaces, multi-tenancy, multi-party); consolidate DQ isolation content. |
| Split system model into per-layer sub-pages and add architecture diagram | DONE | 2026-05-28 | 2026-05-28 | Split each architecture layer in system_model.org into its own sub-page linked via org-roam; add a PlantUML 4-layer architecture diagram; merge site_pdf_and_manual_book story; add NATS org-roam links. |
| Additional system model improvements | DONE | 2026-05-28 | 2026-05-28 | Fix the architecture_layers.puml diagram; simplify system_model.org layer section headings to linked one-liners removing duplicated blurb text. |
PRs
| PR | Title |
|---|---|
| 859 | [agile,doc] Add system-model-readability story and register DeepSeek as LLM co-author |
Plan
The current System Model at projects/modeling/system_model.org is a flat bullet list of components under four layer headings. It is accurate as a reference but does not explain the architecture — there is no narrative and no layer rationale.
The improvement follows a top-down reading order:
- Narrative introduction. A new opening paragraph under
* System Architecture(before the diagram) explains the four-layer design: Foundation provides base infrastructure with no ORE dependencies, Infrastructure adds communication and testing, Domain encodes business logic, and Application delivers user-facing surfaces. The dependency rule (layers only depend downward) is stated explicitly. Layer blurbs. Each layer heading (
** Foundation Layer, etc.) gains a short blurb:- What the layer is responsible for.
- Why it exists as a separate layer.
- What kinds of components live here.
- What it depends on and what depends on it.
The blurbs are placed before the component list so the reader has context before scanning the inventory.
Component tables. Each layer's bullet list converts to a table:
- Column 1: Component (id-linked to its component_overview.org).
- Column 2: One-line description.
- Column 3: Depends on (other components or "none").
The
Depends oncolumn replaces the "Depends on:" suffixes currently appended to descriptions.- Preserve Database Isolation. The
* Database Isolationsection is well-written and is kept as-is. No structural changes.
Decisions
Out of scope
- Changing the component architecture itself (api/core/service split, dependency graph). This story is purely about documentation readability.
- Adding new components or removing existing ones from the inventory.
- Rewriting individual component_overview.org files — those are out of scope here.
- Changes to the PlantUML system diagram (
ores.puml/ores.png).
Review
Review round 1 (gemini-code-assist, 2026-05-26).
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | Use ID link for system_model.org | story.org | Applied | Replaced with id:D773166D... |
| 2 | Remove empty Tasks bullet | story.org | Applied | Removed trailing - |
| 3 | Use ID link for component_overview.org | story.org | Applied | Replaced with id:B9D3D469... (×2) |
| 4 | Use ID link for component_overview.org | story.org | Applied | Second occurrence in Plan step 3 |