Frontend Stack

Frontend Stack

Decisions: [[adr-002-b-frontend-dev-stack]], [[adr-003-b-frontend-prod-stack]].

Dependencies (frontend/package.json)

Package	Version	Role
Bun	>=1.1 (pinned 1.3.5)	Package manager + script runner (replaces npm)
Angular	^21.2.4	Framework — standalone, signals, @angular/build
TypeScript	~5.9.2	Language
PrimeNG	^21.1.3	UI components (design system SSOT)
@primeuix/themes	^2.0.3	Token system for PrimeNG v21
PrimeIcons	^7.0.0	Icon library
Tailwind CSS	^4.2.1	Utility layer (not the design system — PrimeNG is)
tailwindcss-primeui	^0.6.1	Bridge tokens PrimeNG ↔ Tailwind
RxJS	^7.8.0	HTTP interop only — not for state
Vitest	^4.0.8	Test runner

Lockfile: bun.lock (text format). Do not commit node_modules/.

Key Rules

• Never use Tailwind colors directly in templates — use PrimeNG tokens.
• State via signal() / computed() / httpResource(). No .subscribe() for state.
• All components: ChangeDetectionStrategy.OnPush, standalone, inject() over constructor injection.
• @if / @for control flow — not *ngIf / *ngFor.

Common Commands

cd frontend
bun install      # install / update bun.lock
bun start        # dev server :4200 (proxies /api/* → :8000)
bun test         # vitest
bun run build    # production build → dist/frontend/browser

Data Fetching

httpResource() for all data — no raw HttpClient.get() for state. Cross-component invalidation via DataVersionService (signal-based bus). See [[adr-023-frontend-data-invalidation]].

Core Structure

frontend/src/app/
├── core/
│   ├── services/auth.service.ts       # Auth state (signal), login/logout/checkAuth
│   ├── services/data-version.service.ts  # Invalidation bus (DataVersionService)
│   ├── interceptors/auth.interceptor.ts  # withCredentials + X-CSRFToken on mutations
│   ├── interceptors/error.interceptor.ts # 401 → refresh → retry / logout
│   ├── guards/auth.guard.ts           # checkAuth() server round-trip on every activation
│   └── guards/no-auth.guard.ts        # Signal check — redirect to / if authenticated
├── shared/
│   ├── components/                    # kdx-* reusable presentational components
│   └── mocks/                         # Mock data SSOT (showcase + seed)
├── features/                          # Feature pages (router-instantiated)
└── showcase/                          # Design system showcase (/showcase routes)

Design system: [[design-system|stack/design-system]]. Auth wiring: [[auth|stack/auth]].