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

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/<service>.yaml first (spec-first workflow)

Testing Requirements

• docker compose build <service> — verify image builds after any code change
• curl http://localhost:<port>/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