Julien Gautier
49712d0bbf
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.
5.5 KiB
5.5 KiB
Architectural Decision Records
This project records architecturally-significant decisions as ADRs in the MADR 4.0.0 format. References: adr.github.io.
Why ADRs
ADRs capture the why behind a decision — context, drivers, options considered, trade-offs accepted — at the moment the decision is made. They make architecture reviewable, onboarding faster, and prevent the same debate from being re-litigated later.
Conventions
- Format: MADR 4.0.0. Start from template.md.
- Filename:
NNNN-kebab-case-title.md, e.g.0007-adopt-tailwind-for-design-tokens.md. - Numbering: globally sequential 4-digit prefix. Numbers never reset, never get reused — even when an ADR is superseded or deprecated.
- Layout: flat folder. ADRs are not nested into category subfolders; topical organization happens via tags.
- Tags: every ADR carries a
tags:array in the MADR frontmatter, drawn from the tag vocabulary below. An ADR may carry several tags. Propose new tags (or renames) in the same PR that needs them; never invent ad-hoc tags inline. - Status lifecycle:
proposed→accepted→ optionallydeprecatedorsuperseded by [ADR-NNNN](NNNN-other.md). Update the YAML frontmatter; never delete an ADR. - Index maintenance: every ADR addition or status change must update the Index below in the same commit.
When to write an ADR
Write one whenever a development decision is non-trivial: tool or library choice, framework pattern, security control, perf budget, a11y target, naming convention, deprecation, breaking change, or any choice that future contributors would benefit from understanding the why of.
Tag vocabulary
The vocabulary below is the source of truth. It is intentionally coarse — propose extensions only when an existing tag genuinely doesn't fit, and avoid overly narrow tags.
| Tag | Scope |
|---|---|
frontend |
UI, Angular, components, design system, client-side state |
backend |
API, BFF, server-side services |
security |
AuthN, AuthZ, sessions, CSP, dependency scanning, secret management |
performance |
Perf budgets, caching, bundle size, Lighthouse |
accessibility |
WCAG, a11y testing, keyboard, ARIA, contrast |
infrastructure |
CI/CD, hosting, deployment, runtime |
observability |
Logs, metrics, traces, correlation IDs, monitoring |
data |
Persistence, schemas, migrations, data flow |
process |
Team conventions, workflows, repo policy |
Status: starter vocabulary, to be refined as ADRs accumulate. Update this table whenever a tag is added, renamed, or retired.
Index
ADRs are listed in numerical order. To slice by topic, filter on the Tags column.
| # | Title | Status | Tags | Date |
|---|---|---|---|---|
| 0001 | Use ADRs to record architectural decisions | accepted | process |
2026-04-29 |
| 0002 | Adopt Nx monorepo with the apps preset |
accepted | infrastructure, frontend, backend |
2026-04-29 |
| 0003 | Workspace and app naming convention | accepted | process |
2026-04-29 |
| 0004 | Frontend stack — Angular (latest LTS), standalone, zoneless, Signals, CSR-only, Vitest | accepted | frontend |
2026-04-29 |
| 0005 | Backend stack — NestJS over Express, Fastify, Hono | accepted | backend |
2026-04-29 |
| 0006 | Persistence — PostgreSQL with Prisma | accepted | data, backend |
2026-04-29 |
| 0007 | Pre-commit hooks and Conventional Commits | accepted | process |
2026-04-29 |
| 0008 | Identity model — multi-tenant Entra ID for workforce, dual-audience design for future External ID | accepted | security, data |
2026-04-29 |
| 0009 | Authentication flow — OIDC Authorization Code + PKCE via MSAL Node, BFF session pattern | accepted | security, backend |
2026-04-29 |
| 0010 | Session management — opaque session IDs in cookies, payload in self-hosted Redis with AES-GCM at rest | accepted | security, backend, infrastructure |
2026-04-29 |
| 0011 | MFA enforcement — Entra ID Conditional Access baseline, BFF claim sanity-check, step-up hooks designed-in | accepted | security |
2026-04-29 |
| 0012 | Observability — Pino structured logs + OpenTelemetry tracing, W3C Trace Context propagation, stdout + collector | accepted | observability, backend, frontend |
2026-04-29 |
| 0013 | Audit trail — separated append-only Postgres schema, decoupled from app logs | accepted | security, observability, data |
2026-04-29 |
| 0014 | Downstream API access — On-Behalf-Of pattern, unified DownstreamApiClient, audience-aware authorization |
accepted | security, backend |
2026-04-29 |
| 0015 | CI/CD pipeline — Gitea Actions, trunk-based + squash-merge, thin YAML over portable scripts | accepted | infrastructure, process |
2026-04-30 |