# samudralaajaykumarrr/omniflow architecture

> Architecture diagram of the GitHub repository samudralaajaykumarrr/omniflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samudralaajaykumarrr/omniflow
- Repository: https://github.com/samudralaajaykumarrr/omniflow

## Overview

OmniFlow is an event-driven retail order, inventory, and fulfillment platform with an authenticated operator dashboard and an analytics pipeline. The principal workflow is operator order submission through the gateway, order persistence and event publication, then asynchronous saga orchestration that reserves inventory and advances fulfillment. Event data also feeds Bronze/Silver/Gold analytics and forecasting. The README documents these major capabilities; sampled source confirms gateway proxying, inventory operations, saga APIs, and failure-lab triggering, but not every consumer, outbox, or pipeline implementation detail.

Main entry points: [`services/fulfillment-orchestrator/app/consumer.py`](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/fulfillment-orchestrator/app/consumer.py) (Saga orchestrator), [`services/ops-dashboard/src/api`](https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/ops-dashboard/src/api) (Dashboard API clients), [`services/order-service/app/routes.py`](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/order-service/app/routes.py) (Order service), [`services/inventory-service/app/routes.py`](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/inventory-service/app/routes.py) (Inventory service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Operator experience"]
  node_dashboard["Ops dashboard<br/>[App.tsx]"]
  node_dashboard_api["Dashboard API clients"]
end

subgraph group_commerce["Commerce services"]
  node_gateway["API gateway<br/>[routes.py]"]
  node_orders["Order service<br/>[routes.py]"]
  node_order_db[("Order database<br/>[db.py]")]
  node_inventory["Inventory service<br/>[routes.py]"]
  node_inventory_db[("Inventory database<br/>[db.py]")]
end

subgraph group_events["Event orchestration"]
  node_broker["Kafka event bus"]
  node_contracts["Event contracts"]
  node_orchestrator["Saga orchestrator<br/>[consumer.py]"]
  node_saga_state[("Saga and DLQ state<br/>[db.py]")]
end

subgraph group_analytics["Analytics platform"]
  node_data_platform["Streaming pipeline<br/>[bronze.py]"]
  node_silver["Silver transforms<br/>[silver.py]"]
  node_gold["Gold aggregates<br/>[runner.py]"]
  node_object_store[("Parquet object store<br/>[s3.py]")]
  node_forecast["Demand forecasting"]
end

subgraph group_resilience["Failure laboratory"]
  node_failure_api["Failure-lab API<br/>[routes.py]"]
  node_scenario_runner["Scenario runner<br/>[runner.py]"]
end

node_operator(("Ops user"))
node_stack(("Live platform"))
node_observability["Tracing and metrics"]

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests"| node_dashboard_api
node_dashboard_api -->|"calls"| node_gateway
node_gateway -->|"proxies orders"| node_orders
node_gateway -->|"proxies stock"| node_inventory
node_orders -->|"reads and writes"| node_order_db
node_inventory -->|"reads and writes"| node_inventory_db
node_orders -->|"publishes events"| node_broker
node_inventory -->|"publishes events"| node_broker
node_broker -->|"delivers events"| node_orchestrator
node_orchestrator -->|"uses schemas"| node_contracts
node_orchestrator -->|"advances orders"| node_orders
node_orchestrator -->|"reserves stock"| node_inventory
node_orchestrator -->|"stores saga and DLQ"| node_saga_state
node_orchestrator -->|"publishes outcomes"| node_broker
node_broker -->|"streams topics"| node_data_platform
node_data_platform -->|"writes Bronze"| node_object_store
node_data_platform -->|"validates and deduplicates"| node_silver
node_silver -->|"writes Silver"| node_object_store
node_silver -->|"aggregates"| node_gold
node_gold -->|"writes Gold"| node_object_store
node_object_store -->|"supplies datasets"| node_forecast
node_dashboard_api -.->|"requests pipeline views"| node_data_platform
node_dashboard_api -.->|"requests saga and DLQ views"| node_orchestrator
node_dashboard_api -.->|"triggers scenarios"| node_failure_api
node_failure_api -->|"runs scenarios"| node_scenario_runner
node_scenario_runner -->|"exercises services"| node_stack
node_contracts -->|"configures telemetry"| node_observability

click node_dashboard "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/ops-dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/ops-dashboard/src/api"
click node_gateway "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/api-gateway/app/routes.py"
click node_orders "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/order-service/app/routes.py"
click node_order_db "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/order-service/app/db.py"
click node_inventory "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/inventory-service/app/routes.py"
click node_inventory_db "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/inventory-service/app/db.py"
click node_contracts "https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/event-contracts/event_contracts"
click node_orchestrator "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/fulfillment-orchestrator/app/consumer.py"
click node_saga_state "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/fulfillment-orchestrator/app/db.py"
click node_data_platform "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/bronze.py"
click node_silver "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/silver.py"
click node_gold "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/gold/runner.py"
click node_object_store "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/s3.py"
click node_forecast "https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/data-platform/app/forecasting"
click node_failure_api "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/failure-lab/app/routes.py"
click node_scenario_runner "https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/failure-lab/app/runner.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_dashboard,node_dashboard_api,node_operator toneBlue
class node_gateway,node_orders,node_order_db,node_inventory,node_inventory_db toneAmber
class node_broker,node_contracts,node_orchestrator,node_saga_state toneMint
class node_data_platform,node_silver,node_gold,node_object_store,node_forecast toneRose
class node_failure_api,node_scenario_runner,node_stack,node_observability toneIndigo
```

## Components

### Operator experience

- [Ops dashboard](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/ops-dashboard/src/App.tsx): `services/ops-dashboard/src/App.tsx`
- [Dashboard API clients](https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/ops-dashboard/src/api): `services/ops-dashboard/src/api`

### Commerce services

- [API gateway](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/api-gateway/app/routes.py): `services/api-gateway/app/routes.py`
- [Order service](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/order-service/app/routes.py): `services/order-service/app/routes.py`
- [Order database](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/order-service/app/db.py): `services/order-service/app/db.py`
- [Inventory service](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/inventory-service/app/routes.py): `services/inventory-service/app/routes.py`
- [Inventory database](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/inventory-service/app/db.py): `services/inventory-service/app/db.py`

### Event orchestration

- **Kafka event bus**
- [Event contracts](https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/event-contracts/event_contracts): `services/event-contracts/event_contracts`
- [Saga orchestrator](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/fulfillment-orchestrator/app/consumer.py): `services/fulfillment-orchestrator/app/consumer.py`
- [Saga and DLQ state](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/fulfillment-orchestrator/app/db.py): `services/fulfillment-orchestrator/app/db.py`

### Analytics platform

- [Streaming pipeline](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/bronze.py): `services/data-platform/app/bronze.py`
- [Silver transforms](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/silver.py): `services/data-platform/app/silver.py`
- [Gold aggregates](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/gold/runner.py): `services/data-platform/app/gold/runner.py`
- [Parquet object store](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/data-platform/app/s3.py): `services/data-platform/app/s3.py`
- [Demand forecasting](https://github.com/samudralaajaykumarrr/omniflow/tree/main/services/data-platform/app/forecasting): `services/data-platform/app/forecasting`

### Failure laboratory

- [Failure-lab API](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/failure-lab/app/routes.py): `services/failure-lab/app/routes.py`
- [Scenario runner](https://github.com/samudralaajaykumarrr/omniflow/blob/main/services/failure-lab/app/runner.py): `services/failure-lab/app/runner.py`

### Other components

- **Ops user**
- **Live platform**
- **Tracing and metrics**

## Connections

- Ops user → Ops dashboard: uses
- Ops dashboard → Dashboard API clients: requests
- Dashboard API clients → API gateway: calls
- API gateway → Order service: proxies orders
- API gateway → Inventory service: proxies stock
- Order service → Order database: reads and writes
- Inventory service → Inventory database: reads and writes
- Order service → Kafka event bus: publishes events
- Inventory service → Kafka event bus: publishes events
- Kafka event bus → Saga orchestrator: delivers events
- Saga orchestrator → Event contracts: uses schemas
- Saga orchestrator → Order service: advances orders
- Saga orchestrator → Inventory service: reserves stock
- Saga orchestrator → Saga and DLQ state: stores saga and DLQ
- Saga orchestrator → Kafka event bus: publishes outcomes
- Kafka event bus → Streaming pipeline: streams topics
- Streaming pipeline → Parquet object store: writes Bronze
- Streaming pipeline → Silver transforms: validates and deduplicates
- Silver transforms → Parquet object store: writes Silver
- Silver transforms → Gold aggregates: aggregates
- Gold aggregates → Parquet object store: writes Gold
- Parquet object store → Demand forecasting: supplies datasets
- Dashboard API clients → Streaming pipeline: requests pipeline views
- Dashboard API clients → Saga orchestrator: requests saga and DLQ views
- Dashboard API clients → Failure-lab API: triggers scenarios
- Failure-lab API → Scenario runner: runs scenarios
- Scenario runner → Live platform: exercises services
- Event contracts → Tracing and metrics: configures telemetry