ritikaxg/spinup

Purpose and topology

SpinUp is a control-plane-first cloud developer-workspace platform. A Clerk-authenticated browser request creates or resumes a project; the Next.js control plane provisions an EC2-backed code-server workspace and exposes it through its VM public IP. The monorepo contains the web control plane, VM workspace image/bootstrap, Prisma database package, and starter app artifacts.

Product/API entry points

The browser enters through the landing and project dashboard/detail routes: apps/web/app/page.tsx, apps/web/app/projects/page.tsx, and apps/web/app/projects/[projectId]/page.tsx. Project commands enter API routes at apps/web/app/api/project/route.ts and state polling reads apps/web/app/api/project/[projectId]/route.ts. Clerk protection is applied through apps/web/middleware.ts.

Control-plane orchestration

apps/web/services/projectControlPlane.ts is the primary create/resume/delete coordinator. It validates requests, enforces the V1 one-active-runtime-per-user constraint, acquires runtime/create locks, and drives lifecycle transitions. apps/web/services/projectLifecycleManager.ts persists transitions and lifecycle events; apps/web/services/projectRuntimeTruthSource.ts reconciles runtime-facing truth with persisted state. The lifecycle boundary is explicit: CREATED → ALLOCATING_VM → BOOTING_CONTAINER → READY, with failure, stop, deletion, and retry/resume paths.

Allocation and runtime plane

VM allocation is isolated from product/API code. apps/web/services/ec2Manager.ts obtains/reuses instances, waits for public IP, VM-agent health, and workspace readiness. apps/web/services/asgManager.ts makes Auto Scaling Group capacity decisions, backed by AWS adapters in apps/web/lib/aws/asgClient.ts, apps/web/lib/aws/ec2Commands.ts, and apps/web/lib/aws/s3Commands.ts. The control plane calls the agent over HTTP through apps/web/lib/vmAgent/client.ts; agents run on EC2 port 3000 and start Docker containers rather than exposing Docker control directly to the web service.

Persistence, locking, and recovery

Postgres is the authoritative record for users, projects, rooms, assignments, lifecycle fields, and event history, defined in packages/db/prisma/schema.prisma and exported via packages/db/index.ts. Redis is deliberately a non-authoritative coordination/cache layer for distributed locks, runtime assignment mirrors, and cleanup coordination in apps/web/services/redisManager.ts. Background reconciliation and liveness handling are separated into apps/web/services/controlPlaneReconciler.ts, apps/web/services/runtimeHeartbeatManager.ts, and worker entry point apps/web/scripts/control-plane-worker.ts.

Workspace container bootstrap and artifact persistence

The VM agent launches a project-specific code-server container from the workspace bootstrap layer in apps/vm-base-config. apps/vm-base-config/docker/Dockerfile.codeserver defines the runtime image; apps/vm-base-config/entrypoint.sh initializes each workspace; apps/vm-base-config/scripts/startProjectSync.ts supports project-file synchronization. Containers restore project code from S3 or seed it from framework templates, install dependencies, sync changes back to S3, and run code-server on port 8080. Templates cover Next.js, React, and React Native under apps/vm-base-config/base-app.

UI/runtime observation and infrastructure

The UI treats projects as runtime objects: project cards/actions, boot progress, status display, polling, and IDE embedding live under apps/web/app/components/projects, apps/web/app/hooks/useProjectPolling.ts, and apps/web/app/vmWrapper.tsx. Material infrastructure is Next.js/React/TypeScript, Bun, Docker Compose, Prisma/Postgres, Redis, AWS EC2/ASG/S3, Docker/code-server, and Clerk. Local control-plane dependencies are composed in docker-compose.yml; actual workspace execution remains on the AWS VM/AMI/ASG path.