# Architecture Evolution And Runtime Status Last verified against repository code and configuration: 2026-08-05. This document is the canonical status map for StratoFusion's production runtime. It preserves the previous Vercel, Neon, and Fly.io design while distinguishing it from the current VM deployment and from migration mechanisms that remain in the repository for compatibility or rollback. ## Status Vocabulary - **Current**: implemented in the active production configuration. - **Legacy**: previously authoritative and retained only for history, recovery, or compatibility. - **Transitional**: implemented to support rehearsal, cutover, or rollback, but not part of normal production operation. - **Planned**: described as a possible future state without an active production implementation in this repository. When another document conflicts with this status map, use this document with [Deployment](./DEPLOYMENT.md) and the executable files listed under [Verification Evidence](#verification-evidence). ## Current VM Architecture Production runs as a single-host Docker Compose stack on an OVHcloud VM. ```text Browser | v Caddy (public TLS and routing) |-- stratofusion.io ----------> Next.js app (control plane) |-- rclone.stratofusion.io ---> rclone worker (data plane) |-- grafana.stratofusion.io --> Grafana `-- glitchtip.stratofusion.io -> GlitchTip Next.js app ----> Compose PostgreSQL |--> provider APIs and Clerk/Stripe |--> Compose Weaviate when AI Search is enabled `--> rclone worker through the authenticated service contract Compose cron ----> authenticated Next.js cron routes Compose backup --> PostgreSQL dumps and configured offsite storage Prometheus ------> rclone and host metrics ----> Grafana ``` ### Responsibilities And Boundaries | Boundary | Current responsibility | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Next.js control plane | Authentication, ownership, provider/account validation, quota and conflict policy, durable job state, rclone request construction, progress orchestration, and UI/API delivery. | | Provider services and adapters | Translate Google Drive, OneDrive, Dropbox, and other provider behavior into canonical models. Provider-native IDs and quirks stay outside render components. | | rclone data plane | Execute byte-heavy copy, move, backup, sync, bisync, upload, and download work from pre-resolved inputs. Track bounded operation state and progress. | | PostgreSQL | Authoritative production application, job, quota, subscription, OAuth projection, and operation state. GlitchTip uses a separate database in the same PostgreSQL service. | | Caddy | Terminate public TLS and route app, rclone, Grafana, and GlitchTip hostnames. Preserve unbuffered rclone streaming. | | Compose cron | Run the production schedules that previously ran through Vercel Cron. Exactly one replica is the normal production invariant. | | Observability and backup | Prometheus, Grafana, GlitchTip, node-exporter, and the backup container run in the VM stack. Offsite backup remains outside the VM failure domain. | ### Deployment And Scaling - A push to `main`, or a manual recovery dispatch, builds immutable app and rclone images and pushes Git-SHA and `latest` tags to GHCR. - The deploy job runs only when the repository variable `VM_DEPLOY_ENABLED` is `true`, resets `/opt/stratofusion` to the exact workflow SHA, and invokes the drain-gated VM deploy script with that immutable tag. - The current stack scales vertically within one VM. Compose resource limits isolate services, and the production rclone worker serializes heavy child operations with `MAX_CONCURRENT_OPERATIONS=1`. - The repository does not implement an active multi-VM production cluster, automatic rclone horizontal scaling, or automatic database failover. ### Security And Failure Handling - Public TLS terminates at Caddy. Application containers communicate on the private Compose network. - Protected rclone routes still use the service API key contract inherited from the Fly implementation. Temporary rclone configs and provider credentials are handled by the worker and must not appear in logs or documentation. - VM administration is separate from public application ingress. Use key-only SSH and the private Tailscale management plane documented in [VM Administration](./operations/VM_ADMIN_ACCESS.md). - Deployments drain active rclone operations before replacing the worker and give it a five-minute shutdown grace period. - The VM is a larger single failure domain than the previous managed split. PostgreSQL dumps, offsite copies, exact image revisions, monitoring, and a tested restore procedure are therefore part of the production boundary. - A production write occurred after cutover. Repointing DNS to the legacy stack without reconciling databases is not a safe rollback. ## Previous Fly.io Container Architecture Before the Phase-C cutover, production was split across managed services: ```text Browser --> Vercel Next.js control plane --> Neon PostgreSQL | `--> Fly.io rclone service --> provider APIs Vercel Cron --> Next.js cron routes Fly Proxy --> one or more Fly Machines ``` The separation between control plane and data plane remains architecturally valid. What changed is the hosting boundary: the same rclone service now runs inside the VM Compose stack rather than on active Fly Machines. ### Legacy Responsibilities - Vercel hosted the production Next.js application and production schedules. - Neon was the authoritative production PostgreSQL service. - Separate Fly.io development and production apps hosted the rclone worker. - Fly Proxy and Machine settings supplied the worker ingress, lifecycle, and optional burst-capacity model. - Managed platform logs and deployment dashboards were part of normal operations. ### Why It Is Preserved The legacy design explains current names such as `FLYIO_RCLONE_SERVICE_URL`, `FlyioRcloneClient`, `fly-rclone/`, Fly-oriented test fixtures, and historical feature reports. Renaming those stable contracts was not required for the hosting migration. In current operational prose, **rclone service** or **rclone worker** means the hosting-neutral component; **Fly.io rclone** means the retained legacy deployment specifically. The legacy Vercel production project, Neon production data, and stopped Fly apps remain recovery evidence and rollback inputs. They are not independently authoritative, and the Fly apps must not be probed or restarted during normal operation. ## Transitional And Hybrid Behavior The following mechanisms are implemented but are not the normal production runtime: - `vm-staging.*` and `vm-rclone.*` hostnames preserve the Phase-B rehearsal and initial rollback path. - `OAUTH_REHEARSAL_ORIGIN` supports only the exact public rehearsal origin or the local-VM rehearsal origin. Normal production leaves it empty. - `LEGACY_PRODUCTION_WRITE_FREEZE` exists only to freeze the former Vercel production runtime during a controlled restore or reconciliation. - `deploy/restore-from-neon.sh` and cutover validation scripts preserve the database migration procedure; they do not make Neon the current database. - The former Vercel/Neon shared-development environment is retired from active repository policy. Its external resources remain only until the staged, approval-gated retirement runbook is completed. - Historical worklogs under `docs/` retain evidence and commands from the rehearsal and cutover. Their time-bound instructions do not override current operations documentation. ## Planned Or Unimplemented Architecture The following items appear in plans or comments but are not active production architecture: - automatic multi-Machine Fly scaling or the optional `fly-autoscaler` app; - an active-active or multi-host VM application/data-plane cluster; - automated PostgreSQL failover; - a permanent replacement shared-development runtime, which current repository policy explicitly rejects in favor of local development, CI, and temporary approval-gated staging only; - deletion of legacy Vercel, Neon, Fly, rehearsal-DNS, or rollback resources; - provider shells or AI Search capabilities explicitly marked future or gated in their subsystem documentation. Resource deletion and destructive retirement remain approval-gated. A plan, prompt, checklist, or environment variable is not evidence that its target state is implemented. ## Architecture Comparison | Concern | Current VM architecture | Previous managed architecture | Migration/compatibility consequence | | ------------------- | --------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- | | Application hosting | Next.js container on OVHcloud VM | Vercel production | Vercel project retained as legacy configuration, not normal release target. | | Data plane | rclone container in Compose | Fly.io Machines | Service API and legacy `Fly*` names remain compatible. | | Database | Compose PostgreSQL | Neon production | Rollback requires database reconciliation after the first VM write. | | Scheduler | One Compose cron replica | Vercel Cron | `vercel.json` and old cron docs are historical compatibility material. | | Public ingress | Caddy on the VM | Vercel and Fly proxy ingress | Canonical app and rclone hosts now resolve to the VM. | | Scaling | Single-host vertical limits; serialized heavy rclone work | Managed app elasticity and optional Fly Machine scaling | Capacity planning and host failure are now operator responsibilities. | | Observability | Prometheus, Grafana, GlitchTip, node-exporter | Managed platform logs plus external tooling | VM monitoring and backup health are production dependencies. | | Deployment | GitHub Actions, GHCR, exact-SHA SSH deployment | Vercel and Fly deployment workflows | Fly deployment is manual recovery only. | | Recovery | Image rollback plus database/backup reconciliation | Managed deployment rollback and Neon/Fly state | DNS-only rollback is unsafe after post-cutover writes. | ## Environment Applicability | Environment or use case | Architecture to use | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Production | Current VM architecture. | | Local development | Local Next.js, local PostgreSQL, and local rclone processes on Windows. | | Local-VM rehearsal | Optional local Compose/TLS rehearsal using the exact documented local-VM origin and test integrations. | | CI validation | Ephemeral validation only; CI is not an application deployment and has no provider callbacks. | | Temporary staging | Only an explicitly approved, time-bounded migration or rehearsal. It must not become a permanent deployment on the production VM. | | Approved production recovery | Start from current VM backups and exact revisions. Use legacy Vercel/Neon/Fly only with an explicit reconciliation and recovery plan. | | Historical debugging | Use dated reports and worklogs for the behavior at their recorded time, then reconcile with current canonical docs. | ## Verification Evidence The current classification is supported by executable repository state: - `.github/workflows/deploy.yml`: builds and deploys the authoritative VM stack from `main` with production app and rclone hostnames. - `deploy/docker-compose.prod.yml`: defines app, rclone, PostgreSQL, Weaviate, Caddy, cron, backup, and observability services. - `deploy/Caddyfile`: routes the canonical production hostnames to Compose services and disables buffering for rclone streaming. - `deploy/deploy.sh`: requires an immutable SHA, drains rclone work, rolls the stack, refreshes Caddy, and checks application health. - `.github/workflows/fly-rclone-deploy.yml`: manual-only legacy recovery with an explicit paid-capacity confirmation. - `fly-rclone/fly.toml` and `fly-rclone/fly.prod.toml`: retained configs disable Machine auto-start and keep zero minimum Machines. - `src/lib/rclone/core/flyio-client.ts`: preserves the stable client contract while reading the runtime-selected rclone base URL. For current environment values and operational steps, continue with [Deployment](./DEPLOYMENT.md), [Rclone Service](./RCLONE_SERVICE.md), and the [Production VM Runbook](./operations/VM_PRODUCTION_RUNBOOK.md).