FastAPI Microservices Platform is a backend-only, portfolio-oriented e-commerce platform built as independently deployable, event-driven microservices. The e-commerce domain is used to exercise distributed consistency, failure recovery, observability, security, and delivery practices; endpoint count is not the project goal.
The repository has completed Phase 19 — Post-delivery returns and refund
lifecycle. It is intentionally a portfolio repository, not a deployed public
environment. Its CI publishes immutable, scanned container images as build
artifacts and proves the platform in a disposable Kind cluster; neither
operation is a target-environment deployment.
The local
observability profile collects bounded platform metrics, JSON logs, and
traces through Prometheus, Loki, Tempo, and Grafana. Resilience, staff account
recovery/device sessions, moderated catalog reviews, bounded Kubernetes
autoscaling, Shipping-owned fulfilment transitions, and receipt-gated
post-delivery returns have durable contracts, tests, and runbooks. Raw
Kustomize resources remain the reviewable workload baseline, while two Helm
charts package the controlled foundation and application-release sequence. The
main-branch/manual CI workflow installs those charts in a disposable Kind
cluster, waits for controlled migrations and workloads, then proves in-cluster
API readiness and the checkout-to-invoice-to-email, Shipping-to-Order
projection, and post-delivery return workflows. The Kind Job sets
E2E_RUN_RETURNS=1, so its portable checkout runner also creates, approves,
receives, and settles a delivered-order return. It still does not exercise
public ingress, a real payment provider, or merchant settlement. A real target
environment must provide pinned release images, secrets, ingress/TLS, external
durable services, and environment-specific egress policy before public
deployment.
Start with the portfolio reviewer guide. It maps every material claim to its implementation, contract, runbook, or executable CI evidence, and distinguishes verified local/CI behavior from deliberately out-of-scope production operations.
Clients
|
v
Edge / API Gateway
|
v
FastAPI Microservices
|-- service-owned PostgreSQL databases
|-- Transactional Outbox -> Kafka domain events
|-- RabbitMQ -> bounded-context Celery workers
|-- Redis cache / rate limits / presence / WebSocket fan-out
`-- S3-compatible object storage (MinIO initially)
The platform follows these non-negotiable rules:
- Every service is a bounded context and owns its durable data and migrations.
- A service never queries another service's database.
- REST is used for synchronous request/response interactions.
- Kafka transports durable domain facts: what happened.
- RabbitMQ and Celery transport executable work: what needs to be done.
- Redis is disposable and never the source of truth for durable business data.
- Critical domain events use a Transactional Outbox; consumers are idempotent and use an Inbox or equivalent durable deduplication.
- Binary files live in S3-compatible object storage, behind an
ObjectStorageabstraction. - API, event schema, and service/container versions evolve independently.
- Application workloads must be designed Kubernetes-first even while local development uses Docker Compose.
reference-service is a non-domain foundation probe. It proves the shared
HTTP observability, health, metrics, configuration, image, and delivery path;
it owns no business state or database.
Core bounded contexts:
identity-servicecustomer-servicecatalog-servicesearch-serviceinventory-servicecart-serviceorder-servicepayment-servicenotification-servicemedia-servicechat-service
Shipping is an implemented bounded context:
shipping-service— owns aREADYshipment created idempotently fromorder.confirmed.v1, administrator lifecycle commands, its own transition audit, and its ownOutbox. Every command obtains an Order-owned short-lived authorization; an expired authorization is reconciled from Shipping before a refund can proceed.ComposeandKindregister its API, migration, and dedicated event worker; the shared checkout-to-Shipping workflow proves the asynchronous Order projection.
See service boundaries for ownership and non-ownership rules.
services/— independently deployable bounded contexts and the documented service template.libs/— small cross-cutting technical primitives; never shared domain models.contracts/— canonical event and API contract artifacts.infrastructure/— local and deployment infrastructure, introduced incrementally.docs/— architecture, ADRs, diagrams, events, runbooks, and development policy.scripts/— repeatable developer and operational automation.tests/e2e/— cross-service workflow tests introduced with executable services..github/workflows/— CI/CD workflows introduced as corresponding capabilities exist.
The complete intended layout is documented in repository structure.
- Architecture overview
- Communication and consistency
- Service boundaries
- Security baseline
- Observability
- Architecture diagrams
- Open architectural questions
- Architecture Decision Records
- Portfolio reviewer guide
- Event contracts
- Coding standards
- Dependency and version policy
- Testing strategy
- CI/CD strategy
- Invoice and notification runbook
- SMS OTP runbook
- Staff operations runbook
- Search projection runbook
- Edge gateway runbook
- Kubernetes deployment runbook
- Helm delivery charts
- Online payment provider routing runbook
- Post-delivery returns runbook
- Phase 0 plan
- Phase 1 plan
- Phase 2 plan
- Phase 3 plan
- Phase 4 plan
- Phase 5 plan
- Phase 6 plan
- Phase 7 plan
- Phase 8 plan
- Phase 9 plan
- Phase 10 plan
- Phase 11 plan
- Phase 12 plan
- Phase 13 plan
- Phase 14 plan
- Phase 15 plan
- Phase 16 plan
- Phase 17 plan
- Phase 18 plan
- Phase 19 plan
| Phase | Outcome |
|---|---|
| 0 | Architecture & Repository Foundation |
| 1 | Platform Foundation |
| 2 | Identity & Customer |
| 3 | Catalog & Media |
| 4 | Inventory & Cart |
| 5 | Order & Payment |
| 6 | Invoice & Notification |
| 7 | Realtime Chat |
| 8 | Search |
| 9 | Kubernetes |
| 10 | Helm |
| 11 | Complete Observability |
| 12 | Hardening |
| 13 | Staff password reset & device sessions |
| 14 | Catalog reviews, replies & moderation |
| 15 | Kubernetes API autoscaling |
| 16 | Online payment provider routing |
| 17 | Portfolio evidence and reviewer guide |
| 18 | Shipping ownership extraction |
| 19 | Post-delivery returns and refund lifecycle |
The local edge gateway is the only public API entry point: use
https://localhost/api/v1/... and wss://localhost/api/v1/chat/ws.
Local Swagger interfaces are available at https://localhost/docs/ only;
they are not a production ingress feature.
Generate its ignored self-signed certificate once before dev-up with
pwsh -NoProfile -File .\\scripts\\new_local_edge_certificate.ps1. The HTTP
listener http://localhost redirects to TLS. API services no longer publish host ports;
MinIO 9000 (S3 API) and 9001 (console), plus the Mailpit UI 8025, remain
direct local development endpoints.
dev-up first builds API images and then starts Compose; this lets the Invoice
and Notification workers consume the same built service images. It does not
run Alembic migrations automatically: migrations remain explicit,
service-owned commands.
Run Docker Compose directly from the repository root. The ignored root .env
sets COMPOSE_FILE to the canonical Compose configuration, so no --env-file
or -f argument is needed.
pwsh -File .\scripts\platform.ps1 -Task install
pwsh -File .\scripts\platform.ps1 -Task test
pwsh -NoProfile -File .\scripts\new_local_edge_certificate.ps1
docker compose up -d --build
For the optional local telemetry stack, follow the observability profile. It is not a production deployment. docker compose stop docker compose start docker compose up -d --force-recreate pwsh -File .\scripts\platform.ps1 -Task migrate-identity pwsh -File .\scripts\platform.ps1 -Task migrate-customer pwsh -File .\scripts\platform.ps1 -Task migrate-catalog pwsh -File .\scripts\platform.ps1 -Task migrate-search pwsh -File .\scripts\platform.ps1 -Task migrate-media pwsh -File .\scripts\platform.ps1 -Task migrate-inventory pwsh -File .\scripts\platform.ps1 -Task migrate-cart pwsh -File .\scripts\platform.ps1 -Task migrate-order pwsh -File .\scripts\platform.ps1 -Task migrate-payment pwsh -File .\scripts\platform.ps1 -Task migrate-shipping pwsh -File .\scripts\platform.ps1 -Task migrate-notification pwsh -File .\scripts\platform.ps1 -Task migrate-chat $env:RUN_E2E = "1"; uv run pytest tests/e2e/test_phase6_checkout_notification.py
For ordinary local shutdown and restart, use docker compose stop and
docker compose start; they retain the existing containers and their
environment. After changing .env or Compose configuration, use
docker compose up -d --force-recreate. docker compose down removes the
containers. scripts/platform.ps1 remains available as an optional task runner.
This repository is licensed under the MIT License.