# diman4iggg/arbitrage_terminal architecture

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

- Interactive diagram: https://gitdiagram.com/diman4iggg/arbitrage_terminal
- Repository: https://github.com/diman4iggg/arbitrage_terminal

## Overview

Arbitrage Terminal is a read-only perpetual-market arbitrage monitor, not an execution system. Its principal workflow polls enabled exchanges and pairs, normalizes market data, calculates spreads, enriches funding context, persists results, and optionally sends cooldown-protected Telegram alerts; users inspect and configure it through a REST-backed web interface. The graph preserves documented charting and trade-watch capabilities. Several route and service implementations were not excerpted, so their connections are based on the README’s documented pipeline or capabilities rather than claims of source inspection.

Main entry points: [`arbitrage-terminal/backend/app/services/monitoring_service.py`](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/monitoring_service.py) (Monitoring cycle), [`arbitrage-terminal/backend/app/api/router.py`](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/api/router.py) (API router), [`arbitrage-terminal/frontend/src/pages`](https://github.com/diman4iggg/arbitrage_terminal/tree/main/arbitrage-terminal/frontend/src/pages) (Dashboard and views), [`arbitrage-terminal/backend/app/db/models.py`](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/db/models.py) (PostgreSQL data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web terminal"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_pages["Dashboard and views"]
  node_opptable["Opportunity table"]
  node_apiclient["API client<br/>[client.ts]"]
end

subgraph group_api["REST API"]
  node_router["API router<br/>[router.py]"]
end

subgraph group_market["Market monitoring"]
  node_monitor["Monitoring cycle"]
  node_scheduler["Background scheduler<br/>[scheduler.py]"]
  node_adapters["Exchange adapters"]
  node_marketdata["Market data service"]
  node_arbitrage["Spread calculation"]
  node_strategy["Price spread strategy<br/>[price_spread.py]"]
  node_funding["Funding enrichment"]
end

subgraph group_state["Persistence and settings"]
  node_settings["Runtime settings"]
  node_store[("PostgreSQL data<br/>[models.py]")]
  node_persistence["Persistence service"]
end

subgraph group_alerts["Trade watches and alerts"]
  node_tradewatch["Trade watch service"]
  node_notifyservice["Notification service"]
  node_telegram["Telegram sender<br/>[telegram.py]"]
end

node_user(("Terminal user"))
node_telegramapi{{"Telegram Bot API"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_pages
node_pages -->|"requests data"| node_apiclient
node_pages -.->|"presents opportunities"| node_opptable
node_apiclient -->|"calls REST"| node_router
node_scheduler -->|"runs cycle"| node_monitor
node_monitor -->|"loads enabled markets"| node_settings
node_monitor -->|"fetches market data"| node_adapters
node_monitor -->|"collects tickers"| node_marketdata
node_marketdata -.->|"queries exchanges"| node_adapters
node_monitor -->|"calculates spreads"| node_arbitrage
node_arbitrage -->|"delegates calculation"| node_strategy
node_monitor -->|"enriches opportunities"| node_funding
node_monitor -->|"saves results"| node_persistence
node_persistence -->|"writes snapshots"| node_store
node_settings -->|"reads and writes"| node_store
node_router -.->|"serves persisted data"| node_store
node_monitor -->|"updates watched positions"| node_tradewatch
node_monitor -->|"checks alerts"| node_notifyservice
node_notifyservice -->|"sends alerts"| node_telegram
node_telegram -.->|"delivers messages"| node_telegramapi
node_router -.->|"provides charts and status"| node_pages
node_router -->|"routes trade-watch requests"| node_tradewatch

click node_webapp "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/frontend/src/App.tsx"
click node_pages "https://github.com/diman4iggg/arbitrage_terminal/tree/main/arbitrage-terminal/frontend/src/pages"
click node_opptable "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/frontend/src/components/OpportunityTable.tsx"
click node_apiclient "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/frontend/src/api/client.ts"
click node_router "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/api/router.py"
click node_monitor "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/monitoring_service.py"
click node_scheduler "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/core/scheduler.py"
click node_adapters "https://github.com/diman4iggg/arbitrage_terminal/tree/main/arbitrage-terminal/backend/app/exchanges"
click node_marketdata "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/market_data_service.py"
click node_arbitrage "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/arbitrage_service.py"
click node_strategy "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/strategies/price_spread.py"
click node_funding "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/opportunity_funding_service.py"
click node_settings "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/settings_service.py"
click node_store "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/db/models.py"
click node_persistence "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/persistence_service.py"
click node_tradewatch "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/trade_watch_service.py"
click node_notifyservice "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/notification_service.py"
click node_telegram "https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/notifications/telegram.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_webapp,node_pages,node_opptable,node_apiclient,node_user toneBlue
class node_router toneAmber
class node_monitor,node_scheduler,node_adapters,node_marketdata,node_arbitrage,node_strategy,node_funding,node_telegramapi toneMint
class node_settings,node_store,node_persistence toneRose
class node_tradewatch,node_notifyservice,node_telegram toneIndigo
```

## Components

### Web terminal

- [Web app routes](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/frontend/src/App.tsx): `arbitrage-terminal/frontend/src/App.tsx`
- [Dashboard and views](https://github.com/diman4iggg/arbitrage_terminal/tree/main/arbitrage-terminal/frontend/src/pages): `arbitrage-terminal/frontend/src/pages`
- [Opportunity table](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/frontend/src/components/OpportunityTable.tsx): `arbitrage-terminal/frontend/src/components/OpportunityTable.tsx`
- [API client](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/frontend/src/api/client.ts): `arbitrage-terminal/frontend/src/api/client.ts`

### REST API

- [API router](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/api/router.py): `arbitrage-terminal/backend/app/api/router.py`

### Market monitoring

- [Monitoring cycle](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/monitoring_service.py): `arbitrage-terminal/backend/app/services/monitoring_service.py`
- [Background scheduler](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/core/scheduler.py): `arbitrage-terminal/backend/app/core/scheduler.py`
- [Exchange adapters](https://github.com/diman4iggg/arbitrage_terminal/tree/main/arbitrage-terminal/backend/app/exchanges): `arbitrage-terminal/backend/app/exchanges`
- [Market data service](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/market_data_service.py): `arbitrage-terminal/backend/app/services/market_data_service.py`
- [Spread calculation](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/arbitrage_service.py): `arbitrage-terminal/backend/app/services/arbitrage_service.py`
- [Price spread strategy](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/strategies/price_spread.py): `arbitrage-terminal/backend/app/strategies/price_spread.py`
- [Funding enrichment](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/opportunity_funding_service.py): `arbitrage-terminal/backend/app/services/opportunity_funding_service.py`

### Persistence and settings

- [Runtime settings](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/settings_service.py): `arbitrage-terminal/backend/app/services/settings_service.py`
- [PostgreSQL data](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/db/models.py): `arbitrage-terminal/backend/app/db/models.py`
- [Persistence service](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/persistence_service.py): `arbitrage-terminal/backend/app/services/persistence_service.py`

### Trade watches and alerts

- [Trade watch service](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/trade_watch_service.py): `arbitrage-terminal/backend/app/services/trade_watch_service.py`
- [Notification service](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/services/notification_service.py): `arbitrage-terminal/backend/app/services/notification_service.py`
- [Telegram sender](https://github.com/diman4iggg/arbitrage_terminal/blob/main/arbitrage-terminal/backend/app/notifications/telegram.py): `arbitrage-terminal/backend/app/notifications/telegram.py`

### Other components

- **Terminal user**
- **Telegram Bot API**

## Connections

- Terminal user → Web app routes: uses
- Web app routes → Dashboard and views: routes to (evidence: `arbitrage-terminal/frontend/src/App.tsx`)
- Dashboard and views → API client: requests data (evidence: `arbitrage-terminal/frontend/src/api/client.ts`)
- Dashboard and views → Opportunity table: presents opportunities (evidence: `arbitrage-terminal/frontend/src/pages/Dashboard.tsx`)
- API client → API router: calls REST
- Background scheduler → Monitoring cycle: runs cycle (evidence: `arbitrage-terminal/backend/app/core/scheduler.py`)
- Monitoring cycle → Runtime settings: loads enabled markets (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Monitoring cycle → Exchange adapters: fetches market data (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Monitoring cycle → Market data service: collects tickers (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Market data service → Exchange adapters: queries exchanges
- Monitoring cycle → Spread calculation: calculates spreads (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Spread calculation → Price spread strategy: delegates calculation (evidence: `arbitrage-terminal/backend/app/services/arbitrage_service.py`)
- Monitoring cycle → Funding enrichment: enriches opportunities (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Monitoring cycle → Persistence service: saves results (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Persistence service → PostgreSQL data: writes snapshots (evidence: `arbitrage-terminal/backend/app/services/persistence_service.py`)
- Runtime settings → PostgreSQL data: reads and writes (evidence: `arbitrage-terminal/backend/app/services/settings_service.py`)
- API router → PostgreSQL data: serves persisted data
- Monitoring cycle → Trade watch service: updates watched positions (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Monitoring cycle → Notification service: checks alerts (evidence: `arbitrage-terminal/backend/app/services/monitoring_service.py`)
- Notification service → Telegram sender: sends alerts (evidence: `arbitrage-terminal/backend/app/services/notification_service.py`)
- Telegram sender → Telegram Bot API: delivers messages
- API router → Dashboard and views: provides charts and status
- API router → Trade watch service: routes trade-watch requests
