# Atlas OS v2 Architecture

## Decision

Atlas OS v2 remains a Laravel 13 modular monolith on the existing WHM/cPanel and MySQL 8 server. This is the lowest-complexity architecture that preserves strong transactions, one deployment unit, shared identity, and complete traceability across the three current workflows.

Microservices are not justified at Customer Zero scale. The embedded Kernel may be extracted only after at least three independent products reuse stable semantics and operational evidence shows a different scaling, lifecycle, or isolation need.

## Runtime shape

| Layer | Responsibility |
|---|---|
| Blade Runtime | Responsive executive, relationship, sales, delivery, finance, and control-record workspaces |
| HTTP application | Authentication, tenant context, locale, validation, authorization, lifecycle orchestration, private file access |
| Workflow services | Executive pulse, financial derivation, dashboard briefing, audit event capture |
| Domain model | Canonical organization, actor, opportunity, proposal, project, milestone, invoice, transaction, work-record, cycle, metric, evidence, and audit identities |
| Embedded Kernel | Tenant boundary, identity, authority, provenance, versioning, human approval, telemetry, and AI ceiling |
| Persistence | MySQL relational data and Laravel private filesystem storage |

## Module boundaries

| Module | Primary tables | Owns |
|---|---|---|
| Identity & authority | `users`, `organizations`, `organization_user` | membership, role, locale, organization context |
| Executive governance | `work_records`, `record_relationships`, `comments`, `evidence_files` | outcomes, issues, decisions, commitments, exceptions, evidence, reviews |
| Operating cadence | `operating_cycles`, `metrics`, `metric_measurements` | cycle window, KPI contract, observation |
| Relationships | `actors`, `interactions` | organizations/people, relationship stage, contact history, next action |
| Lead-to-cash | `opportunities`, `proposals` | pipeline, probability, proposal versions, acceptance, win/loss |
| Delivery | `projects`, `milestones` | delivery identity, health, manager, milestone acceptance |
| Finance | `financial_accounts`, `invoices`, `financial_transactions` | receivables, collections, expenses, transfers, derived balances |
| Assurance | `audit_logs` | actor, subject, event, before/after state, request provenance |

The modules are separated in code and data semantics but intentionally share one database transaction boundary. A proposal acceptance, project conversion, invoice collection, and audit event do not need distributed consistency machinery.

## Canonical link graph

```text
Organization
 ├─ Memberships / Roles / Locale
 ├─ Operating Cycles ─ Metrics ─ Measurements
 └─ Actor (client / partner / vendor / person)
     ├─ Interactions
     ├─ Opportunity ─ Proposal versions
     │   └─ Project ─ Milestones
     │       ├─ Work Records ─ Evidence / Comments / Relationships
     │       ├─ Invoices ─ Income transactions
     │       └─ Expense / transfer transactions
     └─ Executive Work Records can link directly to actor, opportunity, and project
```

## Consistency rules

- Every domain row carries `organization_id`; HTTP queries fail closed when organization context is absent.
- Route model binding is tenant scoped. Request validation also constrains foreign IDs to the active organization.
- A project and opportunity linked on the same record must resolve to the same actor.
- A project created from an opportunity marks that opportunity won with 100% probability.
- Proposal acceptance records `accepted_at` and advances the opportunity to accepted.
- An invoice’s project/opportunity must belong to its selected actor.
- A cleared payment cannot exceed invoice outstanding value and must match invoice/account currency.
- Transfers require distinct active accounts in the same currency; cross-currency exchange is explicit and deferred.
- Invoice and account balances are derived from source transactions; users never type a balance.
- v2 uses one organization base currency for comparable totals; that currency locks after the first commercial or financial record.
- Material lifecycle actions write an audit event.

## Authority and AI

Roles are small, explicit permission maps because the current role set is stable and does not justify a package. Founder/CEO has organization authority; CFO, Operations Manager, Account Manager, and Assistant System Administrator receive bounded capabilities. Controllers enforce material permissions even where the interface hides unavailable actions.

Decisions remain human-approved. AI is disabled by default and capped at A3 (draft) in configuration. No AI may post cash, approve decisions, alter authority, or perform consequential external action in v2.

## Locale strategy

English is the v2 content language. `users.locale`, `organizations.default_locale`, request locale middleware, supported locale configuration, semantic HTML `lang`, automatic `dir`, and direction-aware shell CSS make Arabic/RTL a content-localization project rather than a database or layout rewrite. Translation catalogs are intentionally deferred until approved Arabic terminology is available.

## Scale path

1. **Now:** database sessions/cache/queue, static assets, synchronous workflows, one WHM deployment.
2. **When measured:** add a supervised queue worker for notifications/imports, then Redis only if database queue/cache contention is observed.
3. **When externalized:** introduce API resources and per-client integration credentials behind the same services and policies.
4. **Only with evidence:** extract a Kernel service or workflow module when independent release cadence, fault isolation, or sustained load requires it.

The design avoids speculative infrastructure while leaving seams at services, enums, module tables, audit events, and filesystem disks.