Non-Functional Requirements¶

Status: Draft — feeds the PRD. Principle: Every NFR must be measurable. No "the system should be fast" — only "a page load must complete within X under Y conditions."

1. Performance & Scalability¶

NFR-P01 — UI Responsiveness¶

Requirement: Any page in the analyst workspace must render within 2 seconds (p95) under normal load (up to 50 concurrent analysts).

Measurement: Lighthouse / Web Vitals on key pages: case list, case detail, analyst workspace.

Rationale: Analysts spend their entire day in the platform. Sub-2-second interactions prevent fatigue and maintain workflow momentum.

NFR-P02 — Screening Response Time¶

Requirement: Name screening against external watchlists must return a result within 5 seconds (p95).

Measurement: Timed from module invocation to response received by workflow engine.

Rationale: Screening happens during onboarding — the customer (or RM) is waiting. 5 seconds is an acceptable pause; longer feels like a system hang.

NFR-P03 — Concurrent Workflow Execution¶

Requirement: The platform must support at least 100 concurrent workflow instances (onboarding cases in progress simultaneously) without degradation.

Measurement: Load test with 100 parallel onboarding workflows, each with screening, risk rating, and network analysis invocations. No API timeout failures.

Rationale: A mid-size compliance team of 8-12 analysts processes dozens of cases simultaneously. 100 concurrent provides comfortable headroom for MVP.

NFR-P04 — Audit Log Write Throughput¶

Requirement: The audit log must sustain at least 1,000 events per second write throughput.

Measurement: Load test with burst of audit events. No event loss; no write timeouts.

Rationale: Every module invocation, state transition, and user action generates at least one audit event. A complex corporate onboarding with parallel tasks can generate 50+ events in seconds.

2. Security¶

NFR-S01 — Encryption in Transit¶

Requirement: All communication between client and server, and between internal services, must use TLS 1.2 or higher. HTTP must redirect to HTTPS.

Measurement: TLS certificate validation. Penetration test confirms no unencrypted endpoints.

NFR-S02 — Encryption at Rest¶

Requirement: All persistent data (database, file storage, audit logs) must be encrypted at rest using AES-256 or equivalent.

Measurement: Verify encryption enabled at storage layer. Key management documented.

NFR-S03 — Authentication Strength¶

Requirement: Password policy must enforce: minimum 12 characters, at least one uppercase, one lowercase, one digit, one special character. Passwords must not be in common password lists.

Measurement: Policy enforced at registration and password change. Integration test verifies breached-password rejection.

NFR-S04 — Session Security¶

Requirement: User sessions must expire after 30 minutes of inactivity. Authentication tokens must expire after 8 hours (maximum workday). Failed login attempts lock account after 5 failures for 15 minutes.

Measurement: Integration tests verify session timeout and lockout behavior.

NFR-S05 — Field-Level Access Control¶

Requirement: Sensitive fields (date of birth, identification numbers, PEP status) must be maskable per role. The Auditor role must see all fields; the Supervisor role should not see DOB or ID numbers unless actively investigating.

Measurement: Role-based field visibility matrix tested for every role.

NFR-S06 — Privileged Access Monitoring¶

Requirement: Any access to sensitive customer data by Admin or privileged roles must generate an audit event with: who accessed, what data, when, and from which IP.

Measurement: Audit log search confirms privileged access events are recorded.

3. Reliability & Availability¶

NFR-R01 — System Uptime¶

Requirement: The platform must achieve 99.5% uptime during business hours (8am-8pm, local time, weekdays). Planned maintenance excluded.

Measurement: Uptime monitoring with 1-minute health check interval.

Rationale: 99.5% means ~30 minutes of acceptable downtime per week. Higher availability (99.9%+) is post-MVP. MVP is single-deployment — don't overpromise.

NFR-R02 — Graceful Degradation¶

Requirement: If an external service (sanctions list provider, corporate registry) is unavailable, the workflow must not fail. Instead: mark the dependent task as BLOCKED, notify the operator, and allow the workflow to continue on other parallel tracks. When the service recovers, retry the blocked task.

Measurement: Integration test with mocked external service downtime.

NFR-R03 — Data Durability¶

Requirement: Once an audit event is written to the log, it must survive system restarts, crashes, and power loss. No audit events may be lost.

Measurement: Kill process mid-write. Restart. Verify no missing or corrupted audit events.

NFR-R04 — Retry with Backoff¶

Requirement: Transient failures (network timeout, database deadlock) must retry up to 3 times with exponential backoff (1s, 2s, 4s). On final exhaustion, the task enters error state with operator notification.

Measurement: Integration test injects transient failures; verifies retry behavior and final state.

4. Observability¶

NFR-O01 — Structured Logging¶

Requirement: All log entries must be structured (JSON format) and include: timestamp, service name, correlation ID, log level, message, and context.

Measurement: Sample log output verified as valid JSON with required fields.

NFR-O02 — Correlation IDs¶

Requirement: Every API request must receive a unique correlation ID. This ID must propagate through all downstream service calls and appear in all log entries and audit events for that request.

Measurement: Trace a request from API gateway → workflow engine → screening module → audit log. All entries share the same correlation ID.

NFR-O03 — Health Check¶

Requirement: Every service must expose a /health endpoint returning: service status (UP/DOWN), database connectivity, external service status, uptime.

