# abdelrahmanhanyy2003-cmyk/egx-flow architecture

> Architecture diagram of the GitHub repository abdelrahmanhanyy2003-cmyk/egx-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdelrahmanhanyy2003-cmyk/egx-flow
- Repository: https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow

## Overview

EGX Flow is a read-only EGX order-flow and market-intelligence terminal. Users explore live or simulated market data, inspect derived signals and portfolio analytics, configure alerts, and replay recorded sessions. The backend normalizes provider events into symbol state, computes market views and distributes updates; persistence supports history and replay. The README documents additional product screens and analytics that are not all represented by sampled source. Some frontend-to-backend wiring and unsampled subsystem internals are therefore left unconnected.

Main entry points: [`backend/app/services/market_service.py`](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/market_service.py) (Market hub), [`backend/app/services/container.py`](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/container.py) (Runtime composition), [`frontend/src/app/page.tsx`](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/page.tsx) (Market terminal), [`backend/app/market_data/symbol_state.py`](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/market_data/symbol_state.py) (Symbol state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Terminal experience"]
  node_terminal["Market terminal<br/>[page.tsx]"]
  node_explorer["Stock explorer<br/>[page.tsx]"]
  node_market_view["Market overview<br/>[page.tsx]"]
  node_whale_view["Whale Radar<br/>[page.tsx]"]
  node_portfolio_view["Portfolio screens<br/>[page.tsx]"]
  node_alerts_view["Alert screens<br/>[page.tsx]"]
  node_replay_view["Replay screen<br/>[page.tsx]"]
  node_heatmap["Heatmap renderer<br/>[HeatmapEngine.ts]"]
end

subgraph group_runtime["Market runtime"]
  node_app["FastAPI application<br/>[main.py]"]
  node_hub["Market hub<br/>[market_service.py]"]
  node_symbol_state["Symbol state<br/>[symbol_state.py]"]
  node_orderbook["Order book"]
  node_ws["WebSocket fan-out"]
end

subgraph group_insights["Analytics and alerts"]
  node_analytics["Market analytics"]
  node_alerts["Alert engine<br/>[engine.py]"]
end

subgraph group_portfolio["Portfolio and replay"]
  node_portfolio["Portfolio analytics"]
  node_replay["Session replay<br/>[replay_service.py]"]
  node_recorder["Session recorder<br/>[recorder.py]"]
end

subgraph group_platform["Providers and persistence"]
  node_provider["Provider interface<br/>[base.py]"]
  node_hermes["EFG Hermes integration"]
  node_db[("Market database<br/>[__init__.py]")]
  node_market_repo["Market repository<br/>[market_repo.py]"]
  node_container["Runtime composition<br/>[container.py]"]
end

node_user(("Terminal user"))

node_user -->|"explores markets"| node_terminal
node_user -->|"screens stocks"| node_explorer
node_user -->|"views overview"| node_market_view
node_user -->|"inspects signals"| node_whale_view
node_user -->|"reviews portfolio"| node_portfolio_view
node_user -->|"configures alerts"| node_alerts_view
node_user -->|"replays sessions"| node_replay_view
node_terminal -->|"renders heatmap"| node_heatmap
node_app -->|"builds runtime"| node_container
node_container -->|"constructs"| node_hub
node_container -->|"constructs"| node_portfolio
node_container -->|"constructs"| node_replay
node_container -->|"selects provider"| node_provider
node_container -->|"configures live"| node_hermes
node_hub -->|"updates state"| node_symbol_state
node_hub -->|"records events"| node_recorder
node_hub -->|"checks signals"| node_alerts
node_hub -->|"publishes updates"| node_ws
node_symbol_state -.->|"maintains book"| node_orderbook
node_hub -->|"computes views"| node_analytics
node_portfolio -->|"reads live prices"| node_hub
node_replay -->|"replays events"| node_hub
node_recorder -->|"persists history"| node_market_repo
node_market_repo -->|"reads and writes"| node_db
node_provider -.->|"implements interface"| node_hermes

click node_terminal "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/page.tsx"
click node_explorer "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/explorer/page.tsx"
click node_market_view "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/market/page.tsx"
click node_whale_view "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/whales/page.tsx"
click node_portfolio_view "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/portfolio/page.tsx"
click node_alerts_view "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/alerts/page.tsx"
click node_replay_view "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/replay/page.tsx"
click node_heatmap "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/components/terminal/engine/HeatmapEngine.ts"
click node_app "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/main.py"
click node_hub "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/market_service.py"
click node_symbol_state "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/market_data/symbol_state.py"
click node_orderbook "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/market_data/orderbook_engine.py"
click node_analytics "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/tree/main/backend/app/analytics"
click node_alerts "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/alerts/engine.py"
click node_ws "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/websocket_manager.py"
click node_portfolio "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/portfolio_service.py"
click node_replay "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/replay_service.py"
click node_recorder "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/replay/recorder.py"
click node_provider "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/providers/base.py"
click node_hermes "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/tree/main/backend/app/integrations/efg_hermes"
click node_db "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/database/models/__init__.py"
click node_market_repo "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/database/repositories/market_repo.py"
click node_container "https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/container.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_terminal,node_explorer,node_market_view,node_whale_view,node_portfolio_view,node_alerts_view,node_replay_view,node_heatmap,node_user toneBlue
class node_app,node_hub,node_symbol_state,node_orderbook,node_ws toneAmber
class node_analytics,node_alerts toneMint
class node_portfolio,node_replay,node_recorder toneRose
class node_provider,node_hermes,node_db,node_market_repo,node_container toneIndigo
```

## Components

### Terminal experience

- [Market terminal](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Stock explorer](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/explorer/page.tsx): `frontend/src/app/explorer/page.tsx`
- [Market overview](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/market/page.tsx): `frontend/src/app/market/page.tsx`
- [Whale Radar](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/whales/page.tsx): `frontend/src/app/whales/page.tsx`
- [Portfolio screens](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/portfolio/page.tsx): `frontend/src/app/portfolio/page.tsx`
- [Alert screens](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/alerts/page.tsx): `frontend/src/app/alerts/page.tsx`
- [Replay screen](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/app/replay/page.tsx): `frontend/src/app/replay/page.tsx`
- [Heatmap renderer](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/frontend/src/components/terminal/engine/HeatmapEngine.ts): `frontend/src/components/terminal/engine/HeatmapEngine.ts`

### Market runtime

- [FastAPI application](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/main.py): `backend/app/main.py`
- [Market hub](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/market_service.py): `backend/app/services/market_service.py`
- [Symbol state](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/market_data/symbol_state.py): `backend/app/market_data/symbol_state.py`
- [Order book](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/market_data/orderbook_engine.py): `backend/app/market_data/orderbook_engine.py`
- [WebSocket fan-out](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/websocket_manager.py): `backend/app/services/websocket_manager.py`

### Analytics and alerts

- [Market analytics](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/tree/main/backend/app/analytics): `backend/app/analytics`
- [Alert engine](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/alerts/engine.py): `backend/app/alerts/engine.py`

### Portfolio and replay

- [Portfolio analytics](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/portfolio_service.py): `backend/app/services/portfolio_service.py`
- [Session replay](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/replay_service.py): `backend/app/services/replay_service.py`
- [Session recorder](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/replay/recorder.py): `backend/app/replay/recorder.py`

### Providers and persistence

- [Provider interface](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/providers/base.py): `backend/app/providers/base.py`
- [EFG Hermes integration](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/tree/main/backend/app/integrations/efg_hermes): `backend/app/integrations/efg_hermes`
- [Market database](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/database/models/__init__.py): `backend/app/database/models/__init__.py`
- [Market repository](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/database/repositories/market_repo.py): `backend/app/database/repositories/market_repo.py`
- [Runtime composition](https://github.com/abdelrahmanhanyy2003-cmyk/egx-flow/blob/main/backend/app/services/container.py): `backend/app/services/container.py`

### Other components

- **Terminal user**

## Connections

- Terminal user → Market terminal: explores markets
- Terminal user → Stock explorer: screens stocks
- Terminal user → Market overview: views overview
- Terminal user → Whale Radar: inspects signals
- Terminal user → Portfolio screens: reviews portfolio
- Terminal user → Alert screens: configures alerts
- Terminal user → Replay screen: replays sessions
- Market terminal → Heatmap renderer: renders heatmap
- FastAPI application → Runtime composition: builds runtime (evidence: `backend/app/main.py`)
- Runtime composition → Market hub: constructs (evidence: `backend/app/services/container.py`)
- Runtime composition → Portfolio analytics: constructs (evidence: `backend/app/services/container.py`)
- Runtime composition → Session replay: constructs (evidence: `backend/app/services/container.py`)
- Runtime composition → Provider interface: selects provider (evidence: `backend/app/services/container.py`)
- Runtime composition → EFG Hermes integration: configures live (evidence: `backend/app/services/container.py`)
- Market hub → Symbol state: updates state (evidence: `backend/app/services/market_service.py`)
- Market hub → Session recorder: records events (evidence: `backend/app/services/market_service.py`)
- Market hub → Alert engine: checks signals (evidence: `backend/app/services/market_service.py`)
- Market hub → WebSocket fan-out: publishes updates (evidence: `backend/app/services/market_service.py`)
- Symbol state → Order book: maintains book
- Market hub → Market analytics: computes views (evidence: `backend/app/services/market_service.py`)
- Portfolio analytics → Market hub: reads live prices (evidence: `backend/app/services/portfolio_service.py`)
- Session replay → Market hub: replays events (evidence: `backend/app/services/replay_service.py`)
- Session recorder → Market repository: persists history (evidence: `backend/app/replay/recorder.py`)
- Market repository → Market database: reads and writes (evidence: `backend/app/database/repositories/market_repo.py`)
- Provider interface → EFG Hermes integration: implements interface
