Architecture & how it works

This page explains Paylood’s architecture so you understand what happens at each deployment.

Overview

┌─────────────────────┐   SSH (port 22)   ┌──────────────────────┐
│  Paylood Hub        │ ────────────────▶ │  Your VPS            │
│  (API + Dashboard)  │                   │  ├─ Docker Engine    │
│                     │                   │  ├─ Traefik / Caddy  │
│  ─ Git OAuth        │   webhook push    │  ├─ App containers   │
│  ─ BullMQ queue     │ ◀──────────────── │  └─ Data volumes     │
│  ─ PostgreSQL/Redis │                   │                      │
└─────────────────────┘                   └──────────────────────┘

• Paylood Hub: the NestJS API, the job queue (BullMQ/Redis) and the dashboard.
• Your VPS: the servers you own. Paylood installs no agent on them — everything happens over SSH + Docker.
• Internet: Git webhooks, domains and SSL go through the proxies.

The deployment lifecycle

1. Trigger: a Git push (webhook) or the Deploy button.
2. Queued job: a deploy job is pushed into the Redis queue (BullMQ).
3. Clone: the repository is cloned at the target branch/commit into a temp folder.
4. Generation: Paylood produces the Dockerfile and .env.production according to the detected stack.
5. Upload: files are sent to the server over SSH into /opt/paylood/projects/<project>-<environment>.
6. Proxy: if a domain is set, Traefik/Caddy is configured (with TLS).
7. Build & Deploy: docker compose up builds and starts the containers.
8. Healthcheck: Paylood checks the application responds before marking the deployment success.
9. Cleanup: old images are removed (except the previous one, kept for rollback).

Stack detection

Repository analysis detects:

• The framework: Node.js, PHP/Laravel, static frontend (Vite/Next/React).
• The services: PostgreSQL, MySQL, MongoDB, Redis, RabbitMQ.
• The listening port (via PORT, APP_PORT, SERVER_PORT, default 3000).
• Monorepos: each service is identified by its path, and the right service is selected.

Server-side infrastructure

Once a project is deployed, your VPS contains:

/opt/paylood/projects/
└── <project>-<environment>/
    ├── docker-compose.yml
    ├── Dockerfile
    ├── .env.production
    └── src/            (removed after build)

The paylood-network Docker network interconnects the containers, and the reverse proxy (Traefik or Caddy) routes incoming traffic.

Paylood’s own database

The installation uses PostgreSQL (persistence) and Redis (job queues, OTP, token blacklist). Paylood’s app data (projects, servers, variables, backups) is stored in PostgreSQL; Git tokens are encrypted before storage.

Real-time streams

Everything is streamed via SSE (Server-Sent Events):

• Deployment status (deployment.<id>.updated).
• Console logs (xterm).
• SSH connection tests.
• Service scans and repository analysis.

Security

• JWT with expiration for authentication.
• Encryption of secrets (Git tokens, private keys) with the encryption key.
• Webhook signature verification (HMAC) for GitHub/Bitbucket, token for GitLab.
• SSH only (no additional open ports on your VPS).
• Helmet + throttling on the public API.