Architecture

Control plane

Laravel modules, authoritative stores, secrets infrastructure, and reliable orchestration.

v1 design baseline. This page specifies intended behavior. Delivery and validation are tracked in the implementation plan; it is not a claim that the platform is already implemented.

Architectural style

Use a modular Laravel monolith, not premature microservices.

Laravel owns orchestration, state transitions, authorization, the API, Filament, MCP operations, audit recording, and workflow decisions.

Separate processes are justified only where the trust boundary or runtime requirements differ:

Public app gateway
Runtime agent
Sandbox runner
SQLite binding service
KV binding service
Egress proxy
Telemetry collector

This keeps the business model and authorization logic cohesive while isolating security-sensitive execution code.

Control-plane modules

Organizations
Identity
Authorization
Applications
Source
Change Sets
Builds
Artifacts
Deployments
Runtime Clusters
Data
Capabilities
Policies
Approvals
Secrets and Integrations
Audit
Usage and Quotas
Billing
Notifications
MCP
Developer Integrations

Each module exposes application-level commands and queries. Filament, REST, MCP, and a future CLI call those same application services.

There must not be separate implementations of CreateApp or RequestDeployment for each interface.

Core infrastructure

PostgreSQL

Authoritative system of record for:

Organizations and memberships
IdP configuration
Apps and environments
Source metadata
Builds and deployments
Policy and approval state
Runtime desired state
Audit metadata
Quotas and usage summaries

Application business data does not live in this database.

Valkey

Used for:

Laravel queues
Short-lived caches
Distributed locks
Rate-limit counters
Session/cache material where appropriate
Command dispatch acceleration

PostgreSQL remains authoritative for state transitions.

Object storage

S3-compatible object storage holds:

Content-addressed build artifacts
Static assets
SBOMs
Scanner reports
Export packages
Encrypted database snapshots
Archived logs
Source bundles where necessary

Artifacts are immutable and addressed by digest.

Forgejo

Hidden source-control backend for managed applications.

Forgejo is not the source of truth for intrnl authorization. The control plane owns membership, app ownership, and permission decisions.

KMS/secrets system

Used for:

Encryption-envelope keys
Signing keys
OIDC client secrets
GitHub App private keys
Runtime cluster certificates
Integration credentials
Raw application secrets where unavoidable

Customer secrets are encrypted with per-organization or per-integration data keys wrapped by the platform key hierarchy.

Reliable orchestration

Use:

Transactional outbox
Idempotent command handlers
Runtime command acknowledgements
Reconciliation loops
Optimistic version columns
Idempotency keys on mutating public APIs

A deployment request should be persisted atomically with its outbox event. Failure to dispatch immediately must not lose the operation.

Runtime clusters periodically reconcile their actual workloads against the desired state held by the control plane. This prevents a temporary queue or network failure from leaving the cluster permanently inconsistent.

Trust zones

Security responsibilities of management, builds, runtimes, bindings, and external AI clients.

Organization tenancy

Tenant context, authorization, row-level security, immutable identifiers, and tenant isolation.