MANOHAR.

PROJECT / 001

OrderFlow

Transactional commerce & outbox backend.

PythonFastAPIPostgreSQLRabbitMQRedisSQLAlchemyAlembicArgon2

TYPE

Backend application

STATUS

Functional

01 / THE PROBLEM

The engineering problem

Commerce applications involve multiple connected entities and operations. In distributed architectures, saving order data to PostgreSQL and publishing an event (OrderCreated) to a message broker are separate operations. If the database commits but broker communication fails, downstream services never receive the event—the fatal dual-write problem.

CONSTRAINTS

Dual-write atomicity

Concurrent stock updates

Broker delivery guarantee

ENGINEERING FOCUS

Transactional Outbox pattern

Pessimistic locking / SKIP LOCKED

At-least-once with idempotent consumer

02 / ARCHITECTURE

How the system works

ORDERFLOW / TRANSACTIONAL ARCHITECTURE & OUTBOX

IDLE / RUNNING SYSTEM
HTTPClientHTTPFastAPIRoutesValidation · RoutingcallServiceLayerBusiness logic · TxqueryRepositoryLayerData access · ORMSQLPostgreSQLOrders · Stock · Outbox
Service
Database
External
Synchronous
Active Packet Flow

OrderFlow transactional pipeline: Service coordinates product verification, inventory decrement, and outbox insertion in one database transaction.

03 / IMPLEMENTATION

What was built

  • 01Designed relational models for products, inventory, orders, order items, outbox events, and payments.
  • 02Implemented Transactional Outbox pattern: order creation and event publication are saved in a single database transaction.
  • 03Built a relay worker process polling the outbox table via SELECT ... FOR UPDATE SKIP LOCKED to prevent duplicate processing.
  • 04Configured RabbitMQ exchange, consumer queues, TTL-backed retry queues, and dead-letter exchanges (DLX).
  • 05Secured authentication workflows with Argon2 password hashing and JWT authorization.
  • 06Managed versioned schema evolution with Alembic migrations.

04 / DECISIONS

Technical decisions

DECISIONREASONING
Transactional OutboxGuarantees message publishing atomicity with database writes, eliminating dual-write failure states.
SELECT ... FOR UPDATE SKIP LOCKEDEnables multiple outbox relay workers to poll pending events concurrently without table lock contention.
RabbitMQ Dead-Letter Exchange (DLX)Routes permanently poisoned messages to a dead queue after exponential retry attempts without blocking healthy messages.
Service-level transactionsRepositories handle data queries only; transaction boundaries are explicitly owned by the service layer.
Argon2 password hashingMemory-hard password hashing recommended by OWASP for superior resistance to GPU cracking.

05 / RELIABILITY

Reliability and failure handling

SCENARIOEXPECTED BEHAVIOURVERIFICATION
Broker disconnects during order creationOrder and outbox record commit atomically; relay worker publishes event once broker reconnects.Outbox persistence test with mock broker outage
Consumer throws unexpected exceptionMessage is routed to retry queue with TTL, then re-queued; sent to DLX if maximum attempts exceeded.DLX routing test with simulated consumer crash
Simultaneous purchase of final inventory unitRow-level locks prevent overselling; second transaction fails with clean OutOfStockException.Concurrent stock checkout test

06 / LIMITATIONS

Known limitations and future work

—Provides at-least-once message delivery, requiring consumers to implement idempotency checks.
—Relay worker polling interval creates sub-second propagation latency compared to Change Data Capture (Debezium).
—Full distributed tracing (OpenTelemetry) is planned for future observability.

Advanced distributed data consistency, transactional outbox pattern, message broker resilience, and relational data modeling.

All projects

NEXT →

FlowForge