How akram6t/deployr works
1. Overall shape
- This is a multi-service deployment platform, organized into a control plane and a serving plane.
- The control plane is the authenticated product UI plus API; the serving plane is the build worker and reverse proxy that actually turns user projects into runnable, routable deployments.
2. Frontend: frontend-nextjs
- A Next.js app that serves both the public marketing site and the logged-in dashboard.
- Public routes include home, pricing, docs, blog, about, and login.
- Auth is handled through pages/api/auth/[...nextauth].ts, so the UI owns the user sign-in flow while the backend handles platform data.
- The dashboard is project-centric: overview, analytics, deployments, deployment detail, settings, and a deploy screen.
3. API backend: api-server
- A TypeScript Node service exposing the platform’s REST API.
- The API is split by domain into controllers for users, projects, and deployments, with request validation schemas and shared route registration.
- Prisma (prisma/schema.prisma) indicates a relational database-backed metadata layer for users, projects, deployments, and related records.
- Authentication is enforced at the API boundary via authMiddleware, so the backend is the source of truth for protected actions.
4. Deployment orchestration
- The API is the coordinator for deployment lifecycle events: creating deployments, tracking status, and likely associating a project with a generated subdomain or custom domain.
- Helpers like generateSubdomain and getRepoNameFromUrl suggest the system maps source repositories to deployable project identities and tenant URLs.
5. Build execution: build-server
- This is a separate Dockerized build worker rather than part of the API or frontend.
- Its purpose is to compile user applications and produce deployable artifacts.
- Because it has a Dockerfile, shell entrypoint, and standalone script, it is meant to run isolated build jobs, matching the README’s emphasis on Cloud Run Jobs for serverless build execution.
6. Traffic serving and tenant routing: reverse-proxy-server
- This service routes incoming requests for subdomains and custom domains to the correct deployment assets.
- It includes a not-found.html fallback and utilities for caching and analytics, which suggests it handles high-volume request routing at the edge.
- The mention of streaming instead of full HTTP proxying indicates it serves static assets in a memory-efficient way.
7. State and data stores
- Relational DB via Prisma: system-of-record for platform entities like users, projects, and deployments.
- Cloud Storage: stores built static assets and deployment output.
- Redis: used as a cache to reduce database load and speed up lookups.
- BigQuery: stores analytics and higher-volume event data for reporting.
- Pub/Sub: acts as the event pipeline for pushing deployment or request events into downstream processing/analytics.
8. Analytics pipeline
- The API contains bigquery service code plus pubsub-to-bigquery utilities, which implies event ingestion is asynchronous rather than inline.
- The reverse proxy also has analytics utilities, so request/usage telemetry is likely captured at the serving edge and forwarded into the analytics pipeline.
9. Cloud and deployment infrastructure
- The architecture is explicitly built around Google Cloud: Cloud Run Jobs, Artifact Registry, Cloud Storage, Pub/Sub, BigQuery, Load Balancer, and Cloud CDN.
- Artifact Registry stores build images, Cloud Run Jobs executes builds, Cloud Storage hosts the generated deployment artifacts, and Cloud CDN/load balancer distribute traffic to the reverse proxy and cached assets.
10. Primary end-to-end flow
- A user signs in through the Next.js frontend.
- The frontend calls the API to create/manage a project and trigger a deployment.
- The API schedules a build job and tracks deployment state in the database.
- The build worker produces artifacts and uploads them to Cloud Storage.
- The reverse proxy resolves the tenant domain/subdomain and serves the matching deployment output.
- Analytics events are collected separately and loaded into BigQuery.
11. Architectural boundary to highlight in a diagram
- Left side: browser-facing product UI and authentication.
- Middle: API control plane and metadata database.
- Right side: build/serve runtime with Cloud Run Jobs, Cloud Storage, and the reverse proxy.
- Cross-cutting: Redis caching, Pub/Sub eventing, and BigQuery analytics.
Main entry points: index.ts Routes · index.js Reverse proxy · frontend-nextjs Frontend · src API server
Components 18
Control plane
Authenticated product UI and API that manage projects and deployments.
- Frontend · Public marketing site, login flow, and authenticated dashboard.
frontend-nextjs - Auth route · Browser sign-in flow handled inside the frontend app.
frontend-nextjs/pages/api/auth/[...nextauth].ts - Dashboard · Project-centric views for overview, analytics, deployments, settings, and deploy actions.
frontend-nextjs/pages/dashboard - Marketing pages · Home, pricing, docs, blog, about, and login pages.
frontend-nextjs/pages - API server · Typed REST backend for platform control and metadata.
api-server/src - Routes · Shared route registration that wires controllers and middleware.
api-server/src/routes/index.ts - Users · User-related API operations.
api-server/src/controllers/userController.ts - Projects · Project CRUD and repository identity mapping.
api-server/src/controllers/projectController.ts - Deployments · Deployment lifecycle, status tracking, and orchestration endpoints.
api-server/src/controllers/deploymentController.ts - Auth guard · API boundary enforcement for protected actions.
api-server/src/utils/authMiddleware.ts
Serving plane
Build and request-serving runtime for deployed user projects.
- Build worker · Standalone build executor that compiles user apps and produces artifacts.
build-server - Reverse proxy · Routes tenant domains and subdomains to the correct deployment output.
reverse-proxy-server/index.js - Proxy cache · In-memory lookup acceleration for routing and metadata.
reverse-proxy-server/utils/lru-cache.js - Edge analytics · Request and usage telemetry emitted from the serving edge.
reverse-proxy-server/utils/analytics.js
Data & cloud
Persistent stores and managed cloud services used across the platform.
- Prisma DB · Relational metadata model for users, projects, deployments, and related records.
api-server/prisma/schema.prisma - Build jobs · Job launcher used to execute isolated builds.
api-server/src/utils/cloud-run-jobs.ts - BigQuery · Warehouse for analytics and higher-volume event reporting.
api-server/src/services/bigquery.ts - Pub/Sub pipe · Async event transport for deployment and analytics ingestion.
api-server/src/utils/pubsub-to-bigquery.ts
Connections 21
- Marketing pages → Frontend: renders · Public site is part of the main frontend application.
- Dashboard → Frontend: renders · Authenticated dashboard routes live in the frontend app.
- Auth route → Frontend: auth in UI · User sign-in is hosted by the frontend.
- Frontend → API server: calls · UI reads and mutates platform state through the backend API.
- API server → Routes: registers · Server startup wires routes through a shared router layer.
- Routes → Users: mounts · User domain endpoints are registered here.
- Routes → Projects: mounts · Project domain endpoints are registered here.
- Routes → Deployments: mounts · Deployment domain endpoints are registered here.
- Routes → Auth guard: protects · Protected routes are enforced by auth middleware.
- Users → Prisma DB: reads/writes · User records are stored in the relational metadata model.
- Projects → Prisma DB: reads/writes · Project metadata and repo identity are persisted in the database.
- Deployments → Prisma DB: tracks · Deployment lifecycle state is persisted in the database.
- Projects → Build jobs: triggers · Project deploy actions schedule isolated build jobs.
- Build jobs → Build worker: executes · Cloud Run runs the standalone build worker container.
- Build worker → Reverse proxy: publishes · Build output becomes available to the serving layer.
- Reverse proxy → Proxy cache: accelerates · Routing and lookup data are cached in memory.
- Reverse proxy → Edge analytics: emits · Serving edge records request telemetry.
- Edge analytics → Pub/Sub pipe: streams · Telemetry is sent through async event transport.
- Pub/Sub pipe → BigQuery: loads · Events are materialized into the analytics warehouse.
- API server → Pub/Sub pipe: publishes · Deployment and platform events are emitted asynchronously.
- Deployments → Reverse proxy: routes to · Deployment records correspond to tenant traffic destinations.