QuickCart — practice microservices platform

A small order-fulfillment system built to practice FastAPI microservices, JWT auth, distributed tracing, log/metric correlation, Docker Compose locally, and Kubernetes for production-shaped deploys.

Docs: How it works, runbooks, improvements & support

High-level design (HLD)

flowchart TB
  Browser["Browser / web-ui"]

  subgraph Edge["Edge"]
    Gateway["Gateway<br/>JWT + CORS"]
  end

  subgraph Domain["Domain services"]
    Auth["auth-service<br/>signup / login"]
    Order["order-service"]
    Inventory["inventory-service"]
    Notification["notification-service"]
  end

  subgraph Data["Data"]
    Postgres[("Postgres 18<br/>DB: quickcart<br/>schemas: auth, orders, inventory")]
    RabbitMQ["RabbitMQ<br/>queue: notifications"]
  end

  subgraph Observability["Observability"]
    Collector["otel-collector"]
    Tempo["Tempo<br/>traces"]
    Loki["Loki<br/>logs"]
    Prom["Prometheus<br/>metrics"]
    Grafana["Grafana"]
  end

  Browser -->|HTTP| Gateway
  Gateway --> Auth
  Gateway --> Order
  Order -->|reserve / release| Inventory
  Order -->|ORDER_CONFIRMED| RabbitMQ
  RabbitMQ --> Notification

  Auth --> Postgres
  Order --> Postgres
  Inventory --> Postgres

  Gateway -.->|OTLP| Collector
  Auth -.->|OTLP| Collector
  Order -.->|OTLP| Collector
  Inventory -.->|OTLP| Collector
  Notification -.->|OTLP| Collector

  Collector --> Tempo
  Collector --> Loki
  Collector --> Prom
  Tempo --> Grafana
  Loki --> Grafana
  Prom --> Grafana

Loading

Layer	Components	Role
UI	web-ui (React/Vite + nginx)	Signup, login, place/lookup orders
Edge	gateway	JWT verify, CORS, BFF to auth + orders
Domain	auth-service, order-service, inventory-service, notification-service	Users, checkout orchestration, stock, async notify
Data	Postgres (schemas), RabbitMQ	Persistence + events
Telemetry	OTel → Collector → Tempo / Loki / Prometheus / Grafana	Traces, logs, metrics

Checkout path: authenticated POST /orders → gateway stamps JWT subject → order creates PENDING → inventory atomic reserve → CONFIRMED → RabbitMQ ORDER_CONFIRMED → notification consumer logs a simulated send.

Roadmap

Phase	Name	Scope	Status
1	Core services	Gateway, Order, Inventory, Notification; REST; Docker; Postgres	Done
2	Observability	OTel per service; Collector + Tempo/Loki/Prometheus/Grafana; starter dashboard	Done
3	Vector search	search-service (pgvector or Qdrant) behind the gateway	Not started
4	Tool calling	agent-service LLM loop calling Order/Inventory as tools (same tracing model)	Not started
5	Auth	Signup/login, bcrypt, JWT-protected order APIs, login rate limit	Done
6	UI	React/Vite SPA as its own service + Docker/k8s	Done

Phases 1, 2, 5, and 6 are complete. Remaining work is Phase 3 and Phase 4. Check ai-rag branch for complete product.

Repo layout

quickcart/
├── docker-compose.yml          # local: infra + observability + app
├── docs/GUIDE.md               # how it works, runbooks, improvements, support
├── services/
│   ├── gateway/
│   ├── auth-service/
│   ├── web-ui/
│   ├── order-service/
│   ├── inventory-service/
│   └── notification-service/
├── observability/              # collector, prometheus, tempo, loki, grafana
├── scripts/                    # DB schemas, pgAdmin servers, local tests
└── k8s/
    ├── base/
    └── overlays/
        ├── dev/
        └── prod/