# yassinos-coder/berth architecture

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

- Interactive diagram: https://gitdiagram.com/yassinos-coder/berth
- Repository: https://github.com/yassinos-coder/berth

## Overview

Berth is a self-hosted deployment control plane: the dashboard and GitHub integrations request deployments, the NestJS server stores desired state and coordinates agents, and Rust agents reconcile Docker on managed VPSs while reporting status and telemetry. The map emphasizes that path, plus authentication, fleet enrollment, proxying, backups, teams, notifications, and public status pages. Several server subsystems are represented at directory level because their source was not sampled; those links are included only where the README documents the relationship.

Main entry points: [`apps/berth-agent/src/panel.rs`](https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/panel.rs) (Agent Runtime), [`apps/berth-ui/src/services`](https://github.com/yassinos-coder/berth/tree/production/apps/berth-ui/src/services) (API Client), [`apps/berth-agent/src/docker.rs`](https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/docker.rs) (Docker Reconciler), [`apps/berth-server/src/github-app/github-webhook.controller.ts`](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/github-app/github-webhook.controller.ts) (GitHub Webhooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard and API"]
  node_dashboard["Web Dashboard"]
  node_ui_api["API Client"]
end

subgraph group_control["Control Plane"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_service_api["Service API"]
  node_service_logic["Service Orchestration"]
  node_github["GitHub Webhooks"]
  node_agent_gateway["Agent Gateway"]
  node_enrollment["Agent Enrollment"]
  node_database[("Panel Database<br/>[prisma.service.ts]")]
end

subgraph group_agent["Server Agent"]
  node_protocol["Shared Protocol<br/>[index.ts]"]
  node_agent_runtime["Agent Runtime<br/>[panel.rs]"]
end

subgraph group_runtime["Host Runtime"]
  node_reconciler["Docker Reconciler<br/>[docker.rs]"]
  node_docker["Docker Services"]
  node_proxy["HTTPS Proxy<br/>[docker.rs]"]
  node_agent_host["Managed VPS"]
end

subgraph group_operations["Operations Features"]
  node_backups["Backup Operations"]
  node_fleet["Fleet Management"]
  node_teams["Teams and RBAC"]
  node_notifications["Notifications"]
  node_status["Status Pages"]
  node_github_service["GitHub Integration"]
end

node_operator(("Operator"))

node_operator -->|"manages"| node_dashboard
node_dashboard -->|"requests data"| node_ui_api
node_ui_api -->|"authenticates"| node_auth
node_ui_api -->|"calls API"| node_service_api
node_service_api -->|"dispatches"| node_service_logic
node_service_logic -.->|"persists state"| node_database
node_github -->|"records deployments"| node_database
node_github -->|"requests reconcile"| node_agent_gateway
node_github_service -.->|"delivers push event"| node_github
node_fleet -.->|"enrolls agent"| node_enrollment
node_enrollment -->|"updates credentials"| node_database
node_agent_gateway -->|"communicates WebSocket"| node_agent_runtime
node_agent_runtime -->|"exchanges messages"| node_protocol
node_agent_runtime -->|"invokes reconcile"| node_reconciler
node_reconciler -->|"applies desired state"| node_docker
node_reconciler -.->|"configures routes"| node_proxy
node_agent_runtime -->|"collects host specs"| node_agent_host
node_agent_runtime -->|"reports status"| node_agent_gateway
node_operator -.->|"manages backups"| node_backups
node_operator -.->|"assigns roles"| node_teams
node_operator -.->|"configures alerts"| node_notifications
node_operator -.->|"publishes status"| node_status

click node_dashboard "https://github.com/yassinos-coder/berth/tree/production/apps/berth-ui/src/pages"
click node_ui_api "https://github.com/yassinos-coder/berth/tree/production/apps/berth-ui/src/services"
click node_auth "https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/auth/services/auth.service.ts"
click node_service_api "https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/services/controllers/services.controller.ts"
click node_service_logic "https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/services/services/services.service.ts"
click node_github "https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/github-app/github-webhook.controller.ts"
click node_agent_gateway "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/agent-gateway"
click node_enrollment "https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/agent-gateway/pki/enrollment.service.ts"
click node_database "https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/prisma/prisma.service.ts"
click node_protocol "https://github.com/yassinos-coder/berth/blob/production/packages/protocol/src/index.ts"
click node_agent_runtime "https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/panel.rs"
click node_reconciler "https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/docker.rs"
click node_proxy "https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/docker.rs"
click node_backups "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/backups"
click node_fleet "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/servers"
click node_teams "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/team"
click node_notifications "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/notifications"
click node_status "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/status-pages"
click node_github_service "https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/github-app"

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_ui_api toneBlue
class node_auth,node_service_api,node_service_logic,node_github,node_agent_gateway,node_enrollment,node_database toneAmber
class node_protocol,node_agent_runtime toneMint
class node_reconciler,node_docker,node_proxy,node_agent_host toneRose
class node_backups,node_fleet,node_teams,node_notifications,node_status,node_github_service,node_operator toneIndigo
```

## Components

### Dashboard and API

- [Web Dashboard](https://github.com/yassinos-coder/berth/tree/production/apps/berth-ui/src/pages): `apps/berth-ui/src/pages`
- [API Client](https://github.com/yassinos-coder/berth/tree/production/apps/berth-ui/src/services): `apps/berth-ui/src/services`

### Control Plane

- [Authentication](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/auth/services/auth.service.ts): `apps/berth-server/src/auth/services/auth.service.ts`
- [Service API](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/services/controllers/services.controller.ts): `apps/berth-server/src/services/controllers/services.controller.ts`
- [Service Orchestration](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/services/services/services.service.ts): `apps/berth-server/src/services/services/services.service.ts`
- [GitHub Webhooks](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/github-app/github-webhook.controller.ts): `apps/berth-server/src/github-app/github-webhook.controller.ts`
- [Agent Gateway](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/agent-gateway): `apps/berth-server/src/agent-gateway`
- [Agent Enrollment](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/agent-gateway/pki/enrollment.service.ts): `apps/berth-server/src/agent-gateway/pki/enrollment.service.ts`
- [Panel Database](https://github.com/yassinos-coder/berth/blob/production/apps/berth-server/src/prisma/prisma.service.ts): `apps/berth-server/src/prisma/prisma.service.ts`

### Server Agent

- [Shared Protocol](https://github.com/yassinos-coder/berth/blob/production/packages/protocol/src/index.ts): `packages/protocol/src/index.ts`
- [Agent Runtime](https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/panel.rs): `apps/berth-agent/src/panel.rs`

### Host Runtime

- [Docker Reconciler](https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/docker.rs): `apps/berth-agent/src/docker.rs`
- **Docker Services**
- [HTTPS Proxy](https://github.com/yassinos-coder/berth/blob/production/apps/berth-agent/src/docker.rs): `apps/berth-agent/src/docker.rs`
- **Managed VPS**

### Operations Features

- [Backup Operations](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/backups): `apps/berth-server/src/backups`
- [Fleet Management](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/servers): `apps/berth-server/src/servers`
- [Teams and RBAC](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/team): `apps/berth-server/src/team`
- [Notifications](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/notifications): `apps/berth-server/src/notifications`
- [Status Pages](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/status-pages): `apps/berth-server/src/status-pages`
- [GitHub Integration](https://github.com/yassinos-coder/berth/tree/production/apps/berth-server/src/github-app): `apps/berth-server/src/github-app`

### Other components

- **Operator**

## Connections

- Operator → Web Dashboard: manages (evidence: `README.md`)
- Web Dashboard → API Client: requests data (evidence: `README.md`)
- API Client → Authentication: authenticates (evidence: `README.md`)
- API Client → Service API: calls API (evidence: `README.md`)
- Service API → Service Orchestration: dispatches (evidence: `apps/berth-server/src/services/controllers/services.controller.ts`)
- Service Orchestration → Panel Database: persists state
- GitHub Webhooks → Panel Database: records deployments (evidence: `apps/berth-server/src/github-app/github-webhook.controller.ts`)
- GitHub Webhooks → Agent Gateway: requests reconcile (evidence: `apps/berth-server/src/github-app/github-webhook.controller.ts`)
- GitHub Integration → GitHub Webhooks: delivers push event (evidence: `README.md`)
- Fleet Management → Agent Enrollment: enrolls agent (evidence: `README.md`)
- Agent Enrollment → Panel Database: updates credentials (evidence: `apps/berth-server/src/agent-gateway/pki/enrollment.service.ts`)
- Agent Gateway → Agent Runtime: communicates WebSocket (evidence: `README.md`)
- Agent Runtime → Shared Protocol: exchanges messages (evidence: `README.md`)
- Agent Runtime → Docker Reconciler: invokes reconcile (evidence: `apps/berth-agent/src/main.rs`)
- Docker Reconciler → Docker Services: applies desired state (evidence: `README.md`)
- Docker Reconciler → HTTPS Proxy: configures routes (evidence: `apps/berth-agent/src/docker.rs`)
- Agent Runtime → Managed VPS: collects host specs
- Agent Runtime → Agent Gateway: reports status (evidence: `README.md`)
- Operator → Backup Operations: manages backups (evidence: `README.md`)
- Operator → Teams and RBAC: assigns roles (evidence: `README.md`)
- Operator → Notifications: configures alerts
- Operator → Status Pages: publishes status