# krish120003/zercel architecture

> Architecture diagram of the GitHub repository krish120003/zercel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krish120003/zercel
- Repository: https://github.com/krish120003/zercel

## Overview

##### Project type and purpose
- This is a full‑stack, cloud‑native “Vercel clone” consisting of three core microservices (web, router, builder), shared libraries/packages, and an IaC layer (terraform).
- Purpose: provide GitHub‑driven deployments, build orchestration, dynamic compute, and a browser‑based UI for site provisioning.

##### File structure
- Top‑level “apps/” folder with three services:
- web (Next.js frontend + API routes + tRPC + server logic)
- router (Node+TypeScript HTTP gateway for real‑time routing of incoming traffic to deployments)
- builder (Node+TypeScript build orchestrator that invokes build jobs and streams logs)
- “packages/” folder with shared ESLint/TS configs and a UI component library.
- “terraform/” for provisioning GCP/Cloudflare/Redis/Postgres infra.
- Monorepo managed with pnpm workspaces and Turbo for generators.

##### README for additional insights
- High‑level description: automatic GitHub deployments, live build logs, CDN caching, SSL, environment variables, serverless functions.
- Infra services: Eventarc for webhooks, Cloud Run & Batch for compute, Cloud Storage for artifacts, Neon Postgres, Upstash Redis, Artifact Registry.

##### Main components
a. Web UI service (apps/web)
- Next.js SSR/CSR
- API layer: NextAuth, GitHub webhook endpoint, builder callback, tRPC router
b. Builder service (apps/builder)
- Receives build‑trigger requests
- Orchestrates GCP Batch/Cloud Run job runners
- Pushes static assets to Cloud Storage and Docker images to Artifact Registry
- Streams build logs back to Web UI (via Eventarc or WebSocket)
c. Router service (apps/router)
- Acts as HTTP reverse‐proxy based on hostname/path
- Fetches routing table from Postgres or Redis cache
- Proxies traffic to static assets (Cloud Storage CDN) or serverless endpoints (Cloud Run)
d. Shared state and data stores
- Neon Postgres: stores user accounts, sites, deployments, environment variables
- Upstash Redis: caching routing tables, build status for real‑time updates
e. External integrations
- GitHub (webhooks to Web UI)
- GCP Cloud Storage (static files)
- GCP Artifact Registry (container images)
- GCP Cloud Run & Batch (compute)
- Cloudflare CDN (public ingress)

##### Relationships and orchestration flows
1. Developer pushes to GitHub → GitHub sends webhook to Web UI’s /api/github/webhook
2. Web UI validates & forwards build request to Builder service (/api/builder/callback)
3. Builder enqueues build job (GCP Batch or Cloud Run job), updates Postgres, caches status in Redis
4. Build jobs run, produce artifacts → upload to Cloud Storage & Artifact Registry
5. Builder streams logs/events back to Web UI (Eventarc → Web UI /api/builder/eventarc)
6. Upon successful build, Builder updates Postgres & invalidates Redis cache
7. Router picks up new route definitions (from Redis or Postgres)
8. End‑user requests arrive at Cloudflare → forwarded to Router → Router proxies to:
- static assets (via CDN origin pointing to Cloud Storage)
- dynamic functions (Cloud Run container for that deployment)

