133 lines
7.6 KiB
Markdown
133 lines
7.6 KiB
Markdown
# Architecture Reference
|
|
|
|
## Runtime Topology
|
|
|
|
1. Next.js runtime serves UI routes and API routes (legacy custom server files are present but not active).
|
|
2. Next.js `pages/` router handles UI routes and API routes under `pages/api/**`.
|
|
3. Middleware (`middleware.js`) injects CSP nonce and security headers on requests/responses.
|
|
4. State management initialized in `pages/_app.js` with Redux wrapper and persistence.
|
|
5. Authentication handled by `next-auth` in `pages/api/auth/[...nextauth].js` with Prisma adapter.
|
|
|
|
## Key Architectural Modules
|
|
|
|
- **Presentation layer:** `pages/`, `components/`, `styles/`
|
|
- **State layer:** `store/store.js` + slice reducers
|
|
- **Domain/service helpers:** `actions/`, `lib/`
|
|
- **Auth persistence:** Prisma client + `prisma/schema.prisma` (next-auth tables in SQL Server)
|
|
- **Portal business data access:** API routes query Dynamics 365 CRM through Azure Service Bus Relay using REST + OData patterns
|
|
- **Relay integrity check:** forwarded CRM-bound API requests include a path-based hash, validated by relay with shared key before forwarding
|
|
- **Infrastructure glue:** `middleware.js`, `next.config.js`, `i18n.js` (plus legacy server files not in active runtime)
|
|
|
|
## High-Risk/Guarded Paths
|
|
|
|
1. `pages/api/auth/[...nextauth].js`
|
|
- Email sign-in flow, callback/redirect logic, session setup.
|
|
2. `middleware.js` and security headers in `next.config.js`
|
|
- CSP and browser hardening policies.
|
|
3. `store/store.js`
|
|
- HYDRATE, persistence, logout storage clearing.
|
|
4. `prisma/schema.prisma`
|
|
- Source of truth for auth/account persistence tables.
|
|
5. File and notification APIs in `pages/api/file/**`, `pages/api/email/**`
|
|
- Upload/document/email side effects and sensitive data handling.
|
|
|
|
## i18n and Routing Model
|
|
|
|
- Locales: `en`, `cy` (configured in `i18n.js`).
|
|
- Locale detection disabled; domain and route rewrites drive behavior.
|
|
- Welsh route aliases maintained in `next.config.js` rewrites.
|
|
- Any new user-facing route should consider:
|
|
- translation resources in `locales/en` and `locales/cy`
|
|
- rewrite parity where a Welsh alias is expected
|
|
- auth pages and callback URLs for locale correctness
|
|
|
|
## External Integration Touchpoints
|
|
|
|
- Dynamics 365 CRM (portal business data): reached via frontend API routes that send REST/OData queries through Azure Service Bus Relay.
|
|
- Azure Service Bus Relay request integrity: relay endpoint is configured via `API_ROOT`; request path (excluding domain) is hashed client-side and validated relay-side with shared hash key.
|
|
|
|
- Azure Storage/Queue: `actions/azurestorage.js`, selected API handlers.
|
|
- GOV.UK Notify email: `actions/index.js`, `pages/api/email/**`, next-auth email provider.
|
|
- Application Insights: `components/azureappinsights.js` and related environment configuration.
|
|
- Mapping embeds and map libs: `components/mapping/**`, DNS/search components.
|
|
- PDF generation/rendering: `pages/api/file/generate*.js`, `components/pdftemplates/**`.
|
|
|
|
## Current Endpoint Contract Hardening Status (2026-03)
|
|
|
|
Recent bounded slices in the endpoint contract-consistency stream have standardized selected high-traffic handlers from raw relay error passthrough to structured response contracts (`respondSuccess` / `respondError`) with explicit required-input guards and phase21 contract coverage.
|
|
|
|
Completed clusters include:
|
|
|
|
- Search document retrieval cluster (`getsearchdocumenthistory*`, `getsearchdocumentdetails*`, `getsearchdocumentTypes_api`)
|
|
- My portal retrieval cluster (`getmycases_api`, `getmyrepresentations_api`, `getwatchedcases_api`, `getawaitingsubmission_api`)
|
|
- Basic search family cluster (`getbasicsearchdetails_api`, `getbasicsearchdetailspaged_api`, `getbasicsearchpaged_api`, `getbasicsearch_by_lparref_api`)
|
|
|
|
Guardrail note: success payload contracts are intentionally preserved to avoid frontend regressions, while negative-path behavior is being normalized endpoint-by-endpoint with corresponding phase21 tests.
|
|
|
|
## Legacy / Inactive Components
|
|
|
|
The following files exist in the repository but are not part of the current active runtime model:
|
|
|
|
- `server.js`
|
|
- `server/server.js`
|
|
|
|
Guidance:
|
|
|
|
- Do not treat these files as active runtime architecture unless explicitly reactivated.
|
|
- If reactivation is proposed, document rationale and rollout/rollback in `memory-bank/change-log.md` and `context/runbook.md`.
|
|
|
|
## Current State Assessment and Prioritised Next Steps (2026-03-25)
|
|
|
|
### Assessment summary
|
|
|
|
The platform has moved into a stronger operational and architectural posture through sustained bounded refactor slices and contract hardening.
|
|
|
|
Strengths:
|
|
|
|
1. **Governance maturity is high**
|
|
- Guardrails are explicit for auth/session integrity, CSP/security headers, Prisma source-of-truth, relay hash integrity, and EN/CY parity.
|
|
2. **API reliability posture has improved materially**
|
|
- Endpoint contract hardening and phase21 contract test expansion have reduced inconsistency in negative-path handling.
|
|
3. **Relay operations are significantly more robust**
|
|
- Shared relay forwarding now includes bounded retry/timeout policy, structured redacted lifecycle logging, and documented rollout/rollback controls.
|
|
4. **Façade decomposition is delivering low-risk progress**
|
|
- `actions` layer migration to shared clients (`relayClient`, `endpointClient`) is reducing duplicated request boilerplate and lowering drift risk.
|
|
|
|
Primary residual risks/gaps:
|
|
|
|
1. **Remaining direct-service inconsistency**
|
|
- Some direct services still contain legacy axios/request patterns and bespoke signed-request blocks.
|
|
2. **Coverage concentration**
|
|
- Contract tests are strong in targeted slices, but end-to-end/high-value journey coverage in sensitive flows remains comparatively sparse.
|
|
3. **Logging hygiene variance**
|
|
- Structured redaction exists in relay paths, but broader codebase logging still has uneven consistency.
|
|
4. **i18n parity assurance remains process-heavy**
|
|
- EN/CY parity relies heavily on manual discipline rather than automated parity checks.
|
|
|
|
### Prioritised next steps
|
|
|
|
1. **Complete direct-service consistency sweep (low risk, high maintainability)**
|
|
- Prioritise `actions/services/searchDirectService.js` for `getJson`/`requestJson` adoption in bounded slices.
|
|
- Preserve existing error-return behavior contracts per function.
|
|
2. **Consolidate signed-request patterns (medium risk, high security clarity)**
|
|
- Introduce a focused signed-request helper for hash-based/signed delete/get pathways currently repeated in service modules.
|
|
- Keep existing hash/header semantics unchanged while reducing duplication.
|
|
3. **Add high-value regression automation (high value)**
|
|
- Add focused automated checks for:
|
|
- auth callback/redirect safety
|
|
- one signed-delete negative path
|
|
- one upload/document authorization negative path
|
|
- one EN/CY route parity check
|
|
4. **Perform targeted logging hardening in sensitive paths**
|
|
- Continue replacing direct/verbose logging in `auth`, `file`, `email`, and account-sensitive endpoint paths with redacted structured logging patterns.
|
|
5. **Introduce EN/CY parity CI checks**
|
|
- Add automated checks for route rewrite parity and locale key alignment to reduce drift and manual burden.
|
|
6. **Continue endpoint sprawl reduction**
|
|
- Keep collapsing duplicated proxy/request patterns behind shared helpers in bounded route clusters while preserving public response contracts.
|
|
|
|
### Recommended execution sequence
|
|
|
|
- **Sequence A (immediate):** Step 1 + Step 3 (fastest risk reduction per effort)
|
|
- **Sequence B (next):** Step 2 + Step 4 (security/logging consistency consolidation)
|
|
- **Sequence C (after):** Step 5 + Step 6 (institutionalise parity and reduce long-tail maintenance cost)
|