Skip to content
This repository was archived by the owner on Jun 2, 2026. It is now read-only.

README.md

Latest commit

 

History

History
248 lines (182 loc) · 5.63 KB

README.md

File metadata and controls

248 lines (182 loc) · 5.63 KB
Raw

Deployment Architecture

This directory documents the deployment-side system architecture for the configuration management platform. It focuses on infrastructure concerns: traffic routing, load balancing, service health, deployment boundaries, and future production extensions.

Target Topology

Users
  -> DNS / HTTPS
  -> Load Balancer / Reverse Proxy
      -> Web Frontend
      -> Backend API Pool
          -> PostgreSQL / Neon
          -> Object Storage, later
          -> Queue / Worker, later

The application code remains a modular full-stack system:

React + Vite frontend
Spring Boot backend
PostgreSQL / Neon database
Flyway migrations
GitHub Actions CI

The deployment layer should keep these responsibilities separate:

Frontend
  Serves the browser UI and static assets.

Reverse Proxy / Load Balancer
  Terminates or forwards HTTPS, routes /api/* to backend replicas, routes the
  rest of the app to frontend hosting, and provides a stable public entrypoint.

Backend API
  Owns authentication, authorization, template/project/scope logic, export
  generation, secret masking, and persistence rules.

Database
  Stores source-of-truth data. It should only be reachable by backend services,
  not by browsers.

Load Balancing Model

The backend is designed to be stateless from a request-routing perspective:

  • authentication uses JWT
  • no server-side HTTP session is required
  • source-of-truth state is stored in PostgreSQL
  • generated export content is produced from backend-managed project scope data

That means multiple backend replicas can sit behind a load balancer:

Load Balancer
  -> backend-1:8080
  -> backend-2:8080
  -> backend-3:8080

The repository includes:

deploy/nginx.production.conf

This is a production-oriented Nginx template. It shows:

  • /api/* routed to a backend API pool
  • /api/health routed to backend health checks
  • / routed to the frontend origin
  • least_conn balancing for backend replicas
  • forwarded headers for reverse-proxy deployments
  • timeout settings for API requests

The backend exposes:

GET /api/health

Use it for platform health probes, uptime monitoring, and load balancer target checks.

Production-Like Compose Stack

For a runnable local deployment that mirrors the target topology, use:

deploy/production-like/

It runs:

  • Nginx reverse proxy on http://127.0.0.1:8090
  • frontend static container
  • scalable backend API replicas
  • PostgreSQL
  • health checks for each service

Start it with:

docker compose -f deploy/production-like/compose.yml up --build --scale backend=2

This stack is the recommended deployment rehearsal for demos and architecture validation. It is closer to production than the regular local dev setup because the browser talks to one public entrypoint and /api/* is routed through the reverse proxy.

Local Load Balancing Demo

The demo environment is under:

deploy/demo/

It runs:

  • Nginx load balancer
  • multiple backend replicas
  • PostgreSQL
  • Redis
  • RabbitMQ

Start it with:

docker compose -f deploy/demo/compose.yml up --build --scale backend=3

Then check backend instance routing:

curl http://127.0.0.1:8088/api/system/instance

Call it multiple times. The instanceId should vary when requests are routed to different backend containers.

The demo is intentionally single-machine. It validates routing behavior, not true multi-zone high availability.

Production Phases

Phase 1: Simple Managed Deployment

Use this when the system is still early but should be reachable by teammates.

Frontend: Vercel / Netlify / static hosting
Backend:  Render / Fly.io / Railway / container host
DB:       Neon PostgreSQL
CI:       GitHub Actions

Required capabilities:

  • HTTPS
  • environment variables for DB/JWT/CORS
  • backend health check
  • CI test/build
  • Flyway migrations on backend startup

Phase 2: Reverse Proxy + Backend Replicas

Use this when backend uptime and traffic routing matter.

DNS
  -> Reverse Proxy / Load Balancer
      -> Frontend
      -> Backend replica pool
          -> Neon PostgreSQL

Add:

  • Nginx / Caddy / Cloudflare / AWS ALB / platform load balancer
  • multiple backend replicas
  • /api/health target checks
  • centralized logs
  • stricter CORS allowed origins

Phase 3: File and Async Workloads

Use this when import/export/diff/impact analysis becomes heavier.

Backend API
  -> Job Queue
  -> Background Worker
  -> Object Storage

Add:

  • object storage for generated config files
  • export/import job records
  • background worker for long-running tasks
  • notification service for approvals and finished jobs
  • audit log for export/download actions

Environment Variables

Backend production deployments should set:

SPRING_PROFILES_ACTIVE=prod
SERVER_PORT=8080
DATABASE_URL=jdbc:postgresql://...
DATABASE_USERNAME=...
DATABASE_PASSWORD=...
JWT_SECRET=strong-secret
JWT_EXPIRATION_SECONDS=3600
CORS_ALLOWED_ORIGINS=https://your-frontend-domain

Frontend production deployments should set:

VITE_API_BASE_URL=https://your-api-domain

Do not expose database credentials to the frontend.

Operational Checklist

Before treating a deployment as production-like, verify:

  • GET /api/health returns UP
  • frontend can log in and call backend APIs
  • backend can run Flyway migrations
  • CORS only allows expected frontend origins
  • JWT secret is not the local default
  • database is not publicly reachable from browsers
  • logs are available for frontend, backend, and reverse proxy
  • backend restart does not log users out unexpectedly beyond JWT expiration
  • export preview/download masks secrets