##### Architectural patterns and design principles
- Microservices: clear separation of concerns among Web, Builder, Router
- Event‑driven: webhook → build events → log streaming
- CQRS‑like: Command path (build requests) vs Query path (runtime routing)
- Shared monorepo for consistency, Turborepo for code‑gen
- IaC with Terraform for reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Integrations
  GitHub["GitHub"]:::external
  EndUser["End User (Browser)"]:::external

  %% Web UI Service
  subgraph "Web UI Service"
    direction TB
    WebUI["Web UI Service\n(apps/web/)"]:::frontend
    NextAuth["NextAuth Route\n/api/auth/[...nextauth]"]:::frontend
    GithubWebhook["GitHub Webhook\n/api/github/webhook"]:::frontend
    BuilderCallback["Builder Callback\n/api/builder/callback"]:::frontend
    EventarcEndpoint["Eventarc Endpoint\n/api/builder/eventarc"]:::frontend
    TRPCRouter["tRPC Router\n/api/trpc/[trpc]"]:::backend
    BuildLib["Build Utility\n(server/lib/build.ts)"]:::backend
    PostgresClient["Postgres Client\n(db/schema.ts)"]:::db
    RedisClient["Redis Client\n(redis/index.ts)"]:::cache

    WebUI -->|uses| NextAuth
    WebUI -->|uses| GithubWebhook
    WebUI -->|uses| BuilderCallback
    WebUI -->|uses| EventarcEndpoint
    WebUI -->|uses| TRPCRouter
    WebUI -->|calls| BuildLib
    WebUI -->|reads/writes| PostgresClient
    WebUI -->|caches| RedisClient
  end

  %% Builder Service
  subgraph "Builder Service"
    direction TB
    Builder["Builder Service\n(apps/builder/)"]:::backend
    Dockerfile["Dockerfile"]:::backend
    BuildScript["build.sh"]:::backend

    Builder -->|builds image| Dockerfile
    Builder -->|runs script| BuildScript
  end

  %% Router Service
  subgraph "Router Service"
    direction TB
    Router["Router Service\n(apps/router/)"]:::backend
    Entrypoint["Entry Point\n(src/index.ts)"]:::backend
    EnvConfig["Env Config\n(src/env.js)"]:::backend

    Router -->|loads| Entrypoint
    Router -->|loads| EnvConfig
  end

  %% Terraform IaC
  subgraph "Terraform (IaC)"
    direction TB
    TFMain["main.tf"]:::infra
    TFVars["variables.tf"]:::infra
    TFEnv["setup_env.sh"]:::infra

    TFMain --> TFVars
    TFMain --> TFEnv
  end

  %% Shared Packages
  subgraph "Shared Packages"
    direction TB
    UIPkg["UI Library\n(packages/ui/)"]:::shared
    ESLint["ESLint Config\n(packages/eslint-config/)"]:::shared
    TSConfig["TS Config\n(packages/typescript-config/)"]:::shared
  end

  %% Data Stores & Services
  Postgres["Neon Postgres"]:::db
  Redis["Upstash Redis"]:::cache
  CloudStorage["GCP Cloud Storage"]:::storage
  ArtifactRegistry["GCP Artifact Registry"]:::registry
  GCPCompute["GCP Compute\n(Cloud Run / Batch)"]:::compute
  CDN["Cloudflare CDN"]:::external

  %% Orchestration Flow
  GitHub -->|"Webhook\n/api/github/webhook"| GithubWebhook
  GithubWebhook -->|HTTP Forward| BuilderCallback
  BuilderCallback -->|HTTP Request\n/api/builder/callback| Builder
  Builder -->|"enqueue job"| GCPCompute
  GCPCompute -->|"upload artifacts"| CloudStorage
  GCPCompute -->|"push image"| ArtifactRegistry
  Builder -->|"update"| Postgres
  Builder -->|"cache status"| Redis
  Builder -->|"Eventarc"| EventarcEndpoint
  EventarcEndpoint -->|HTTP Logs| WebUI

  %% Runtime Routing
  EndUser -->|"HTTP Request"| CDN
  CDN -->|"forward"| Router
  Router -->|"proxy static"| CloudStorage
  Router -->|"proxy dynamic"| GCPCompute
  Router -->|"fetch routes"| Redis
  Redis -->|"fallback"| Postgres

  %% Click Events
  click WebUI "https://github.com/krish120003/zercel/tree/main/apps/web/"
  click NextAuth "https://github.com/krish120003/zercel/blob/main/apps/web/src/app/api/auth/[...nextauth]/route.ts"
  click GithubWebhook "https://github.com/krish120003/zercel/blob/main/apps/web/src/app/api/github/webhook/route.ts"
  click BuilderCallback "https://github.com/krish120003/zercel/blob/main/apps/web/src/app/api/builder/callback/route.ts"
  click EventarcEndpoint "https://github.com/krish120003/zercel/blob/main/apps/web/src/app/api/builder/eventarc/route.ts"
  click TRPCRouter "https://github.com/krish120003/zercel/blob/main/apps/web/src/app/api/trpc/[trpc]/route.ts"
  click BuildLib "https://github.com/krish120003/zercel/blob/main/apps/web/src/server/lib/build.ts"
  click PostgresClient "https://github.com/krish120003/zercel/blob/main/apps/web/src/server/db/schema.ts"
  click RedisClient "https://github.com/krish120003/zercel/blob/main/apps/web/src/server/redis/index.ts"
  click Builder "https://github.com/krish120003/zercel/tree/main/apps/builder/"
  click Dockerfile "https://github.com/krish120003/zercel/tree/main/apps/builder/Dockerfile"
  click BuildScript "https://github.com/krish120003/zercel/blob/main/apps/builder/build.sh"
  click Router "https://github.com/krish120003/zercel/tree/main/apps/router/"
  click Entrypoint "https://github.com/krish120003/zercel/blob/main/apps/router/src/index.ts"
  click EnvConfig "https://github.com/krish120003/zercel/blob/main/apps/router/src/env.js"
  click TFMain "https://github.com/krish120003/zercel/blob/main/terraform/main.tf"
  click TFVars "https://github.com/krish120003/zercel/blob/main/terraform/variables.tf"
  click TFEnv "https://github.com/krish120003/zercel/blob/main/terraform/setup_env.sh"
  click UIPkg "https://github.com/krish120003/zercel/tree/main/packages/ui/"
  click ESLint "https://github.com/krish120003/zercel/tree/main/packages/eslint-config/"
  click TSConfig "https://github.com/krish120003/zercel/tree/main/packages/typescript-config/"

  %% Styles
  classDef frontend fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
  classDef backend fill:#FCE4EC,stroke:#F8BBD0,color:#880E4F
  classDef db fill:#E8F5E9,stroke:#A5D6A7,color:#1B5E20
  classDef cache fill:#FFF3E0,stroke:#FFCC80,color:#E65100
  classDef storage fill:#E1F5FE,stroke:#81D4FA,color:#01579B
  classDef registry fill:#F3E5F5,stroke:#CE93D8,color:#4A148C
  classDef compute fill:#FFEBEE,stroke:#EF9A9A,color:#B71C1C
  classDef infra fill:#ECEFF1,stroke:#B0BEC5,color:#263238
  classDef shared fill:#FFFDE7,stroke:#FFF59D,color:#F57F17
  classDef external fill:#F5F5F5,stroke:#BDBDBD,color:#424242
```
