# services/ ## Purpose All six microservices of the checkout platform. Each service is fully self-contained: its own language runtime, Dockerfile, database, OpenAPI spec, and readme. Services communicate only via HTTP REST (saga commands) or Kafka events — never by sharing a database or importing each other's code. ## Subdirectories | Directory | Purpose | |-----------|---------| | `ordering/` | Go + Chi — Order aggregate + PaymentSaga orchestrator. Entry point for checkout. Port 5001. See `ordering/AGENTS.md` | | `payment/` | Java + Spring Boot — Payment aggregate. Simulates gateway approval/decline. Port 5002. See `payment/AGENTS.md` | | `inventory/` | Java + Spring Boot — StockItem aggregate. Manages soft reservations. Port 5003. See `inventory/AGENTS.md` | | `billing/` | Java + Spring Boot — Invoice aggregate. Generates invoice records after payment. Port 5004. See `billing/AGENTS.md` | | `customer/` | Java + Spring Boot — Customer aggregate. Read-only in the checkout flow. Port 5005. See `customer/AGENTS.md` | | `notification/` | Python + FastAPI — Stateless Kafka consumer. Sends email via Brevo SMTP. Port 5006. See `notification/AGENTS.md` | ## For AI Agents ### Working In This Directory - **Only Ordering initiates inter-service calls** — Payment, Inventory, Billing, Customer are passive responders. Do not add outbound HTTP calls to those services. - Every service must expose `GET /health` → `{"status": "ok"}` for Docker Compose health checks - Service-to-service URLs use Docker Compose DNS: `http://payment:5002`, `http://inventory:5003`, etc. - Every write endpoint on Payment, Inventory, and Billing requires an `Idempotency-Key` header — enforce in the spec and in code - When adding a new endpoint, update `docs/api-specs/.yaml` first (spec-first workflow) ### Testing Requirements - `docker compose build ` — verify image builds after any code change - `curl http://localhost:/health` — verify health endpoint responds - For saga changes, run the full happy-path flow via the frontend or `scripts/gateway-smoke-test.sh` ### Common Patterns - Java services share the same Spring Boot structure: `Application.java` entry point, `HealthController.java`, `application.properties` - Go service uses `chi` router with explicit JSON encoding - Python service uses FastAPI with type-annotated route handlers - All Dockerfiles follow a multi-stage build: build stage → minimal runtime image ## Dependencies ### Internal - `docs/api-specs/` — each service loads its own spec for request validation at startup - `docker-compose.yml` — declares ports, env vars, health checks, and `depends_on` ordering