# nirodhauwanpriya/reactive-commerce-orchestrator architecture

> Architecture diagram of the GitHub repository nirodhauwanpriya/reactive-commerce-orchestrator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nirodhauwanpriya/reactive-commerce-orchestrator
- Repository: https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator

## Overview

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: [`src/server.ts`](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/server.ts) (Server), [`src/shared/database/pool.ts`](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/pool.ts) (Postgres pool), [`src/shared/database/queue.ts`](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/queue.ts) (Message broker), [`src/shared/saga/order.saga.ts`](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/saga/order.saga.ts) (Order saga)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution modes"]
  node_api_entrypoint["API entrypoint<br/>http runtime<br/>[api.ts]"]
  node_workers_entrypoint["Workers entrypoint<br/>consumer runtime<br/>[workers.ts]"]
  node_outbox_entrypoint["Outbox entrypoint<br/>relay runtime<br/>[outbox.ts]"]
end

subgraph group_domains["Domain modules"]
  node_users["Users<br/>feature module<br/>[user.routes.ts]"]
  node_products["Products<br/>feature module<br/>[product.routes.ts]"]
  node_cart["Cart<br/>feature module<br/>[cart.routes.ts]"]
  node_orders["Orders<br/>feature module<br/>[order.routes.ts]"]
  node_payments["Payments<br/>feature module<br/>[payment.routes.ts]"]
  node_notifications["Notifications<br/>async module"]
end

subgraph group_shared["Shared core"]
  node_server["Server<br/>http host<br/>[server.ts]"]
  node_auth_middleware["Auth guard<br/>middleware<br/>[auth.middleware.ts]"]
  node_db_pool[("Postgres pool<br/>sql persistence<br/>[pool.ts]")]
  node_redis[("Redis cache<br/>volatile state<br/>[redis.ts]")]
  node_queue["Message broker<br/>amqp broker<br/>[queue.ts]"]
  node_outbox_processor["Outbox relay<br/>event relay"]
  node_order_saga{{"Order saga<br/>orchestration<br/>[order.saga.ts]"}}
  node_metrics["Metrics<br/>telemetry<br/>[metrics.ts]"]
  node_tracer["Tracer<br/>telemetry<br/>[tracer.ts]"]
end

subgraph group_runtime["Deployment"]
  node_postgres[("PostgreSQL<br/>database service<br/>[docker-compose.yml]")]
  node_rabbitmq["RabbitMQ<br/>broker service<br/>[docker-compose.yml]"]
  node_redis_service[("Redis<br/>cache service<br/>[docker-compose.yml]")]
end

node_api_entrypoint -->|"starts"| node_server
node_server -->|"uses"| node_auth_middleware
node_server -->|"mounts"| node_users
node_server -->|"mounts"| node_products
node_server -->|"mounts"| node_cart
node_server -->|"mounts"| node_orders
node_server -->|"mounts"| node_payments
node_users -->|"persists"| node_db_pool
node_products -->|"reads"| node_db_pool
node_cart -->|"stores"| node_redis
node_cart -->|"persists"| node_db_pool
node_orders -->|"transacts"| node_db_pool
node_orders -->|"publishes"| node_queue
node_payments -->|"transacts"| node_db_pool
node_payments -->|"publishes"| node_queue
node_workers_entrypoint -->|"consumes"| node_queue
node_workers_entrypoint -->|"drives"| node_order_saga
node_order_saga -->|"coordinates"| node_orders
node_order_saga -->|"coordinates"| node_payments
node_order_saga -->|"triggers"| node_notifications
node_outbox_entrypoint -->|"runs"| node_outbox_processor
node_outbox_processor -->|"reads"| node_db_pool
node_outbox_processor -->|"publishes"| node_queue
node_metrics -->|"instruments"| node_server
node_tracer -->|"instruments"| node_server
node_tracer -->|"instruments"| node_workers_entrypoint
node_db_pool -->|"connects"| node_postgres
node_redis -->|"connects"| node_redis_service
node_queue -->|"connects"| node_rabbitmq

