# SPECIFICATIONS/02_REQUIREMENTS/02_NON_FUNCTIONAL.md **PURPOSE:** Defines the quality attributes the system must exhibit. These are testable constraints on HOW the system behaves, not WHAT it does. **CONSTRAINT:** Implementation strategies for these requirements are defined exclusively in the referenced constitution files. This file states WHAT is required — the constitutions define HOW it is achieved. --- ## NFR-001: Performance ### NFR-001-1: Read Response Time Any read API MUST respond within **500ms** under a load of at least 100,000 contracts in the database. ### NFR-001-2: Cursor Pagination for Unbounded Lists All list endpoints that return unbounded or large-scale datasets MUST use cursor-based pagination (not offset-based) to prevent query degradation as dataset grows. - Default page size: 20 records - Maximum page size: 100 records - Endpoints returning naturally bounded datasets (e.g., a single customer's contract list) are exempt from this requirement ### NFR-001-3: Customer List Response Time Customer list endpoint (sorted by nearest due installment) MUST respond within **50ms**. - This requires pre-computed data structures — live queries at this scale are not acceptable for list pages - Detail pages may use live queries with a separate response time budget ### NFR-001-4: Analytics Response Time Analytics KPIs endpoint MUST respond within **200ms**. - KPIs use pre-computed daily snapshot tables — data may be up to 24 hours stale - KPIs results are cached with TTL-based expiration for repeated same-range queries - Analytics Charts endpoint computes data live from actual database tables (no pre-computation) ### NFR-001-5: Time Filter Efficiency Customer list time filtering MUST use a pre-computed date field — computing first-contract-date at query time is not acceptable. > **Performance strategy and implementation:** `../03_ARCHITECTURE/03_PERFORMANCE_STRATEGY.md` --- ## NFR-002: Infrastructure ### NFR-002-1: Application Stack - Framework: Laravel 12+ - Language: PHP 8.3+ ### NFR-002-2: Database - PostgreSQL 15+ (required for JSONB, Materialized Views, FILTER clause, BOOL_OR aggregate) - No SQLite support — PostgreSQL is the only database ### NFR-002-3: Required Packages - `spatie/laravel-permission` — RBAC - `maatwebsite/excel` — Excel export - `barryvdh/laravel-dompdf` — PDF export > **Full technology stack and integration points:** `../03_ARCHITECTURE/01_SYSTEM_OVERVIEW.md` --- ## NFR-003: Security All security requirements (authentication, authorization, rate limiting, input protection, credential security, error information control) MUST be enforced per the canonical specification. > **Canonical specification:** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Security Mandates --- ## NFR-004: API Response Architecture All API responses MUST follow a single unified structure with consistent field names and types, ensuring no endpoint returns a custom or non-standard response envelope. > **Canonical specification:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Response Architecture --- ## NFR-005: Exception Handling Architecture All exceptions MUST be mapped to structured API responses through a single centralized mapping file, preventing any direct exception-to-JSON conversion inside application logic. > **Canonical specification:** `../../CONSTITUTIONS/02_ERROR_BOUNDARIES.md` --- ## NFR-006: Domain Routing Architecture Each business domain MUST load its own routes independently through a central dynamic discovery mechanism, without requiring individual ServiceProviders solely for the purpose of routing. > **Canonical specification:** `../../CONSTITUTIONS/05_ROUTING_PROVIDERS.md` --- ## NFR-007: Localization All user-facing text in API responses MUST use the translation system — no hardcoded language strings in PHP code. > **Canonical specification:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Localization Confinement --- ## NFR-008: File Handling All file operations (upload, delete, URL generation) MUST go through a single centralized service, ensuring secure naming and consistent URL resolution. > **Canonical specification:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → File Handling Confinement --- ## NFR-009: Reliability ### NFR-009-1: Async Heavy Operations Report generation (Excel/PDF) MUST use background processing — synchronous generation that blocks the API response is prohibited. ### NFR-009-2: Transactional Integrity Operations that modify multiple database entities MUST execute within a single database transaction. Partial state is not allowed. > **Implementation:** `../../CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` → Database Transactions ### NFR-009-3: Idempotent Seeders All database seeders MUST be safe to run multiple times without creating duplicate records or causing errors. > **Implementation:** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Seeder Standards ### NFR-009-4: Realistic Test Data Test factories MUST generate realistic Arabic data conforming to the system's locale and specific format constraints (e.g., Syrian phone numbers). > **Implementation:** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Factory Standards --- ## NFR-010: Architectural Compliance The system MUST follow Clean Architecture with strict layer separation, ensuring no layer performs responsibilities assigned to another layer. > **Canonical specification:** `.specify/memory/constitution.md` → Core Principles --- ## NFR-011: Data Integrity Constraints The system MUST enforce critical data integrity constraints at multiple levels (application code and database schema) to prevent invalid states. > **Canonical rules:** `../01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-001-1, BR-002-4, BR-004-4 --- ## NFR-012: Database Schema Standards All database schema MUST follow the defined conventions regarding identifiers, timestamps, monetary value types, status column types, and the prohibition of soft deletes. > **Canonical specification:** `../../CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` → Schema Conventions --- ## NFR-013: Version Control Workflow All development MUST follow the specified branch structure (main/develop/feature/fix) and commit message format (Conventional Commits). > **Canonical specification:** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Git Workflow