alunduil / alunduil/alunduil-infrastructure

Documentation and diagramming strategy recorded as an ADR

Ouverte
#140 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
documentation
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.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.