# Developer architecture guide

## Runtime shape

PowerAMS is a server-rendered PHP 8.2+ modular monolith. `public/index.php` is the only application front controller. `bootstrap/app.php` loads environment/configuration and constructs the core application. `routes/web.php` and `routes/api.php` register browser and REST routes.

```text
HTTP/CLI
  → Router and middleware
  → thin controller
  → module service (business rules, authorization, transactions, audit)
  → repository (PDO prepared statements and airline-scoped persistence)
  → MySQL 8
```

`app/Core` contains routing, requests/responses, sessions, CSRF, authentication context, validation, database/migrations, views, errors, logging, pagination, uploads, cache, jobs, and production health. `app/Shared` contains cross-module provider contracts. Each directory under `app/Modules` owns controllers, services, and repositories for one business area.

## Engineering constraints

- Keep controllers thin and business decisions in services.
- Put SQL in repositories and bind all values through PDO prepared statements.
- Pass `airline_id` through every operational service and scope repository reads/writes by it.
- Authorize at middleware and service boundaries; do not trust hidden navigation.
- Store timestamps in UTC and airport timezones as explicit IANA identifiers.
- Use DECIMAL strings/integer minor-unit helpers for money, never binary floating-point arithmetic.
- Record status transitions, approvals, immutable transactions, and critical actions in their history/audit tables.
- Use soft deletion for mutable master records. Never silently overwrite approved financial/operational evidence.
- Store uploads outside `public/` with generated names; route downloads through tenant/permission checks.
- Preserve module patterns and avoid unrelated refactors.

## Request security

Browser mutations require CSRF middleware. Secure sessions regenerate on login and use database-backed revocation. API calls use expiring hashed bearer tokens, client scopes, per-token rate limits, JSON-only mutation bodies, idempotency keys, request logs, and tenant context. Security middleware supplies CSP, clickjacking, MIME-sniffing, referrer, permissions, and production error controls.

## Data changes and tests

Create forward-only migration files implementing the migration contract and a reviewed `down()` method. MySQL DDL may commit implicitly. Run status, backup, migrate, tests, and health checks before activating code.

Commands:

```bash
php tests/run.php
php tests/quality/static-analysis.php
php tests/production/production-readiness.php
php cli migrate:status
php cli health:check
```

The default job dispatcher is synchronous. Do not add a process supervisor until an explicit persistent queue adapter and retry/dead-letter contract exist.