Stable interfaces and data ownership

Recommended repository structure

services/order/
services/restaurant/
services/payment/
services/notification/
services/delivery-coordinator/
services/delivery-replica/
gateway/nginx.conf
deploy/compose.yaml
db/migrations/
tests/integration/
docs/assignment-1.md ... assignment-6.md
README.md

System-wide technical rules

• Each service owns its persistent state. Order and Restaurant may use the same Postgres container for teaching convenience but must use separate databases/schemas and must not modify one another's private tables.
• Gateway accepts public HTTP requests; internal services use Compose DNS and explicit client-side timeouts.
• Expose /healthz on each HTTP service; include correlation_id and instance_id in logs.
• Keep the public API backward-compatible as assignments evolve; notify students before deliberate breaking changes.
• Payment remains simulated. No real payment gateway, financial transaction or personal data is allowed.
• For asynchronous processing, state observed guarantees precisely: at-least-once deliveries, idempotent effects where implemented, and explicit unknown outcomes after crashes.
• Election does not imply consensus. Replication does not imply safe leader failover. Students must name their failure model and guarantee.

Example order state transitions

State	Event	New state
PENDING	Inventory held and payment succeeds	CONFIRMED
PENDING	Inventory unavailable or payment rejected	CANCELLED
CONFIRMED	Courier assigned	OUT_FOR_DELIVERY
OUT_FOR_DELIVERY	Completed	DELIVERED

Checkpoint contract

Each version tag is independently testable with an instructor-provided fixture. If a previous stage is incomplete, the instructor may provide minimal reference scaffolding so the student can attempt the next distributed-systems concept without losing all later marks. Replacing unfinished functionality should be disclosed in the student report.