Skip to main content

​
Architecture Overview

ProjectSpecter follows a modern, containerized architecture designed for scalability and ease of management.

​
System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Internet / Users                        │
└──────────────────────────┬──────────────────────────────────┘
                           │
                 ┌─────────▼────────────┐
                 │   Cloudflare DNS    │
                 │   & WAF             │
                 └─────────┬────────────┘
                           │
              ┌────────────┴────────────┐
              │                         │
      Port 80 (HTTP)          Port 443 (HTTPS)
              │                         │
              └────────────┬────────────┘
                           │
        ┌──────────────────▼──────────────────┐
        │    Traefik (Reverse Proxy)          │
        │  - Route matching                   │
        │  - SSL/TLS termination              │
        │  - Load balancing                   │
        │  - Middleware orchestration         │
        └──────────────────┬──────────────────┘
                           │
        ┌──────────────────▼──────────────────┐
        │   Internal Docker Network           │
        │   (traefik-proxy)                   │
        └──────────────────┬──────────────────┘
                           │
        ┌──────────────────▼──────────────────┐
        │  Middleware Layer                   │
        │  - Descope Authentication           │
        │  - Request Logging                  │
        │  - Compression                      │
        └──────────────────┬──────────────────┘
                           │
        ┌──────────────────▼──────────────────┐
        │   Application Services              │
        │                                     │
        │  ├─ Descope Auth Service           │
        │  ├─ Custom Applications            │
        │  ├─ Microservices                  │
        │  ├─ Databases                      │
        │  └─ APIs                           │
        └─────────────────────────────────────┘

​
Core Components

​
1. Traefik Reverse Proxy

Purpose: Central routing and load balancing Key Features:
  • Dynamic service discovery via Docker
  • Automatic SSL/TLS certificate generation
  • HTTP to HTTPS redirect
  • Request routing based on hostnames
  • Middleware support for authentication, compression, etc.
  • Built-in dashboard and API
Configuration:
  • Static config: traefik.yml
  • Dynamic config: Docker labels in compose files
  • Ports: 80 (HTTP), 443 (HTTPS), 8080 (Dashboard)
How it works:
  1. Receives all incoming requests on ports 80/443
  2. Inspects request headers and URL
  3. Matches against configured routes
  4. Applies middleware (e.g., authentication)
  5. Routes to appropriate backend service
  6. Returns response to client

​
2. Descope Authentication Service

Purpose: Enterprise authentication and authorization Key Features:
  • OAuth/OpenID Connect provider
  • Single Sign-On (SSO)
  • Magic links
  • Passkeys
  • Multi-factor authentication
  • User management
  • Session management
Integration:
  • Implements /verify endpoint for Traefik middleware
  • Sets authentication cookies for *.starfleet-command.dev
  • Redirects unauthenticated users to login page
Flow:
  1. User requests protected service
  2. Traefik applies descope-verify@docker middleware
  3. Middleware calls Descope verify endpoint
  4. If no session → redirect to login at auth.starfleet-command.dev
  5. User authenticates
  6. Descope creates session and sets cookie
  7. User redirected back to original service
  8. Traefik verifies session → allows access

​
3. Docker & Networking

Purpose: Service containerization and communication Network Model: 
┌─────────────────────────────────────┐
│   traefik-proxy Network             │
│   (Docker User-Defined Network)     │
│                                     │
│  ├─ traefik (reverse proxy)        │
│  ├─ descope-auth (auth service)    │
│  ├─ application1                    │
│  ├─ application2                    │
│  └─ [other services]                │
│                                     │
└─────────────────────────────────────┘
Key Benefits:
  • Services communicate by container name
  • Automatic DNS resolution
  • Isolated from host network
  • Easy service discovery

​
4. Cloudflare Integration

Purpose: DNS management and domain security Responsibility:
  • DNS record management
  • DDoS protection
  • WAF (Web Application Firewall)
  • SSL/TLS infrastructure (optional, we use Let’s Encrypt)
  • API access for Traefik ACME challenges
DNS Records: 
@ (root)      A  209.141.33.10
traefik       A  209.141.33.10
auth          A  209.141.33.10
*             A  209.141.33.10  (wildcard)

​
Request Flow Example

​
Scenario: User accesses Traefik dashboard

1. User opens browser and visits: https://traefik.starfleet-command.dev

2. Browser resolves DNS:
   traefik.starfleet-command.dev → 209.141.33.10

3. TLS handshake:
   - Browser connects to 209.141.33.10:443
   - Server presents certificate for starfleet-command.dev
   - SSL/TLS session established

