# belgrano9/discord-bot architecture

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

- Interactive diagram: https://gitdiagram.com/belgrano9/discord-bot
- Repository: https://github.com/belgrano9/discord-bot

## Overview

##### Project Type and Purpose
- This is a full-stack (bot-centric) Python application: a Discord bot that integrates with financial markets APIs to provide real-time stock/crypto data, portfolio management, alerts, reports, and trading functionality.
- Key purpose: expose commands in Discord channels, process them via “cogs,” fetch/process data via API clients, persist configurations and historical data locally, and issue background tasks (alerts, reports, live price streams).

##### File Structure
- Top-level:
- Dockerfile/docker-compose: container/deployment setup
- pyproject.toml, requirements.txt: Python packaging
- config files: `config.py`, `reports_config.json`, `stock_alerts.json`, `.env` driven
- `discord_bot/`: core application
- `webapp/`: standalone utility scripts (fee calculators)
- `tests/`: pytest tests
- Within `discord_bot/`:
- `bot.py` & `logging_setup.py`: entrypoint & logging
- `api/`: HTTP/WS clients for exchanges & financial data
- feature modules (`alerts/`, `portfolio/`, `price_tracker/`, `reports/`, `stocks/`, `trading/`): each has a Cog (Discord command groups), models, services, storage, command handlers, readmes
- `utils/`: shared helpers (embeds, validation)

##### README for Additional Insights
- Architecture overview: Discord.py core, API Clients, local file‐storage DB, scheduled tasks, WebSocket integration for live crypto prices.
- Supported exchanges: KuCoin, Bitvavo, Financial Datasets.

