# Implementation Plan: Base Architecture - Foundation Layers (SP-03)

**Branch**: `feat/SP-03-base-architecture` | **Date**: 2026-06-04 | **Spec**: [link](../spec.md)

**Input**: Feature specification from `/specs/003-base-architecture/spec.md`

## Summary

Create the foundational architecture layer for the Tamkeen installment finance system: 8 Eloquent models with semantic relationships, Repository pattern infrastructure (BaseRepositoryInterface + BaseEloquentRepository), BaseResource for unified API responses, Exception Handler integration via ExceptionClassToMethod.php, and Queue infrastructure with database driver.

**Technical Approach**: Laravel 11+ with PHP 8.2+, PostgreSQL 15+, following Clean Architecture strict layers (Repository is sole database gateway). User model implements hard immutability (no deletion). Exception handling uses config/ExceptionClassToMethod.php mapping (NOT withExceptions()).

## Technical Context

**Language/Version**: PHP 8.2+

**Primary Dependencies**: Laravel 11+, spatie/laravel-permission, bcmath extension

**Storage**: PostgreSQL 15+

**Testing**: PHPUnit

**Target Platform**: Linux server (API-first Backend)

**Project Type**: API-first Backend (consumed via Mobile App)

**Performance Goals**: N/A (infrastructure layer)

**Constraints**: Clean Architecture strict layers, Repository is sole database gateway, bcmath mandatory for any financial math, all monetary fields DECIMAL(10,2), cursor-based pagination (Constitution Section 4.3), Exception handling via ExceptionClassToMethod.php

**Scale/Scope**: 8 Eloquent models, 2 repository classes, 1 base resource, Exception Handler mapping via config, Queue configuration

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Gate | Status | Notes |
|------|--------|-------|
| Clean Architecture — Strict Layers | ✅ PASS | Repository pattern infrastructure enforces sole database gateway |
| Domain Separation | ✅ PASS | Models follow Domain folder structure (app/Domains/{Domain}/Models/) |
| Financial Data Principles | ✅ PASS | FR-016 mandates decimal(10,2) casting for all monetary fields |
| Immutability & State Rules | ✅ PASS | FR-009 implements hard immutability for User model (delete throws exception) |
| Code Quality Standards | ✅ PASS | PHPUnit testing framework assumed (Constitution requirement) |
| API Constitution | ✅ PASS | BaseResource + ExceptionClassToMethod.php ensure unified responses |
| Cursor-Based Pagination | ✅ PASS | FR-010 includes cursorPaginate() per Constitution Section 4.3 |
| Exception Handling Pattern | ✅ PASS | Uses config/ExceptionClassToMethod.php (not bootstrap/app.php withExceptions()) |

**No violations detected.**

## Project Structure

### Documentation (this feature)

```text
specs/003-base-architecture/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output (if needed)
└── tasks.md             # Phase 2 output (/speckit.tasks command)
```

### Source Code (repository root)

```text
app/
├── Models/
│   └── User.php                    ← FR-001: User with semantic relationships + hard immutability
├── Domains/
│   ├── Auth/
│   │   └── Models/
│   │       └── Admin.php           ← FR-002: Admin with HasRoles + admin guard
│   ├── Contract/
│   │   └── Models/
│   │       ├── Contract.php         ← FR-003: Contract with relationships
│   │       └── Installment.php      ← FR-004: Installment with contract relationship
│   ├── Payment/
│   │   └── Models/
│   │       ├── Payment.php          ← FR-005: Payment with contract + auditLogs
│   │       └── PaymentAuditLog.php  ← FR-006: PaymentAuditLog with contract + payment
│   ├── Agent/
│   │   └── Models/
│   │       └── AgentSharesLog.php   ← FR-007: AgentSharesLog with agent
│   └── Notification/
│       └── Models/
│           └── NotificationTemplate.php ← FR-008: Standalone model
├── Shared/
│   ├── Repositories/
│   │   ├── Contracts/
│   │   │   └── BaseRepositoryInterface.php  ← FR-010: CRUD + cursorPaginate interface
│   │   └── Eloquent/
│   │       └── BaseEloquentRepository.php   ← FR-011: Eloquent implementation
│   └── Http/
│       └── Resources/
│           └── BaseResource.php     ← FR-012: Unified response base
├── Helpers/
│   ├── ApiResponseHelper.php        ← Already exists from SP-01
│   └── CostumErrorResponse.php     ← Already exists from SP-01
├── Providers/
│   └── AppServiceProvider.php       ← Repository bindings
config/
├── app.php                          ← timezone Asia/Damascus
├── queue.php                        ← database driver config
└── ExceptionClassToMethod.php        ← FR-013: Exception mapping (EXISTING - do NOT modify pattern)
.env                                 ← FR-014: QUEUE_CONNECTION=database
database/
└── migrations/
    └── create_jobs_table.php        ← FR-015: Verify exists from Laravel defaults
```

**Structure Decision**: Following Constitution's Domain Separation pattern. All business models in `app/Domains/{Domain}/Models/`. Shared infrastructure (repositories, resources) in `app/Shared/`. Repository pattern enforced as sole database gateway.

**Exception Handling Note**: FR-013 uses existing `config/ExceptionClassToMethod.php` pattern. Do NOT use `withExceptions()` in `bootstrap/app.php`. The config file maps exception classes to `CostumErrorResponse` methods.

## Complexity Tracking

> **Fill ONLY if Constitution Check has violations that must be justified**

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | N/A | N/A |

## Phase 0: Research

**Research.md** will document:
- Laravel model relationship best practices
- Repository pattern implementation patterns in Laravel
- Laravel BaseResource customization for unified responses
- Exception Handler mapping via ExceptionClassToMethod.php (existing pattern)
- Queue database driver configuration