click node_api_entrypoint "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/entrypoints/api.ts"
click node_workers_entrypoint "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/entrypoints/workers.ts"
click node_outbox_entrypoint "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/entrypoints/outbox.ts"
click node_server "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/server.ts"
click node_auth_middleware "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/middlewares/auth.middleware.ts"
click node_db_pool "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/pool.ts"
click node_redis "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/redis.ts"
click node_queue "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/queue.ts"
click node_outbox_processor "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/workers/outbox.processor.ts"
click node_order_saga "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/saga/order.saga.ts"
click node_metrics "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/monitoring/metrics.ts"
click node_tracer "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/monitoring/tracer.ts"
click node_users "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/users/user.routes.ts"
click node_products "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/products/product.routes.ts"
click node_cart "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/cart/cart.routes.ts"
click node_orders "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/orders/order.routes.ts"
click node_payments "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/payments/payment.routes.ts"
click node_notifications "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/notifications/notification.worker.ts"
click node_postgres "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/docker-compose.yml"
click node_rabbitmq "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/docker-compose.yml"
click node_redis_service "https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/docker-compose.yml"

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_api_entrypoint,node_workers_entrypoint,node_outbox_entrypoint toneBlue
class node_users,node_products,node_cart,node_orders,node_payments,node_notifications toneAmber
class node_server,node_auth_middleware,node_db_pool,node_redis,node_queue,node_outbox_processor,node_order_saga,node_metrics,node_tracer toneMint
class node_postgres,node_rabbitmq,node_redis_service toneRose
```

## Components

### Execution modes

Runtime entrypoints for API handling, background consumers, and outbox relay.

- [API entrypoint](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/entrypoints/api.ts): http runtime · Bootstraps the synchronous request/response process. · `src/entrypoints/api.ts`
- [Workers entrypoint](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/entrypoints/workers.ts): consumer runtime · Starts background consumer loops for async processing. · `src/entrypoints/workers.ts`
- [Outbox entrypoint](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/entrypoints/outbox.ts): relay runtime · 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](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/users/user.routes.ts): feature module · User-facing HTTP handlers and schema bootstrapping. · `src/modules/users/user.routes.ts`
- [Products](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/products/product.routes.ts): feature module · Product catalog HTTP handlers. · `src/modules/products/product.routes.ts`
- [Cart](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/cart/cart.routes.ts): feature module · Cart state and request handlers. · `src/modules/cart/cart.routes.ts`
- [Orders](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/orders/order.routes.ts): feature module · Order HTTP handlers and async worker logic. · `src/modules/orders/order.routes.ts`
- [Payments](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/payments/payment.routes.ts): feature module · Payment HTTP handlers and async worker logic. · `src/modules/payments/payment.routes.ts`
- [Notifications](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/modules/notifications/notification.worker.ts): async module · Notification worker processing broker-driven events. · `src/modules/notifications/notification.worker.ts`

### Shared core

Cross-cutting infrastructure, orchestration, and observability components.

- [Server](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/server.ts): http host · Configures the HTTP server and mounts the API surface. · `src/server.ts`
- [Auth guard](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/middlewares/auth.middleware.ts): middleware · Request boundary control for authenticated operations. · `src/shared/middlewares/auth.middleware.ts`
- [Postgres pool](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/pool.ts): sql persistence · Transactional database access for core business state. · `src/shared/database/pool.ts`
- [Redis cache](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/redis.ts): volatile state · Cache and session-like state for fast ephemeral access. · `src/shared/database/redis.ts`
- [Message broker](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/database/queue.ts): amqp broker · Queue abstraction backing asynchronous work distribution. · `src/shared/database/queue.ts`
- [Outbox relay](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/workers/outbox.processor.ts): event relay · Reads persisted outbox records and publishes them to the broker. · `src/shared/workers/outbox.processor.ts`
- [Order saga](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/saga/order.saga.ts): orchestration · Coordinates multi-step order and payment progression. · `src/shared/saga/order.saga.ts`
- [Metrics](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/monitoring/metrics.ts): telemetry · Application metrics instrumentation and exposure. · `src/shared/monitoring/metrics.ts`
- [Tracer](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/src/shared/monitoring/tracer.ts): telemetry · Distributed tracing instrumentation and propagation. · `src/shared/monitoring/tracer.ts`

### Deployment

Containerized backing services and runtime dependencies.

- [PostgreSQL](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/docker-compose.yml): database service · Primary transactional datastore. · `docker-compose.yml`
- [RabbitMQ](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/docker-compose.yml): broker service · Message broker used for background workflow processing. · `docker-compose.yml`
- [Redis](https://github.com/nirodhauwanpriya/reactive-commerce-orchestrator/blob/master/docker-compose.yml): cache service · Containerized cache dependency. · `docker-compose.yml`

## Connections

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