Technical Documentation
This section covers the engineering of Registry: the two-service architecture, the reactive backend, the Angular frontend, the data model and API contracts, the security model, and the Architecture Decision Records that justify each choice. It assumes the Functional Documentation — especially the Roles & Permissions baseline — is understood.
System at a glance
Registry is delivered as two independently versioned services plus two supporting infrastructure components:
The browser loads the SPA from nginx, which calls the backend over REST, authenticating via HttpOnly cookies rather than a token held in JavaScript. Authentication is delegated to an external OIDC provider; the backend both validates JWTs (as a resource server) and brokers the code/refresh exchanges (as a confidential client). All state lives in a single PostgreSQL database. See Security for the cookie/CSRF mechanics and the separate, unauthenticated management port that carries health/metrics/docs.
Documentation map
| Page | Purpose |
|---|---|
| Getting Started | Run the whole stack locally: prerequisites, dependencies, and configuration |
| Architecture | The hexagonal backend, the Angular frontend, and how a request flows end to end |
| Security | Authentication flow, JWT-to-user mapping, and how the project-scoped RBAC is enforced |
| Data Model | The PostgreSQL schema, entity relationships, auditing, and trigram search |
| API Reference | Every /api/v1 endpoint, grouped by domain, with its required permission |
| ADR index | All Architecture Decision Records, in causal order |
Stack summary
Versions are given to the major only; the source repositories hold the exact pins.
| Layer | Backend | Frontend |
|---|---|---|
| Language | Kotlin 2 (JVM toolchain 25) | TypeScript 6 |
| Framework | Spring Boot 4 · WebFlux (reactive) | Angular 22 (standalone components) |
| Architecture | Hexagonal (ports & adapters), ArchUnit-enforced | Domain-driven folders, per-route lazy state |
| State / data | R2DBC (reactive) + Flyway migrations | NGXS (selectSignal) behind per-domain facades |
| UI | — | PrimeNG + @primeuix/themes + Bootstrap grid |
| Auth | OAuth2 resource server + confidential client (OIDC), HttpOnly cookies, stateless HMAC CSRF | withCredentials HTTP interceptor relaying the CSRF header, route guards |
| API docs | springdoc OpenAPI (feature-flagged) | — |
| i18n | Spring MessageSource (en, fr) | @ngx-translate (en, fr) |
| Observability | Actuator + Micrometer/Prometheus | — |
| Build | Gradle (Kotlin DSL) | Angular CLI + pnpm |
| Runtime image | Distroless Java 25, non-root, JVM jar | Unprivileged nginx serving the static bundle |
| Persistence | PostgreSQL (pg_trgm trigram search) | — |
| Release | semantic-release → GHCR (retain 5) | semantic-release → GHCR (retain 5) |