# Architecture

## Shape

Atlas OS V1 is a Laravel modular monolith. This is a deliberate product decision: the embedded Kernel earns extraction only after at least three independent workflows reuse stable semantics and the separation creates measurable lifecycle or reliability value.

## Layers

| Layer | Responsibility |
|---|---|
| Blade Runtime | Responsive founder workspace, tailored record views, forms, and approval surfaces |
| HTTP application | Authentication, validation, authorization, workflows, file access, audit events |
| Domain model | Organizations, records, relationships, evidence, cycles, metrics, measurements |
| Embedded Kernel | Stable identity, tenant boundary, lifecycle, authority, provenance, versions, telemetry |
| Persistence | MySQL relational data and private Laravel filesystem storage |

## Canonical records

`work_records` is a typed, versioned record model for outcomes, issues, decisions, commitments, exceptions, evidence, and reviews. Shared fields establish consistent identity, authority, status, priority, horizon, owner, approver, source, confidence, deadlines, and outcome learning.

`record_relationships` makes context explicit with `depends_on`, `supports`, `blocks`, `derived_from`, `supersedes`, `caused_by`, and `affects` links.

Specialized tables exist only where lifecycle and query behavior justify them:

- `operating_cycles`
- `evidence_files`
- `metrics` and `metric_measurements`
- `comments`
- `audit_logs`

## Tenant isolation

Every domain row carries `organization_id`. The `BelongsToOrganization` concern applies an organization scope derived from the authenticated membership and session. Route model binding therefore cannot retrieve a record from another organization. Controllers additionally validate membership-owned user and cycle identifiers.

## Authority model

Roles are implemented without an extra package to reduce deployment complexity. Founder/CEO has full organization authority. CFO, Operations Manager, Account Manager, and Assistant System Administrator receive explicit permission sets in `App\Enums\Role`.

Material decisions remain human-approved. The later AI seam is capped at A3 (draft) by configuration until a separate governed activation decision.

## Audit and provenance

Material create, update, approve, upload, relationship, membership, metric, cycle, and settings actions write actor, subject, before/after data, IP, user agent, and timestamp to `audit_logs`. Evidence files remain private and are downloaded only through an authorized controller.