Architecture overview

How browser traffic, durable state, background execution, and node actions fit together.

Repository-validated operator guidance View source ↗

#Complete system

A browser reaches Forge Web through the public proxy. Web calls Forge API. The API stores state and migrations in PostgreSQL, uses Redis where configured, and coordinates commands with Beacon. Beacon controls the Docker runtime and its local workload files. Backup artifacts can be local or S3-compatible; multi-node restore needs a repository reachable from every eligible node.

#Request and command flows

Flow	Path
Browser request	Browser → Caddy or Traefik → Forge Web; /api traffic is proxied to Forge API.
Game start	Dashboard/API → stored operation → Beacon request → Docker/container/files → observation returned to Forge.
Application deployment	Dashboard/API → deployment and revision records → Beacon build or Compose action → health observation → deployment status.
Backup and restore	Beacon reads workload data → backup adapter → local or S3-compatible repository → destination Beacon restores and reports result.

#Text topology

Architecture at a glance

Browser
  │ HTTPS 443
  ▼
Caddy or Traefik ─── Forge Web :3000
  │ /api
  ▼
Forge API :8080 ─── PostgreSQL :5432 (private)
  │                 Redis :6379 (private)
  │ authenticated commands / observations
  ▼
Beacon :9090 ─── Docker socket ─── workload containers
  └── SFTP :2022 ─── node data directory

#Background execution

The current repository starts background services from the API process and from Beacon. There is no separately shipped Forge worker binary or systemd worker unit. API cron jobs are loaded from PostgreSQL when the cron service starts; Beacon also starts its own scheduler for node-side tasks.