Contents
PR Summary
What problems was I solving
The page-gateway-service was monolithic with business logic, HTTP handling, and external service dependencies intermixed throughout a single file. This made testing difficult, horizontal changes hard, and maintenance error-prone.
What user-facing changes did I ship
None. This refactoring maintains all existing HTTP API contracts and user-visible behavior. Endpoints behave identically; long-request latency is unchanged.
How I implemented it
Reorganized page-gateway-service into a functional-hexagonal architecture with six Nx modules:
- page-gateway-service-core (port: critical) - 81 files of pure functional domain logic (analytics, routing, session decisions) moved from impl layer
- page-gateway-service-ports (port: high) - 28 files of public interface definitions for hexagonal boundaries (analytics, consent, form, rendering ports)
- page-gateway-service-adapters (port: high) - 51 files binding external services (page-data-plane, assets-service, form-service) to ports using explicit parameter mapping instead of unsafe casts
- page-gateway-service-app (port: high) - 65 use case functions orchestrating port composition and core utilities
- page-ui-state-stream (port: critical) - Upgraded from prototype to production with 23 files for real-time SSE page state updates using Redis pub/sub, decorator pattern, and state miss retry logic
- page-gateway-service-impl (port: critical) - 30 files for HTTP server, middleware, routing, and dependency injection. Extracted page-render-route (402 lines) from monolithic page-gateway.ts
All 151 unit tests pass. Core utilities are pure (no side effects), enabling isolated testing. Ports define clear boundaries; adhered to repository's @architect/ namespace conventions.
Description for the changelog
Refactored page-gateway-service into functional-hexagonal architecture with six Nx modules and clear layer separation. Moved all pure domain logic (analytics routing, session decisions, state snapshot building) into new page-gateway-service-core library with 48 unit tests. Extracted 21 public port interfaces and 51 external service adapters to separate worrying. Implemented production-grade SSE page state streaming in page-ui-state-stream with Redis pub/sub, decorator pattern, and state miss retry logic. All HTTP endpoints retain identical behavior; no breaking changes to APIs or telemetry.