- For “Trading,” show sub‐components: MarketService, OrderService, ReactionHandler
- For “Portfolio,” show Calculator, PriceService, Storage
- Configuration flow:
- `.env` → `config.py` → passed into API clients at startup
- Test hooks (e.g. test handlers) if desired

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems" 
        direction TB
        DiscordAPI(("Discord API")):::external
        Exchanges(("Exchanges & Data Providers")):::external
    end

    %% Bot Core
    subgraph "Bot Core" 
        direction TB
        BotEntrypoint["Bot Entrypoint\n(bot.py)"]:::frontend
        LoggingSetup["Logging Setup\n(logging_setup.py)"]:::infra
    end

    DiscordAPI -->|gateway events| BotEntrypoint
    BotEntrypoint --> LoggingSetup

    %% Feature Cogs
    subgraph "Feature Cogs" 
        direction TB
        AlertsCog["Alerts Cog\n(cog.py)"]:::frontend
        PortfolioCog["Portfolio Cog\n(cog.py)"]:::frontend
        PriceTrackerCog["Price Tracker Cog\n(cog.py)"]:::frontend
        ReportsCog["Reports Cog\n(cog.py)"]:::frontend
        StocksCog["Stocks Cog\n(cog.py)"]:::frontend
        TradingCog["Trading Cog\n(cog.py)"]:::frontend
    end

    BotEntrypoint --> AlertsCog
    BotEntrypoint --> PortfolioCog
    BotEntrypoint --> PriceTrackerCog
    BotEntrypoint --> ReportsCog
    BotEntrypoint --> StocksCog
    BotEntrypoint --> TradingCog

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        AlertMonitor["Alert Monitor Service\n(alert_monitor.py)"]:::service
        AlertService["Alert Commands\n(alert_commands.py)\nAlert Model\n(alert_model.py)"]:::service
        PortfolioCalc["Portfolio Calculator\n(calculator.py)"]:::service
        PortfolioPrice["Portfolio Price Service\n(price_service.py)"]:::service
        PriceService["Price Tracker Service\n(price_service.py)"]:::service
        ReportGenerator["Report Generator\n(report_generator.py)"]:::service
        ReportScheduler["Reports Scheduler\n(scheduler.py)"]:::service
        FinancialService["Financial Service\n(financial_service.py)"]:::service
        StockPriceService["Stock Price Service\n(price_service.py)"]:::service
        TradingBinance["Binance Service\n(binance_service.py)"]:::service
        TradingKuCoin["KuCoin Service\n(kucoin_service.py)"]:::service
        MarketService["Market Service\n(market_service.py)"]:::service
    end

    AlertsCog --> AlertService
    PortfolioCog --> PortfolioCalc
    PortfolioCog --> PortfolioPrice
    PriceTrackerCog --> PriceService
    ReportsCog --> ReportGenerator
    StocksCog --> FinancialService
    StocksCog --> StockPriceService
    TradingCog --> TradingBinance
    TradingCog --> TradingKuCoin
    TradingCog --> MarketService

    %% API Clients
    subgraph "API Clients & Adapters" 
        direction TB
        APIBase["API Base\n(base.py)"]:::infra
        BinanceAdapter["Binance Adapter\n(binance.py)"]:::infra
        KuCoinAdapter["KuCoin Adapter\n(kucoin.py)"]:::infra
        BitvavoAdapter["Bitvavo Adapter\n(bitvavo.py)"]:::infra
        FinancialAPI["Financial API Client\n(financial.py)"]:::infra
        PricesAPI["Prices API Client\n(prices.py)"]:::infra
        WSConnector["KuCoin WS\n(binance_connector.py)"]:::infra
    end

    AlertService --> APIBase
    PortfolioPrice --> PricesAPI
    PriceService --> WSConnector
    FinancialService --> FinancialAPI
    TradingBinance --> BinanceAdapter
    TradingKuCoin --> KuCoinAdapter
    MarketService --> APIBase

    APIBase --> BinanceAdapter
    APIBase --> KuCoinAdapter
    APIBase --> BitvavoAdapter

    %% Local Persistence
    subgraph "Local Persistence" 
        direction TB
        AlertStorage["Alert Storage\n(alert_storage.py)"]:::storage
        PortfolioStorage["Portfolio Storage\n(portfolio_storage.py)"]:::storage
        TrackerStorage["Tracker Storage\n(tracker_storage.py)"]:::storage
        ReportsStorage["Reports Storage\n(storage.py)"]:::storage
        ConfigFiles["Config Files\n(reports_config.json,\nstock_alerts.json)"]:::storage
    end

    AlertMonitor --> AlertStorage
    AlertService --> AlertStorage
    PortfolioCalc --> PortfolioStorage
    PriceService --> TrackerStorage
    ReportGenerator --> ReportsStorage
    AlertService --> ConfigFiles
    ReportGenerator --> ConfigFiles

    %% Background Tasks
    subgraph "Background Tasks" 
        direction TB
        AlertScheduler["Alert Monitor\n(background)"]:::task
        ReportTask["Report Scheduler\n(background)"]:::task
        LiveTracker["Live Price Tracker\n(WebSocket)"]:::task
    end

    AlertScheduler --> AlertMonitor
    ReportTask --> ReportGenerator
    LiveTracker --> PriceService

    %% Data Flows to Discord
    AlertMonitor -->|sends message| AlertsCog
    ReportGenerator -->|sends report| ReportsCog
    PriceService -->|updates| PriceTrackerCog

    %% Click Events
    click BotEntrypoint "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/bot.py"
    click LoggingSetup "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/logging_setup.py"
    click AlertsCog "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/alerts/cog.py"
    click AlertService "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/alerts/alert_commands.py"
    click AlertService "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/alerts/alert_model.py"
    click AlertMonitor "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/alerts/alert_monitor.py"
    click AlertStorage "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/alerts/alert_storage.py"
    click PortfolioCog "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/portfolio/cog.py"
    click PortfolioCalc "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/portfolio/calculator.py"
    click PortfolioPrice "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/portfolio/price_service.py"
    click PortfolioStorage "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/portfolio/portfolio_storage.py"
    click PriceTrackerCog "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/price_tracker/cog.py"
    click PriceService "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/price_tracker/price_service.py"
    click TrackerStorage "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/price_tracker/tracker_storage.py"
    click ReportsCog "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/reports/cog.py"
    click ReportGenerator "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/reports/report_generator.py"
    click ReportScheduler "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/reports/scheduler.py"
    click ReportsStorage "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/reports/storage.py"
    click StocksCog "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/stocks/cog.py"
    click FinancialService "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/stocks/services/financial_service.py"
    click StockPriceService "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/stocks/services/price_service.py"
    click TradingCog "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/trading/cog.py"
    click TradingBinance "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/trading/services/binance_service.py"
    click TradingKuCoin "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/trading/services/kucoin_service.py"
    click MarketService "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/trading/services/market_service.py"
    click APIBase "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/base.py"
    click BinanceAdapter "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/binance.py"
    click KuCoinAdapter "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/kucoin.py"
    click BitvavoAdapter "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/bitvavo.py"
    click FinancialAPI "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/financial.py"
    click PricesAPI "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/prices.py"
    click WSConnector "https://github.com/belgrano9/discord-bot/blob/master/discord_bot/api/binance_connector.py"
    click ConfigFiles "https://github.com/belgrano9/discord-bot/blob/master/reports_config.json"
    click ConfigFiles "https://github.com/belgrano9/discord-bot/blob/master/stock_alerts.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef service fill:#DFF2D8,stroke:#4CAF50,color:#000
    classDef infra fill:#FFE5CC,stroke:#FF9800,color:#000
    classDef storage fill:#FFF3CD,stroke:#FFCA28,color:#000
    classDef external fill:#F0F0F0,stroke:#AAAAAA,color:#000,stroke-dasharray: 5 5
    classDef task fill:#E8DAEF,stroke:#9C27B0,color:#000,stroke-dasharray: 5 5
```
