# SPECIFICATIONS/03_ARCHITECTURE/04_DECISION_RECORDS_HISTORICAL.md

**PURPOSE:** Historical context for code structure decisions. The implementation rules derived from these decisions have been permanently migrated to the `CONSTITUTIONS/` folder as canonical law. This file exists solely to document WHY these choices were made — it defines NO build rules.

> **For the actual implementation rules:** See the "Current Authority" column below.

---

## Code Structure Decisions

### ADR-022: Eloquent Scopes Not Repositories
Scopes are the default for reusable queries. Repository Pattern introduced only when genuinely needed.
**Rationale:** Reduce boilerplate. Faster onboarding. Scopes solve the reusable query problem natively.
**Current Authority:** `../../CONSTITUTIONS/04_DATABASE_COMMUNICATION.md`

### ADR-025: Laravel 11 Exception Mapping Pattern
Use `withExceptions()` + single `ExceptionMappings.php` file. No custom config files.
**Rationale:** Standard Laravel pattern. Single mapping file. Type-safe closures.
**Current Authority:** `../../CONSTITUTIONS/02_ERROR_BOUNDARIES.md`

### ADR-028: DTOs for Complex Write Operations
DTOs are the standard for Create/Update operations that involve data transformation. Simple operations may skip DTOs.
**Rationale:** The DTO acts as the single point where business concepts map to database columns. For trivial operations, overhead is not justified.
**Current Authority:** `../../CONSTITUTIONS/09_DTOS.md` (Supersedes this ADR's original threshold rules)

### ADR-044: FileService Facade
All file operations go through `FileService` facade — never direct Storage facade or URL helpers.
**Rationale:** Prevent duplicated logic. Enforce secure naming. Single place to change behavior.
**Current Authority:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md`

### ADR-045: Single Formatter + Standalone Pagination Helper
Response formatting uses a single `ApiResponseFormatter` class with `success()` and `error()` methods only. No semantic shortcuts.
**Rationale:** The Formatter must be "blind" — it builds JSON structure without understanding error semantics. Separating pagination prevents the Formatter from knowing about cursor logic.
**Current Authority:** `../../CONSTITUTIONS/02_ERROR_BOUNDARIES.md`

### ADR-046: Scope Traits When Crowded
Extract model scopes into Traits in `Scopes/` subdirectory when a Model file becomes too large.
**Rationale:** Code organization tool. Not an architectural layer — just file management.
**Current Authority:** `../../CONSTITUTIONS/04_DATABASE_COMMUNICATION.md`

### ADR-049: Multi-language via lang/ Files
Arabic default, extensible without code changes. Folder structure by context. `__()` function for all messages.
**Rationale:** Forward slash for folder paths, dots only for nested keys within same file.
**Current Authority:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md`

### ADR-050: Exception Default Messages via English Log Text
Domain exceptions receive an English technical message in their constructor (for logs and CLI). Translated user-facing messages are generated exclusively in the Exception Mappings layer.
**Rationale:** Keeps the Domain layer completely free of HTTP and localization concerns. Works seamlessly in CLI and Queue environments.
**Current Authority:** `../../CONSTITUTIONS/02_ERROR_BOUNDARIES.md`

### ADR-051: Query Classes for Complex Aggregations
Dedicated Query classes for queries that build complex aggregations or add computed columns via subselects.
**Rationale:** Scopes modify existing queries (WHERE, ORDER BY). Query classes build standalone queries with JOINs, GROUP BY, subselects.
**Current Authority:** `../../CONSTITUTIONS/04_DATABASE_COMMUNICATION.md`

### ADR-052: ClientType Enum for Type Safety
Backed enum for role flag values instead of raw strings.
**Rationale:** Prevents typos. IDE autocomplete. Values must match JSONB flag strings exactly.
**Current Authority:** `../../CONSTITUTIONS/03_ENUMS.md`

### ADR-055: Response Builder Classes for Complex Reads
Dedicated Builder classes for assembling complex read responses requiring multiple queries or computed fields.
**Rationale:** Resources must not contain business logic or DB queries. Services express write use cases. Builders sit between: orchestrate queries and assemble arrays without writing data.
**Current Authority:** `../../CONSTITUTIONS/04_DATABASE_COMMUNICATION.md`

### ADR-057: Controller as Orchestrator
Controller may perform light assembly work (merging Service output with Resource/Builder output) rather than delegating every line to Service.
**Rationale:** Previous pattern made Controller a useless proxy. New pattern gives Controller context about response structure without business logic.
**Current Authority:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md`

### ADR-058: Backed Enum Classes with Pure Methods
PHP backed enums for all status columns. Enums MAY contain pure methods (Boolean checks, transition rules). Display logic MUST live in separate Display classes.
**Rationale:** Type safety and IDE support. Pure methods inside enums prevent scattered `if` checks. Separating display keeps the enum free of presentation concerns.
**Current Authority:** `../../CONSTITUTIONS/03_ENUMS.md`