# akram6t/deployr architecture

> Architecture diagram of the GitHub repository akram6t/deployr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akram6t/deployr
- Repository: https://github.com/akram6t/deployr

## Overview

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: [`api-server/src/routes/index.ts`](https://github.com/akram6t/deployr/blob/main/api-server/src/routes/index.ts) (Routes), [`reverse-proxy-server/index.js`](https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/index.js) (Reverse proxy), [`frontend-nextjs`](https://github.com/akram6t/deployr/tree/main/frontend-nextjs) (Frontend), [`api-server/src`](https://github.com/akram6t/deployr/tree/main/api-server/src) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_frontend["Frontend<br/>Next.js app"]
  node_nextauth["Auth route<br/>NextAuth endpoint<br/>[[...nextauth].ts]"]
  node_dashboard["Dashboard<br/>project UI"]
  node_marketing["Marketing pages<br/>public UI"]
  node_api["API server<br/>Node API"]
  node_routes["Routes<br/>routing layer<br/>[index.ts]"]
  node_users["Users<br/>controller<br/>[userController.ts]"]
  node_projects["Projects<br/>controller"]
  node_deployments["Deployments<br/>controller"]
  node_auth["Auth guard<br/>middleware<br/>[authMiddleware.ts]"]
end

subgraph group_runtime["Serving plane"]
  node_build["Build worker<br/>Dockerized worker"]
  node_proxy["Reverse proxy<br/>edge server<br/>[index.js]"]
  node_cache(("Proxy cache<br/>LRU cache<br/>[lru-cache.js]"))
  node_analytics["Edge analytics<br/>telemetry utils<br/>[analytics.js]"]
end

subgraph group_infra["Data & cloud"]
  node_prisma[("Prisma DB<br/>schema<br/>[schema.prisma]")]
  node_cloudrun["Build jobs<br/>Cloud Run jobs<br/>[cloud-run-jobs.ts]"]
  node_bigquery[("BigQuery<br/>analytics store<br/>[bigquery.ts]")]
  node_pubsub["Pub/Sub pipe<br/>event pipeline"]
end

node_marketing -->|"renders"| node_frontend
node_dashboard -->|"renders"| node_frontend
node_nextauth -->|"auth in UI"| node_frontend
node_frontend -->|"calls"| node_api
node_api -->|"registers"| node_routes
node_routes -->|"mounts"| node_users
node_routes -->|"mounts"| node_projects
node_routes -->|"mounts"| node_deployments
node_routes -->|"protects"| node_auth
node_users -->|"reads/writes"| node_prisma
node_projects -->|"reads/writes"| node_prisma
node_deployments -->|"tracks"| node_prisma
node_projects -->|"triggers"| node_cloudrun
node_cloudrun -->|"executes"| node_build
node_build -->|"publishes"| node_proxy
node_proxy -->|"accelerates"| node_cache
node_proxy -->|"emits"| node_analytics
node_analytics -->|"streams"| node_pubsub
node_pubsub -->|"loads"| node_bigquery
node_api -->|"publishes"| node_pubsub
node_deployments -->|"routes to"| node_proxy

click node_frontend "https://github.com/akram6t/deployr/tree/main/frontend-nextjs"
click node_nextauth "https://github.com/akram6t/deployr/blob/main/frontend-nextjs/pages/api/auth/[...nextauth].ts"
click node_dashboard "https://github.com/akram6t/deployr/tree/main/frontend-nextjs/pages/dashboard"
click node_marketing "https://github.com/akram6t/deployr/tree/main/frontend-nextjs/pages"
click node_api "https://github.com/akram6t/deployr/tree/main/api-server/src"
click node_routes "https://github.com/akram6t/deployr/blob/main/api-server/src/routes/index.ts"
click node_users "https://github.com/akram6t/deployr/blob/main/api-server/src/controllers/userController.ts"
click node_projects "https://github.com/akram6t/deployr/blob/main/api-server/src/controllers/projectController.ts"
click node_deployments "https://github.com/akram6t/deployr/blob/main/api-server/src/controllers/deploymentController.ts"
click node_auth "https://github.com/akram6t/deployr/blob/main/api-server/src/utils/authMiddleware.ts"
click node_prisma "https://github.com/akram6t/deployr/blob/main/api-server/prisma/schema.prisma"
click node_cloudrun "https://github.com/akram6t/deployr/blob/main/api-server/src/utils/cloud-run-jobs.ts"
click node_bigquery "https://github.com/akram6t/deployr/blob/main/api-server/src/services/bigquery.ts"
click node_pubsub "https://github.com/akram6t/deployr/blob/main/api-server/src/utils/pubsub-to-bigquery.ts"
click node_build "https://github.com/akram6t/deployr/tree/main/build-server"
click node_proxy "https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/index.js"
click node_cache "https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/utils/lru-cache.js"
click node_analytics "https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/utils/analytics.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_nextauth,node_dashboard,node_marketing,node_api,node_routes,node_users,node_projects,node_deployments,node_auth toneBlue
class node_build,node_proxy,node_cache,node_analytics toneAmber
class node_prisma,node_cloudrun,node_bigquery,node_pubsub toneMint
```

## Components

### Control plane

Authenticated product UI and API that manage projects and deployments.

- [Frontend](https://github.com/akram6t/deployr/tree/main/frontend-nextjs): Next.js app · Public marketing site, login flow, and authenticated dashboard. · `frontend-nextjs`
- [Auth route](https://github.com/akram6t/deployr/blob/main/frontend-nextjs/pages/api/auth/[...nextauth].ts): NextAuth endpoint · Browser sign-in flow handled inside the frontend app. · `frontend-nextjs/pages/api/auth/[...nextauth].ts`
- [Dashboard](https://github.com/akram6t/deployr/tree/main/frontend-nextjs/pages/dashboard): project UI · Project-centric views for overview, analytics, deployments, settings, and deploy actions. · `frontend-nextjs/pages/dashboard`
- [Marketing pages](https://github.com/akram6t/deployr/tree/main/frontend-nextjs/pages): public UI · Home, pricing, docs, blog, about, and login pages. · `frontend-nextjs/pages`
- [API server](https://github.com/akram6t/deployr/tree/main/api-server/src): Node API · Typed REST backend for platform control and metadata. · `api-server/src`
- [Routes](https://github.com/akram6t/deployr/blob/main/api-server/src/routes/index.ts): routing layer · Shared route registration that wires controllers and middleware. · `api-server/src/routes/index.ts`
- [Users](https://github.com/akram6t/deployr/blob/main/api-server/src/controllers/userController.ts): controller · User-related API operations. · `api-server/src/controllers/userController.ts`
- [Projects](https://github.com/akram6t/deployr/blob/main/api-server/src/controllers/projectController.ts): controller · Project CRUD and repository identity mapping. · `api-server/src/controllers/projectController.ts`
- [Deployments](https://github.com/akram6t/deployr/blob/main/api-server/src/controllers/deploymentController.ts): controller · Deployment lifecycle, status tracking, and orchestration endpoints. · `api-server/src/controllers/deploymentController.ts`
- [Auth guard](https://github.com/akram6t/deployr/blob/main/api-server/src/utils/authMiddleware.ts): middleware · 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](https://github.com/akram6t/deployr/tree/main/build-server): Dockerized worker · Standalone build executor that compiles user apps and produces artifacts. · `build-server`
- [Reverse proxy](https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/index.js): edge server · Routes tenant domains and subdomains to the correct deployment output. · `reverse-proxy-server/index.js`
- [Proxy cache](https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/utils/lru-cache.js): LRU cache · In-memory lookup acceleration for routing and metadata. · `reverse-proxy-server/utils/lru-cache.js`
- [Edge analytics](https://github.com/akram6t/deployr/blob/main/reverse-proxy-server/utils/analytics.js): telemetry utils · 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](https://github.com/akram6t/deployr/blob/main/api-server/prisma/schema.prisma): schema · Relational metadata model for users, projects, deployments, and related records. · `api-server/prisma/schema.prisma`
- [Build jobs](https://github.com/akram6t/deployr/blob/main/api-server/src/utils/cloud-run-jobs.ts): Cloud Run jobs · Job launcher used to execute isolated builds. · `api-server/src/utils/cloud-run-jobs.ts`
- [BigQuery](https://github.com/akram6t/deployr/blob/main/api-server/src/services/bigquery.ts): analytics store · Warehouse for analytics and higher-volume event reporting. · `api-server/src/services/bigquery.ts`
- [Pub/Sub pipe](https://github.com/akram6t/deployr/blob/main/api-server/src/utils/pubsub-to-bigquery.ts): event pipeline · Async event transport for deployment and analytics ingestion. · `api-server/src/utils/pubsub-to-bigquery.ts`

## Connections

- 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.
