alunduil / alunduil/alunduil-infrastructure
Documentation and diagramming strategy recorded as an ADR
- Langage dominant
- Shell
- Étoiles
- 0
- Forks
- 0
- Merge moyen
- 6 h 30 min
- PR mergées (30 j)
- 97
Description
## Summary
Record, as an ADR, how this repo documents and diagrams the
personal-systems architecture: hand-authored Mermaid for every view —
data flow, network and physical topology, and the remaining quality
and risk axes — with C4 and a modelling tool recorded as the rejected
alternative. The ADR is the deliverable: chosen approach, rejected
alternatives, consequences.
## Motivation
Every diagram artifact that follows (#141, #142, #143, #144) needs a
settled "why this format" to point at, or the call gets re-litigated
per artifact. The C4 model issue (#84) closed as not planned — its
structural scope dispersed to the DFD (#143), the network and
physical map (#142), the asset inventory (#141), and the
repo-organisation assessment (#255), leaving no artifact a modelling
tool would carry. That closure is itself the decision this ADR
records. Mirrors how the repo already treats methodology as the lever
(threat model in #85).
## Scope
Output is `docs/`, no `.tf`.
- Record the decision: hand-authored Mermaid, rendered natively in
GitHub Markdown, for the DFD, the network and physical map, and the
remaining non-structural views. No modelling tool, no export step.
- Record C4/Structurizr as the rejected alternative, citing the
evidence from the #84 attempt (PR #91, branch
`alunduil/worktree/gentle-chigger`): one-model-many-views bought a
Structurizr → PlantUML → committed-SVG export toolchain, and the
deployment export dropped the node detail — addresses, models, link
types — that #142 needs. Name the cost of the choice too: divergence
between hand-authored views with no single model to check them
against.
- Anchor the view catalog to Rozanski & Woods' viewpoints and
perspectives so additions are deliberate, not ad-hoc. Canonical
set (verified against viewpoints-and-perspectives.info): 7
viewpoints — Context, Functional, Information, Concurrency,
Development, Deployment, Operational; 10 perspectives — Security,
Performance & Scalability, Availability & Resilience, Evolution,
Accessibility, Development Resource, Internationalization,
Location, Regulation, Usability. State which we cover for a
~4-device estate and which we skip on purpose.
- ADR scaffold (location + template) is shared with #93 — whichever
ADR lands first establishes `docs/adr/` and the template. Template
is Nygard (light: context / decision / consequences). Don't
duplicate the scaffold task across the two issues. No ordering
dependency either way.
- Rationale prose from the #84 attempt sits at
`docs/architecture/README.md` on the `alunduil/worktree/gentle-chigger`
branch, which is not landing. Harvest what's still true into the
ADR rather than treating it as existing repo content — `docs/` on
`main` has no `architecture/`.
## Acceptance criteria
- [ ] ADR recorded under the agreed `docs/adr/` path, Nygard-style
- [ ] Names hand-authored Mermaid as the format for every diagram
artifact, with the reason
- [ ] Records C4/Structurizr as rejected, citing the #84 / PR #91
attempt and the export limitations it hit
- [ ] References the R&W viewpoints/perspectives catalog and the
covered/skipped call for this estate
- [ ] Consequences recorded, including hand-authored divergence with
no single model behind the views
- [ ] Diátaxis classification: explanation
## Additional context
Spine for the artifact issues that follow: #141 (asset inventory),
#142 (network and physical map), #143 (DFD), #144 (backup and DR).
Sibling ADR: #93 (compute platform) — shares the ADR scaffold, no
ordering dependency. Superseded structural model: #84. Threat model:
#85. Remaining C4 use in the repo: #255, scoped to repo organisation
for the DDD call.
Guide de contribution
Aucun guide de contribution indexé pour ce dépôt
Évaluation
Cette issue n'a pas encore été évaluée.