Initial commit

docs/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# 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.
+
+