Skip to content

About

Event-driven FastAPI microservices architecture with executable delivery evidence.

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

FastAPI Microservices Platform

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.

Project status

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.

Review this repository

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.

Architecture at a glance

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 ObjectStorage abstraction.
  • API, event schema, and service/container versions evolve independently.
  • Application workloads must be designed Kubernetes-first even while local development uses Docker Compose.

Implemented services

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-service
  • customer-service
  • catalog-service
  • search-service
  • inventory-service
  • cart-service
  • order-service
  • payment-service
  • notification-service
  • media-service
  • chat-service

Shipping is an implemented bounded context:

  • shipping-service — owns a READY shipment created idempotently from order.confirmed.v1, administrator lifecycle commands, its own transition audit, and its own Outbox. Every command obtains an Order-owned short-lived authorization; an expired authorization is reconciled from Shipping before a refund can proceed. Compose and Kind register 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.

Repository map

  • 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.

Documentation

Roadmap

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

Local development

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.

License

This repository is licensed under the MIT License.

About

Event-driven FastAPI microservices architecture with executable delivery evidence.

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages