# nabinav/deployhub architecture

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

- Interactive diagram: https://gitdiagram.com/nabinav/deployhub
- Repository: https://github.com/nabinav/deployhub

## Overview

#### Purpose and entry points
DeployHub is a Go backend for repository-driven container deployments: GitHub source is connected, built into Docker images, published to Google Artifact Registry, and run on Cloud Run. The process starts at `main.go`; HTTP-facing orchestration is concentrated in `handler/`, while background deployment execution is in `worker/worker.go`.

#### HTTP/API and user session boundary
Handlers expose authentication, repository selection, deployment initiation, project retrieval, logs, image versions, rollback, deletion, and proxy behavior. They translate dashboard/API requests into persistence records and queued deployment work.
- `handler/auth.go`
- `handler/deployHandler.go`
- `handler/rollback.go`

Authentication integrates OAuth and JWT cookies/tokens, separating external GitHub identity exchange from application session verification.
- `auth/oauth.go`
- `jwt/create.go`
- `jwt/verify.go`

#### Project and deployment persistence
The `db` package is the system of record for users, projects, deployment jobs/status, environment variables, image IDs, queues, and logs. Handlers and workers should cross this boundary rather than own state directly.
- `db/init.go`
- `db/jobCreate.go`
- `db/updateProject.go`

Deployment state supports lifecycle transitions and recovery-oriented operations such as rollback, project deletion, and image-version lookup.
- `db/changeProjectStatus.go`
- `db/getDockerImageId.go`
- `db/log.go`

#### Queue-driven deployment execution
A deploy request creates/updates persisted work, then Redis-backed queue operations feed the worker. `worker/worker.go` is the asynchronous control-plane stage that performs deployment work independently of the request lifecycle.
- `redis/add.go`
- `db/updateQueue.go`
- `worker/worker.go`

The worker’s input/output contract is represented by deployment and worker schemas.
- `schema/deploySchema.go`
- `schema/workerSchema.go`

#### Source-control integration
GitHub access covers OAuth, repository discovery/selection, and webhook registration for continuous deployment. Git operations are isolated from handler concerns.
- `auth/oauth.go`
- `handler/repo.go`
- `cmd/git.go`

Webhook support forms the inbound continuous-deployment boundary; source retrieval is handled separately before builds.
- `webhook/addHook.go`
- `helper/getRepo.go`

#### Build and cloud deployment pipeline
The deployment stage clones/prepares source, detects or uses project Docker configuration, executes Docker build/push operations, and deploys the resulting image to GCP Cloud Run. Cloud-specific deployment orchestration is centered in:
- `deploy/deploy.go`
- `utils/docker.go`
- `helper/gcloudPublic.go`

Shell/command execution is abstracted behind utilities, making Docker and gcloud invocation a material host-runtime dependency.
- `utils/command.go`
- `utils/docker.go`

#### Runtime configuration, observability, and operations
Per-project environment variables are persisted then serialized/injected into deployment execution, rather than requiring repository `.env` files.
- `db/getProjectEnv.go`
- `utils/parse_env.go`
- `utils/env_string.go`

Logs flow from deployment execution into persistent logging and are surfaced through handlers. Deployment management also includes public proxying, rollback, and deletion paths.
- `log/logWriting.go`
- `handler/logHandler.go`
- `handler/proxy.go`

#### Infrastructure envelope
The service runs as a Go container (`Dockerfile`) and is locally composed with dependent services (`compose.yml`). Its material external systems are GitHub, Docker, Google Artifact Registry/Cloud Run, Redis, and the database initialized through `db/init.go`.

