# gsmota323/zploy architecture

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

- Interactive diagram: https://gitdiagram.com/gsmota323/zploy
- Repository: https://github.com/gsmota323/zploy

## Overview

Zploy is a local, prototype PaaS for managing apps and deploying GitHub repositories into Docker containers. Users authenticate (or use the documented study mode), create and configure apps, then request a deployment manually or trigger one with a GitHub push webhook. The API records deployment state and queues work; a separate worker fetches code, prepares and builds an image, starts the container, and records status and logs. The web panel operates the platform and presents deployment information. The worker excerpt is partial, so uncertain internal deployment wiring is omitted.

Main entry points: [`src/app.ts`](https://github.com/gsmota323/zploy/blob/main/src/app.ts) (Express application), [`src/workers/deployWorker.ts`](https://github.com/gsmota323/zploy/blob/main/src/workers/deployWorker.ts) (Deploy worker), [`prisma/schema.prisma`](https://github.com/gsmota323/zploy/blob/main/prisma/schema.prisma) (PostgreSQL database), [`src/controllers/deployController.ts`](https://github.com/gsmota323/zploy/blob/main/src/controllers/deployController.ts) (Deploy controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web panel"]
  node_panel["Web panel<br/>[dashboard.html]"]
  node_frontend_api["Frontend API client<br/>[api.js]"]
end

subgraph group_api["API and management"]
  node_server["Express application<br/>[app.ts]"]
  node_app_routes["App routes<br/>[appRoutes.ts]"]
  node_auth_routes["Auth routes<br/>[authRoutes.ts]"]
  node_user_routes["User routes<br/>[userRoutes.ts]"]
  node_app_controller["App controller<br/>[appController.ts]"]
  node_deploy_controller["Deploy controller"]
  node_env_controller["Environment controller<br/>[envController.ts]"]
  node_auth_controller["Auth controller<br/>[authController.ts]"]
  node_user_controller["User controller<br/>[userController.ts]"]
  node_app_service["App service<br/>[appService.ts]"]
  node_auth_service["Auth service<br/>[authService.ts]"]
  node_env_service["Environment service<br/>[envService.ts]"]
  node_study_mode["Study mode"]
  node_webhook_utils["GitHub webhook utilities<br/>[githubWebhook.ts]"]
end

subgraph group_state["Platform state"]
  node_database[("PostgreSQL database<br/>[schema.prisma]")]
  node_redis[("Redis<br/>[redis.ts]")]
end

subgraph group_deploy["Deployment runtime"]
  node_queue["Deploy queue<br/>[deployQueue.ts]"]
  node_worker["Deploy worker<br/>[deployWorker.ts]"]
  node_docker_provider["Docker provider<br/>[dockerProvider.ts]"]
  node_deploy_provider["Provider interface"]
  node_deploy_logs["Deploy log service"]
  node_dockerfile["Dockerfile utilities<br/>[dockerfile.ts]"]
  node_command_logs["Command log runner"]
end

subgraph group_integrations["External systems"]
  node_github["GitHub"]
  node_docker["Docker engine"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_panel
node_panel -->|"requests"| node_frontend_api
node_frontend_api -->|"calls API"| node_server
node_server -->|"mounts"| node_app_routes
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_user_routes
node_app_routes -->|"dispatches"| node_app_controller
node_app_routes -->|"dispatches"| node_deploy_controller
node_app_routes -->|"dispatches"| node_env_controller
node_auth_routes -->|"dispatches"| node_auth_controller
node_user_routes -->|"dispatches"| node_user_controller
node_app_controller -->|"calls"| node_app_service
node_app_controller -->|"reads/writes"| node_database
node_app_controller -->|"enqueues"| node_queue
node_deploy_controller -->|"reads/writes"| node_database
node_deploy_controller -->|"enqueues"| node_queue
node_deploy_controller -->|"records/fetches"| node_deploy_logs
node_deploy_controller -->|"stops container"| node_docker_provider
node_env_controller -->|"checks ownership"| node_database
node_env_controller -->|"calls"| node_env_service
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"reads user"| node_database
node_user_controller -->|"reads profile"| node_database
node_server -->|"validates webhook"| node_webhook_utils
node_server -->|"matches app; records deploy"| node_database
node_server -->|"enqueues webhook deploy"| node_queue
node_server -.->|"receives push webhook"| node_github
node_queue -->|"stores jobs"| node_redis
node_worker -->|"consumes jobs"| node_queue
node_worker -->|"reads/writes deploy state"| node_database
node_worker -->|"records progress"| node_deploy_logs
node_worker -->|"runs logged commands"| node_command_logs
node_worker -->|"prepares build input"| node_dockerfile
node_worker -->|"clones repository"| node_github
node_worker -->|"builds and runs containers"| node_docker
node_docker_provider -->|"controls containers"| node_docker
node_docker_provider -->|"implements"| node_deploy_provider
node_deploy_logs -->|"stores logs"| node_database

click node_panel "https://github.com/gsmota323/zploy/blob/main/frontend/dashboard.html"
click node_frontend_api "https://github.com/gsmota323/zploy/blob/main/frontend/js/api.js"
click node_server "https://github.com/gsmota323/zploy/blob/main/src/app.ts"
click node_app_routes "https://github.com/gsmota323/zploy/blob/main/src/routes/appRoutes.ts"
click node_auth_routes "https://github.com/gsmota323/zploy/blob/main/src/routes/authRoutes.ts"
click node_user_routes "https://github.com/gsmota323/zploy/blob/main/src/routes/userRoutes.ts"
click node_app_controller "https://github.com/gsmota323/zploy/blob/main/src/controllers/appController.ts"
click node_deploy_controller "https://github.com/gsmota323/zploy/blob/main/src/controllers/deployController.ts"
click node_env_controller "https://github.com/gsmota323/zploy/blob/main/src/controllers/envController.ts"
click node_auth_controller "https://github.com/gsmota323/zploy/blob/main/src/controllers/authController.ts"
click node_user_controller "https://github.com/gsmota323/zploy/blob/main/src/controllers/userController.ts"
click node_app_service "https://github.com/gsmota323/zploy/blob/main/src/services/appService.ts"
click node_auth_service "https://github.com/gsmota323/zploy/blob/main/src/services/authService.ts"
click node_env_service "https://github.com/gsmota323/zploy/blob/main/src/services/envService.ts"
click node_study_mode "https://github.com/gsmota323/zploy/blob/main/src/services/studyModeService.ts"
click node_queue "https://github.com/gsmota323/zploy/blob/main/src/queues/deployQueue.ts"
click node_worker "https://github.com/gsmota323/zploy/blob/main/src/workers/deployWorker.ts"
click node_docker_provider "https://github.com/gsmota323/zploy/blob/main/src/services/deployment/dockerProvider.ts"
click node_deploy_provider "https://github.com/gsmota323/zploy/blob/main/src/services/deployment/deploymentProvider.ts"
click node_deploy_logs "https://github.com/gsmota323/zploy/blob/main/src/services/deployLogService.ts"
click node_dockerfile "https://github.com/gsmota323/zploy/blob/main/src/utils/dockerfile.ts"
click node_command_logs "https://github.com/gsmota323/zploy/blob/main/src/utils/runCommandWithLogs.ts"
click node_webhook_utils "https://github.com/gsmota323/zploy/blob/main/src/utils/githubWebhook.ts"
click node_database "https://github.com/gsmota323/zploy/blob/main/prisma/schema.prisma"
click node_redis "https://github.com/gsmota323/zploy/blob/main/src/config/redis.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_panel,node_frontend_api toneBlue
class node_server,node_app_routes,node_auth_routes,node_user_routes,node_app_controller,node_deploy_controller,node_env_controller,node_auth_controller,node_user_controller,node_app_service,node_auth_service,node_env_service,node_study_mode,node_webhook_utils toneAmber
class node_database,node_redis toneMint
class node_queue,node_worker,node_docker_provider,node_deploy_provider,node_deploy_logs,node_dockerfile,node_command_logs toneRose
class node_github,node_docker,node_operator toneIndigo
```

## Components

### Web panel

- [Web panel](https://github.com/gsmota323/zploy/blob/main/frontend/dashboard.html): `frontend/dashboard.html`
- [Frontend API client](https://github.com/gsmota323/zploy/blob/main/frontend/js/api.js): `frontend/js/api.js`

### API and management

- [Express application](https://github.com/gsmota323/zploy/blob/main/src/app.ts): `src/app.ts`
- [App routes](https://github.com/gsmota323/zploy/blob/main/src/routes/appRoutes.ts): `src/routes/appRoutes.ts`
- [Auth routes](https://github.com/gsmota323/zploy/blob/main/src/routes/authRoutes.ts): `src/routes/authRoutes.ts`
- [User routes](https://github.com/gsmota323/zploy/blob/main/src/routes/userRoutes.ts): `src/routes/userRoutes.ts`
- [App controller](https://github.com/gsmota323/zploy/blob/main/src/controllers/appController.ts): `src/controllers/appController.ts`
- [Deploy controller](https://github.com/gsmota323/zploy/blob/main/src/controllers/deployController.ts): `src/controllers/deployController.ts`
- [Environment controller](https://github.com/gsmota323/zploy/blob/main/src/controllers/envController.ts): `src/controllers/envController.ts`
- [Auth controller](https://github.com/gsmota323/zploy/blob/main/src/controllers/authController.ts): `src/controllers/authController.ts`
- [User controller](https://github.com/gsmota323/zploy/blob/main/src/controllers/userController.ts): `src/controllers/userController.ts`
- [App service](https://github.com/gsmota323/zploy/blob/main/src/services/appService.ts): `src/services/appService.ts`
- [Auth service](https://github.com/gsmota323/zploy/blob/main/src/services/authService.ts): `src/services/authService.ts`
- [Environment service](https://github.com/gsmota323/zploy/blob/main/src/services/envService.ts): `src/services/envService.ts`
- [Study mode](https://github.com/gsmota323/zploy/blob/main/src/services/studyModeService.ts): `src/services/studyModeService.ts`
- [GitHub webhook utilities](https://github.com/gsmota323/zploy/blob/main/src/utils/githubWebhook.ts): `src/utils/githubWebhook.ts`

### Platform state

- [PostgreSQL database](https://github.com/gsmota323/zploy/blob/main/prisma/schema.prisma): `prisma/schema.prisma`
- [Redis](https://github.com/gsmota323/zploy/blob/main/src/config/redis.ts): `src/config/redis.ts`

### Deployment runtime

- [Deploy queue](https://github.com/gsmota323/zploy/blob/main/src/queues/deployQueue.ts): `src/queues/deployQueue.ts`
- [Deploy worker](https://github.com/gsmota323/zploy/blob/main/src/workers/deployWorker.ts): `src/workers/deployWorker.ts`
- [Docker provider](https://github.com/gsmota323/zploy/blob/main/src/services/deployment/dockerProvider.ts): `src/services/deployment/dockerProvider.ts`
- [Provider interface](https://github.com/gsmota323/zploy/blob/main/src/services/deployment/deploymentProvider.ts): `src/services/deployment/deploymentProvider.ts`
- [Deploy log service](https://github.com/gsmota323/zploy/blob/main/src/services/deployLogService.ts): `src/services/deployLogService.ts`
- [Dockerfile utilities](https://github.com/gsmota323/zploy/blob/main/src/utils/dockerfile.ts): `src/utils/dockerfile.ts`
- [Command log runner](https://github.com/gsmota323/zploy/blob/main/src/utils/runCommandWithLogs.ts): `src/utils/runCommandWithLogs.ts`

### External systems

- **GitHub**
- **Docker engine**

### Other components

- **Operator**

## Connections

- Operator → Web panel: uses
- Web panel → Frontend API client: requests
- Frontend API client → Express application: calls API
- Express application → App routes: mounts
- Express application → Auth routes: mounts
- Express application → User routes: mounts
- App routes → App controller: dispatches
- App routes → Deploy controller: dispatches
- App routes → Environment controller: dispatches
- Auth routes → Auth controller: dispatches
- User routes → User controller: dispatches
- App controller → App service: calls
- App controller → PostgreSQL database: reads/writes
- App controller → Deploy queue: enqueues
- Deploy controller → PostgreSQL database: reads/writes
- Deploy controller → Deploy queue: enqueues
- Deploy controller → Deploy log service: records/fetches
- Deploy controller → Docker provider: stops container
- Environment controller → PostgreSQL database: checks ownership
- Environment controller → Environment service: calls
- Auth controller → Auth service: calls
- Auth service → PostgreSQL database: reads user
- User controller → PostgreSQL database: reads profile
- Express application → GitHub webhook utilities: validates webhook
- Express application → PostgreSQL database: matches app; records deploy
- Express application → Deploy queue: enqueues webhook deploy
- Express application → GitHub: receives push webhook
- Deploy queue → Redis: stores jobs
- Deploy worker → Deploy queue: consumes jobs
- Deploy worker → PostgreSQL database: reads/writes deploy state
- Deploy worker → Deploy log service: records progress
- Deploy worker → Command log runner: runs logged commands
- Deploy worker → Dockerfile utilities: prepares build input
- Deploy worker → GitHub: clones repository
- Deploy worker → Docker engine: builds and runs containers
- Docker provider → Docker engine: controls containers
- Docker provider → Provider interface: implements
- Deploy log service → PostgreSQL database: stores logs