# ABC Core Project Rules (Phase 1.1)

These rules are permanent and must never be violated.

## 1. Backend First

- No HTML.
- No CSS.
- No Bootstrap.
- No Admin Template.
- No Customer Dashboard.
- Only backend code (PHP, SQL, JSON APIs).

## 2. PHP 7.4+

- The project MUST remain compatible with PHP 7.4+.
- MySQL / MariaDB via PDO.
- Apache / cPanel / Shared Hosting compatible.
- No Laravel, CodeIgniter, Symfony, or any framework.
- Pure Object-Oriented PHP.

## 3. Modular Architecture

Every module has exactly ONE responsibility and is self-contained.

Module structure:
```
Modules/Authentication/
  Controllers/
  Services/
  Repositories/
  Models/
  Routes/
  Validation/
```

No service should perform another service's work.

## 4. Single Source of Truth

Business logic must NEVER be duplicated.

Examples:
- Transfer logic exists in ONE place only.
- Deposit logic exists in ONE place only.
- Ledger logic exists in ONE place only (Core/Ledger.php).
- Approval logic exists in ONE place only.
- Notification logic exists in ONE place only.

## 5. Ledger First

Money must NEVER be modified directly.

Forbidden:
```sql
UPDATE accounts SET balance = balance - amount
```

Required flow:
```
Transaction
  ↓
Ledger Entry (Core/Ledger.php)
  ↓
Balance Update (recalculated from ledger)
  ↓
Audit Log
  ↓
Receipt Queue
  ↓
Notification Event
```

Everything financial must pass through the Ledger Core.

## 6. Clean Architecture

Separate these layers strictly:
- Controllers — coordinate requests/responses, NO business logic
- Services — contain ALL business logic
- Repositories — contain ALL SQL, NO business logic
- Models — lightweight data containers
- Helpers — reusable utility functions
- Config — configuration values
- Constants — typed-safe constants, NO hardcoded strings
- Events — decoupled communication between services
- Queue — background job processing

Never mix responsibilities.

## 7. Repository Pattern

No Controller, Service, Helper, or Middleware may execute SQL directly.

ALL SQL must exist only inside Repository classes.

Flow:
```
TransferService
  ↓
TransactionRepository
  ↓
Database
```

## 8. Event-Driven Architecture

Services publish events instead of tightly calling one another.

```
TransferService
  ↓
  TransferCompletedEvent
  ↓
  EventDispatcher
  ↓
  NotificationListener
  AuditListener
  ReceiptListener
```

This reduces coupling and allows adding listeners without modifying the publisher.

## 9. Queue System

Notifications, receipts, statements, reports, and exports MUST be queued.

The Queue is file-based for shared-hosting compatibility.

Queue types:
- Email notifications
- Statement generation
- Report generation
- Receipt generation
- Background exports
- Data imports

## 10. Security First

Everything must be designed with security in mind:
- Prepared Statements
- Password Hashing (BCRYPT, cost 12)
- Session Security (regenerate IDs, HttpOnly, SameSite)
- CSRF Protection
- Input Validation (Validator class)
- Rate Limiting (file-based, per IP)
- Security Headers (XSS, CSP, Frame-Options)
- Audit Logs (every financial action)
- OTP Support (Phase 3)

## 11. Notification Philosophy

Notifications must NEVER interrupt banking operations.

Supported channels:
- Email (queued)
- In-App Notification

Not supported:
- SMS
- WhatsApp
- Push Notification

If email fails, the transaction still succeeds. The notification is retried via the queue.

## 12. Banking Philosophy

A transaction is only complete after ALL of these succeed:
1. Ledger Entry
2. Transaction Record
3. Audit Log
4. Receipt Record
5. Notification Queue
6. Database Commit

If any one fails, the entire transaction must rollback safely.

## 13. Coding Standard

- Readable
- Professional
- Maintainable
- Reusable
- Scalable
- No duplicated code
- No hardcoded values — use Constants or Config
- Everything configurable via `.env` or `app/Config`

## 14. Frontend Independence

The backend must NEVER contain frontend code.

Frontends that may consume this API:
- Customer Portal
- Admin Dashboard
- Flutter Mobile App
- Android App
- iOS App
- React Frontend
- Vue Frontend
- Angular Frontend

All are external and communicate via the same JSON API.

## 15. UUID Rule

Public API responses must NEVER expose sequential database IDs.

All public identifiers must be UUIDs.

Internal integer IDs may remain for database efficiency and foreign keys,
but they are never returned in API responses.

## 16. API Versioning

All routes MUST begin with `/api/v1/`.

Never expose root endpoints like `/login`.

Always use `/api/v1/auth/login`.

Future versions: `/api/v2/`, `/api/v3/` without changing the core.

## 17. Constants Rule

Never use hardcoded strings for banking concepts.

Use the Constants layer:
- `AccountTypes::SAVINGS`
- `Currencies::NGN`
- `TransactionTypes::TRANSFER`
- `UserStatus::ACTIVE`

This ensures type safety, consistency, and easy expansion.