<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->

# e04-mid-project — Microservices Checkout Platform

## Purpose

University assignment implementing a polyglot microservices platform for e-commerce checkout and invoice payment. The system spans order placement, stock reservation, payment authorization, invoice issuance, and customer notification. Runs entirely via `docker compose up --build` — no host-level runtimes required.

## Key Files

| File | Description |
|------|-------------|
| `docker-compose.yml` | Wires all containers together on a shared `checkout-net` network |
| `.env.example` | Template for all required environment variables — safe to commit |
| `.env` | Real credentials (Brevo SMTP, DB passwords) — gitignored |
| `Makefile` | Common dev commands: `make up`, `make down`, `make build`, `make logs` |
| `CLAUDE.md` | Project-specific instructions for Claude Code |
| `GETTING_STARTED.md` | Onboarding guide for new developers |
| `README.md` | Project overview |

## Subdirectories

| Directory | Purpose |
|-----------|---------|
| `services/` | Six microservices (Go, Java, Python) — see `services/AGENTS.md` |
| `docs/` | Architecture, DDD analysis, OpenAPI specs — see `docs/AGENTS.md` |
| `frontend/` | React + Vite checkout UI — see `frontend/AGENTS.md` |
| `gateway/` | Kong API Gateway (DB-less declarative mode) — see `gateway/AGENTS.md` |
| `scripts/` | Smoke tests and initialization helpers — see `scripts/AGENTS.md` |
| `.ai/` | Agent instruction files and reusable prompts |

## For AI Agents

### Working In This Directory
- **Never hardcode secrets** — all config goes in `.env`, referenced from `docker-compose.yml`
- **Never run code directly on the host** — all execution is inside Docker containers
- The single deploy command is `docker compose up --build`; do not suggest multi-step host setup
- Service-to-service calls use Docker Compose DNS names (e.g. `http://payment:5002`), never `localhost`
- Read `.ai/AGENTS.md` for the full universal agent instruction set before making changes

### Testing Requirements
- `make build` — verify all images build successfully after any change
- Health check every service: `GET /health` must return `{"status": "ok"}`
- See `scripts/gateway-smoke-test.sh` for end-to-end smoke tests

### Common Patterns
- Each service has its own `Dockerfile`, `readme.md`, and OpenAPI spec in `docs/api-specs/`
- Environment variables follow the pattern `SERVICE_VAR_NAME=value` in `.env.example`
- All write endpoints carry an `Idempotency-Key` header

## Dependencies

### External
- Docker + Docker Compose — container runtime
- Kong 3.x OSS — API Gateway (DB-less mode)
- Apache Kafka (KRaft) — event streaming
- PostgreSQL — one instance per service (five total)
- Brevo SMTP — transactional email relay (free tier)

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->