Move the ADR folder under docs/ alongside the rest of the project
documentation. Convention (flat folder, globally-sequential 4-digit
numbering, tags-based categorization, MADR 4.0.0 format) is unchanged
- only the path moved.
- git mv decisions docs/decisions preserves history for all 18 ADRs +
README + template (19 files renamed in this commit).
- ADR-0001 amended in-place with a dated note documenting the
relocation. Status remains 'accepted' - the location detail
changed, the decision did not.
- All cross-references updated:
- CLAUDE.md (~17 ADR links + 3 mentions of decisions/ in the Project
rules section)
- docs/README.md (now references decisions/ as a sibling under docs/)
- docs/setup/03-angular-nx-monorepo.md (paths shortened from
../../decisions/ to ../decisions/, since setup/ and decisions/ are
now both inside docs/)
- docs/decisions/0003 ../CLAUDE.md adjusted to ../../CLAUDE.md
(one extra level of nesting)
- docs/decisions/template.md mention of the README path
- notes/asvs-level-decision-briefing-rssi.md mention of the index
Sanity verified: every ADR link in CLAUDE.md, docs/setup/03, and
docs/decisions/0001 resolves to an existing file. pnpm nx run-many
-t lint passes on 8 projects.
Nx 22 generators inject AI agent tooling into the repo via marked
sections and side files. Rather than re-deleting them after every
generator run, track the workspace-level ones and document why.
- CLAUDE.md gains a 'General Guidelines for working with Nx' section
between Nx-managed markers; future Nx versions will update this
section automatically without touching our project rules above.
Pre-existing prettier-formatted blank lines added before code blocks
are kept.
- .claude/settings.json (228 bytes) enables the nx-claude-plugins
marketplace from nrwl/nx-ai-agents-config; tracked for contributor
consistency. The personal .claude/settings.local.json stays
gitignored.
- .github/ is the Nx AI skills/prompts/agents catalog. Kept despite
being GitHub-named; it does not conflict with our Gitea workflows
which will live under .gitea/workflows/ (per ADR-0015).
- .gitignore picks up Nx-managed transient dirs (.nx/polygraph,
.claude/worktrees) and a trailing newline fix.
AGENTS.md is removed: it duplicated only the Nx auto-injected guidance
that CLAUDE.md already carries (CLAUDE.md is the strictly broader file
- project rules + Nx section). One source of truth for AI-agent
guidance.
The Architecture section title and the Repository status paragraph
still referred to 'phase-1 ADRs' as if that were the current state.
Update both to reflect that ADRs 0001-0017 (phase 1 + 2 + 3a) are
recorded, that the security baseline ADR is paused awaiting RSSI
input, and that docs/setup/03 has already been rewritten to align
with the ADRs.
Pin the perf framework. Front-end metrics tracked at Google Core Web
Vitals 'Good' thresholds (LCP <= 2.5s, INP <= 200ms, CLS <= 0.1, plus
TBT <= 200ms, TTFB <= 800ms) and Lighthouse Performance >= 90 on
critical routes. Lighthouse CI (@lhci/cli) enforces them in CI with
median-of-3 runs to mitigate runner variance, on a curated
critical-routes list (login, home, accessibility statement, flagship
features as they land). Wires into the perf gate slot from ADR-0015.
Bundle budgets enforced at nx build via Angular's project.json budgets
array, type 'error': initial <= 300 KB gzip, lazy chunks <= 100 KB
gzip, per-component CSS <= 6 KB. source-map-explorer wired as an Nx
analyze target for diagnosis on budget breaches.
Back-end SLOs documented per endpoint family (p95/p99) and observed
via the OpenTelemetry spans already shipped by ADR-0012 - advisory in
CI (load profile unrepresentative), alerting in production. Quarterly
review tightens budgets when achievable.
Scheduled weekly Lighthouse run on the prod env via the existing
security-scheduled.yml workflow extends coverage beyond PR-time.
Explicit a11y/perf trade-off rule: when they conflict, a11y wins (per
APF's mission, ADR-0016). The perf budget is then re-evaluated at the
next quarterly review.
No browser-side RUM SDK in v1 - the OTel browser tracing from ADR-0012
plus scheduled prod Lighthouse runs cover the gap. RUM revisited in
v2 if a real incident escapes the existing signal.
decisions/README.md index updated. CLAUDE.md gains an explicit
'Performance budgets' line pointing to ADR-0017.
Pin the a11y baseline given the host organisation context (APF France
Handicap, where accessibility is the core mission, not a compliance
checkbox):
- Conformance: WCAG 2.2 AA universal + AAA on criteria with high
impact for the user base (1.4.6 Enhanced Contrast 7:1, 2.2.3 No
Timing, 2.3.3 Animation from Interactions, 3.1.5 Reading Level,
1.4.8 Visual Presentation, 2.4.9 Link Purpose, 3.3.5 Help). RGAA 4.1
alignment for French audit context.
- User-preferences panel as a first-class feature: contrast (3 tiers),
text size (up to 200%), motion, text spacing, cognitive
simplification, reading focus. Persisted in session (ADR-0010).
- UI stack: Angular CDK + spartan-ng + TailwindCSS (not Angular
Material; not React libs). Components copy-pasted into
libs/shared/ui under our control. Design tokens with
contrast-verified colour pairs in libs/shared/tokens.
- Tooling and CI gates: @angular-eslint/template/* a11y rules
(blocking), @axe-core/playwright e2e blocking on critical/serious
violations, design-token contrast verifier (blocking), touch-target
size check (blocking on 44x44 min, default 48x48). Wires into the
a11y gate slot from ADR-0015.
- Manual testing: keyboard and screen reader required on every UI PR
via PR-template checklist; APF user-panel session before every major
release covering visual / motor / cognitive / hearing categories.
- Documentation: public accessibility statement at /accessibility (EN)
and /accessibilite (FR) - EAA legal requirement, generated from
source-of-truth in the repo. Internal patterns library in
docs/accessibility/.
decisions/README.md index updated. CLAUDE.md gains an explicit
'Accessibility' line pointing to ADR-0016 and the CI/CD line is
adjusted to mark the a11y gate as locked-in (no longer 'future').
The host organisation - APF France Handicap - was confirmed on
2026-04-30. Update all in-repo references to use apf_portal
(snake_case in prose) and apf-portal (kebab-case workspace name and
repo URL). Touched: CLAUDE.md, ADRs 0001/0002/0003/0015, and the Nx
bootstrap setup guide.
The historical name is preserved as a single sentence in ADR-0003 as
a self-validating example of the function-prefixed naming convention
designed exactly for this scenario - the apps (portal-shell,
portal-bff) and the lib conventions (feature-<name>, shared-<scope>)
were unaffected by the rename, which was the explicit point of
ADR-0003.
Memory state aligned out-of-band: project_adastra.md retired,
project_apf_portal.md created with the expanded APF context (host
org, health + financial data scope, ASVS L3 pending RSSI input, UI
stack decision spartan-ng + CDK + Tailwind, expanded phase-3 status).
Pending follow-ups (user-side, not in this commit):
- rename the Gitea repo julien/adastra_portal -> julien/apf_portal
- git remote set-url origin gitea@git.unespace.com:julien/apf_portal.git
- optionally rename the local working directory ~/Works/adastra_portal/
-> ~/Works/apf_portal/
Pin the CI/CD shape with an explicit two-level structure, anticipating
the GitLab migration on the 6-18-month horizon:
Level 1 - vendor-neutral, survives the migration:
- Trunk-based with short-lived feature branches; squash-merge only.
- Branch protection on main: no direct push, no force push, linear
history, required green CI, required reviewers = 0 in v1 (raised to
>=1 when a second contributor joins), branch deletion after merge.
- Required CI gates (all blocking): format, lint, type-check, test,
build (nx affected), audit (pnpm + Trivy), secret-scan (gitleaks),
commit-lint (Conventional Commits on the PR commit range). Future
a11y and perf gates land with their respective ADRs.
- Conventional Commits validated locally (hook from ADR-0007) and in
CI as defense in depth.
- Signed commits recommended but not required in v1; revisited at the
GitLab migration.
- Thin YAML: all orchestration logic lives in package.json scripts
(ci:check, ci:scan, ci:commits) and Nx targets. Workflow files only
do checkout, setup, cache, and call one script per job. The migration
rewrites the YAML wrappers, never the gates.
- Secrets convention SCOPE_PURPOSE; gitleaks enforces no-secrets-in-code.
- Container images / deploy explicitly out of scope (deferred to the
on-prem infrastructure ADR).
Level 2 - Gitea Actions specific, will be superseded by a GitLab
migration ADR:
- Engine: Gitea Actions (built-in, GitHub Actions-compatible syntax,
partial portability hedge if the org pivots to GitHub).
- Runners: >=3 self-hosted act_runner instances on-prem, Debian image
pinned by SHA, weekly rebuild via security-scheduled.yml.
- Three workflow files: ci.yml (PR + push to main), release.yml
(stub for tag, populated by the deploy ADR), security-scheduled.yml
(weekly Trivy + gitleaks full-tree scan + Renovate trigger).
Migration weight estimated at 3-5 days dev/ops when GitLab arrives:
the YAML is rewritten, the gates and scripts are unchanged. A future
ADR will explicitly supersede only the level-2 sections.
decisions/README.md index updated. CLAUDE.md gains an explicit 'CI/CD'
line pointing to ADR-0015 and noting the future GitLab supersession.
Pin the framework for calls from the BFF to integrated downstream APIs.
The concrete list of downstream services is not yet known, but the
framework must exist so that the day a developer adds an integration the
answer is 'use the standard client', not 'invent something'.
A DownstreamApisModule exposes a DownstreamApiClientFactory that produces
typed clients from per-service DownstreamApiConfig blocks. Each config
declares the auth strategy, base URL, timeout, retry, circuit breaker,
bulkhead, and audienceConstraint.
Default auth strategy for Entra-protected downstreams is On-Behalf-Of
(MSAL Node acquireTokenOnBehalfOf). Downstream-scoped tokens are cached
in Redis under obo:{user_id_hash}:{resource}, encrypted with AES-256-GCM
using a dedicated key (OBO_CACHE_ENCRYPTION_KEY) distinct from the
session-encryption key so a cache compromise doesn't cascade into a
session compromise.
Fallback strategy for non-Entra downstreams is service credential +
signed user-assertion header (X-User-Assertion JWT signed by the BFF's
private key, verified by downstreams against the BFF JWKS at
/.well-known/jwks.json). Token relay is rejected as a default;
per-user credential mapping is rejected outright.
Resilience composes via cockatiel: timeout outermost, then retry (only
on idempotent verbs and retriable error classes), circuit breaker per
service, bulkhead per service. Each call opens a downstream.<service>
OpenTelemetry span; auth failures emit audit events. Downstream errors
are translated at the client boundary - never bubbled with raw payload.
Audience pre-check is enforced at the call site (not at controller
entry) - even a missing authorization guard upstream cannot bypass the
audience constraint.
The framework is forward-looking; concrete integrations land per-service
in code config (no per-integration ADR unless the integration deviates
non-trivially from the defaults). Strategy code is exercised by
mock-driven tests until the first real integration ships.
decisions/README.md index updated. CLAUDE.md gains an explicit
'Downstream API access' line pointing to ADR-0014.
Pin the audit-trail architecture: a dedicated 'audit' schema in the same
Postgres instance as business data, with three Postgres roles enforcing
append-only at the database layer - audit_writer (INSERT only),
audit_reader (SELECT only), audit_archiver (DELETE only on rows past the
retention threshold). No role anywhere holds UPDATE or TRUNCATE; the BFF
verifies this at startup with a deliberate failing UPDATE probe.
The audit stream is decoupled from the application logs (different sink,
different access controls, different retention) but cross-referenced via
trace_id (ADR-0012) and actor_id_hash, which uses the same salt as the
app logs so an investigator joins the two streams without re-hashing.
Events captured in v1 cover the auth and session lifecycle: sign_in
(success/failure), sign_out, session.expired, session.revoked,
token.validation.failed, mfa.assertion.failed, authz.deny. Hooks for
admin actions and sensitive data access are designed-in but inert until
v1+ features call them - kept alive by tests so they don't drift.
Failure semantics are blocking - if the audit INSERT fails, the
in-flight operation fails with 503. Trade-off acknowledged: the audit DB
is part of the trust path. Mitigation is HA Postgres in prod, deferred
to the infrastructure ADR.
Retention defaults to 365 days, env-overridable, enforced by a daily
purge running under audit_archiver. The retention default is engineering
prudence, not legal advice - the org-side legal review of the actual
applicable retention regime is explicitly owed and noted in the ADR.
Cryptographic chaining and WORM storage are deferred unless a compliance
regime demands them.
decisions/README.md index updated. CLAUDE.md gains an explicit
'Audit trail' line pointing to ADR-0013.
Pin the observability foundation. Two signals are in scope: structured
logs and distributed traces.
Logs: pino + nestjs-pino, JSON line-delimited on stdout, with a fixed
envelope (level, time, service, version, env, trace_id, span_id,
session_id, user_id_hash, audience, msg, ...). Pino redact strips a
reviewable allowlist of sensitive paths (Authorization/Cookie headers,
*.password, *.access_token, *.refresh_token, ...). user_id_hash uses a
per-environment salt (LOG_USER_ID_SALT) so the same userId is not
correlatable across environments.
Tracing: OpenTelemetry SDK for Node + auto-instrumentations (HTTP,
Express, NestJS, pg, ioredis, Prisma). The SPA also runs OTel-Web with
an HTTP interceptor propagating traceparent on outbound calls; the same
trace_id is the correlation identifier from the user click to the DB
query. No separate X-Correlation-ID.
Request-scoped context lives in nestjs-cls; the Pino formatter and the
future audit-log writer pull from CLS - no per-call threading.
Sampling is 100% at the application; tail sampling is performed at the
local OpenTelemetry Collector (deferred to the phase-3 infrastructure
ADR, where the on-prem backend - Grafana stack, ELK, or other - will be
chosen). Output: stdout for logs, OTLP/HTTP for traces, both consumed
by the local collector. The application stays vendor-neutral.
Audit logs are explicitly out of scope of this ADR - they share the
trace_id but use a separate writer and a separate sink (next ADR).
decisions/README.md index updated. CLAUDE.md gains an explicit
'Observability' summary pointing to ADR-0012.
Pin the MFA policy: enforcement lives in Entra ID Conditional Access at
the tenant level (org IT responsibility) - the application code does not
implement MFA mechanics. The BFF performs a defense-in-depth sanity-check
on the id_token amr claim at session creation; sessions without evidence
of multi-factor authentication are rejected. The accepted amr values are
maintained in a small in-source list and reviewed on cadence.
Step-up MFA is designed-in for v1 but dormant: a @RequireMfa() decorator
and a RequireMfaGuard ship in the codebase, the session payload carries
mfaVerifiedAt, and the SPA HTTP interceptor handles the 401 + claims
challenge round trip. No v1 route is annotated, since v1 has no admin UI
or other operations sensitive enough to require fresh MFA. The hooks are
kept alive by automated tests so they don't drift.
Authentication Context Classes (ACR-based step-up) are not used in v1;
they remain a future option if specific operations later demand them.
Service-account / app-only flows are out of scope.
decisions/README.md index updated. CLAUDE.md gains an explicit 'MFA' line
pointing to ADR-0011.
Pin the session-state architecture: the browser carries only an opaque
crypto-random session id in __Host-portal_session, signed with
SESSION_SECRET. The payload (userId, audience, curated claims, encrypted
tokens, timestamps) lives in self-hosted Redis, accessed via the standard
express-session + connect-redis pair under the NestJS Express adapter.
The id_token / access_token / refresh_token tuple is encrypted with
AES-256-GCM before being stored - per-record IV, GCM auth tag - using
SESSION_ENCRYPTION_KEY. A Redis snapshot or memory dump alone is not
enough to forge a working session; the encryption key must also be
compromised. Tampered or wrong-key records are rejected and audited.
TTL policy: idle 30 min sliding (TTL refreshed on each request) +
absolute 12 h (checked in a global interceptor, triggers DEL on expiry).
Topology: Redis Sentinel (3+ nodes) in prod with TLS and ACL; single node
in dev. Operational specifics deferred to a phase-3 infrastructure ADR.
Revocation is immediate (DEL session:{id}). A secondary index
user_sessions:{userId} supports per-user listing and force-logout. No
PostgreSQL mirror; historical trace lives in the future audit-log ADR.
decisions/README.md index updated. CLAUDE.md gains an explicit 'Sessions'
line pointing to ADR-0010.
Pin the BFF authentication mechanics: OAuth 2.0 Authorization Code Flow
with PKCE, executed server-side via @azure/msal-node's
ConfidentialClientApplication. Tokens are held in the BFF session and
never reach the browser; the SPA only ever sees the opaque
__Host-portal_session cookie.
Token validation enforces the tenant allowlist from ADR-0008 (iss check)
and maps the audience claim to our Audience enum at the validation step.
Refresh-token rotation is enabled via MSAL acquireTokenSilent. Cookies
use the __Host- prefix (forces Secure/Path=/, no Domain) with
HttpOnly/SameSite=Lax. CSRF uses the double-submit pattern with a
matching X-CSRF-Token header on every state-changing request, enforced
by a NestJS interceptor and injected client-side by an Angular HTTP
interceptor. Logout is RP-initiated against Entra's end_session_endpoint.
Routes are pinned: GET /auth/login, GET /auth/callback, POST
/auth/logout, GET /auth/me. AuthGuard is registered globally - public
routes must be explicitly opted in.
Local dev runs over HTTPS via mkcert to keep cookie behaviour identical
to prod. All Entra-specific values come from environment variables; the
BFF refuses to start without them.
decisions/README.md index updated. CLAUDE.md gains an explicit
'Authentication flow' line pointing to ADR-0009.
Capture the v1 identity model: Microsoft Entra ID, multi-tenant app with
B2B guest invitation for partner-org employees, workforce-only
authentication in v1. Code and data are architected for dual audience
from day one (Audience enum, audience claim in sessions, audience column
+ RLS policies on shared tables, claims-based authz) so that adding Entra
External ID for customers later is a switch-flip rather than a refactor.
The dev environment uses a Microsoft 365 Developer Program tenant (free,
renewable) to unblock work while the prod tenant is being provisioned by
the org IT contact. Production requires Entra ID P1 licensing - flagged
here so it can be planned, not surprised.
decisions/README.md index updated. CLAUDE.md 'Identity' line now points
to ADR-0008.
- decisions/0007-pre-commit-hooks-and-conventional-commits.md formalizes
Husky + lint-staged + commitlint with Conventional Commits as the local
quality-gate baseline.
- decisions/README.md index updated.
- docs/setup/03 section 8 rewritten to reference the ADR and document the
full hook setup (pre-commit, commit-msg, commitlint config).
- docs/setup/03 future-work table 'ADR(s)' column removed; future ADR
numbers are now assigned at the moment each ADR is written, not
pre-reserved.
- CLAUDE.md aligned: pre-allocated phase-2 ADR numbers replaced by phase
references; a pointer to ADR-0007 added under 'Local quality gates'.
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.
Julien Gautier