# SPECIFICATIONS/03_ARCHITECTURE/01_SYSTEM_OVERVIEW.md

**PURPOSE:** High-level description of the technologies, architectural patterns, and integration points that define the system. This file answers "what is the system built with and how is it conceptually organized?" — it contains zero implementation instructions.

---

## Technology Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| Framework | Laravel 12+ | Application framework |
| Language | PHP 8.3+ | Backend language |
| Database | PostgreSQL 15+ | Data persistence |
| Auth | Laravel Sanctum | API token authentication |
| Permissions | Spatie Laravel Permission | Dynamic RBAC |
| Export (Excel) | `maatwebsite/excel` | Excel generation |
| Export (PDF) | `barryvdh/laravel-dompdf` | PDF generation |
| Queue | Laravel Queues | Async operations |
| Timezone | `Asia/Damascus` (UTC+3) | Server timezone |

**Database Requirement:** PostgreSQL 15+ is mandatory — the system depends on JSONB, Materialized Views, `FILTER (WHERE ...)` clause, and `BOOL_OR()` aggregate.

---

## Architectural Patterns

### I. Clean Architecture — Strict Layers
Every request flows through strictly separated layers, each with a single conceptual responsibility. No layer performs the job of another.

> **Canonical implementation boundaries:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md`

### II. Domain Separation
Each business domain is isolated in its own directory with all required components. Domain routes are loaded centrally via a dynamic discovery mechanism without requiring individual service providers for routing.

> **Canonical routing mechanism:** `../../CONSTITUTIONS/05_ROUTING_PROVIDERS.md`

### III. Spec-Driven Development
All development is driven by Specs. The Master Constitution is the supreme authority — any conflict with any document is resolved in favor of the Constitution.

### IV. State Table Pattern
Installments are pre-generated as physical rows at contract creation — not computed dynamically on request. This enables direct status filtering, index-backed sorting, and sub-second list queries without JOINs.

> **State definitions and transitions:** `02_STATE_MACHINES.md`

### V. Append-Only Ledger
Payments follow a strict append-only pattern with LIFO-only reversal. All changes are logged in an independent audit trail with self-contained narrative text. Historical narrative is preserved even after payment deletion.

> **Payment engine algorithms and rules:** `../05_ALGORITHMS/03_PAYMENT_ENGINE.md`
> **Narrative generation rules:** `../05_ALGORITHMS/05_NARRATIVE_GENERATION.md`

---

## Integration Points

| Integration | Purpose | Key Constraint |
|-------------|---------|----------------|
| Spatie Permission | Role and permission management | All permissions use `guard_name = 'admin'` |
| Laravel Sanctum | Token-based API authentication | Tokens are hard-deleted on logout |
| Laravel Storage | File persistence | All operations MUST go through FileService |
| Laravel Queues | Background job execution | Required for export operations |
| maatwebsite/excel | Excel export | Must be executed via Jobs only |
| barryvdh/laravel-dompdf | PDF export | Must be executed via Jobs only |

> **File handling implementation:** `../../CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → File Handling Confinement
> **Security implementation:** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Security Mandates