# younes101020/delivery architecture

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

- Interactive diagram: https://gitdiagram.com/younes101020/delivery
- Repository: https://github.com/younes101020/delivery

## Overview

##### Project Type and Purpose
- This is a full-stack, self-hostable deployment platform (“Delivery”)—an open-source Netlify/Vercel alternative.
- The monorepo uses pnpm+Turborepo, with:
- apps/web: Next.js web UI (React)
- apps/jobs: Node.js/TypeScript HTTP API & background job service (Express/Koa-style + Bull/Redis)
- packages/*: shared libraries (auth, DB migrations via Drizzle, utils, ESLint configs)
- infrastructure: Traefik reverse proxy + Docker Compose configs

##### High-Level Architecture Components
a. Ingress & Routing
- Traefik (Docker) routes incoming HTTP/S requests to the web app or API.
- Docker-Compose defines service networks for web, jobs, Redis, SQL DB, etc.
b. Frontend (apps/web)
- Next.js app with pages + API routes
- React components subscribe to SSE endpoints for real-time status
- Client-side calls Next.js API routes under `/api/…`
c. API & Job Service (apps/jobs)
- Exposes REST endpoints (auth, applications, databases, deployments, envvars, version, GitHub webhooks)
- Uses Bull + Redis as job queue
- Background workers pick up jobs: start/stop containers, provision databases, handle deployments
- Tasks interact with remote Docker hosts over SSH (packages/jobs/src/lib/remote-docker + ssh utils)
d. Persistence
- Postgres (managed via Drizzle ORM + migrations in packages/drizzle)
- Redis (used by Bull for job queue)
e. External Integrations
- GitHub (OAuth apps + webhooks for deployments)
- Remote Docker Hosts (Docker Engine over SSH)

##### Relationships & Data/Control Flows
- User → (HTTPS) Traefik → Next.js UI
- UI → (HTTP/JSON or SSE) Next.js API routes
- Next.js API → (HTTP/gRPC) Job Service REST API
- Job Service → (Bull) Redis queue → Worker processes
- Workers → (Docker Engine via SSH) create/stop containers
- Job Service & Workers → (SQL) Postgres for metadata, configuration
- GitHub Webhooks → Traefik → Job Service `/api/webhooks/github` → trigger deployment jobs

##### Architectural Patterns & Design Principles
- Microservices-style separation: UI vs API/jobs vs background workers
- Queue-based async processing (Bull + Redis) for long-running tasks
- Server-side rendering + API co-location in Next.js for fast UX and incremental adoption
- Shared packages for cross-cutting concerns (auth, DB migrations, utilities)
- Infrastructure as code: Docker Compose + Traefik dynamic/static configs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Ingress
    User["User"]:::external
    subgraph "Ingress & Routing"
        Traefik["Traefik Load Balancer"]:::infra
    end
    User -->|"HTTPS"| Traefik

    %% Frontend Layer
    subgraph "Frontend Layer"
        NextApp["Next.js Web Application"]:::frontend
        APIRoutes["Next.js API Routes"]:::frontend
    end
    Traefik -->|"HTTP/S"| NextApp
    NextApp -->|"HTTP/JSON"| APIRoutes
    NextApp -.->|"SSE"| APIRoutes

    %% API & Job Service
    subgraph "API & Job Service" 
        JobAPI["Job Service API (Express)"]:::backend
    end
    APIRoutes -->|"HTTP/JSON"| JobAPI

    %% Queue and Workers
    subgraph "Async Processing"
        RedisQ["Redis Queue"]:::database
        Worker["Background Worker"]:::worker
    end
    JobAPI -->|"Bull"| RedisQ
    RedisQ -->|"Queue Consume"| Worker

    %% Workers to Docker Hosts
    subgraph "External Systems"
        GitHub["GitHub"]:::external
        DockerHosts["Remote Docker Hosts"]:::external
    end
    Worker -->|"SSH"| DockerHosts

    %% Persistence
    subgraph "Persistence"
        Postgres["Postgres Database"]:::database
    end
    JobAPI -->|"SQL"| Postgres
    Worker -->|"SQL"| Postgres

    %% Webhooks paths
    GitHub -->|"Webhooks (HTTPS)"| Traefik
    Traefik -->|"HTTP/JSON"| JobAPI

    %% Shared Libraries and Tooling
    subgraph "Monorepo Shared"
        SharedAuth["Auth Lib"]:::shared
        SharedDrizzle["Drizzle Migrations"]:::shared
        SharedUtils["Utils Lib"]:::shared
        ESLintCfg["ESLint Configs"]:::shared
    end

    subgraph "Monorepo Tooling"
        PNPM["pnpm & Turborepo"]:::infra
    end

    %% Click Events
    click Traefik "https://github.com/younes101020/delivery/blob/main/infrastructure/traefik-config/traefik.yaml"
    click Traefik "https://github.com/younes101020/delivery/blob/main/infrastructure/traefik-config/dynamic.yaml"
    click PNPM "https://github.com/younes101020/delivery/blob/main/pnpm-workspace.yaml"
    click PNPM "https://github.com/younes101020/delivery/blob/main/turbo.json"
    click NextApp "https://github.com/younes101020/delivery/tree/main/apps/web/"
    click APIRoutes "https://github.com/younes101020/delivery/tree/main/apps/web/src/app/api/"
    click JobAPI "https://github.com/younes101020/delivery/blob/main/apps/jobs/src/app.ts"
    click JobAPI "https://github.com/younes101020/delivery/blob/main/apps/jobs/src/index.ts"
    click JobAPI "https://github.com/younes101020/delivery/tree/main/apps/jobs/src/routes/"
    click RedisQ "https://github.com/younes101020/delivery/blob/main/compose.prod.yaml"
    click RedisQ "https://github.com/younes101020/delivery/blob/main/compose.prod.local.yaml"
    click SharedAuth "https://github.com/younes101020/delivery/blob/main/packages/auth/src/index.ts"
    click SharedDrizzle "https://github.com/younes101020/delivery/tree/main/packages/drizzle/src/"
    click SharedUtils "https://github.com/younes101020/delivery/blob/main/packages/utils/src/index.ts"
    click ESLintCfg "https://github.com/younes101020/delivery/blob/main/packages/eslint-config/base.js"
    click ESLintCfg "https://github.com/younes101020/delivery/blob/main/packages/eslint-config/next.js"
    click GitHub "https://github.com/younes101020/delivery/tree/main/apps/web/src/app/api/webhooks/github/"
    click JobAPI "https://github.com/younes101020/delivery/tree/main/apps/jobs/src/routes/githubapps/"
    click JobAPI "https://github.com/younes101020/delivery/tree/main/apps/jobs/src/routes/webhooks/github/"
    click Worker "https://github.com/younes101020/delivery/blob/main/apps/jobs/src/lib/configure-bull-board.ts"
    click Worker "https://github.com/younes101020/delivery/tree/main/apps/jobs/src/lib/tasks/"
    click Worker "https://github.com/younes101020/delivery/tree/main/apps/jobs/src/lib/remote-docker/"
    click Worker "https://github.com/younes101020/delivery/tree/main/apps/jobs/src/lib/ssh/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0288D1;
    classDef backend fill:#D0EFFF,stroke:#0277BD;
    classDef database fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;
    classDef worker fill:#E8F5E9,stroke:#43A047;
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-dasharray: 5 5;
    classDef infra fill:#F1F8E9,stroke:#8BC34A;
    classDef shared fill:#F3E5F5,stroke:#9C27B0;
```