Measurement: Health endpoint returns 200 with expected body.

NFR-O04 — Key Metrics¶

Requirement: The platform must expose: active workflow count, cases per status, average case age, SLA breach count (last 24h), screening requests per minute, error rate.

Measurement: Metrics endpoint or dashboard confirms all metrics available.

5. Usability¶

NFR-U01 — Low Click Count¶

Requirement: Common analyst tasks must not exceed 5 clicks from the case list to completion: - Approve a low-risk case: ≤ 3 clicks - Escalate a case: ≤ 2 clicks - Request additional document: ≤ 3 clicks

Measurement: Usability test with sample analyst workflows. Count clicks.

NFR-U02 — Error Messages¶

Requirement: All error messages must include: (1) what went wrong in plain language, (2) what the user can do about it, (3) a reference ID for support. No stack traces in the UI.

Measurement: Review every error path. No raw exception text visible to end users.

NFR-U03 — Loading States¶

Requirement: Every action that takes > 300ms must show a loading indicator (spinner, skeleton, or progress bar). Actions that complete in < 300ms may skip it.

Measurement: UI audit confirms no "dead clicks" — every button provides feedback within 300ms.

Requirement: (Post-MVP) Key analyst actions must be keyboard-accessible: navigate case list (↑↓), open case (Enter), approve (Ctrl+Enter), reject (Ctrl+Backspace).

6. Maintainability¶

NFR-M01 — Modular Architecture¶

Requirement: Each bounded context (onboarding, screening, risk rating, case management, etc.) must be a separate module with a clearly defined interface. Modules must not import from each other's internals.

Measurement: Architecture review. Dependency graph shows no circular dependencies between modules. Internal packages are not exported.

NFR-M02 — Configuration Over Code¶

Requirement: Business rule changes (thresholds, document requirements, approval matrices, workflow templates) must be changeable via the configuration engine without code deployment. Only infrastructure changes and new module capabilities require deployment.

Measurement: Demonstrate: change a risk threshold → active immediately in production without restart.

NFR-M03 — API Versioning¶

Requirement: All REST APIs must be versioned (e.g., /api/v1/onboarding). Breaking changes require a new version. Old versions supported for at least one release cycle.

Measurement: API changelog. Integration tests for both current and previous version.

NFR-M04 — Test Coverage¶

Requirement: Business logic must have ≥ 80% line coverage. Critical paths (onboarding flow, screening matching, risk scoring) must have ≥ 90% branch coverage.

Measurement: Coverage report from CI pipeline.

7. Compliance & Data Retention¶

NFR-C01 — Audit Retention¶

Requirement: All audit events must be retained for a minimum of 7 years from the date of creation. After 7 years, events may be archived to cold storage but must remain retrievable within 30 days.

Measurement: Verify oldest retained event is not automatically deleted before 7-year mark.

NFR-C02 — Decision Reproducibility¶

Requirement: For any decision made in the last 7 years, an auditor must be able to reconstruct: the exact inputs, the config version active, the modules invoked and their outputs, the actor, the timestamp, and the rationale — within 5 minutes of search.

Measurement: Timed audit exercise: pick a random case from 3 years ago, auditor searches and reconstructs. Must complete within 5 minutes.

NFR-C03 — Data Minimization¶

Requirement: The platform must not collect or store personal data beyond what is required for the KYC/CDD process. Document storage must have configurable retention — after customer offboarding, documents must be deletable per policy.

Measurement: Data inventory audit. No unnecessary PII fields.

NFR-C04 — Right to Access / Right to Erasure¶

Requirement: (P1 — when GDPR-applicable jurisdiction supported) The platform must support exporting all data for a given customer in a machine-readable format, and deleting all personal data on request, while preserving anonymized audit trail.

8. API Standards¶

NFR-A01 — Consistent API Design¶

Requirement: All REST APIs must follow these conventions: - Resource names: plural nouns (/cases, /customers) - HTTP methods: GET (read), POST (create), PUT (full update), PATCH (partial update), DELETE (remove) - Pagination: ?page=1&limit=50 with Link header for next/prev - Error responses: { "error": { "code": "CASE_NOT_FOUND", "message": "...", "refId": "abc-123" } } - Idempotency: POST/PUT/PATCH accept Idempotency-Key header

Measurement: OpenAPI spec validates all endpoints. Linter enforces conventions.

NFR-A02 — Rate Limiting¶

Requirement: API endpoints must enforce rate limits. Default: 100 requests per minute per user. Screening endpoints: 20 requests per minute (external service cost control).

Measurement: Load test exceeds rate limit. Verify 429 response with Retry-After header.

9. NFR Summary¶

Category	Count	Key Metric
Performance & Scalability	4	2s UI, 5s screening, 100 concurrent workflows
Security	6	TLS 1.2+, AES-256, 12-char passwords, 30min session
Reliability & Availability	4	99.5% uptime, graceful degradation, retry with backoff
Observability	4	JSON logs, correlation IDs, health checks, metrics
Usability	3	≤5 clicks, plain-language errors, loading states
Maintainability	4	Modular, config-over-code, API versioning, 80% coverage
Compliance & Retention	4	7-year audit retention, 5-min reconstruction, data minimization
API Standards	2	Consistent REST, rate limiting
Total	31

NFRs derived from: Onboarding Spec §14-16, Blueprint §8-9/§13, Engineering Spec §13-16.