How nirodhauwanpriya/reactive-commerce-orchestrator works
1. Overall shape
- This repo is a TypeScript, containerized e-commerce backend built around a single API edge plus background workers.
- The architecture is split into three execution modes under src/entrypoints: api.ts for HTTP, workers.ts for consumers, and outbox.ts for relay processing.
2. HTTP/API boundary
- src/server.ts and the src/modules/*/*.routes.ts / *.controller.ts files define the synchronous REST surface.
- Domains exposed over HTTP are users, products, cart, orders, and payments.
- src/shared/middlewares/auth.middleware.ts is the main request boundary control, implying authenticated endpoints for state-changing operations.
3. Domain modularization
- Each business area is isolated in its own module folder, with controller + route pairs for request handling.
- This keeps cart/order/payment/user logic separated at the feature boundary, which is useful when diagramming bounded contexts rather than a monolith of shared handlers.
4. Stateful storage layer
- src/shared/database/pool.ts indicates a PostgreSQL connection pool for transactional persistence.
- src/shared/database/redis.ts provides Redis access, and the README indicates it is used for cart/session-like volatile state.
- src/modules/users/schema.sql suggests the repo includes DB schema bootstrapping for at least the user domain.
5. Asynchronous messaging layer
- src/shared/database/queue.ts is the broker abstraction, backed by RabbitMQ per the README.
- Message-driven work is split into dedicated workers: order.worker.ts, payment.worker.ts, and notification.worker.ts.
- This means the system does not rely solely on synchronous HTTP for business completion; it uses queue-backed background processing.
6. Transactional outbox flow
- src/shared/workers/outbox.processor.ts and src/entrypoints/outbox.ts implement an outbox relay.
- The likely data flow is: business transaction writes to PostgreSQL, event record is stored in an outbox table, then the relay publishes to RabbitMQ.
- This is the key boundary for consistency between database writes and async event emission.
7. Saga orchestration
- src/shared/saga/order.saga.ts is the coordination layer for multi-step order processing.
- The saga likely reacts to queue events and drives order/payment state transitions, rather than allowing each service to act independently.
- In diagrams, this should be shown as the orchestration brain between order, payment, and downstream side effects.
8. Workers as the async execution plane
- src/entrypoints/workers.ts likely starts one or more consumer loops.
- The workers encapsulate long-running or failure-prone operations such as payment handling and notifications, keeping them off the request thread.
- This separation is important: HTTP paths return quickly, while queues complete the business workflow later.
9. Observability subsystem
- src/shared/monitoring/metrics.ts and src/shared/monitoring/tracer.ts show built-in metrics and distributed tracing support.
- The README ties this to Prometheus for metrics scraping and OpenTelemetry/Jaeger for trace propagation and visualization.
- monitoring/prometheus.yml is the scrape configuration, so telemetry is treated as a first-class deployment component.
10. Deployment/runtime boundaries
- Dockerfile and docker-compose.yml indicate the system is designed to run as a set of containers, not as a single binary.
- The README implies separate runtime roles for API, workers, outbox processor, PostgreSQL, Redis, RabbitMQ, and observability backends.
- For an architecture diagram, treat these as distinct deployable units connected by HTTP, SQL, Redis, and AMQP.
11. Primary request/data flows
- Typical flow: client calls REST endpoint → controller validates/handles → reads/writes PostgreSQL and/or Redis → order events are persisted to outbox → outbox relay publishes to RabbitMQ → workers consume and continue the workflow → saga coordinates outcomes and compensation.
- Notifications appear to be fully asynchronous, driven from broker events rather than direct API calls.
12. Important diagram boundaries
- Strong boundaries exist between:
- Request/response API layer
- Transactional database layer
- Cache layer
- Message broker / async processing layer
- Observability plane
- Those separations are the core of the system’s architecture and should be shown explicitly in any diagram.
13. What to emphasize as the central pattern
- The repo is not just a CRUD service: it is organized around event-driven checkout/order processing with outbox reliability and saga-based orchestration.
- That combination is the main architectural theme tying the modules, workers, and infrastructure together.
Main entry points: server.ts Server · pool.ts Postgres pool · queue.ts Message broker · order.saga.ts Order saga
Components 21
Execution modes
Runtime entrypoints for API handling, background consumers, and outbox relay.
- API entrypoint · Bootstraps the synchronous request/response process.
src/entrypoints/api.ts - Workers entrypoint · Starts background consumer loops for async processing.
src/entrypoints/workers.ts - Outbox entrypoint · Runs the outbox publisher that bridges database events to the broker.
src/entrypoints/outbox.ts
Domain modules
Feature boundaries for the core commerce capabilities exposed through HTTP and workers.
- Users · User-facing HTTP handlers and schema bootstrapping.
src/modules/users/user.routes.ts - Products · Product catalog HTTP handlers.
src/modules/products/product.routes.ts - Cart · Cart state and request handlers.
src/modules/cart/cart.routes.ts - Orders · Order HTTP handlers and async worker logic.
src/modules/orders/order.routes.ts - Payments · Payment HTTP handlers and async worker logic.
src/modules/payments/payment.routes.ts - Notifications · Notification worker processing broker-driven events.
src/modules/notifications/notification.worker.ts
Shared core
Cross-cutting infrastructure, orchestration, and observability components.
- Server · Configures the HTTP server and mounts the API surface.
src/server.ts - Auth guard · Request boundary control for authenticated operations.
src/shared/middlewares/auth.middleware.ts - Postgres pool · Transactional database access for core business state.
src/shared/database/pool.ts - Redis cache · Cache and session-like state for fast ephemeral access.
src/shared/database/redis.ts - Message broker · Queue abstraction backing asynchronous work distribution.
src/shared/database/queue.ts - Outbox relay · Reads persisted outbox records and publishes them to the broker.
src/shared/workers/outbox.processor.ts - Order saga · Coordinates multi-step order and payment progression.
src/shared/saga/order.saga.ts - Metrics · Application metrics instrumentation and exposure.
src/shared/monitoring/metrics.ts - Tracer · Distributed tracing instrumentation and propagation.
src/shared/monitoring/tracer.ts
Deployment
Containerized backing services and runtime dependencies.
- PostgreSQL · Primary transactional datastore.
docker-compose.yml - RabbitMQ · Message broker used for background workflow processing.
docker-compose.yml - Redis · Containerized cache dependency.
docker-compose.yml
Connections 29
- API entrypoint → Server: starts · API entrypoint initializes the HTTP server.
- Server → Auth guard: uses · Server applies authentication controls to protected routes.
- Server → Users: mounts · Registers the user HTTP surface.
- Server → Products: mounts · Registers the product HTTP surface.
- Server → Cart: mounts · Registers the cart HTTP surface.
- Server → Orders: mounts · Registers the order HTTP surface.
- Server → Payments: mounts · Registers the payment HTTP surface.
- Users → Postgres pool: persists · User module writes and reads transactional state.
- Products → Postgres pool: reads · Product module accesses persistent catalog data.
- Cart → Redis cache: stores · Cart module uses volatile cache state.
- Cart → Postgres pool: persists · Cart module may also touch durable storage.
- Orders → Postgres pool: transacts · Order processing is backed by PostgreSQL transactions.
- Orders → Message broker: publishes · Orders emit async work onto the broker.
- Payments → Postgres pool: transacts · Payment state is recorded durably.
- Payments → Message broker: publishes · Payment outcomes can trigger async processing.
- Workers entrypoint → Message broker: consumes · Worker runtime consumes broker messages.
- Workers entrypoint → Order saga: drives · Workers execute saga-coordinated workflow steps.
- Order saga → Orders: coordinates · Saga governs order state transitions.
- Order saga → Payments: coordinates · Saga sequences payment steps and outcomes.
- Order saga → Notifications: triggers · Saga can fan out notification side effects.
- Outbox entrypoint → Outbox relay: runs · Outbox runtime executes the relay processor.
- Outbox relay → Postgres pool: reads · Relay reads persisted outbox records from the database.
- Outbox relay → Message broker: publishes · Relay forwards durable events to the broker.
- Metrics → Server: instruments · HTTP surface is instrumented for telemetry.
- Tracer → Server: instruments · HTTP surface propagates trace context.
- Tracer → Workers entrypoint: instruments · Background consumers participate in tracing.
- Postgres pool → PostgreSQL: connects · Application database pool targets PostgreSQL.
- Redis cache → Redis: connects · Application cache client targets Redis.
- Message broker → RabbitMQ: connects · Broker abstraction targets RabbitMQ.