README – Single Production & Developer Manual

This README is the only manual you need for both running the platform in production and onboarding new developers. It consolidates operational procedures, configuration guidelines, and development workflows into a single, version‑controlled document.

Purpose

Provide a clear, searchable reference for production tasks such as deployment, monitoring, and backup.
Offer a concise developer guide covering environment setup, code standards, and contribution workflow.
Ensure that any change to the stack or process is reflected in one place, reducing drift between docs and reality.

Current Stack

The platform runs on a modern, container‑friendly stack. Below is a snapshot of the versions used in the latest release.

web:
  framework: Node.js 18.17.0
  server: Nginx 1.24.0
  runtime: Docker 24.0.5

database:
  primary: PostgreSQL 15.4
  cache: Redis 7.2.1

messaging:
  broker: RabbitMQ 3.11.13

monitoring:
  metrics: Prometheus 2.48.0
  alerts: Alertmanager 0.26.0

Web layer – Node.js application served behind Nginx reverse proxy.
Data layer – PostgreSQL for relational data, Redis for session storage and caching.
Messaging – RabbitMQ handles asynchronous job queues.
Observability – Prometheus scrapes metrics; Alertmanager routes alerts.

Production Workflow

Build – Run docker compose build to create images.
Deploy – Use docker compose up -d on the target host.
Verify – Check health endpoints (/healthz) and Prometheus targets.
Backup – Schedule nightly pg_dump and Redis RDB snapshots.

Development Workflow

Clone the repository.
Copy .env.example to .env and adjust local values.
Run docker compose up -d to start all services.
Execute npm run dev inside the web container for hot‑reloading.
Run tests with npm test before committing.

For detailed step‑by‑step instructions, see the sections below or search this README using your IDE's full‑text search.