75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# 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.
|
||
|
||
|