kubernetes/docs/ARCHITECTURE.md

Architecture Overview

High-Level Flow

Client (Postman/Mobile)
        │  HTTPS (queue.workolik.com via Traefik 443)
        ▼
Traefik (TLS terminate, Host rule: queue.workolik.com)
        │  HTTP to k3s LB (port 8201)
        ▼
k3s LoadBalancer (klipper-lb) : fastapi-lb
        │  ClusterIP Service fastapi-backend:8000
        ▼
FastAPI Pods (4→20 via HPA)
        │  Publish to NATS (JetStream)
        ▼
External NATS (nats.workolik.com:4222) – Stream: EVENTS / Subject: api.>
        │  Worker subscription (worker_consumer)
        ▼
Worker Pods (2→10 via HPA)
        │  Forward with original HTTP method
        ▼
External API (https://jupiter.nearle.app)

Components

• Ingress / Edge

  • DNS: queue.workolik.com → server IP
  • Traefik: terminates TLS, routes Host=queue.workolik.com → LB 8201
  • k3s LoadBalancer (klipper-lb): Service fastapi-lb on 8201 (HTTP)

• App Layer

  • FastAPI Deployment: 4 replicas (HPA 4–20), probes on /health and /ready
  • FastAPI Service: fastapi-backend ClusterIP on 8000
  • Endpoints publish to NATS with method metadata

• Messaging

  • NATS JetStream (external): Stream EVENTS, Subject api.>, Consumer worker_consumer

• Workers

  • Worker Deployment: 2 replicas (HPA 2–10), probes on /metrics (9090)
  • Forwards to https://jupiter.nearle.app with the same HTTP method (PUT for updatedelivery, POST for others)

• Autoscaling & Health

  • Metrics-server running; HPAs on FastAPI and Worker
  • Liveness/Readiness probes ensure pod health

API Surface (FastAPI → Worker → External)

• PUT /live/api/v1/deliveries/updatedelivery → PUT to Nearle
• POST /live/api/v2/partners/createriderlog → POST to Nearle
• POST /live/api/v2/deliveries/createdeliverylog → POST to Nearle
• POST /live/api/v2/partners/createbreaklog → POST to Nearle
• POST /live/api/v2/partners/updatebreaklog → POST to Nearle

Key Ports

• External TLS: 443 (Traefik)
• LB HTTP into k3s: 8201 (klipper-lb → FastAPI Service 8000)
• FastAPI container: 8000
• Worker metrics: 9090
• NATS: 4222 (external)

Files of Interest

• manifests/fastapi-deployment.yaml, manifests/worker-deployment.yaml
• manifests/fastapi-loadbalancer.yaml (klipper-lb)
• Dockerfile (multi-target: api, worker)
• docker-compose.yml (Traefik labels for HTTPS)
• scripts/app.py, scripts/worker.py, scripts/setup_jetstream.py

Notes

• TLS is terminated at Traefik; traffic to k3s is HTTP on 8201.
• Keep external exposure through Traefik Host rule to reduce scanner noise.
• HPAs rely on metrics-server; already running and feeding FastAPI/Worker HPAs.