# Research and Architecture Decisions

Research checked on 16 August 2026 against current primary documentation.

## ADR-001 — Laravel 13 on PHP 8.4

**Decision:** retain Laravel 13 and run it with the server’s PHP 8.4.

**Why:** Laravel 13 supports PHP 8.3–8.5, with security fixes scheduled through 17 March 2028. The existing code already follows Laravel 13’s bootstrap and routing model; a framework change would add risk without product value.

Source: [Laravel 13 release notes](https://laravel.com/docs/13.x/releases), [Laravel 13 deployment requirements](https://laravel.com/docs/13.x/deployment).

## ADR-002 — Modular monolith, not microservices

**Decision:** one Laravel application and one MySQL database, organized around explicit domain modules.

**Why:** the three workflows share identity and require strong multi-record consistency. Laravel database transactions automatically roll back a failed closure, which is a direct match for proposal acceptance, project conversion, and payment/status updates. The current scale has no demonstrated independent scaling or release-cadence need.

Source: [Laravel database transactions](https://laravel.com/docs/13.x/database).

## ADR-003 — Server-rendered Blade with static assets

**Decision:** keep the responsive Blade runtime and static CSS/JavaScript.

**Why:** the product is form-, table-, and review-heavy; it gains little from a separate SPA build/runtime. This reduces WHM deployment dependencies, preserves Laravel validation/session behavior, and improves rollback simplicity. API resources can be added later without replacing the domain services.

## ADR-004 — Relational canonical model

**Decision:** use specialized relational tables for lifecycle-rich entities and the typed `work_records` kernel for governance semantics.

**Why:** actors, opportunities, proposals, projects, milestones, invoices, and transactions have different constraints and query paths. A generic JSON record store would weaken foreign keys, monetary precision, reporting, and data integrity. Work records stay generic where shared governance semantics are genuinely stable.

## ADR-005 — Defense-in-depth tenancy and authorization

**Decision:** organization global scopes, tenant-constrained validation, permission checks, and relational foreign keys all apply.

**Why:** authentication alone is not authorization. Laravel distinguishes gates/policies for resource actions; Atlas uses a compact role permission map plus controller checks today and can move resource rules into policies as the external role model expands. OWASP ASVS 5.0 is the verification baseline, not a certification claim.

Source: [Laravel authorization](https://laravel.com/docs/13.x/authorization), [OWASP ASVS](https://owasp.org/www-project-application-security-verification-standard/).

## ADR-006 — Private evidence by default

**Decision:** uploaded evidence stays on Laravel’s private local disk and is served only through authorized downloads.

**Why:** Laravel’s default local-disk root is `storage/app/private`; using a controller preserves tenant and permission checks. A future S3-compatible disk can replace local storage through the same filesystem API.

Source: [Laravel file storage](https://laravel.com/docs/13.x/filesystem).

## ADR-007 — Parallel WHM release

**Decision:** install v2 into a new directory, database, and temporary subdomain; cut over only after smoke testing.

**Why:** the supplied v1 has no production data to migrate, so a clean database is safer than an in-place mutation. cPanel supports domain document-root management and HTTPS redirects. Laravel requires the web server to expose only `public/`, writable `storage`/`bootstrap/cache`, production debug off, and optimized caches.

Source: [Laravel deployment](https://laravel.com/docs/13.x/deployment), [cPanel Domains](https://docs.cpanel.net/cpanel/domains/domains/), [cPanel PHP](https://docs.cpanel.net/ea4/php/about-php/).

## ADR-008 — Database queue/cache first

**Decision:** use database session, cache, and queue drivers; do not require Redis or a permanent worker in v2.

**Why:** current workflows are synchronous and low-volume. Redis and supervised workers are future performance tools, not current correctness requirements. Laravel’s scheduler needs one cron entry, while cPanel warns against overlapping jobs; scheduled commands should use Laravel overlap guards when introduced.

Source: [Laravel task scheduling](https://laravel.com/docs/13.x/scheduling), [cPanel Cron Jobs](https://docs.cpanel.net/cpanel/advanced/cron-jobs/).

## ADR-009 — English first, Arabic-ready

**Decision:** ship English content with locale identity, request locale middleware, semantic `lang`/`dir`, and RTL CSS.

**Why:** Laravel supports request-time locale switching and per-locale catalogs. Arabic copy should be translated only after terminology and review ownership are approved; architectural support exists now without shipping unverified language.

Source: [Laravel localization](https://laravel.com/docs/13.x/localization).

## ADR-010 — AI remains off

**Decision:** no live AI provider in the core release.

**Why:** the blueprints require evidence, bounded authority, cost controls, evaluation, and a kill switch. Deterministic workflow and finance logic must not depend on a model. The current seam permits future draft-only assistance after a separate governed activation decision.