Mini Vercel Clone

Overview

Problem

Core users

• Indie developers shipping small apps
• Students learning deployment systems
• Small teams that need preview deployments
• Builders who want to understand CI/CD internals

MVP scope

• GitHub repo import through OAuth or a GitHub App connection
• Project creation with build command and output directory configuration
• One build worker that can clone or download source, run install/build, and capture logs
• Static app deployment to S3/R2-style object storage
• Generated preview URL for each successful deployment
• Deployment history with status, duration, commit SHA, and manual redeploy
• Basic environment variable management for build-time values

Non-goals

• Do not support every framework initially
• Do not support complex team billing
• Do not build full Kubernetes orchestration at first
• Do not support arbitrary long-running backend services in the MVP
• Do not promise production-grade isolation until the worker sandbox is proven

Core system components

• Next.js dashboard for projects, deployments, logs, domains, and env vars
• API service for project metadata, deployment creation, webhooks, and permissions
• Git provider connection service for OAuth tokens, repo access, and webhook setup
• Build job queue using BullMQ, Inngest, Trigger.dev, or a Postgres-backed queue
• Build worker that runs dependency install, build command, log streaming, and artifact upload
• Object storage bucket for static build artifacts
• Router layer that maps generated hostnames to deployment artifact prefixes
• Postgres database for users, projects, deployments, domains, logs metadata, and env vars

Suggested architecture

• Frontend: a Next.js dashboard with project lists, deployment timelines, log views, domain setup, and environment variable forms.
• Backend: a REST or route-handler API that owns project metadata, deployment creation, GitHub webhook handling, auth checks, and build job enqueueing.
• Worker: an isolated build process pulls repo tarballs or clones GitHub repos, installs dependencies, runs the configured build command, captures logs, uploads output, and updates deployment status.
• Database: Postgres or Supabase stores users, projects, deployments, build metadata, domains, env var references, and provider connections.
• Queue: a durable job queue holds pending builds and lets workers retry, fail, or mark jobs as timed out.
• Storage: S3 or Cloudflare R2 stores static artifacts by project/deployment prefix.
• Runtime/Serving: MVP serves static files through object storage plus CDN. Later versions can route to containerized Node apps or serverless functions.
• External APIs: GitHub OAuth/GitHub App APIs for repo access, webhooks, commit metadata, and branch events.

Data model

• User: id, name, email, avatarUrl, createdAt
• GitProviderConnection: id, userId, provider, accessTokenRef, installationId, scopes, createdAt
• Project: id, ownerId, repoFullName, frameworkPreset, buildCommand, outputDirectory, rootDirectory, createdAt
• Deployment: id, projectId, commitSha, branch, status, artifactPrefix, previewUrl, startedAt, finishedAt
• BuildLog: id, deploymentId, sequence, stream, message, createdAt
• EnvironmentVariable: id, projectId, key, encryptedValue, scope, createdAt
• Domain: id, projectId, hostname, verifiedAt, targetDeploymentId

API design

• POST /api/projects - create a project from a GitHub repo
• GET /api/projects - list projects for the current user
• GET /api/projects/:id - load project settings and recent deployments
• POST /api/projects/:id/deployments - enqueue a manual deployment
• GET /api/deployments/:id - read deployment status and metadata
• GET /api/deployments/:id/logs - stream or page through build logs
• POST /api/github/webhook - validate GitHub events and enqueue builds
• POST /api/projects/:id/env - create or update encrypted env vars
• POST /api/projects/:id/domains - add a generated or custom domain

Key technical challenges

• Running untrusted build commands safely
• Capturing build logs in real time without losing ordering
• Preventing runaway builds with CPU, memory, time, and output limits
• Handling environment variables securely in workers
• Mapping generated URLs to immutable deployments
• Caching dependencies without sharing unsafe state between projects
• Supporting multiple frameworks without brittle detection logic

Tradeoffs

• Start with static deployments because they are easier to isolate, cheaper to serve, and simpler to cache.
• Use one queue and one worker first so the build lifecycle stays understandable before adding distributed workers.
• Use generated URLs before custom domains to avoid DNS and certificate complexity in the MVP.
• Prefer explicit build configuration over magical framework detection until real usage patterns are visible.

Security considerations

• Sandbox builds in containers or another isolated runtime.
• Enforce CPU, memory, disk, network, and time limits for every build.
• Encrypt environment variables and only decrypt inside the build worker.
• Validate GitHub webhook signatures and ignore events from unknown installations.
• Isolate project artifacts by deployment prefix and never let one project read another project's output.
• Rate-limit deploy requests and reject suspicious build output volume.

Scaling path

• Start with one worker and a single object storage bucket.
• Move to distributed workers with queue priority and per-plan concurrency limits.
• Add build cache, dependency cache, and artifact deduplication.
• Add CDN invalidation and immutable deployment URLs.
• Add preview branch automation, custom domains, and eventually containerized runtime services.

Observability

• Structured logs for API actions, queue events, worker steps, and router misses.
• Metrics for build duration, failure rate, queue depth, cache hits, and artifact size.
• Trace IDs passed from deployment creation to worker logs.
• Audit logs for env var changes, domain changes, and manual redeploys.
• Admin dashboard for stuck builds, failing workers, and webhook delivery failures.

Future features

• Branch preview automation
• Custom domains with certificate provisioning
• Build cache and dependency cache
• Framework presets for Next.js, Vite, Astro, and static HTML
• Serverless functions or containerized app runtime
• Team permissions and project transfer

Related projects