# lildibbb/crypto_trading architecture

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

- Interactive diagram: https://gitdiagram.com/lildibbb/crypto_trading
- Repository: https://github.com/lildibbb/crypto_trading

## Overview

##### Project type and purpose
- This is a full-stack “Crypto Trading Bot” application.
- Frontend: a React + TypeScript SPA built with Vite, TanStack Router, ShadCN UI, Recharts.
- Backend: a FastAPI service in Python, using TortoiseORM + aerich for migrations, PostgreSQL for storage, and a Binance WebSocket client for real-time market data.

##### File structure
- Top‐level directories:
- backend/ → FastAPI app, models, database layer, scripts, WebSocket client
- frontend/ → Vite‐powered React app with components, routes, API client, UI library
- Root files: .env.example (env vars), package.json + bun.lockb (frontend toolchain), README.md
- Patterns:
- Clear frontend/backend separation
- Backend organized around modules: `main.py` (app entry), `models.py` (ORM), `database.py` (connection), `binance_ws.py` (market feed), `scripts.py` (batch jobs)
- Frontend follows a component + route tree structure with `lib/api.ts` as HTTP client

##### README for additional insights
- Tech stack calls out React/Vite/TanStack Router on the front, FastAPI/TortoiseORM/PostgreSQL on the back
- Future features: candle charts (live + historical via Binance API), order management via Binance WebSocket

##### Don’t overthink—break the system into as many logical parts as needed
- Presentation (React SPA)
- API Layer (FastAPI routers)
- Services (market-data client, order manager)
- Data Access (ORM + migrations)
- Persistence (PostgreSQL)
- External (Binance REST & WS)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend (Browser)" 
        direction TB
        Browser["User's Browser<br/>React SPA"]:::frontend
        UI["UI Components"]:::frontend
        APIClient["HTTP API Client"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI Service)"
        direction TB
        API["FastAPI HTTP Router"]:::backend
        BL["Business Logic & Services"]:::backend
        WSClient["Binance WS Client"]:::backend
        Scripts["Scheduled & Utility Scripts"]:::backend
        ORM["TortoiseORM Models"]:::backend
        DBConn["Database Connection Setup"]:::backend
        Config1["pyproject.toml"]:::backend
        Config2["requirements.txt"]:::backend
    end

    %% Database
    Postgres[(PostgreSQL Database)]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        BinanceREST["Binance REST API"]:::external
        BinanceWS["Binance WebSocket API"]:::external
    end

    %% Connections
    Browser -->|"UI events"| UI
    UI -->|"calls API client"| APIClient
    APIClient -->|"REST calls (GET/POST)"| API
    API -->|"CRUD via ORM"| ORM
    ORM -->|"connects"| Postgres
    API -->|"DB connection"| DBConn
    API -->|"GET historical data"| BinanceREST
    API -->|"<--WS market data / order updates-->"| BinanceWS
    BL -->|uses| WSClient
    Scripts -->|"fetch historical"| BinanceREST
    Scripts -->|"write to DB"| Postgres

    %% Click Events Frontend
    click Browser "https://github.com/lildibbb/crypto_trading/tree/main/frontend/src"
    click UI "https://github.com/lildibbb/crypto_trading/tree/main/frontend/src/components/ui"
    click APIClient "https://github.com/lildibbb/crypto_trading/blob/main/frontend/src/lib/api.ts"
    click Browser "https://github.com/lildibbb/crypto_trading/blob/main/frontend/index.html"
    click Browser "https://github.com/lildibbb/crypto_trading/blob/main/frontend/src/main.tsx"
    click Browser "https://github.com/lildibbb/crypto_trading/blob/main/frontend/src/routes/__root.tsx"
    click Browser "https://github.com/lildibbb/crypto_trading/blob/main/frontend/src/routes/index.tsx"
    click Browser "https://github.com/lildibbb/crypto_trading/blob/main/frontend/src/routeTree.gen.ts"

    %% Click Events Backend
    click API "https://github.com/lildibbb/crypto_trading/blob/main/backend/main.py"
    click WSClient "https://github.com/lildibbb/crypto_trading/blob/main/backend/binance_ws.py"
    click Scripts "https://github.com/lildibbb/crypto_trading/blob/main/backend/scripts.py"
    click ORM "https://github.com/lildibbb/crypto_trading/blob/main/backend/models.py"
    click DBConn "https://github.com/lildibbb/crypto_trading/blob/main/backend/database.py"
    click Config1 "https://github.com/lildibbb/crypto_trading/blob/main/backend/pyproject.toml"
    click Config2 "https://github.com/lildibbb/crypto_trading/blob/main/backend/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#E8D0FF,stroke:#6f42c1,stroke-width:1px;
    classDef database fill:#FFE6A7,stroke:#b58900,stroke-width:1px;
    classDef external fill:#E2E2E2,stroke:#555555,stroke-width:1px;
```
