01-Platform-Strategy
🔒
Repolished. Production infrastructure is locked in B0 — Production Infrastructure (CentOS + LiteSpeed + Laravel + MySQL). Where this page disagrees with B0, B0 wins. Earlier wording calling the product "iPhone-first" or naming PostgreSQL/Nginx as default is superseded.
🏗️
Web-first, mobile-supported. Decisions here are binding for the rest of the spec. The Laravel Control Center is the primary operator surface; the iPhone app is a fully-featured remote with full parity over the same API.
1. Build order
- Production infrastructure (B0) — CentOS-compatible Linux + LiteSpeed + lsphp 8.3 + MySQL/MariaDB + Redis + Supervisor + Let's Encrypt.
- Backend API + admin shell (Laravel 11, B1) — projects, runs, events, files, snapshots, RAG, providers, Git, docs auto-update, server params, API tokens, Filament admin.
- Web Control Center (Livewire 3 + Reverb, B5) — live console, diff viewer, plan/approve, RAG inspector. Part of v1.
- iPhone client (SwiftUI, B6) — driven entirely by the same API; full parity with the Control Center.
Android is not in v1.
2. Backend stack
| Layer | Choice | Reason |
|---|---|---|
| Framework | Laravel 11 (or latest stable) | Mature HTTP/queue/auth, Sanctum, Horizon. |
| Auth | Laravel Sanctum (personal access tokens) | Native fit for mobile + API tokens. |
| Web server | LiteSpeed Web Server 6.x (OpenLiteSpeed or Enterprise) + lsphp 8.3 via LSAPI | Locked in B0. Nginx/Apache/PHP-FPM are not supported in prod. |
| Operating system | CentOS-compatible Linux (AlmaLinux 9 / Rocky 9) | SELinux enforcing; RPM packaging. |
| Primary DB | MySQL 8.0 or MariaDB 11.4+ | Default. JSON columns, utf8mb4, InnoDB. |
| Vector store | MySQL JSON column (default) → app-layer cosine similarity | Driver-aware. Opt-in upgrade to PostgreSQL 16 + pgvector when a project exceeds ~50k chunks. |
| Cache / queue / pubsub | Redis 7 | Queues, locks, SSE fan-out. |
| Jobs | Laravel Horizon | Long-running agent jobs, observable. |
| Object storage | S3-compatible | Snapshot archives, downloadable logs. |
| AI: chat | OpenAI API • Anthropic API | Provider-agnostic interface. |
| AI: embeddings | OpenAI text-embedding-3-large (configurable) | Strong recall on code/docs. |
| Claude Code | Local adapter via CLI / SDK | Wrapped in ClaudeCodeAgentService. |
| Git | Server-side git binary via GitService | Sandboxed working dirs. |
| Process exec | symfony/process with allowlist | Timeouts + signal handling. |
| Streaming | SSE (primary) + WebSocket optional | Simpler, mobile-friendly. |
| Testing | PHPUnit + Pest + HTTP feature tests | Required for every service. |
Vector storage — default and upgrade path
RAG storage is abstracted behind RagContextService and the rag_chunks migration is driver-aware:
- Default (MySQL/MariaDB):
embeddingis aJSONcolumn. Cosine similarity is computed in the app layer (FastVector / PHP). Works to ~50k chunks per project.
- Upgrade path (PostgreSQL 16 + pgvector): flip
DB_CONNECTION=pgsqland runphp artisan agent:reindex --all. The same migration createsembedding vector(3072)and anivfflatindex.
- Future: MariaDB 11.7+ vector indexes when GA in the host distro.
No Qdrant/Milvus/Weaviate sidecar in v1.
3. iPhone stack
| Layer | Choice |
|---|---|
| UI | SwiftUI (iOS 17+) |
| Architecture | MVVM + @Observable view models + Swift Concurrency (async/await) |
| Networking | URLSession • a typed APIClient |
| Live events | URLSession SSE reader (line-by-line) |
| Auth | Token in Keychain |
| Storage | SwiftData / Core Data for local caches |
| Diff viewer | Custom UnifiedDiffView (text first; syntax later) |
| Notifications | APNs for run-state changes (optional, v1.1) |
4. Environments
| Env | Purpose | Web server | DB | Notes |
|---|---|---|---|---|
local | Dev | php artisan serve or LSWS in Docker | MySQL 8 in Docker | RAG ON, real OpenAI key optional, mock provider available. |
staging | Pre-prod | LiteSpeed + lsphp 8.3 on CentOS-compatible | MySQL 8 / MariaDB 11.4+ | Real keys, throttled, public push disabled. |
production | Prod | LiteSpeed + lsphp 8.3 on CentOS-compatible (AlmaLinux 9 / Rocky 9) | MySQL 8 / MariaDB 11.4+ (managed or self-hosted) | Snapshots to local disk + optional S3 mirror; Horizon + Reverb supervised by Supervisor. SSL via Let's Encrypt. |
5. Process supervision
php artisan horizonruns the agent queues:agents-default,agents-long,rag-index,docs.
- Long agent runs use the
agents-longqueue with a long timeout and a Horizon supervisor configured for it.
- One agent per project workspace at a time, enforced by a Redis lock
workspace:lock:{project_id}with a TTL.
6. Configuration / secrets
- All credentials come from server params (see
08 — Server Params & Configuration).
- Nothing is hardcoded.
.envholds only bootstrap values (DB connection, Redis URL, app key).
- Tokens and API keys live in the
agent_settingstable (encrypted) and are surfaced throughconfig/agent_workspace.phpvia a custom config repository.
7. Folder layout target
See section 6 of the master Spec Pack page. Production on-disk layout (/var/www/agent-workspace/{current,releases,shared,logs}/...) is defined in B0 §3.
8. Coding standards
- PSR-12 + Laravel Pint.
- All services constructor-injected. No facades inside services; facades only in controllers/jobs.
- Strict types declared at the top of every PHP file.
- Every public service method has a Pest test.
- No business logic in controllers.
- Every migration is reversible.