Main entry points: [`worker/worker.go`](https://github.com/nabinav/deployhub/blob/main/worker/worker.go) (Deployment worker), [`handler/deployHandler.go`](https://github.com/nabinav/deployhub/blob/main/handler/deployHandler.go) (API handlers), [`deploy/deploy.go`](https://github.com/nabinav/deployhub/blob/main/deploy/deploy.go) (Deployment orchestration), [`db/init.go`](https://github.com/nabinav/deployhub/blob/main/db/init.go) (Deployment database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP & Sessions"]
  node_main["Service entrypoint<br/>Go application<br/>[main.go]"]
  node_handlers["API handlers<br/>HTTP orchestration<br/>[deployHandler.go]"]
  node_auth["OAuth and JWT<br/>identity boundary<br/>[oauth.go]"]
  node_webhooks["Webhook registration<br/>GitHub integration<br/>[addHook.go]"]
end

subgraph group_control["Deployment Control Plane"]
  node_schemas["Deployment contracts<br/>Go schemas<br/>[deploySchema.go]"]
  node_worker["Deployment worker<br/>async control plane<br/>[worker.go]"]
  node_logs["Deployment logging<br/>observability writer<br/>[logWriting.go]"]
end

subgraph group_storage["Persistence &amp; Queue"]
  node_database[("Deployment database<br/>system of record<br/>[init.go]")]
  node_job_state["Job and project state<br/>persistence operations<br/>[jobCreate.go]"]
  node_redis["Redis queue<br/>work queue<br/>[add.go]"]
end

subgraph group_delivery["Build &amp; Cloud Delivery"]
  node_source["Repository retrieval<br/>Git source preparation<br/>[getRepo.go]"]
  node_deploy["Deployment orchestration<br/>build and release pipeline<br/>[deploy.go]"]
  node_command["Host command runner<br/>shell abstraction<br/>[command.go]"]
  node_docker["Docker build and push<br/>container runtime<br/>[docker.go]"]
  node_environment["Project environment injection<br/>runtime configuration<br/>[parse_env.go]"]
end

node_github{{"GitHub<br/>external source control"}}
node_gcp{{"Artifact Registry &amp; Cloud Run<br/>cloud delivery target"}}

node_main -->|"serves"| node_handlers
node_handlers -->|"authenticates"| node_auth
node_auth -->|"OAuth exchange"| node_github
node_handlers -->|"registers"| node_webhooks
node_webhooks -->|"creates hooks"| node_github
node_handlers -->|"reads and writes"| node_database
node_handlers -->|"creates deployment work"| node_job_state
node_job_state -->|"enqueues work"| node_redis
node_redis -->|"delivers jobs"| node_worker
node_worker -->|"uses"| node_schemas
node_worker -->|"updates lifecycle state"| node_database
node_worker -->|"retrieves source"| node_source
node_source -->|"clones repository"| node_github
node_worker -->|"loads project variables"| node_environment
node_worker -->|"executes deployment"| node_deploy
node_deploy -->|"builds and pushes"| node_docker
node_deploy -->|"runs through"| node_command
node_docker -->|"publishes image"| node_gcp
node_deploy -->|"deploys service"| node_gcp
node_worker -->|"emits logs"| node_logs
node_logs -->|"persists"| node_database
node_handlers -.->|"retrieves logs and versions"| node_database

click node_main "https://github.com/nabinav/deployhub/blob/main/main.go"
click node_handlers "https://github.com/nabinav/deployhub/blob/main/handler/deployHandler.go"
click node_auth "https://github.com/nabinav/deployhub/blob/main/auth/oauth.go"
click node_webhooks "https://github.com/nabinav/deployhub/blob/main/webhook/addHook.go"
click node_database "https://github.com/nabinav/deployhub/blob/main/db/init.go"
click node_job_state "https://github.com/nabinav/deployhub/blob/main/db/jobCreate.go"
click node_redis "https://github.com/nabinav/deployhub/blob/main/redis/add.go"
click node_schemas "https://github.com/nabinav/deployhub/blob/main/schema/deploySchema.go"
click node_worker "https://github.com/nabinav/deployhub/blob/main/worker/worker.go"
click node_source "https://github.com/nabinav/deployhub/blob/main/helper/getRepo.go"
click node_deploy "https://github.com/nabinav/deployhub/blob/main/deploy/deploy.go"
click node_command "https://github.com/nabinav/deployhub/blob/main/utils/command.go"
click node_docker "https://github.com/nabinav/deployhub/blob/main/utils/docker.go"
click node_environment "https://github.com/nabinav/deployhub/blob/main/utils/parse_env.go"
click node_logs "https://github.com/nabinav/deployhub/blob/main/log/logWriting.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_main,node_handlers,node_auth,node_webhooks toneBlue
class node_schemas,node_worker,node_logs toneAmber
class node_database,node_job_state,node_redis toneMint
class node_source,node_deploy,node_command,node_docker,node_environment toneRose
class node_github,node_gcp toneNeutral
```

## Components

### HTTP & Sessions

- [Service entrypoint](https://github.com/nabinav/deployhub/blob/main/main.go): Go application · `main.go`
- [API handlers](https://github.com/nabinav/deployhub/blob/main/handler/deployHandler.go): HTTP orchestration · Handles deploys, projects, logs, rollback, deletion, and proxying. · `handler/deployHandler.go`
- [OAuth and JWT](https://github.com/nabinav/deployhub/blob/main/auth/oauth.go): identity boundary · Exchanges GitHub identity and verifies application sessions. · `auth/oauth.go`
- [Webhook registration](https://github.com/nabinav/deployhub/blob/main/webhook/addHook.go): GitHub integration · `webhook/addHook.go`

### Deployment Control Plane

- [Deployment contracts](https://github.com/nabinav/deployhub/blob/main/schema/deploySchema.go): Go schemas · `schema/deploySchema.go`
- [Deployment worker](https://github.com/nabinav/deployhub/blob/main/worker/worker.go): async control plane · Consumes queued deployment work independently of HTTP requests. · `worker/worker.go`
- [Deployment logging](https://github.com/nabinav/deployhub/blob/main/log/logWriting.go): observability writer · `log/logWriting.go`

### Persistence & Queue

- [Deployment database](https://github.com/nabinav/deployhub/blob/main/db/init.go): system of record · Stores users, projects, jobs, status, environments, images, queues, and logs. · `db/init.go`
- [Job and project state](https://github.com/nabinav/deployhub/blob/main/db/jobCreate.go): persistence operations · `db/jobCreate.go`
- [Redis queue](https://github.com/nabinav/deployhub/blob/main/redis/add.go): work queue · `redis/add.go`

### Build & Cloud Delivery

- [Repository retrieval](https://github.com/nabinav/deployhub/blob/main/helper/getRepo.go): Git source preparation · `helper/getRepo.go`
- [Deployment orchestration](https://github.com/nabinav/deployhub/blob/main/deploy/deploy.go): build and release pipeline · Builds, publishes, and deploys the selected project. · `deploy/deploy.go`
- [Host command runner](https://github.com/nabinav/deployhub/blob/main/utils/command.go): shell abstraction · Executes Docker and gcloud commands. · `utils/command.go`
- [Docker build and push](https://github.com/nabinav/deployhub/blob/main/utils/docker.go): container runtime · `utils/docker.go`
- [Project environment injection](https://github.com/nabinav/deployhub/blob/main/utils/parse_env.go): runtime configuration · Serializes persisted project variables for deployment execution. · `utils/parse_env.go`

### Other components

- **GitHub**: external source control
- **Artifact Registry & Cloud Run**: cloud delivery target

## Connections

- Service entrypoint → API handlers: serves
- API handlers → OAuth and JWT: authenticates
- OAuth and JWT → GitHub: OAuth exchange
- API handlers → Webhook registration: registers
- Webhook registration → GitHub: creates hooks
- API handlers → Deployment database: reads and writes
- API handlers → Job and project state: creates deployment work
- Job and project state → Redis queue: enqueues work
- Redis queue → Deployment worker: delivers jobs
- Deployment worker → Deployment contracts: uses
- Deployment worker → Deployment database: updates lifecycle state
- Deployment worker → Repository retrieval: retrieves source
- Repository retrieval → GitHub: clones repository
- Deployment worker → Project environment injection: loads project variables
- Deployment worker → Deployment orchestration: executes deployment
- Deployment orchestration → Docker build and push: builds and pushes
- Deployment orchestration → Host command runner: runs through
- Docker build and push → Artifact Registry & Cloud Run: publishes image
- Deployment orchestration → Artifact Registry & Cloud Run: deploys service
- Deployment worker → Deployment logging: emits logs
- Deployment logging → Deployment database: persists
- API handlers → Deployment database: retrieves logs and versions