4. HTTP Request:
   GET / HTTP/1.1
   Host: traefik.starfleet-command.dev

5. Traefik processes request:
   a) Receives on port 443 (websecure entrypoint)
   b) Inspects hostname: traefik.starfleet-command.dev
   c) Matches route: traefik.http.routers.traefik
   d) Applies middleware: descope-verify@docker

6. Middleware verification:
   a) Calls Descope service: /verify
   b) Checks for valid session
   c) No session found → redirect to login

7. Response:
   HTTP/1.1 307 Temporary Redirect
   Location: https://auth.starfleet-command.dev/?redirect=...

8. User logs in at auth.starfleet-command.dev

9. After login:
   a) Session created
   b) Cookie set for .starfleet-command.dev
   c) Redirected to traefik.starfleet-command.dev
   d) Middleware verifies session → allows access
   e) Dashboard loads successfully

​
Data Flow Diagram

External Request
      │
      ├─→ [Port 80 HTTP] → Redirect to HTTPS
      │
      └─→ [Port 443 HTTPS] 
          │
          ├─→ [Traefik Router]
          │   - Host matching
          │   - Route selection
          │
          ├─→ [Traefik Middleware]
          │   - descope-verify@docker
          │   - Other middleware
          │
          ├─→ [Authentication Check]
          │   - Valid session? → Continue
          │   - No session? → Redirect to /auth
          │
          └─→ [Backend Service]
              - Process request
              - Return response

​
Deployment Model

​
Single VPS Deployment

┌─────────────────────────────────────┐
│   VPS (209.141.33.10)               │
│                                     │
│  ┌──────────────────────────────┐  │
│  │  Docker Engine               │  │
│  │                              │  │
│  │  ┌────────────────────────┐  │  │
│  │  │ Traefik Container     │  │  │
│  │  │ Ports: 80, 443, 8080  │  │  │
│  │  └────────────────────────┘  │  │
│  │                              │  │
│  │  ┌────────────────────────┐  │  │
│  │  │ Descope Auth Container│  │  │
│  │  │ Port: 3000            │  │  │
│  │  └────────────────────────┘  │  │
│  │                              │  │
│  │  ┌────────────────────────┐  │  │
│  │  │ Other Services         │  │  │
│  │  │ (as needed)            │  │  │
│  │  └────────────────────────┘  │  │
│  │                              │  │
│  │  Network: traefik-proxy      │  │
│  └──────────────────────────────┘  │
│                                     │
└─────────────────────────────────────┘
Storage:
  • ACME certificates: /opt/traefik/acme/acme.json
  • Session data: In-memory (ephemeral)
  • Configuration: Volume mounts from host

​
Security Model

​
Network Security

  • Services not exposed to host network
  • Only Traefik has external network access
  • Services communicate through Docker network
  • Port 22 (SSH) restricted to specific IPs

​
Application Security

  • SSL/TLS encryption in transit
  • Authentication required for protected services
  • Descope handles credential management
  • Session tokens validated per request

​
Certificate Management

  • Automatic renewal via Let’s Encrypt
  • Cloudflare DNS challenge integration
  • 90-day default expiration with auto-renewal
  • Stored encrypted in acme.json

​
Scaling Considerations

​
Horizontal Scaling

Add more VPS instances behind load balancer:
      
Load Balancer
    │
    ├─→ VPS 1 (Traefik + Services)
    ├─→ VPS 2 (Traefik + Services)
    └─→ VPS 3 (Traefik + Services)

​
Vertical Scaling

  • Increase VPS CPU/RAM
  • Add more service replicas
  • Increase Docker resource limits

​
Service-Specific Scaling

services:
  myapp:
    # Can run multiple instances
    deploy:
      replicas: 3  # 3 instances
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

​
Technology Stack

LayerTechnologyVersionPurpose
Reverse ProxyTraefikv2.11Routing & load balancing
AuthenticationDescopeLatestEnterprise auth
ContainerizationDocker24.0+Container runtime
OrchestrationDocker Composev2Service orchestration
DNSCloudflareAPI v4Domain management
CertificatesLet’s EncryptACME v2SSL/TLS

​
Architecture Principles

  1. Containerization - All services run in Docker
  2. Infrastructure as Code - Define services in code (docker-compose.yml)
  3. Single Responsibility - Each service has one purpose
  4. Stateless Services - Services can be restarted without data loss
  5. Automatic Discovery - Traefik discovers services dynamically
  6. Security First - HTTPS by default, authentication required
  7. Observability - Logs and metrics accessible
  8. Reproducibility - Same config across environments
Next: Quickstart Guide