Home/About/Documentation

System Architecture & Operational Flows

Clean Layered Architecture

Thin Route Handlers → Domain Business Services → Repository Data Access. Zero business rules leaked inside React components or API routes.

Strict Data Boundaries (Anti-IDOR)

Cross-user isolation enforced at the service layer. Reports, complaints, and licenses require cryptographic PINs and DOB matching; zero enumerable integer IDs.

Multi-Role Access Control (RBAC)

Public Citizens, Sworn Deputies, IAB Investigators, and System Administrators with privilege escalation barriers and full audit logging.

Core Application Flows

Select an operational workflow to review step-by-step user interactions and backend safeguards.

Public Reporting

Citizen Crime Incident Reporting Flow

End-to-end citizen reporting with anonymous support, cryptographic reference generation, and PIN-secured tracking.

STEP-BY-STEP WORKFLOW

1. Intake & Classification

Actor: Citizen / Reporting Party

User Action: Select incident category (Theft, Assault, Vandalism, Hit & Run, etc.), enter date/time, and detail narrative.

System Process: Performs client-side Zod validation ensuring min. 10 characters and valid 4-digit year format.

Security Safeguard: Sanitizes input strings against XSS; enforces category whitelist.

2. Identity Disclosure Option

Actor: Citizen

User Action: Choose between Disclosed Identity (Full name, phone, email) or Full Anonymous filing.

System Process: If anonymous, masks identity in database as 'ANONYMOUS CITIZEN' while preserving audit logging.

Security Safeguard: Zero PII stored on anonymous filings; server strips contact info prior to persistence.

3. Cryptographic Case Reference & PIN Issuance

Actor: System (ReportService)

User Action: Generates high-entropy Case Reference (e.g. CR-2026-9921) and a unique 6-digit access PIN.

System Process: Displays one-time credentials to the citizen with instructions to preserve PIN for case updates.

Security Safeguard: Stores argon2/secure hash of the PIN. Access requires exact Case Ref + PIN match (Anti-IDOR).

4. Status Tracking & Supplemental Evidence

Actor: Citizen / Assigned Deputy

User Action: Citizen enters Case Reference + PIN on Tracking Desk to view investigation status or submit new evidence.

System Process: Displays report timeline (SUBMITTED -> UNDER_REVIEW -> INVESTIGATING -> RESOLVED).

Security Safeguard: Rejects any tracking attempt with mismatched PIN without leaking record existence.

TECHNICAL IMPLEMENTATION MAPPING

Endpoint: POST /api/reports, GET /api/reports, POST /api/reports/revision

Service Layer: src/core/services/report-service.ts

Validator: Zod Schema: createReportSchema, reportRevisionSchema

Boundary: Strict PIN verification; users cannot view other citizens' incident reports.