# ojhapranjal26/featherdeploy architecture

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

- Interactive diagram: https://gitdiagram.com/ojhapranjal26/featherdeploy
- Repository: https://github.com/ojhapranjal26/featherdeploy

## Overview

FeatherDeploy is a self-hosted PaaS for managing applications and databases across a worker cluster. Users work through the web panel to configure projects and services, deploy applications, and monitor runtime status; administrators also manage nodes, storage, and access. The control plane coordinates persisted state and node operations, while workers run containers and the proxy engine reconciles routing. The README documents GitHub-based push-to-deploy, framework detection, and automatic TLS; some implementation wiring is not visible in the sampled excerpts, so those links are shown only where supported.

Main entry points: [`backend/internal/handler/deployments.go`](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/deployments.go) (API handlers), [`backend/cmd/server/main.go`](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/cmd/server/main.go) (HTTP server), [`frontend/src/App.tsx`](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/App.tsx) (Panel routes), [`frontend/src/api/client.ts`](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web panel"]
  node_app["Panel routes<br/>[App.tsx]"]
  node_project_ui["Project workflows<br/>[ProjectPage.tsx]"]
  node_deploy_ui["Deployment views"]
  node_cluster_ui["Cluster views<br/>[ClusterPage.tsx]"]
  node_storage_ui["Storage management<br/>[StoragePage.tsx]"]
  node_api["API client<br/>[client.ts]"]
end

subgraph group_control["Control plane"]
  node_server["HTTP server<br/>[main.go]"]
  node_handlers["API handlers<br/>[deployments.go]"]
  node_deploy["Deploy scheduler<br/>[scheduler.go]"]
  node_detect["Framework detection<br/>[detect.go]"]
  node_github["GitHub integration<br/>[github.go]"]
  node_storage["Object storage API<br/>[storage.go]"]
end

subgraph group_runtime["Cluster runtime"]
  node_node["Worker agent<br/>[main.go]"]
  node_runner["Container runner<br/>[runner.go]"]
  node_node_daemon["Node daemon<br/>[daemon.go]"]
end

subgraph group_state["Cluster state and networking"]
  node_database[("Distributed database<br/>[db.go]")]
  node_coordination["Cluster coordination<br/>[coordination.go]"]
  node_proxy["Route reconciliation<br/>[engine.go]"]
  node_nginx["Proxy configuration<br/>[nginx.go]"]
end

node_user(("User"))
node_github_service["GitHub"]
node_etcd[("Etcd")]
node_rqlite[("rqlite")]
node_podman["Podman containers"]
node_edge["HTTPS edge proxy"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_project_ui
node_app -->|"routes to"| node_deploy_ui
node_app -->|"routes to"| node_cluster_ui
node_app -->|"routes to"| node_storage_ui
node_project_ui -->|"requests"| node_api
node_deploy_ui -->|"requests"| node_api
node_cluster_ui -->|"requests"| node_api
node_storage_ui -->|"requests"| node_api
node_api -->|"calls API"| node_server
node_server -->|"dispatches"| node_handlers
node_handlers -->|"reads and writes"| node_database
node_handlers -->|"requests deployment"| node_deploy
node_deploy -->|"orchestrates"| node_node_daemon
node_node_daemon -->|"contacts worker"| node_node
node_node -->|"starts workloads"| node_runner
node_runner -->|"runs containers"| node_podman
node_handlers -->|"uses detection"| node_detect
node_handlers -->|"dispatches integration"| node_github
node_github -.->|"OAuth and app access"| node_github_service
node_server -->|"initializes"| node_coordination
node_coordination -->|"coordinates state"| node_etcd
node_server -->|"uses storage"| node_rqlite
node_proxy -->|"watches routes"| node_etcd
node_proxy -->|"applies configuration"| node_nginx
node_edge -->|"forwards HTTPS"| node_server
node_handlers -->|"dispatches storage requests"| node_storage
node_storage -->|"stores metadata"| node_database
node_server -->|"starts engine"| node_proxy

click node_app "https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/App.tsx"
click node_project_ui "https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/ProjectPage.tsx"
click node_deploy_ui "https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/DeploymentListPage.tsx"
click node_cluster_ui "https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/ClusterPage.tsx"
click node_storage_ui "https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/StoragePage.tsx"
click node_api "https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/api/client.ts"
click node_server "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/cmd/server/main.go"
click node_handlers "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/deployments.go"
click node_deploy "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/deploy/scheduler.go"
click node_detect "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/detect/detect.go"
click node_github "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/github.go"
click node_storage "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/storage.go"
click node_database "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/db/db.go"
click node_coordination "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/coordination/coordination.go"
click node_proxy "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/proxyengine/engine.go"
click node_nginx "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/nginx/nginx.go"
click node_node "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/cmd/node/main.go"
click node_runner "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/deploy/runner.go"
click node_node_daemon "https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/netdaemon/daemon.go"

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_app,node_project_ui,node_deploy_ui,node_cluster_ui,node_storage_ui,node_api,node_user toneBlue
class node_server,node_handlers,node_deploy,node_detect,node_github,node_storage,node_etcd,node_rqlite toneAmber
class node_node,node_runner,node_node_daemon toneMint
class node_database,node_coordination,node_proxy,node_nginx toneRose
class node_github_service,node_podman,node_edge toneIndigo
```

## Components

### Web panel

- [Panel routes](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Project workflows](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/ProjectPage.tsx): `frontend/src/pages/ProjectPage.tsx`
- [Deployment views](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/DeploymentListPage.tsx): `frontend/src/pages/DeploymentListPage.tsx`
- [Cluster views](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/ClusterPage.tsx): `frontend/src/pages/ClusterPage.tsx`
- [Storage management](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/pages/StoragePage.tsx): `frontend/src/pages/StoragePage.tsx`
- [API client](https://github.com/ojhapranjal26/featherdeploy/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Control plane

- [HTTP server](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/cmd/server/main.go): `backend/cmd/server/main.go`
- [API handlers](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/deployments.go): `backend/internal/handler/deployments.go`
- [Deploy scheduler](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/deploy/scheduler.go): `backend/internal/deploy/scheduler.go`
- [Framework detection](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/detect/detect.go): `backend/internal/detect/detect.go`
- [GitHub integration](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/github.go): `backend/internal/handler/github.go`
- [Object storage API](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/handler/storage.go): `backend/internal/handler/storage.go`

### Cluster runtime

- [Worker agent](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/cmd/node/main.go): `backend/cmd/node/main.go`
- [Container runner](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/deploy/runner.go): `backend/internal/deploy/runner.go`
- [Node daemon](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/netdaemon/daemon.go): `backend/internal/netdaemon/daemon.go`

### Cluster state and networking

- [Distributed database](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/db/db.go): `backend/internal/db/db.go`
- [Cluster coordination](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/coordination/coordination.go): `backend/internal/coordination/coordination.go`
- [Route reconciliation](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/proxyengine/engine.go): `backend/internal/proxyengine/engine.go`
- [Proxy configuration](https://github.com/ojhapranjal26/featherdeploy/blob/main/backend/internal/nginx/nginx.go): `backend/internal/nginx/nginx.go`

### Other components

- **User**
- **GitHub**
- **Etcd**
- **rqlite**
- **Podman containers**
- **HTTPS edge proxy**

## Connections

- User → Panel routes: uses
- Panel routes → Project workflows: routes to
- Panel routes → Deployment views: routes to
- Panel routes → Cluster views: routes to
- Panel routes → Storage management: routes to
- Project workflows → API client: requests
- Deployment views → API client: requests
- Cluster views → API client: requests
- Storage management → API client: requests
- API client → HTTP server: calls API
- HTTP server → API handlers: dispatches
- API handlers → Distributed database: reads and writes
- API handlers → Deploy scheduler: requests deployment
- Deploy scheduler → Node daemon: orchestrates
- Node daemon → Worker agent: contacts worker
- Worker agent → Container runner: starts workloads
- Container runner → Podman containers: runs containers
- API handlers → Framework detection: uses detection
- API handlers → GitHub integration: dispatches integration
- GitHub integration → GitHub: OAuth and app access
- HTTP server → Cluster coordination: initializes
- Cluster coordination → Etcd: coordinates state
- HTTP server → rqlite: uses storage
- Route reconciliation → Etcd: watches routes
- Route reconciliation → Proxy configuration: applies configuration
- HTTPS edge proxy → HTTP server: forwards HTTPS
- API handlers → Object storage API: dispatches storage requests
- Object storage API → Distributed database: stores metadata
- HTTP server → Route reconciliation: starts engine