# Architecture and route map

## Architecture

Laravel 13, PHP 8.3+, Blade, Livewire, Alpine only for small client-side behavior, Tailwind, MySQL/MariaDB, Laravel mail/notifications/filesystem, database queue, and cPanel scheduler. No external package is required beyond Laravel and Livewire: Livewire is required for progressive interactive forms and review interfaces and runs in normal PHP requests—no Redis, Docker, or permanent process.

Each user belongs to a workspace through `workspace_user`. Client contacts are users tied to a single `client_id`; team users are workspace users with a role. Policies scope every model through its workspace/client relationship. Services own transitions, invitations, approvals, delivery, and invoice totals.

## Route map

| Group | Prefix | Middleware | Examples |
|---|---|---|---|
| Public | `/` | guest/throttle | login, password reset, invitation acceptance |
| Team app | `/app` | auth, verified, active-user, team-member | dashboard, clients, projects, calendar, queue, team, invoices, activity, settings |
| Client portal | `/portal` | auth, verified, active-user, client-contact | overview, request, projects, files, invoices, profile, account |
| File download | `/files/{file}/download` | auth, file policy | private, auditable download |
| Invitations | `/invitations/{token}` | signed rate limited guest | acceptance only; token lookup is hashed |

## State ownership

`ProjectWorkflowService` validates server-side transitions. `InvitationService` issues/revokes token hashes. `FileService` validates and stores uploads. `RevisionService`, `ApprovalService`, and `DeliveryService` perform transactional state changes and create immutable activity events.