# 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.