Ledgr Network Architecture

Overview

Ledgr runs as a set of three Docker containers orchestrated by Docker Compose. All containers communicate over a private Docker bridge network called ledgr_network. This network is invisible to the host machine and the internet — only the Nginx frontend container exposes a public port.

The architecture follows a reverse-proxy pattern: the browser talks only to Nginx on port 80 (or 443 with TLS). Nginx forwards API calls internally to the Node.js container, which in turn queries the PostgreSQL container — neither of which is reachable from outside.

Network Topology Diagram

The diagram below shows how traffic flows from the internet through each layer of the stack.

Container Inventory

Network Configuration

Docker Compose network definition

# docker-compose.yml — networks block
networks:
  ledgr-net:
    driver: bridge
    name:   ledgr_network
    internal: false   # allows outbound internet (e.g. npm install)

Port Exposure Matrix

Understanding the difference between ports (published to host) and expose (internal only) is critical to the security posture of this deployment.

Internal DNS & Service Discovery

Docker's embedded DNS resolver automatically maps each container's service name to its internal IP address. No static IPs or hosts files are needed.

How Nginx references the API

# nginx/nginx.conf
location /api/ {
  proxy_pass  http://ledgr-api:4000;   # Docker DNS resolves "ledgr-api"
  proxy_set_header  Host              $host;
  proxy_set_header  X-Real-IP         $remote_addr;
  proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
}

How the API connects to PostgreSQL

# backend/db/pool.js — pg Pool config
const pool = new Pool({
  host:     'ledgr-db',   // resolved by Docker DNS
  port:     5432,
  database: 'ledgr',
  user:     'ledgr',
  password: process.env.PGPASSWORD,
});

Traffic Flow

The following steps trace a complete request lifecycle from a user's browser through all three containers.

Example: User logs in

Network Security Controls

Environment & Secrets

Generating secrets

# JWT secret (64 bytes)
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

# Encryption key (32 bytes)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Or with openssl
openssl rand -hex 64   # JWT_SECRET
openssl rand -hex 32   # ENCRYPTION_KEY

Useful Commands

Starting & stopping

# Start all containers
docker compose up -d --build

# Stop all containers
docker compose down

# Stop and remove volumes (DELETES ALL DATA)
docker compose down -v

Viewing logs

# All containers
docker compose logs -f

# Specific container
docker compose logs -f ledgr-api
docker compose logs -f ledgr-db
docker compose logs -f ledgr-frontend

Seeding the admin account

# Run once after first start
docker compose exec ledgr-api node db/seed.js

Inspecting the network

# Show all containers and their IPs on the network
docker network inspect ledgr_network

# Verify containers can reach each other
docker compose exec ledgr-api ping ledgr-db
docker compose exec ledgr-frontend ping ledgr-api

# Check open ports on the host (only port 80 should appear)
ss -tlnp | grep docker

Database access (admin only)

# Open psql shell inside the DB container
docker compose exec ledgr-db psql -U ledgr -d ledgr

# Run a query
docker compose exec ledgr-db psql -U ledgr -d ledgr \
  -c "SELECT id, email, role, mfa_enabled FROM users;"

Healthcheck status

# See health status of all containers
docker compose ps

# Detailed healthcheck info
docker inspect --format='{{json .State.Health}}' ledgr-api | python3 -m json.tool