Julien Gautier
79eee77594
Set up the foundation for the adastra-portal project: - CLAUDE.md captures durable project rules (quality bar, security/perf/a11y as first-class, language, commit conventions, ADR proactivity). - docs/ and decisions/ scaffolding with maintained indexes (docs/README.md and decisions/README.md), MADR 4.0.0 template, and tag vocabulary. - Phase-1 ADRs (0001-0006) lock structural choices: ADR usage, Nx monorepo with the apps preset, naming convention (adastra-portal / portal-shell / portal-bff), Angular CSR/zoneless/Signals/Vitest, NestJS over Express, PostgreSQL with Prisma. - docs/setup/ guides translated to English. - .gitignore covers Node/Nx artifacts and the personal notes/ scratchpad. The Nx workspace itself is not yet bootstrapped; that step is gated on a revised setup guide aligned with the ADRs.
63 lines
3.4 KiB
Markdown
63 lines
3.4 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-04-29
|
|
decision-makers: R&D Lead
|
|
tags: [process]
|
|
---
|
|
|
|
# Use ADRs to record architectural decisions
|
|
|
|
## Context and Problem Statement
|
|
|
|
Architecturally-significant decisions will be taken throughout the lifecycle of `adastra-portal`. Without a written, durable trace of *why* a decision was made — context, drivers, alternatives, trade-offs — that knowledge fades within months. New contributors re-litigate settled debates, the rationale of constraints (security, performance, accessibility) gets lost, and reversing a choice later becomes risky because nobody remembers what it was protecting against.
|
|
|
|
How do we record decisions in a way that is light enough to be sustained, durable enough to outlive contributor turnover, and integrated into the development workflow?
|
|
|
|
## Decision Drivers
|
|
|
|
* Preserve the *why* of each decision so future contributors can understand or revisit it without re-deriving it.
|
|
* Make architecture reviewable — both at the time of a decision and during retrospective audits.
|
|
* Keep the format light enough that writing an ADR isn't a bureaucratic deterrent.
|
|
* Live alongside the code in version control, so decisions evolve with what they govern.
|
|
* Match the project's stated values: high technical bar, no bricolage, security/performance/accessibility as first-class concerns whose rationale must be traceable.
|
|
|
|
## Considered Options
|
|
|
|
* No formal records — rely on commit messages and tribal knowledge.
|
|
* External wiki / Confluence — decisions live outside the codebase.
|
|
* ADRs in markdown using the [MADR 4.0.0](https://github.com/adr/madr) format, in-repo.
|
|
* ADRs in another format (Nygard, Y-Statement, Cockburn).
|
|
|
|
## Decision Outcome
|
|
|
|
Chosen option: **ADRs in markdown using MADR 4.0.0**, stored in `decisions/` at the repository root.
|
|
|
|
Conventions are defined in [README.md](README.md):
|
|
- flat folder layout (no nested category folders);
|
|
- globally sequential 4-digit numeric prefix (`NNNN-kebab-title.md`);
|
|
- categorization via the `tags:` field in the MADR frontmatter, drawn from a canonical vocabulary;
|
|
- status lifecycle: `proposed` → `accepted` → optionally `deprecated` / `superseded by ADR-NNNN`;
|
|
- index maintained in [README.md](README.md) alongside any ADR change.
|
|
|
|
### Consequences
|
|
|
|
* Good, because the *why* of every architecturally-significant decision is captured at the moment it is made and travels with the code.
|
|
* Good, because ADRs are reviewed via the normal pull-request flow — architecture becomes an explicit team conversation.
|
|
* Good, because MADR provides enough structure (drivers, options, trade-offs) without being heavy.
|
|
* Good, because flat-folder + tags scales better than nested category folders as the count grows.
|
|
* Bad, because writing an ADR adds friction; this must be balanced against the cost of *not* writing one.
|
|
* Bad, because the index is maintained manually until tooling or a CI check is added.
|
|
|
|
### Confirmation
|
|
|
|
* Every change introducing or transitioning the status of an ADR updates the index table in [README.md](README.md) in the same commit.
|
|
* PR review explicitly checks for ADR proposal whenever a non-trivial decision is being introduced.
|
|
* (Future) A CI lint job validates filename pattern, frontmatter shape, and tag vocabulary.
|
|
|
|
## More Information
|
|
|
|
* MADR 4.0.0 specification: https://github.com/adr/madr
|
|
* General ADR resources: https://adr.github.io/
|
|
* Template: [template.md](template.md)
|
|
* Tag vocabulary: see "Tag vocabulary" in [README.md](README.md).
|