# ishatalwaria/eventflow-ai architecture

> Architecture diagram of the GitHub repository ishatalwaria/eventflow-ai, 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/ishatalwaria/eventflow-ai
- Repository: https://github.com/ishatalwaria/eventflow-ai

## Overview

EventFlow AI accepts tenant events, creates workflow state and an outbox record transactionally, then routes work through broker-backed workflow stages with retries and compensation. Operators use the React console to explore events, workflows, commerce, incidents, analytics, health, and settings. The README documents the dual-broker delivery and ClickHouse lifecycle analytics; source-index references and excerpts support selected implementation links. Several subsystems were not sampled, so their internal call paths are not expanded.

Main entry points: [`frontend/src/features`](https://github.com/ishatalwaria/eventflow-ai/tree/main/frontend/src/features) (Operations Features), [`apps/events/services.py`](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/services.py) (Event Acceptance), [`apps/processing/saga/engine.py`](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/saga/engine.py) (Saga Engine), [`apps/processing`](https://github.com/ishatalwaria/eventflow-ai/tree/main/apps/processing) (Broker Delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Event Ingestion"]
  node_event_api["Event API<br/>[views.py]"]
  node_event_acceptance["Event Acceptance<br/>[services.py]"]
  node_event_store[("Events<br/>[models.py]")]
end

subgraph group_runtime["Workflow Runtime"]
  node_outbox[("Transactional Outbox<br/>[outbox.py]")]
  node_broker_delivery["Broker Delivery"]
  node_workflow_state[("Workflow State<br/>[models.py]")]
  node_saga_engine["Saga Engine<br/>[engine.py]"]
  node_saga_definitions["Saga Definitions<br/>[definitions.py]"]
end

subgraph group_operations["Operations Intelligence"]
  node_analytics["Lifecycle Analytics"]
  node_incident_assistant["Incident Assistant<br/>[service.py]"]
  node_health_observability["Health Observability<br/>[observability.py]"]
end

subgraph group_commerce["Commerce Domain"]
  node_commerce_stages["Commerce Stages<br/>[fulfillment.py]"]
  node_commerce_data[("Orders Inventory Payments<br/>[models.py]")]
end

subgraph group_console["Web Console"]
  node_console_routes["Console Routes<br/>[App.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_console_features["Operations Features"]
  node_auth_management["Authentication Management<br/>[SettingsPage.tsx]"]
end

node_operator(("Operator"))
node_service_client(("Service Client"))

node_service_client -->|"submits events"| node_event_api
node_event_api -.->|"accepts events"| node_event_acceptance
node_event_acceptance -->|"creates events"| node_event_store
node_event_acceptance -->|"creates workflow"| node_workflow_state
node_event_acceptance -->|"records outbox"| node_outbox
node_outbox -->|"publishes messages"| node_broker_delivery
node_broker_delivery -->|"dispatches tasks"| node_saga_engine
node_saga_engine -->|"updates state"| node_workflow_state
node_saga_engine -->|"selects definition"| node_saga_definitions
node_saga_engine -->|"gets handler"| node_commerce_stages
node_commerce_stages -->|"updates commerce"| node_commerce_data
node_broker_delivery -->|"streams lifecycle"| node_analytics
node_operator -->|"uses console"| node_console_routes
node_console_routes -->|"routes to"| node_console_features
node_console_features -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_event_api
node_console_features -.->|"views analytics"| node_analytics
node_console_features -.->|"investigates incidents"| node_incident_assistant
node_console_features -.->|"views health"| node_health_observability
node_console_features -.->|"manages credentials"| node_auth_management

click node_event_api "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/views.py"
click node_event_acceptance "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/services.py"
click node_event_store "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/models.py"
click node_outbox "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/outbox.py"
click node_broker_delivery "https://github.com/ishatalwaria/eventflow-ai/tree/main/apps/processing"
click node_workflow_state "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/workflows/models.py"
click node_saga_engine "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/saga/engine.py"
click node_saga_definitions "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/saga/definitions.py"
click node_commerce_stages "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/commerce/stages/fulfillment.py"
click node_commerce_data "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/commerce/models.py"
click node_analytics "https://github.com/ishatalwaria/eventflow-ai/tree/main/apps/analytics"
click node_incident_assistant "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/incidents/service.py"
click node_health_observability "https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/common/observability.py"
click node_console_routes "https://github.com/ishatalwaria/eventflow-ai/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/ishatalwaria/eventflow-ai/blob/main/frontend/src/api/client.ts"
click node_console_features "https://github.com/ishatalwaria/eventflow-ai/tree/main/frontend/src/features"
click node_auth_management "https://github.com/ishatalwaria/eventflow-ai/blob/main/frontend/src/features/settings/SettingsPage.tsx"

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_event_api,node_event_acceptance,node_event_store,node_service_client toneBlue
class node_outbox,node_broker_delivery,node_workflow_state,node_saga_engine,node_saga_definitions toneAmber
class node_analytics,node_incident_assistant,node_health_observability toneMint
class node_commerce_stages,node_commerce_data toneRose
class node_console_routes,node_api_client,node_console_features,node_auth_management,node_operator toneIndigo
```

## Components

### Event Ingestion

- [Event API](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/views.py): `apps/events/views.py`
- [Event Acceptance](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/services.py): `apps/events/services.py`
- [Events](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/events/models.py): `apps/events/models.py`

### Workflow Runtime

- [Transactional Outbox](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/outbox.py): `apps/processing/outbox.py`
- [Broker Delivery](https://github.com/ishatalwaria/eventflow-ai/tree/main/apps/processing): `apps/processing`
- [Workflow State](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/workflows/models.py): `apps/workflows/models.py`
- [Saga Engine](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/saga/engine.py): `apps/processing/saga/engine.py`
- [Saga Definitions](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/processing/saga/definitions.py): `apps/processing/saga/definitions.py`

### Operations Intelligence

- [Lifecycle Analytics](https://github.com/ishatalwaria/eventflow-ai/tree/main/apps/analytics): `apps/analytics`
- [Incident Assistant](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/incidents/service.py): `apps/incidents/service.py`
- [Health Observability](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/common/observability.py): `apps/common/observability.py`

### Commerce Domain

- [Commerce Stages](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/commerce/stages/fulfillment.py): `apps/commerce/stages/fulfillment.py`
- [Orders Inventory Payments](https://github.com/ishatalwaria/eventflow-ai/blob/main/apps/commerce/models.py): `apps/commerce/models.py`

### Web Console

- [Console Routes](https://github.com/ishatalwaria/eventflow-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/ishatalwaria/eventflow-ai/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Operations Features](https://github.com/ishatalwaria/eventflow-ai/tree/main/frontend/src/features): `frontend/src/features`
- [Authentication Management](https://github.com/ishatalwaria/eventflow-ai/blob/main/frontend/src/features/settings/SettingsPage.tsx): `frontend/src/features/settings/SettingsPage.tsx`

### Other components

- **Operator**
- **Service Client**

## Connections

- Service Client → Event API: submits events
- Event API → Event Acceptance: accepts events
- Event Acceptance → Events: creates events (evidence: `apps/events/services.py`)
- Event Acceptance → Workflow State: creates workflow (evidence: `apps/events/services.py`)
- Event Acceptance → Transactional Outbox: records outbox (evidence: `apps/events/services.py`)
- Transactional Outbox → Broker Delivery: publishes messages
- Broker Delivery → Saga Engine: dispatches tasks (evidence: `apps/processing/saga/engine.py`)
- Saga Engine → Workflow State: updates state (evidence: `apps/processing/saga/engine.py`)
- Saga Engine → Saga Definitions: selects definition (evidence: `apps/processing/saga/engine.py`)
- Saga Engine → Commerce Stages: gets handler (evidence: `apps/processing/saga/engine.py`)
- Commerce Stages → Orders Inventory Payments: updates commerce (evidence: `apps/commerce/stages/fulfillment.py`)
- Broker Delivery → Lifecycle Analytics: streams lifecycle
- Operator → Console Routes: uses console
- Console Routes → Operations Features: routes to (evidence: `frontend/src/App.tsx`)
- Operations Features → API Client: requests data
- API Client → Event API: calls API
- Operations Features → Lifecycle Analytics: views analytics
- Operations Features → Incident Assistant: investigates incidents
- Operations Features → Health Observability: views health
- Operations Features → Authentication Management: manages credentials
