Files

T

Julien Gautier 79eee77594 chore: initialize repository with project rules, docs, and phase-1 ADRs

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.

2026-04-29 20:43:00 +02:00

3.4 KiB

Raw Blame History

status, date, decision-makers, tags

status

date

decision-makers

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 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:

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 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 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
Tag vocabulary: see "Tag vocabulary" in README.md.

3.4 KiB Raw Blame History