# aparnamol-ks/shipforge architecture

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

- Interactive diagram: https://gitdiagram.com/aparnamol-ks/shipforge
- Repository: https://github.com/aparnamol-ks/shipforge

## Overview

ShipForge is a self-hosted CI/CD service. Users configure projects and pipeline commands in the React dashboard, then manually trigger builds or receive GitHub push-triggered builds. The API records build state and enqueues jobs; a Redis worker runs configured stages in Docker, records results and logs, and publishes events for dashboard updates. The graph includes documented capabilities such as retries, cancellation, and polling; several subsystem links rely on the README because their implementation was not excerpted.

Main entry points: [`backend/app/builds/runner.py`](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/runner.py) (Build runner), [`backend/app/builds/router.py`](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/router.py) (Build endpoints), [`backend/app/webhooks/github.py`](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/webhooks/github.py) (GitHub webhook), [`frontend/src/pages`](https://github.com/aparnamol-ks/shipforge/tree/main/frontend/src/pages) (Project pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["React dashboard<br/>[App.tsx]"]
  node_project_pages["Project pages"]
  node_project_ui["Project controls"]
  node_build_ui["Build history<br/>[BuildList.tsx]"]
  node_frontend_api["API client<br/>[projects.ts]"]
  node_ws_hook["Build updates hook"]
end

subgraph group_api["API and projects"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_project_routes["Project endpoints<br/>[router.py]"]
  node_project_service["Project management<br/>[service.py]"]
  node_webhook["GitHub webhook<br/>[github.py]"]
  node_build_routes["Build endpoints<br/>[router.py]"]
  node_build_service["Build lifecycle<br/>[service.py]"]
end

subgraph group_build["Build execution"]
  node_worker["Queue worker<br/>[worker.py]"]
  node_runner["Build runner<br/>[runner.py]"]
  node_workspace["Workspace handling"]
  node_repository["Repository handling<br/>[service.py]"]
  node_docker["Docker executor<br/>[docker_executor.py]"]
end

subgraph group_infra["Persistence and events"]
  node_database[("PostgreSQL data<br/>[models.py]")]
  node_db_connection["Database sessions<br/>[connection.py]"]
  node_redis_queue["Redis queue<br/>[queue.py]"]
  node_redis_events["Redis events<br/>[events.py]"]
  node_subscriber["Event subscriber<br/>[subscriber.py]"]
  node_event_listener["Build event listener<br/>[event_listener.py]"]
  node_websocket["WebSocket endpoint<br/>[websocket.py]"]
  node_logs["Build logs<br/>[log_service.py]"]
end

node_user(("User"))
node_github(("GitHub"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"routes to"| node_project_pages
node_project_pages -->|"renders"| node_project_ui
node_project_pages -->|"renders"| node_build_ui
node_project_ui -->|"calls"| node_frontend_api
node_build_ui -->|"calls"| node_frontend_api
node_project_pages -->|"loads data"| node_frontend_api
node_project_pages -->|"opens updates"| node_ws_hook
node_ws_hook -->|"connects"| node_websocket
node_frontend_api -->|"HTTP requests"| node_fastapi
node_fastapi -->|"registers"| node_project_routes
node_fastapi -->|"registers"| node_build_routes
node_fastapi -->|"registers"| node_webhook
node_project_routes -->|"calls"| node_project_service
node_project_service -->|"reads and writes"| node_database
node_webhook -->|"receives push"| node_github
node_github -->|"sends push"| node_webhook
node_webhook -->|"matches repository"| node_project_service
node_webhook -->|"creates build"| node_build_service
node_webhook -->|"schedules build"| node_redis_queue
node_build_routes -->|"checks project"| node_project_service
node_build_routes -->|"manages lifecycle"| node_build_service
node_build_routes -->|"schedules build"| node_redis_queue
node_build_service -->|"reads and writes"| node_database
node_worker -->|"dequeues"| node_redis_queue
node_worker -->|"loads records"| node_database
node_worker -->|"runs build"| node_runner
node_runner -->|"handles checkout"| node_repository
node_runner -->|"manages workspace"| node_workspace
node_runner -->|"executes stages"| node_docker
node_runner -->|"updates state"| node_build_service
node_runner -->|"records output"| node_logs
node_runner -->|"publishes events"| node_redis_events
node_logs -->|"stores logs"| node_database
node_redis_events -->|"publishes stream"| node_subscriber
node_event_listener -->|"subscribes"| node_subscriber
node_build_routes -->|"forwards events"| node_event_listener
node_event_listener -->|"forwards updates"| node_websocket
node_websocket -.->|"sends events"| node_ws_hook
node_build_routes -->|"reads logs"| node_logs
node_frontend_api -->|"requests builds"| node_build_routes

click node_dashboard "https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/App.tsx"
click node_project_pages "https://github.com/aparnamol-ks/shipforge/tree/main/frontend/src/pages"
click node_project_ui "https://github.com/aparnamol-ks/shipforge/tree/main/frontend/src/components"
click node_build_ui "https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/components/BuildList.tsx"
click node_frontend_api "https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/api/projects.ts"
click node_ws_hook "https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/hooks/useBuildWebSocket.ts"
click node_fastapi "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/main.py"
click node_project_routes "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/projects/router.py"
click node_project_service "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/projects/service.py"
click node_webhook "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/webhooks/github.py"
click node_build_routes "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/router.py"
click node_build_service "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/service.py"
click node_worker "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/worker.py"
click node_runner "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/runner.py"
click node_workspace "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/workspace_service.py"
click node_repository "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/repositories/service.py"
click node_docker "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/docker_executor.py"
click node_database "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/database/models.py"
click node_db_connection "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/database/connection.py"
click node_redis_queue "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/queue.py"
click node_redis_events "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/events.py"
click node_subscriber "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/subscriber.py"
click node_event_listener "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/event_listener.py"
click node_websocket "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/websocket.py"
click node_logs "https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/log_service.py"

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_project_pages,node_project_ui,node_build_ui,node_frontend_api,node_ws_hook,node_user toneBlue
class node_fastapi,node_project_routes,node_project_service,node_webhook,node_build_routes,node_build_service toneAmber
class node_worker,node_runner,node_workspace,node_repository,node_docker toneMint
class node_database,node_db_connection,node_redis_queue,node_redis_events,node_subscriber,node_event_listener,node_websocket,node_logs toneRose
class node_github toneIndigo
```

## Components

### Dashboard

- [React dashboard](https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Project pages](https://github.com/aparnamol-ks/shipforge/tree/main/frontend/src/pages): `frontend/src/pages`
- [Project controls](https://github.com/aparnamol-ks/shipforge/tree/main/frontend/src/components): `frontend/src/components`
- [Build history](https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/components/BuildList.tsx): `frontend/src/components/BuildList.tsx`
- [API client](https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/api/projects.ts): `frontend/src/api/projects.ts`
- [Build updates hook](https://github.com/aparnamol-ks/shipforge/blob/main/frontend/src/hooks/useBuildWebSocket.ts): `frontend/src/hooks/useBuildWebSocket.ts`

### API and projects

- [FastAPI app](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project endpoints](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/projects/router.py): `backend/app/projects/router.py`
- [Project management](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/projects/service.py): `backend/app/projects/service.py`
- [GitHub webhook](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/webhooks/github.py): `backend/app/webhooks/github.py`
- [Build endpoints](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/router.py): `backend/app/builds/router.py`
- [Build lifecycle](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/service.py): `backend/app/builds/service.py`

### Build execution

- [Queue worker](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/worker.py): `backend/app/redis_client/worker.py`
- [Build runner](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/runner.py): `backend/app/builds/runner.py`
- [Workspace handling](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/workspace_service.py): `backend/app/builds/workspace_service.py`
- [Repository handling](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/repositories/service.py): `backend/app/repositories/service.py`
- [Docker executor](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/docker_executor.py): `backend/app/builds/docker_executor.py`

### Persistence and events

- [PostgreSQL data](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/database/models.py): `backend/app/database/models.py`
- [Database sessions](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/database/connection.py): `backend/app/database/connection.py`
- [Redis queue](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/queue.py): `backend/app/redis_client/queue.py`
- [Redis events](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/events.py): `backend/app/redis_client/events.py`
- [Event subscriber](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/redis_client/subscriber.py): `backend/app/redis_client/subscriber.py`
- [Build event listener](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/event_listener.py): `backend/app/builds/event_listener.py`
- [WebSocket endpoint](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/websocket.py): `backend/app/builds/websocket.py`
- [Build logs](https://github.com/aparnamol-ks/shipforge/blob/main/backend/app/builds/log_service.py): `backend/app/builds/log_service.py`

### Other components

- **User**
- **GitHub**

## Connections

- User → React dashboard: uses
- React dashboard → Project pages: routes to (evidence: `frontend/src/App.tsx`)
- Project pages → Project controls: renders (evidence: `frontend/src/pages/ProjectsPage.tsx`)
- Project pages → Build history: renders (evidence: `frontend/src/pages/ProjectDetailsPage.tsx`)
- Project controls → API client: calls (evidence: `frontend/src/components/ProjectForm.tsx`)
- Build history → API client: calls (evidence: `frontend/src/components/BuildList.tsx`)
- Project pages → API client: loads data (evidence: `frontend/src/pages/ProjectDetailsPage.tsx`)
- Project pages → Build updates hook: opens updates (evidence: `frontend/src/pages/ProjectDetailsPage.tsx`)
- Build updates hook → WebSocket endpoint: connects (evidence: `frontend/src/hooks/useBuildWebSocket.ts`)
- API client → FastAPI app: HTTP requests (evidence: `frontend/src/api/projects.ts`)
- FastAPI app → Project endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Build endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → GitHub webhook: registers (evidence: `backend/app/main.py`)
- Project endpoints → Project management: calls (evidence: `backend/app/projects/router.py`)
- Project management → PostgreSQL data: reads and writes (evidence: `backend/app/projects/service.py`)
- GitHub webhook → GitHub: receives push
- GitHub → GitHub webhook: sends push
- GitHub webhook → Project management: matches repository (evidence: `backend/app/webhooks/github.py`)
- GitHub webhook → Build lifecycle: creates build (evidence: `backend/app/webhooks/github.py`)
- GitHub webhook → Redis queue: schedules build (evidence: `backend/app/webhooks/github.py`)
- Build endpoints → Project management: checks project (evidence: `backend/app/builds/router.py`)
- Build endpoints → Build lifecycle: manages lifecycle (evidence: `backend/app/builds/router.py`)
- Build endpoints → Redis queue: schedules build (evidence: `backend/app/builds/router.py`)
- Build lifecycle → PostgreSQL data: reads and writes (evidence: `backend/app/builds/service.py`)
- Queue worker → Redis queue: dequeues (evidence: `backend/app/redis_client/worker.py`)
- Queue worker → PostgreSQL data: loads records (evidence: `backend/app/redis_client/worker.py`)
- Queue worker → Build runner: runs build (evidence: `backend/app/redis_client/worker.py`)
- Build runner → Repository handling: handles checkout (evidence: `backend/app/builds/runner.py`)
- Build runner → Workspace handling: manages workspace (evidence: `backend/app/builds/runner.py`)
- Build runner → Docker executor: executes stages (evidence: `backend/app/builds/runner.py`)
- Build runner → Build lifecycle: updates state (evidence: `backend/app/builds/runner.py`)
- Build runner → Build logs: records output (evidence: `backend/app/builds/runner.py`)
- Build runner → Redis events: publishes events (evidence: `backend/app/redis_client/worker.py`)
- Build logs → PostgreSQL data: stores logs (evidence: `backend/app/builds/log_service.py`)
- Redis events → Event subscriber: publishes stream (evidence: `backend/app/redis_client/subscriber.py`)
- Build event listener → Event subscriber: subscribes (evidence: `backend/app/builds/event_listener.py`)
- Build endpoints → Build event listener: forwards events (evidence: `backend/app/builds/router.py`)
- Build event listener → WebSocket endpoint: forwards updates (evidence: `backend/app/builds/router.py`)
- WebSocket endpoint → Build updates hook: sends events
- Build endpoints → Build logs: reads logs (evidence: `backend/app/builds/router.py`)
- API client → Build endpoints: requests builds (evidence: `frontend/src/api/projects.ts`)
