# prajexec/deployr architecture

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

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

## Overview

DeployService accepts deployments through its dashboard or REST API, records them, and queues isolated builds. Workers build and publish static artifacts while emitting live logs; users can monitor, cancel, or roll back deployments. The router serves preview and current project releases from artifact storage. The graph combines sampled call sites with README-documented service responsibilities; unsampled subsystem internals are represented only where the README supports them.

Main entry points: [`apps/api/src/server.ts`](https://github.com/prajexec/deployr/blob/main/apps/api/src/server.ts) (REST API), [`apps/worker/src/builder.ts`](https://github.com/prajexec/deployr/blob/main/apps/worker/src/builder.ts) (Sandbox builder), [`packages/shared/src/db/deployments.ts`](https://github.com/prajexec/deployr/blob/main/packages/shared/src/db/deployments.ts) (Deployment records), [`apps/worker/src/index.ts`](https://github.com/prajexec/deployr/blob/main/apps/worker/src/index.ts) (Queue consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_dashboard["Web dashboard<br/>[App.tsx]"]
  node_sse_client["SSE client<br/>[sse-client.ts]"]
end

subgraph group_api["Deployment API"]
  node_api_server["REST API<br/>[server.ts]"]
  node_queue_producer["Job producer<br/>[queue.ts]"]
  node_log_manager["Log stream manager"]
end

subgraph group_worker["Build processing"]
  node_worker["Queue consumer<br/>[index.ts]"]
  node_processor["Job processor<br/>[processor.ts]"]
  node_builder["Sandbox builder<br/>[builder.ts]"]
  node_extractor["Archive extractor<br/>[tar-extractor.ts]"]
  node_log_writer["Build log writer<br/>[stream-writer.ts]"]
  node_recovery["Crash recovery<br/>[recovery.ts]"]
  node_cleanup["Resource cleanup<br/>[cleanup.ts]"]
end

subgraph group_shared["Shared services"]
  node_db_access["Deployment records<br/>[deployments.ts]"]
  node_state_machine["Status transitions<br/>[state-machine.ts]"]
  node_schema["Project schema<br/>[schema.ts]"]
  node_redis_client["Redis client<br/>[redis.ts]"]
  node_storage["Artifact storage client<br/>[storage.ts]"]
end

subgraph group_delivery["Static delivery"]
  node_router["Wildcard router<br/>[server.ts]"]
end

node_user(("Operator"))
node_api_client(("REST client"))
node_docker["Docker runtime"]
node_postgres[("PostgreSQL")]
node_redis[("Redis")]
node_s3[("S3-compatible storage")]
node_browser(("Site visitor"))

node_user -->|"uses"| node_dashboard
node_user -->|"triggers deploy"| node_api_client
node_dashboard -->|"calls API"| node_api_server
node_api_client -->|"submits deployment"| node_api_server
node_api_server -->|"creates records"| node_db_access
node_api_server -->|"enqueues build"| node_queue_producer
node_queue_producer -->|"dispatches job"| node_worker
node_worker -->|"processes job"| node_processor
node_processor -->|"runs build"| node_builder
node_builder -->|"extracts archives"| node_extractor
node_builder -->|"runs isolated build"| node_docker
node_builder -->|"uploads artifacts"| node_storage
node_builder -->|"writes build logs"| node_log_writer
node_log_writer -->|"appends log stream"| node_redis_client
node_redis_client -->|"connects to"| node_redis
node_worker -->|"recovers stuck jobs"| node_recovery
node_worker -->|"schedules cleanup"| node_cleanup
node_api_server -->|"serves live logs"| node_log_manager
node_log_manager -->|"reads log streams"| node_redis_client
node_dashboard -->|"streams logs"| node_sse_client
node_sse_client -->|"opens SSE stream"| node_api_server
node_db_access -->|"checks transitions"| node_state_machine
node_db_access -->|"queries tables"| node_schema
node_db_access -->|"reads and writes"| node_postgres
node_router -->|"resolves releases"| node_db_access
node_router -->|"fetches site assets"| node_storage
node_storage -->|"reads and writes objects"| node_s3
node_browser -->|"requests deployed site"| node_router
node_api_server -->|"reads archived logs"| node_storage

click node_dashboard "https://github.com/prajexec/deployr/blob/main/apps/web/src/App.tsx"
click node_api_server "https://github.com/prajexec/deployr/blob/main/apps/api/src/server.ts"
click node_queue_producer "https://github.com/prajexec/deployr/blob/main/apps/api/src/queue.ts"
click node_log_manager "https://github.com/prajexec/deployr/blob/main/apps/api/src/log-stream-manager.ts"
click node_worker "https://github.com/prajexec/deployr/blob/main/apps/worker/src/index.ts"
click node_processor "https://github.com/prajexec/deployr/blob/main/apps/worker/src/processor.ts"
click node_builder "https://github.com/prajexec/deployr/blob/main/apps/worker/src/builder.ts"
click node_extractor "https://github.com/prajexec/deployr/blob/main/apps/worker/src/tar-extractor.ts"
click node_log_writer "https://github.com/prajexec/deployr/blob/main/apps/worker/src/stream-writer.ts"
click node_recovery "https://github.com/prajexec/deployr/blob/main/apps/worker/src/recovery.ts"
click node_cleanup "https://github.com/prajexec/deployr/blob/main/apps/worker/src/cleanup.ts"
click node_db_access "https://github.com/prajexec/deployr/blob/main/packages/shared/src/db/deployments.ts"
click node_state_machine "https://github.com/prajexec/deployr/blob/main/packages/shared/src/state-machine.ts"
click node_schema "https://github.com/prajexec/deployr/blob/main/packages/shared/src/db/schema.ts"
click node_redis_client "https://github.com/prajexec/deployr/blob/main/packages/shared/src/redis.ts"
click node_storage "https://github.com/prajexec/deployr/blob/main/packages/shared/src/storage.ts"
click node_router "https://github.com/prajexec/deployr/blob/main/apps/router/src/server.ts"
click node_sse_client "https://github.com/prajexec/deployr/blob/main/apps/web/src/sse-client.ts"

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_dashboard,node_sse_client,node_api_client toneBlue
class node_api_server,node_queue_producer,node_log_manager,node_postgres,node_redis,node_s3 toneAmber
class node_worker,node_processor,node_builder,node_extractor,node_log_writer,node_recovery,node_cleanup toneMint
class node_db_access,node_state_machine,node_schema,node_redis_client,node_storage toneRose
class node_router,node_user,node_docker,node_browser toneIndigo
```

## Components

### User entry points

- [Web dashboard](https://github.com/prajexec/deployr/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [SSE client](https://github.com/prajexec/deployr/blob/main/apps/web/src/sse-client.ts): `apps/web/src/sse-client.ts`

### Deployment API

- [REST API](https://github.com/prajexec/deployr/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Job producer](https://github.com/prajexec/deployr/blob/main/apps/api/src/queue.ts): `apps/api/src/queue.ts`
- [Log stream manager](https://github.com/prajexec/deployr/blob/main/apps/api/src/log-stream-manager.ts): `apps/api/src/log-stream-manager.ts`

### Build processing

- [Queue consumer](https://github.com/prajexec/deployr/blob/main/apps/worker/src/index.ts): `apps/worker/src/index.ts`
- [Job processor](https://github.com/prajexec/deployr/blob/main/apps/worker/src/processor.ts): `apps/worker/src/processor.ts`
- [Sandbox builder](https://github.com/prajexec/deployr/blob/main/apps/worker/src/builder.ts): `apps/worker/src/builder.ts`
- [Archive extractor](https://github.com/prajexec/deployr/blob/main/apps/worker/src/tar-extractor.ts): `apps/worker/src/tar-extractor.ts`
- [Build log writer](https://github.com/prajexec/deployr/blob/main/apps/worker/src/stream-writer.ts): `apps/worker/src/stream-writer.ts`
- [Crash recovery](https://github.com/prajexec/deployr/blob/main/apps/worker/src/recovery.ts): `apps/worker/src/recovery.ts`
- [Resource cleanup](https://github.com/prajexec/deployr/blob/main/apps/worker/src/cleanup.ts): `apps/worker/src/cleanup.ts`

### Shared services

- [Deployment records](https://github.com/prajexec/deployr/blob/main/packages/shared/src/db/deployments.ts): `packages/shared/src/db/deployments.ts`
- [Status transitions](https://github.com/prajexec/deployr/blob/main/packages/shared/src/state-machine.ts): `packages/shared/src/state-machine.ts`
- [Project schema](https://github.com/prajexec/deployr/blob/main/packages/shared/src/db/schema.ts): `packages/shared/src/db/schema.ts`
- [Redis client](https://github.com/prajexec/deployr/blob/main/packages/shared/src/redis.ts): `packages/shared/src/redis.ts`
- [Artifact storage client](https://github.com/prajexec/deployr/blob/main/packages/shared/src/storage.ts): `packages/shared/src/storage.ts`

### Static delivery

- [Wildcard router](https://github.com/prajexec/deployr/blob/main/apps/router/src/server.ts): `apps/router/src/server.ts`

### Other components

- **Operator**
- **REST client**
- **Docker runtime**
- **PostgreSQL**
- **Redis**
- **S3-compatible storage**
- **Site visitor**

## Connections

- Operator → Web dashboard: uses (evidence: `README.md`)
- Operator → REST client: triggers deploy (evidence: `README.md`)
- Web dashboard → REST API: calls API (evidence: `README.md`)
- REST client → REST API: submits deployment (evidence: `README.md`)
- REST API → Deployment records: creates records (evidence: `apps/api/src/server.ts`)
- REST API → Job producer: enqueues build (evidence: `apps/api/src/server.ts`)
- Job producer → Queue consumer: dispatches job (evidence: `README.md`)
- Queue consumer → Job processor: processes job (evidence: `apps/worker/src/index.ts`)
- Job processor → Sandbox builder: runs build (evidence: `apps/worker/src/processor.ts`)
- Sandbox builder → Archive extractor: extracts archives (evidence: `apps/worker/src/builder.ts`)
- Sandbox builder → Docker runtime: runs isolated build (evidence: `README.md`)
- Sandbox builder → Artifact storage client: uploads artifacts (evidence: `apps/worker/src/builder.ts`)
- Sandbox builder → Build log writer: writes build logs (evidence: `apps/worker/src/builder.ts`)
- Build log writer → Redis client: appends log stream (evidence: `apps/worker/src/stream-writer.ts`)
- Redis client → Redis: connects to (evidence: `README.md`)
- Queue consumer → Crash recovery: recovers stuck jobs (evidence: `apps/worker/src/index.ts`)
- Queue consumer → Resource cleanup: schedules cleanup (evidence: `apps/worker/src/index.ts`)
- REST API → Log stream manager: serves live logs (evidence: `README.md`)
- Log stream manager → Redis client: reads log streams (evidence: `README.md`)
- Web dashboard → SSE client: streams logs (evidence: `apps/web/src/App.tsx`)
- SSE client → REST API: opens SSE stream
- Deployment records → Status transitions: checks transitions (evidence: `packages/shared/src/db/deployments.ts`)
- Deployment records → Project schema: queries tables (evidence: `packages/shared/src/db/deployments.ts`)
- Deployment records → PostgreSQL: reads and writes (evidence: `README.md`)
- Wildcard router → Deployment records: resolves releases (evidence: `apps/router/src/server.ts`)
- Wildcard router → Artifact storage client: fetches site assets (evidence: `apps/router/src/server.ts`)
- Artifact storage client → S3-compatible storage: reads and writes objects (evidence: `packages/shared/src/storage.ts`)
- Site visitor → Wildcard router: requests deployed site (evidence: `README.md`)
- REST API → Artifact storage client: reads archived logs (evidence: `apps/api/src/server.ts`)
