# System Patterns — PEDW FrontEnd

## Architecture style

- Next.js 14 (Pages Router) monolith with route handlers in `pages/` and API handlers in `pages/api/**`.
- Mix of SSR/client rendering with Redux hydration (`HYDRATE`) and client persistence.
- Integration-heavy backend-for-frontend pattern: many internal API routes proxy to external services.

## Module boundaries

- `pages/`: route composition and API endpoints.
- `components/`: UI feature modules (case, search, dns, myportal, account, admin, mapping).
- `actions/`: shared API client helpers, token/header/hash helpers, and side-effect utilities.
- `lib/`: domain/form helper logic.
- `store/`: Redux reducers, wrapper, and persistence config.
- `prisma/`: auth/session persistence schema.

## API patterns

- Endpoint naming commonly uses `*_api.js` under `pages/api/endpoint/`, `pages/api/file/`, `pages/api/admin/`.
- Recurring endpoint implementation pattern:
    1. build query path,
    2. create HMAC hash (`hash` query param),
    3. fetch OAuth token,
    4. forward to relay URL,
    5. return normalized JSON / error.
- Swagger annotations are embedded in many API files for route documentation.

## Data and integration boundaries

- **Auth/session persistence**: Prisma models (`User`, `Account`, `Session`, `VerificationToken`) on SQL Server.
- **Case/business data**: fetched via API proxy routes to Dynamics/relay endpoints (not via Prisma business models).
- **File/document handling**: Azure blob-backed APIs under `pages/api/file/**`, including hash checks on sensitive routes.

## Internal conventions and recurring implementation choices

- Bilingual route mapping through `next.config.js` rewrites plus `i18n.js` page namespace mapping.
- Security headers are split across `middleware.js` (CSP + runtime security headers) and `next.config.js` static headers.
- Breadcrumb/back-link logic is centralized in `components/breadcrumbs.js` and depends on route/query state.
- Case summary behavior is appeal-type driven with branching UI/eligibility logic in `components/case/summary.js`.
- Proxy and direct variants coexist for some APIs (`*proxy_api.js`), so behavior parity must be checked when changing one side.