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.
This commit is contained in:
Julien Gautier
@@ -0,0 +1,95 @@
|
||||
---
|
||||
status: accepted
|
||||
date: 2026-04-29
|
||||
decision-makers: R&D Lead
|
||||
tags: [frontend]
|
||||
---
|
||||
|
||||
# Frontend stack — Angular (latest LTS), standalone, zoneless, Signals, CSR-only, Vitest
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
The portal's frontend (`portal-shell`) is a single-page application that aggregates access to existing applications and progressively integrates re-developed features. It sits fully behind authentication: no public content. We need to fix the framework, the rendering mode, the change-detection model, and the test runner now, so subsequent ADRs (auth flow, observability, accessibility, performance budgets) can build on a stable foundation.
|
||||
|
||||
What frontend stack maximizes alignment with our backend (NestJS), gives us first-class accessibility and performance hooks, and is enterprise-stable for a long-lived project?
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
* Architectural alignment with NestJS (DI, decorators, modules, RxJS) — minimizes cognitive distance for the team.
|
||||
* Performance and accessibility as first-class concerns from day one.
|
||||
* Long-term enterprise stability (no pre-1.0, no exotic stack).
|
||||
* End-to-end type safety.
|
||||
* No public surface — all content gated by authentication, which removes the usual SSR drivers (SEO, anonymous LCP).
|
||||
|
||||
## Considered Options
|
||||
|
||||
* **Angular (latest LTS) — standalone, zoneless, Signals, CSR, Vitest.** (Chosen.)
|
||||
* Angular with SSR (`@angular/ssr`).
|
||||
* React + Next.js (or Vite + React Router).
|
||||
* Vue + Nuxt.
|
||||
* Svelte + SvelteKit.
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
Chosen option: **Angular at the latest LTS major**, with the following modern defaults:
|
||||
|
||||
* **Standalone APIs** — no `NgModule`s. Configuration is composed via providers; routing is functional.
|
||||
* **Zoneless change detection** — no `Zone.js`. Change detection is driven by Signals and explicit `markForCheck` where needed.
|
||||
* **Signals** — primary reactive primitive for component state. RxJS retained for async streams (HTTP, events).
|
||||
* **Vitest** — unit and component test runner (Karma is deprecated upstream).
|
||||
* **CSR only — no SSR** for v1. Reconsider only if a measured performance metric requires it.
|
||||
* **SCSS** for styles. Design-token strategy to be defined in a future ADR.
|
||||
* **Strict TypeScript** across the workspace (`strict: true`, `noUncheckedIndexedAccess: true`).
|
||||
|
||||
### Consequences
|
||||
|
||||
* Good, because the team works with a single mental model across front and back (DI, decorators, RxJS).
|
||||
* Good, because zoneless + Signals removes Zone.js overhead and gives finer-grained, more predictable reactivity.
|
||||
* Good, because Vitest is significantly faster than Karma and shares the Vite toolchain Nx already uses.
|
||||
* Good, because CSR keeps the BFF free of SSR concerns (no auth-aware rendering, no double-fetch, no hydration debugging) — simpler operational surface.
|
||||
* Bad, because Angular's release cadence is brisk; the project commits to staying on LTS rather than skipping versions.
|
||||
* Bad, because zoneless and Signals are recent — though stable, the broader Angular ecosystem still includes Zone-dependent libraries that must be vetted before adoption.
|
||||
* Bad, because CSR yields a minimal initial HTML payload; this must be paired with strong performance budgets (covered by ADR-0015, future).
|
||||
|
||||
### Confirmation
|
||||
|
||||
* `package.json` pins Angular to the current LTS major.
|
||||
* `app.config.ts` registers `provideZonelessChangeDetection()` (or its current stable equivalent) and standalone routing.
|
||||
* `tsconfig.base.json` sets `strict: true` and `noUncheckedIndexedAccess: true`.
|
||||
* CI runs `pnpm nx test portal-shell` (Vitest).
|
||||
* No `import 'zone.js'` anywhere in the codebase.
|
||||
* `@angular/ssr` is not installed.
|
||||
|
||||
## Pros and Cons of the Options
|
||||
|
||||
### Angular CSR (chosen)
|
||||
|
||||
* Good, because alignment with NestJS minimizes context-switching for the team.
|
||||
* Good, because mature, enterprise-supported (Google + community).
|
||||
* Good, because Signals + zoneless make Angular's reactivity competitive with React/Vue.
|
||||
* Bad, because verbosity is higher than minimalist frameworks.
|
||||
|
||||
### Angular SSR
|
||||
|
||||
* Good, because better TTFB and accessibility on first paint for unauthenticated content.
|
||||
* Bad, because we have no unauthenticated content — the gain is essentially zero.
|
||||
* Bad, because SSR-with-auth introduces non-trivial complexity (cookie-aware fetch, hydration with secured data).
|
||||
|
||||
### React + Next.js
|
||||
|
||||
* Good, because large ecosystem, fast iteration.
|
||||
* Bad, because no architectural alignment with NestJS — different DI/state paradigms.
|
||||
* Bad, because Next.js's defaults push toward server components and edge rendering, which conflict with our on-prem, all-authenticated profile.
|
||||
|
||||
### Vue + Nuxt / Svelte + SvelteKit
|
||||
|
||||
* Good, because lighter syntax, strong DX.
|
||||
* Bad, because no DI alignment with NestJS.
|
||||
* Bad, because smaller enterprise-grade community than Angular or React.
|
||||
|
||||
## More Information
|
||||
|
||||
* Angular zoneless change detection: https://angular.dev/guide/experimental/zoneless
|
||||
* Angular Signals: https://angular.dev/guide/signals
|
||||
* Vitest with Nx: https://nx.dev/nx-api/vite
|
||||
* Related ADRs: [ADR-0005](0005-backend-stack-nestjs.md), ADR-0008 (auth flow, future), ADR-0014 (accessibility, future), ADR-0015 (performance budgets, future).
|
||||
Reference in New Issue
Block a user