Architecture Overview

NeXuS uses a microservices architecture with Docker Compose orchestration, Traefik reverse proxy, and dual-network isolation.

System Diagram

┌─────────────────────────────────────────────────────────┐
│                    Cloudflare CDN                        │
│                  (SSL, WAF, DDoS)                        │
└────────────────────┬────────────────────────────────────┘
                     │
              ┌──────▼──────┐
              │   Traefik   │ ← Reverse Proxy + Auto SSL
              └─────┬───────┘
       ┌────────────┼────────────┐
       │            │            │
  ┌────▼───┐  ┌────▼────┐  ┌────▼────┐
  │Frontend│  │   API   │  │  Auth   │
  │Next.js │  │ Express │  │ Service │
  └────────┘  └────┬────┘  └────┬────┘
                   │            │
       ┌───────────┼────────────┼───────────┐
       │           │            │           │
  ┌────▼────┐ ┌───▼───┐   ┌────▼────┐ ┌───▼────┐
  │PostgreSQL│ │ Redis │   │ MongoDB │ │Memcached│
  └─────────┘ └───────┘   └─────────┘ └────────┘

Key Design Decisions

Dual-Network Architecture

NeXuS uses two Docker networks to enforce isolation:

• traefik-public — External network managed by Traefik. All public-facing services connect here to receive HTTPS traffic via Traefik's reverse proxy.
• nexus-internal — Internal bridge network with internal: true. Databases live exclusively on this network with no external routing allowed.

Services that need both public access and database connectivity (API, Auth, CMS) connect to both networks.

Traefik Reverse Proxy

Every public service gets automatic HTTPS via Traefik labels:

• Automatic Let's Encrypt certificate provisioning
• Host-based routing (e.g., api.sebhosting.com → API container port 4000)
• All services share the traefik-public network
• TLS termination at the proxy level

Stateless Services

All application services are stateless and can be restarted or scaled independently. State lives in the databases:

• PostgreSQL — User accounts, refresh tokens, relational data
• MongoDB — CMS content, document storage
• Redis — Session cache, distributed caching, pub/sub
• Memcached — High-performance object cache (LRU, 256MB limit)

Technology Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript
API Gateway	Express.js, TypeScript
Auth	Express.js, bcryptjs, JWT, PostgreSQL
Databases	PostgreSQL 16, MongoDB 7, Redis 7, Memcached
Reverse Proxy	Traefik v3
Monitoring	Prometheus, Grafana
CDN/DNS	Cloudflare
AI	Claude API, MCP Protocol
Container Runtime	Docker 29+, Docker Compose

Repository Structure

nexus/
├── frontend/              # Next.js frontend app
├── backend/               # API Gateway (Express)
├── services/
│   ├── auth-service/      # JWT authentication
│   ├── cms-service/       # Headless CMS
│   ├── cdn-service/       # Static asset delivery
│   ├── cache-service/     # Caching layer
│   ├── waf-service/       # Web application firewall
│   ├── ai-gateway/        # Claude API integration
│   └── mcp-server/        # Claude MCP tools
├── infrastructure/
│   ├── docker/            # Docker Compose configs
│   ├── prometheus/        # Metrics config
│   ├── grafana/           # Dashboard provisioning
│   └── traefik/           # Reverse proxy config
└── docs/                  # This documentation site