# aaronstone-lut/order-management-v2 architecture

> Architecture diagram of the GitHub repository aaronstone-lut/order-management-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaronstone-lut/order-management-v2
- Repository: https://github.com/aaronstone-lut/order-management-v2

## Overview

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: [`app/modules/payment/adapters/outbound/sql_repository.py`](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/outbound/sql_repository.py) (Payment SQL repository), [`app/wiring.py`](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/wiring.py) (Composition root), [`app/modules/orders/adapters/outbound/sql_repository.py`](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/adapters/outbound/sql_repository.py) (Order SQL repository), [`main.py`](https://github.com/aaronstone-lut/order-management-v2/blob/master/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orders["Orders"]
  node_order_commands["Order use cases"]
  node_order_domain["Order aggregate<br/>[order.py]"]
  node_order_values["Order value objects<br/>[money.py]"]
  node_order_events["Order events<br/>[events.py]"]
  node_order_repo["Order SQL repository<br/>[sql_repository.py]"]
  node_completion_handler["Payment completion handler"]
  node_notification_handler["Order notification handler"]
end

subgraph group_payments["Payments"]
  node_checkout_handler["Checkout event handler"]
  node_payment_usecases["Payment use cases<br/>[process_payment.py]"]
  node_payment_domain["Payment aggregate<br/>[payment.py]"]
  node_payment_gateway["Payment gateways"]
  node_payment_repo["Payment SQL repository<br/>[sql_repository.py]"]
  node_reconciliation["Payment reconciliation"]
end

subgraph group_shared["Shared infrastructure"]
  node_notifier["Console notification sender<br/>[console_sender.py]"]
  node_db[("Database sessions<br/>[engine.py]")]
  node_outbox_store[("SQL outbox store<br/>[sql_store.py]")]
  node_outbox_worker["Outbox worker and processor"]
  node_dispatcher["Event dispatcher"]
  node_event_serializer["Event serializer<br/>[serializer.py]"]
  node_processed_store[("Processed event store<br/>[sql_store.py]")]
end

subgraph group_runtime["API and runtime"]
  node_order_api["Order HTTP API<br/>[http.py]"]
  node_payment_api["Payment HTTP API<br/>[http.py]"]
  node_wiring["Composition root<br/>[wiring.py]"]
  node_app_entry["FastAPI application<br/>[main.py]"]
end

node_customer(("Customer"))

node_customer -->|"submits order"| node_order_api
node_order_api -.->|"invokes"| node_order_commands
node_order_commands -.->|"changes state"| node_order_domain
node_order_domain -->|"uses values"| node_order_values
node_order_domain -->|"emits events"| node_order_events
node_order_commands -.->|"persists order"| node_order_repo
node_order_repo -->|"uses session"| node_db
node_order_repo -->|"writes events"| node_outbox_store
node_order_events -->|"dispatches checkout"| node_checkout_handler
node_checkout_handler -->|"creates payment"| node_payment_domain
node_payment_api -.->|"invokes"| node_payment_usecases
node_payment_usecases -->|"advances state"| node_payment_domain
node_payment_usecases -.->|"charges payment"| node_payment_gateway
node_payment_usecases -->|"persists payment"| node_payment_repo
node_payment_repo -->|"uses session"| node_db
node_payment_repo -->|"writes events"| node_outbox_store
node_payment_repo -->|"loads and saves"| node_payment_domain
node_reconciliation -.->|"finds stale payments"| node_payment_repo
node_payment_domain -->|"emits completion"| node_completion_handler
node_completion_handler -->|"marks order paid"| node_order_repo
node_order_domain -->|"emits paid event"| node_notification_handler
node_notification_handler -->|"sends notification"| node_notifier
node_notification_handler -.->|"deduplicates"| node_processed_store
node_wiring -->|"constructs"| node_order_repo
node_wiring -->|"constructs"| node_payment_repo
node_wiring -->|"registers handlers"| node_dispatcher
node_wiring -->|"creates worker"| node_outbox_worker
node_outbox_worker -.->|"processes entries"| node_outbox_store
node_outbox_worker -.->|"dispatches events"| node_dispatcher
node_outbox_store -->|"serializes events"| node_event_serializer
node_app_entry -->|"mounts routes"| node_order_api
node_app_entry -->|"mounts routes"| node_payment_api
node_app_entry -->|"starts worker"| node_wiring
node_app_entry -->|"initializes database"| node_db

click node_order_api "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/adapters/inbound/http.py"
click node_order_commands "https://github.com/aaronstone-lut/order-management-v2/tree/master/app/modules/orders/use_cases"
click node_order_domain "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/domain/order.py"
click node_order_values "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/domain/money.py"
click node_order_events "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/domain/events.py"
click node_order_repo "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/adapters/outbound/sql_repository.py"
click node_checkout_handler "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/use_cases/handlers/order_checkout_handler.py"
click node_payment_api "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/inbound/http.py"
click node_payment_usecases "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/use_cases/process_payment.py"
click node_payment_domain "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/domain/payment.py"
click node_payment_gateway "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/outbound/two_step_gateway.py"
click node_payment_repo "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/outbound/sql_repository.py"
click node_reconciliation "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/use_cases/reconcile_payments.py"
click node_completion_handler "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/use_cases/handlers/payment_completed_handler.py"
click node_notification_handler "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/use_cases/handlers/order_notification_handler.py"
click node_notifier "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/notifications/console_sender.py"
click node_db "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/db/engine.py"
click node_outbox_store "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/outbox/sql_store.py"
click node_outbox_worker "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/outbox/background_worker.py"
click node_dispatcher "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/events/simple_dispatcher.py"
click node_event_serializer "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/events/serializer.py"
click node_processed_store "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/processed_events/sql_store.py"
click node_wiring "https://github.com/aaronstone-lut/order-management-v2/blob/master/app/wiring.py"
click node_app_entry "https://github.com/aaronstone-lut/order-management-v2/blob/master/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_order_commands,node_order_domain,node_order_values,node_order_events,node_order_repo,node_completion_handler,node_notification_handler toneBlue
class node_checkout_handler,node_payment_usecases,node_payment_domain,node_payment_gateway,node_payment_repo,node_reconciliation toneAmber
class node_notifier,node_db,node_outbox_store,node_outbox_worker,node_dispatcher,node_event_serializer,node_processed_store toneMint
class node_order_api,node_payment_api,node_wiring,node_app_entry toneRose
class node_customer toneIndigo
```

## Components

### Orders

- [Order use cases](https://github.com/aaronstone-lut/order-management-v2/tree/master/app/modules/orders/use_cases): `app/modules/orders/use_cases`
- [Order aggregate](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/domain/order.py): `app/modules/orders/domain/order.py`
- [Order value objects](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/domain/money.py): `app/modules/orders/domain/money.py`
- [Order events](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/domain/events.py): `app/modules/orders/domain/events.py`
- [Order SQL repository](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/adapters/outbound/sql_repository.py): `app/modules/orders/adapters/outbound/sql_repository.py`
- [Payment completion handler](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/use_cases/handlers/payment_completed_handler.py): `app/modules/orders/use_cases/handlers/payment_completed_handler.py`
- [Order notification handler](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/use_cases/handlers/order_notification_handler.py): `app/modules/orders/use_cases/handlers/order_notification_handler.py`

### Payments

- [Checkout event handler](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/use_cases/handlers/order_checkout_handler.py): `app/modules/payment/use_cases/handlers/order_checkout_handler.py`
- [Payment use cases](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/use_cases/process_payment.py): `app/modules/payment/use_cases/process_payment.py`
- [Payment aggregate](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/domain/payment.py): `app/modules/payment/domain/payment.py`
- [Payment gateways](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/outbound/two_step_gateway.py): `app/modules/payment/adapters/outbound/two_step_gateway.py`
- [Payment SQL repository](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/outbound/sql_repository.py): `app/modules/payment/adapters/outbound/sql_repository.py`
- [Payment reconciliation](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/use_cases/reconcile_payments.py): `app/modules/payment/use_cases/reconcile_payments.py`

### Shared infrastructure

- [Console notification sender](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/notifications/console_sender.py): `app/shared/notifications/console_sender.py`
- [Database sessions](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/db/engine.py): `app/shared/db/engine.py`
- [SQL outbox store](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/outbox/sql_store.py): `app/shared/outbox/sql_store.py`
- [Outbox worker and processor](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/outbox/background_worker.py): `app/shared/outbox/background_worker.py`
- [Event dispatcher](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/events/simple_dispatcher.py): `app/shared/events/simple_dispatcher.py`
- [Event serializer](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/events/serializer.py): `app/shared/events/serializer.py`
- [Processed event store](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/shared/processed_events/sql_store.py): `app/shared/processed_events/sql_store.py`

### API and runtime

- [Order HTTP API](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/orders/adapters/inbound/http.py): `app/modules/orders/adapters/inbound/http.py`
- [Payment HTTP API](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/modules/payment/adapters/inbound/http.py): `app/modules/payment/adapters/inbound/http.py`
- [Composition root](https://github.com/aaronstone-lut/order-management-v2/blob/master/app/wiring.py): `app/wiring.py`
- [FastAPI application](https://github.com/aaronstone-lut/order-management-v2/blob/master/main.py): `main.py`

### Other components

- **Customer**

## Connections

- Customer → Order HTTP API: submits order
- Order HTTP API → Order use cases: invokes
- Order use cases → Order aggregate: changes state (evidence: `app/modules/orders/use_cases/ports/order_repository.py`)
- Order aggregate → Order value objects: uses values (evidence: `app/modules/orders/domain/order.py`)
- Order aggregate → Order events: emits events (evidence: `app/modules/orders/domain/order.py`)
- Order use cases → Order SQL repository: persists order
- Order SQL repository → Database sessions: uses session (evidence: `app/modules/orders/adapters/outbound/sql_repository.py`)
- Order SQL repository → SQL outbox store: writes events (evidence: `app/modules/orders/adapters/outbound/sql_repository.py`)
- Order events → Checkout event handler: dispatches checkout (evidence: `app/modules/payment/use_cases/handlers/order_checkout_handler.py`)
- Checkout event handler → Payment aggregate: creates payment (evidence: `app/modules/payment/use_cases/handlers/order_checkout_handler.py`)
- Payment HTTP API → Payment use cases: invokes
- Payment use cases → Payment aggregate: advances state (evidence: `app/modules/payment/use_cases/process_payment.py`)
- Payment use cases → Payment gateways: charges payment
- Payment use cases → Payment SQL repository: persists payment (evidence: `app/modules/payment/use_cases/process_payment.py`)
- Payment SQL repository → Database sessions: uses session (evidence: `app/modules/payment/adapters/outbound/sql_repository.py`)
- Payment SQL repository → SQL outbox store: writes events (evidence: `app/modules/payment/adapters/outbound/sql_repository.py`)
- Payment SQL repository → Payment aggregate: loads and saves (evidence: `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 (evidence: `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 (evidence: `app/modules/orders/use_cases/handlers/order_notification_handler.py`)
- Order notification handler → Processed event store: deduplicates
- Composition root → Order SQL repository: constructs (evidence: `app/wiring.py`)
- Composition root → Payment SQL repository: constructs (evidence: `app/wiring.py`)
- Composition root → Event dispatcher: registers handlers (evidence: `app/wiring.py`)
- Composition root → Outbox worker and processor: creates worker (evidence: `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 (evidence: `main.py`)
- FastAPI application → Payment HTTP API: mounts routes (evidence: `main.py`)
- FastAPI application → Composition root: starts worker (evidence: `main.py`)
- FastAPI application → Database sessions: initializes database (evidence: `main.py`)
