Next.js 16+ Frontend Integration Guide: Compliance + Project Finance (PF)

This guide explains how to build a robust, user-friendly frontend in Next.js 16+ that leverages the Compliance module as the system of record and integrates deeply with Project Finance (PF). It focuses on architecture, data flows, UX patterns, and operational concerns. No code is included; use this as a blueprint for implementation.

1) Goals and Principles

Reliability-first: enforce compliance at PF mutation points (budgets, invoicing, milestones) and surface clear outcomes (success, approval required, rejected, flagged).
Least surprise: user-defined rules live in a centralized Compliance UI; PF consumes them, emphasizing project-scoped policies.
Observable-by-default: propagate correlation IDs, display status and rule outcomes, and leverage ETag-based caching for list views.
Secure-by-default: apply RBAC on all Compliance actions and PF mutations; prefer header-based auth (X-User-ID, X-User-Roles).

Compliance
- Dashboard: high-level compliance posture, recent events/violations, by entity type (expense, invoice, budget, PF).
- Rules: CRUD for policy rules; filterable by scope (global, user, team, project).
- Templates: standard + custom templates; apply to create rules for a specific scope (esp. project).
- Events & Violations: lists with filtering, pagination, ETag; resolve actions capture resolution notes.
Project Finance
- Project Dashboard: budgets, spend, milestones, invoices, and a compliance status summary for the current project.
- Billing
  - Progress Billing: create invoice by percent with compliance gating (approval required or rejection).
  - Milestones: create/complete milestones; on invoice attempt, show compliance outcome.
- Budgets
  - Allocations: create/update allocations with compliance enforcement and informative warnings.

Navigation: use a persistent project switcher that carries projectId to PF views and to compliance filter context (for project-scoped rules).

3) Authentication & RBAC

Gateway headers: include X-User-ID and X-User-Roles on all requests. Roles map to permissions; Compliance endpoints require compliance:view and compliance:manage as configured; PF routes require project:finance:view|edit.
Guard client routes using server components or middleware that checks user roles in session and fetches minimal RBAC metadata for conditional rendering (e.g., hide “Create Rule” if no manage permission).

4) Data Fetching Strategy (Next.js 16+)

Server Components for SSR data: PF dashboard, Compliance lists (events, violations, rules, templates). Use fetch with If-None-Match and handle 304 to re-use cached data.
Client Components for forms/mutations: create/update rule, template, apply template, resolve event/violation, create invoice/budget allocation/milestone.
SWR/RTK Query (optional) for client-side revalidation after mutations. Respect ETag invalidation by re-fetching the resource on 201/204/409.

5) Endpoint Hardening in the Frontend

Idempotency: for POST/PUT that may be retried (rule/template create, resolve), set an Idempotency-Key header (UUID) and stash it in component state to prevent duplicate submissions.
Rate limiting: gracefully handle 429 with backoff and toast/banner messaging.
ETag: for list endpoints (/compliance/events, /compliance/violations, /compliance/rules, /compliance/templates) store ETag per filter key and set If-None-Match on re-requests.

6) PF + Compliance Flows

Progress Billing (PF → Compliance)
- User enters percent; submit to /api/project-finance/{projectFinanceID}/bill-progress.
- Responses:
  - 201 Created: show success + invoice summary.
  - 409 Approval Required: display approval dialog; present link to AWF status; disable further billing until approval.
  - 400/422: show in-form error; highlight invalid inputs.
  - Compliance events/violations are recorded automatically; optionally show a non-blocking banner if only flagged.
Milestone Invoice (PF → Compliance)
- User selects milestone; click “Create Invoice”.
- Same outcomes as above. Display “awaiting approval” state if required.
Budget Allocation (PF → Compliance)
- User proposes allocation; on submit, handle outcomes:
  - Reject: block with clear rule reference (name/summary) and remediation guidance.
  - Require Approval/Redirect: open AWF request UI and reflect pending state in list.
  - Flag: allow proceed, show informational banner.
Rules & Templates (Compliance UI)
- Rules CRUD: create rules with entity_type (invoice, budget, expense), scope (project with scope_id=projectId for PF), conditions, and actions.
- Templates: list standard, clone/apply to project; guide the user to project scope when applying for PF.
- Use optimistic UI for create/update with idempotency; revalidate lists with ETag.

7) Rule Editor UX

Condition Builder: support simple and composite conditions (AND/OR) with entity fields used by PF operations, e.g., Amount, Total, ProjectID, ReallocationPercentage.
Action Chooser: reject, flag, require_approval (redirect). Provide tooltips and examples for PF scenarios.
Scope Selector: emphasize project scope for PF; auto-fill scope_id from current project context.

8) Approval Workflow (AWF) Integration

When a PF operation returns an approval-required response, open an “Approval Requested” modal with:
- Workflow name and first approver.
- Link to “View Approval” page (AWF instance detail).
- Readiness checks and next steps banner on the PF page.
AWF Status: show approval progress inline in PF tables (e.g., allocation or milestone row shows Pending/Approved/Rejected with timestamp).

9) Observability & Telemetry in the Frontend

Propagate X-Request-ID or add a correlation header per request; log major interactions (rule create, invoice try) to your client log sink.
Use page-level loading and error boundaries; for transient server errors (e.g., 500), offer a retry with exponential backoff.

10) Validation and Sanitization

Validate payloads client-side to mirror server constraints: required fields, numeric ranges, date order. Display inline errors.
Sanitize strings (names, descriptions) to prevent accidental injection into logs/queries. Prefer server-generated IDs and safe enums for types/scopes.

11) Performance Patterns

Chunk data fetching by route segment; cache ETag responses per filter key.
Virtualize long Compliance lists; provide quick filters (entity type, status, severity, project).
Debounce rule/template search inputs; prefetch PF dashboard data on project switch.

12) Configuration & Environments

Base URL: pull from env at build time; support per-environment configs.
Feature Flags: gate Compliance UI elements with a COMPLIANCE_ENABLED flag; present a read-only banner if disabled.

13) Error Handling Playbook

401: show login prompt or warn about missing headers in gateway.
403: show permission denied with instructions to request access.
404: for PF entities, show “not configured” and CTA to create PF record.
409 (idempotent conflict or approval required): render appropriate callouts; for approval required, link AWF.
422/400: show field-level validation messages.
500: show friendly error, log correlation ID, offer retry with escalation option.

14) Testing Strategy

E2E: replicate compliance_e2e.postman_collection.json flows with Cypress/Playwright; assert on headers (ETag, Idempotency-Key) and response codes.
Integration: mock fetch for rule evaluation outcomes; test PF mutation UI branches (success, flag, reject, require approval).
Accessibility: ensure forms and modals are navigable and screen-reader friendly.

15) Rollout Plan

Phase 1: Read-only Compliance dashboard and PF status badges.
Phase 2: Enable rule management and PF gating for invoices.
Phase 3: Expand to budgets and expenses; introduce AWF UI and notifications.
Phase 4: Optimize performance, telemetry dashboards, and admin UX.

Use this guide to implement a maintainable, observable, and secure frontend that makes Compliance the central authority while enabling PF to be the principal consumer of project-scoped policies.

Welcome