How aaronstone-lut/order-management-v2 works
This is a Clean Architecture e-commerce backend with Orders and Payment bounded contexts. The main workflow is order creation and checkout, payment reservation/confirmation, then payment completion marks the order paid and triggers notification. SQL repositories persist aggregates and their events atomically; a background outbox worker dispatches those events, while processed-event storage supports idempotency. The README documents the business stages and persistence capabilities; several HTTP routes and use cases are represented by paths and documentation rather than inspected implementation excerpts.
Main entry points: outbound/sql_repository.py Payment SQL repository · wiring.py Composition root · outbound/sql_repository.py Order SQL repository · main.py FastAPI application
Components 25
Orders
- Order use cases
app/modules/orders/use_cases - Order aggregate
app/modules/orders/domain/order.py - Order value objects
app/modules/orders/domain/money.py - Order events
app/modules/orders/domain/events.py - Order SQL repository
app/modules/orders/adapters/outbound/sql_repository.py - Payment completion handler
app/modules/orders/use_cases/handlers/payment_completed_handler.py - Order notification handler
app/modules/orders/use_cases/handlers/order_notification_handler.py
Payments
- Checkout event handler
app/modules/payment/use_cases/handlers/order_checkout_handler.py - Payment use cases
app/modules/payment/use_cases/process_payment.py - Payment aggregate
app/modules/payment/domain/payment.py - Payment gateways
app/modules/payment/adapters/outbound/two_step_gateway.py - Payment SQL repository
app/modules/payment/adapters/outbound/sql_repository.py - Payment reconciliation
app/modules/payment/use_cases/reconcile_payments.py
Shared infrastructure
- Console notification sender
app/shared/notifications/console_sender.py - Database sessions
app/shared/db/engine.py - SQL outbox store
app/shared/outbox/sql_store.py - Outbox worker and processor
app/shared/outbox/background_worker.py - Event dispatcher
app/shared/events/simple_dispatcher.py - Event serializer
app/shared/events/serializer.py - Processed event store
app/shared/processed_events/sql_store.py
API and runtime
- Order HTTP API
app/modules/orders/adapters/inbound/http.py - Payment HTTP API
app/modules/payment/adapters/inbound/http.py - Composition root
app/wiring.py - FastAPI application
main.py
Other components
- Customer
Connections 34
- Customer → Order HTTP API: submits order
- Order HTTP API → Order use cases: invokes
- Order use cases → Order aggregate: changes state
app/modules/orders/use_cases/ports/order_repository.py - Order aggregate → Order value objects: uses values
app/modules/orders/domain/order.py - Order aggregate → Order events: emits events
app/modules/orders/domain/order.py - Order use cases → Order SQL repository: persists order
- Order SQL repository → Database sessions: uses session
app/modules/orders/adapters/outbound/sql_repository.py - Order SQL repository → SQL outbox store: writes events
app/modules/orders/adapters/outbound/sql_repository.py - Order events → Checkout event handler: dispatches checkout
app/modules/payment/use_cases/handlers/order_checkout_handler.py - Checkout event handler → Payment aggregate: creates payment
app/modules/payment/use_cases/handlers/order_checkout_handler.py - Payment HTTP API → Payment use cases: invokes
- Payment use cases → Payment aggregate: advances state
app/modules/payment/use_cases/process_payment.py - Payment use cases → Payment gateways: charges payment
- Payment use cases → Payment SQL repository: persists payment
app/modules/payment/use_cases/process_payment.py - Payment SQL repository → Database sessions: uses session
app/modules/payment/adapters/outbound/sql_repository.py - Payment SQL repository → SQL outbox store: writes events
app/modules/payment/adapters/outbound/sql_repository.py - Payment SQL repository → Payment aggregate: loads and saves
app/modules/payment/adapters/outbound/sql_repository.py - Payment reconciliation → Payment SQL repository: finds stale payments
- Payment aggregate → Payment completion handler: emits completion
- Payment completion handler → Order SQL repository: marks order paid
app/modules/orders/use_cases/handlers/payment_completed_handler.py - Order aggregate → Order notification handler: emits paid event
- Order notification handler → Console notification sender: sends notification
app/modules/orders/use_cases/handlers/order_notification_handler.py - Order notification handler → Processed event store: deduplicates
- Composition root → Order SQL repository: constructs
app/wiring.py - Composition root → Payment SQL repository: constructs
app/wiring.py - Composition root → Event dispatcher: registers handlers
app/wiring.py - Composition root → Outbox worker and processor: creates worker
app/wiring.py - Outbox worker and processor → SQL outbox store: processes entries
- Outbox worker and processor → Event dispatcher: dispatches events
- SQL outbox store → Event serializer: serializes events
- FastAPI application → Order HTTP API: mounts routes
main.py - FastAPI application → Payment HTTP API: mounts routes
main.py - FastAPI application → Composition root: starts worker
main.py - FastAPI application → Database sessions: initializes database
main.py