# cortex-ai-quant/crypto-arbitrage-bot-automated-trading architecture

> Architecture diagram of the GitHub repository cortex-ai-quant/crypto-arbitrage-bot-automated-trading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading
- Repository: https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading

## Overview

#### Purpose and Scope
This repository is a small Python implementation scaffold for a crypto-arbitrage bot. The README presents a broader “Cortex AI” trading product, but the checked-in source surface is limited to configuration, market scanning, and execution modules under `src/`. Claims about dashboards, binaries, AI inference, MEV protection, and multi-chain routing are not verifiable from the provided tree.

#### Entry Points and Runtime
The likely runtime is Python 3.10+ with dependencies installed from `requirements.txt`. No CLI script, service launcher, web server, or packaged executable is present in the tree; consumers likely import the package or invoke a module externally.
- Package boundary: `src/__init__.py`
- Dependency declaration: `requirements.txt`
- Automation/validation boundary: `.github/workflows/ci.yml`

#### Configuration and Secrets Boundary
`src/config.py` is the architecture’s expected source for runtime settings: exchange endpoints, API credentials, trading thresholds, symbols, or risk limits. It should isolate environment-specific and sensitive values from scanning/execution logic. The repository does not expose a dedicated secrets manager, database, or deployment manifest.
- Configuration component: `src/config.py`
- Ignore policy likely protects local artifacts/secrets: `.gitignore`

#### Market Discovery / Opportunity Scanning
`src/scanner.py` is the market-data and strategy-detection stage. It is the natural boundary for obtaining quotes/order-book information from exchanges or chain/DEX providers, normalizing prices, and emitting candidate arbitrage opportunities. Its inputs should come from configured external APIs; its outputs should be strategy-neutral opportunity records consumed by execution.
- Scanner stage: `src/scanner.py`
- Scanner configuration source: `src/config.py`

#### Trade Execution and External Integrations
`src/executor.py` is the order-routing stage. It should translate validated scanner opportunities into exchange or on-chain trade actions, handle side/order sequencing, and report execution results or failures. This is the highest-risk boundary because it interacts with trading-enabled exchange API keys and potentially wallet/signing infrastructure. The README names Binance, OKX, Bybit, STON.fi, Raydium, and Jupiter, but no provider-specific integration files are visible.
- Execution stage: `src/executor.py`
- Shared configuration: `src/config.py`

#### Primary Control Flow
The intended control loop is:
1. Load runtime settings and credentials from `src/config.py`.
2. `src/scanner.py` polls or subscribes to market data and calculates spreads.
3. Scanner emits an executable candidate when profitability/risk criteria are met.
4. `src/executor.py` submits and monitors the required orders/transactions.
5. Results feed operational logging or subsequent scan decisions; no persistent storage, queue, dashboard, or telemetry component is visible in this repository.

#### Infrastructure and Operational Boundaries
The documented deployment target is a local machine or VPS running Python, with network access to exchange APIs and blockchain/DEX infrastructure. GitHub Actions CI exists at `.github/workflows/ci.yml`, but no Docker, cloud infrastructure, database, message broker, or monitoring stack is represented. The implementation should therefore treat external exchange/network APIs as unreliable boundaries and keep credential handling, rate limiting, idempotency, and execution safety concentrated around `src/config.py` and `src/executor.py`.

Main entry points: [`src/executor.py`](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/executor.py) (Trade executor), [`src/__init__.py`](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/__init__.py) (Package boundary), [`src/config.py`](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/config.py) (Runtime configuration), [`src/scanner.py`](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/scanner.py) (Market scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Python Runtime"]
  node_package["Package boundary<br/>Python package<br/>[__init__.py]"]
  node_config["Runtime configuration<br/>settings and credentials<br/>[config.py]"]
  node_scanner["Market scanner<br/>opportunity detection<br/>[scanner.py]"]
  node_executor["Trade executor<br/>order routing<br/>[executor.py]"]
  node_dependencies["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
end

subgraph group_external["External Boundaries"]
  node_providers{{"Market and trading APIs"}}
  node_credentials{{"Trading credentials"}}
end

subgraph group_automation["Automation"]
  node_ci["GitHub Actions CI<br/>validation workflow<br/>[ci.yml]"]
end

node_ignore["Ignore policy<br/>repository policy<br/>[.gitignore]"]

node_dependencies -->|"installs runtime libraries"| node_package
node_package -->|"loads"| node_config
node_package -->|"hosts"| node_scanner
node_package -->|"hosts"| node_executor
node_config -->|"supplies scan settings"| node_scanner
node_config -->|"supplies limits and endpoints"| node_executor
node_credentials -.->|"configured as sensitive values"| node_config
node_providers -->|"market data"| node_scanner
node_scanner -->|"executable opportunity"| node_executor
node_executor -->|"orders / transactions"| node_providers
node_executor -->|"uses trading authority"| node_credentials
node_executor -.->|"execution outcomes"| node_scanner
node_ignore -.->|"protects local values"| node_config
node_ci -->|"validates"| node_package

click node_package "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/__init__.py"
click node_config "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/config.py"
click node_scanner "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/scanner.py"
click node_executor "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/executor.py"
click node_dependencies "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/requirements.txt"
click node_ignore "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/.gitignore"
click node_ci "https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/.github/workflows/ci.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_package,node_config,node_scanner,node_executor,node_dependencies toneBlue
class node_providers,node_credentials toneAmber
class node_ci toneMint
class node_ignore toneNeutral
```

## Components

### Python Runtime

Imported or externally invoked; no launcher is present.

- [Package boundary](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/__init__.py): Python package · `src/__init__.py`
- [Runtime configuration](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/config.py): settings and credentials · Isolates exchange endpoints, credentials, thresholds, and risk limits. · `src/config.py`
- [Market scanner](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/scanner.py): opportunity detection · Normalizes market data and emits candidate arbitrage opportunities. · `src/scanner.py`
- [Trade executor](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/src/executor.py): order routing · Submits and monitors trading actions for validated opportunities. · `src/executor.py`
- [Python dependencies](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/requirements.txt): dependency manifest · `requirements.txt`

### External Boundaries

Unreliable market, exchange, and chain providers.

- **Market and trading APIs**: exchange / DEX / chain APIs · Provides quotes and accepts orders or transactions.
- **Trading credentials**: API keys / wallet signing · Sensitive authority used at the execution boundary.

### Automation

- [GitHub Actions CI](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/.github/workflows/ci.yml): validation workflow · `.github/workflows/ci.yml`

### Other components

- [Ignore policy](https://github.com/cortex-ai-quant/crypto-arbitrage-bot-automated-trading/blob/main/.gitignore): repository policy · Likely excludes local artifacts and secrets. · `.gitignore`

## Connections

- Python dependencies → Package boundary: installs runtime libraries
- Package boundary → Runtime configuration: loads
- Package boundary → Market scanner: hosts
- Package boundary → Trade executor: hosts
- Runtime configuration → Market scanner: supplies scan settings
- Runtime configuration → Trade executor: supplies limits and endpoints
- Trading credentials → Runtime configuration: configured as sensitive values
- Market and trading APIs → Market scanner: market data
- Market scanner → Trade executor: executable opportunity
- Trade executor → Market and trading APIs: orders / transactions
- Trade executor → Trading credentials: uses trading authority
- Trade executor → Market scanner: execution outcomes
- Ignore policy → Runtime configuration: protects local values
- GitHub Actions CI → Package boundary: validates