1. Use ADRs for Architecture Decisions

Status

Accepted — 2026-04-19

Context

jjk.engineer is a solo-maintained Angular SSR blog with an evolving architecture. Decisions have historically been made and implemented without formal documentation, leaving intent implicit in the code. As the system grows in complexity — multi-agent Claude Code workflows, Firebase integrations, PWA infrastructure, n8n automation — the need to capture why things are the way they are has become apparent.

Decision

We will use Nygard-format ADRs stored in docs-site/architecture/decisions/ to document significant architectural decisions, both retroactively and going forward.

Files follow the naming convention NNNN-short-title.md, where NNNN is a zero-padded sequential number. Retroactive ADRs carry the status Accepted and an approximate date reflecting when the decision was actually made.

Each ADR contains the Nygard sections: Title, Status, Context, Decision, Consequences.

Consequences

• Intent is captured alongside the code, so future-me (and any agent reading the repo) can reconstruct why a given shape exists without spelunking through git history.
• The format is lightweight and low-friction: a single Markdown file per decision, no tooling required.
• There is no enforcement mechanism. ADRs get written only if the author remembers to write them. Drift between actual architecture and documented decisions is possible and will not be caught automatically.
• Retroactive ADRs are inherently approximate — dates and rationale reconstructed after the fact are best-effort, not authoritative.
• The numbering scheme is sequential and append-only. Superseded decisions stay in the log with their status updated, rather than being deleted.