# agent-thor/governance-trading-agent architecture

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

- Interactive diagram: https://gitdiagram.com/agent-thor/governance-trading-agent
- Repository: https://github.com/agent-thor/governance-trading-agent

## Overview

##### Project Type and Purpose
- This is a domain-specific, full-stack automated trading agent for cryptocurrency governance proposals.
- It ingests proposals, runs sentiment and summarization models, makes trading decisions, executes orders on an exchange, persists data in databases, exposes a REST API, and sends notifications (e.g., Slack).

##### Top-Level Component Analysis
- Entry Points
- `main.py` / `__main__.py` – CLI/daemon launcher
- `setup.py` / `install.sh` – installation and packaging
- API Layer (`api/`)
- Exposes REST endpoints (e.g., management of trades, proposals)
- Uses `api/dynamo_utils.py` for direct DynamoDB access
- Core Business Logic (`core/`)
- `trade_logic.py` – encapsulates decision‐making rules
- `delete_live_trade.py` – housekeeping of active trades
- Data Ingestion / Adapters
- `download_models.py` – initial model setup
- `examples/` – sample usage of data providers
- `database/scan_proposal.py` & `database/mongo_provider.py` – support for multiple DB backends
- `api` or `database/dynamo_utils.py` – DynamoDB adapter
- Exchange Integration (`exchange/`)
- `binance_api.py` – order placement, market data fetch
- `price_monitor.py` – live price stream & triggers
- `open_stop.py` – stop‐loss / take‐profit logic
- `coin.json` & `precision.json` – instrument metadata
- Models (`models/`)
- `sentiment.py`, `summarization.py`, `reasoning.py`
- Domain-specific price models (`bullish_price.py`, `bearish_price.py`)
- Services (`services/`)
- `slack_bot.py` – Slack notifications of decisions / errors
- Utilities (`utils/`)
- Logging, configuration loader, time formatting, HTML cleaning
- Persistence Layer (`database/`)
- MongoDB & DynamoDB providers
- Tests (`tests/`) – unit tests for data provider factory

##### Data Flow & Component Interactions
- External Inputs
- Governance proposal sources (via HTTP, Firebase, etc.)
- Market data feed (exchange API)
- Ingestion & Storage
- Data adapter reads proposals → `database/` (Mongo/Dynamo)
- Processing Pipeline
- Core logic loads proposals → runs through `models/` (summarization, sentiment)
- Decision engine (`core/trade_logic.py`) produces trade signals
- Execution
- Trade signals → `exchange/binance_api.py` to place orders
- Price monitoring & stops via `exchange/price_monitor.py` + `open_stop.py`
- Persistence & Notifications
- Store executed trade record (`utils/save_trades.py`)
- Send Slack alerts (`services/slack_bot.py`)
- External API
- Expose endpoints (`api/`) for querying trades or forcing actions

##### Architectural Patterns & Principles
- Layered Architecture:
- Presentation/API → Business Logic → Data Access → External Services
- Single Responsibility:
- Each module (e.g., `trade_logic.py`, `slack_bot.py`) has one clear role
- Adapter Pattern:
- Multiple database implementations (Mongo vs. Dynamo)
- Exchange abstraction via `binance_api.py`

a. Components
- External Sources (Governance Feed, Exchange Market Data)
- Data Adapters (inside `database/` & `api/`)
- Core Engine (sentiment & summarization models + trade_logic)
- Exchange Client (Binance API wrapper)
- Persistence (MongoDB, DynamoDB)
- Notification Service (Slack)
- REST API Layer
b. Relationships & Data Flow
- Bidirectional where appropriate (e.g., API calls, DB reads)
c. Technologies & Frameworks
- Python 3, FastAPI (if used in `api/`), Boto3 (DynamoDB), PyMongo, Ollama (for model serving)
- Docker or virtualenv (implied by `install.sh`, `requirements.txt`)
d. Important Patterns
- Adapter pattern for DB & exchange
- Pipeline pattern for data processing and ML inference

##### Diagramming Conventions
- Blue for Core/Processing
- Green for Data Stores
- Orange for External Services (Exchange, Slack)
- Grey for Setup/Install steps
- Rectangles for modules/components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Sources
    ext1["Governance Proposal Feed"]:::external
    ext2["Exchange Market Data"]:::external

    %% Setup & Launch
    subgraph "Setup & Launch"
        main["main.py"]:::setup
        cli["__main__.py"]:::setup
        setupScript["setup.py"]:::setup
        installScript["install.sh"]:::setup
    end

    %% API Layer
    subgraph "API Layer"
        apiDir["api/"]:::api
        apiDyn["dynamo_utils.py"]:::api
    end

    %% Data Ingestion & Adapters
    subgraph "Data Ingestion & Adapters"
        downloadModels["download_models.py"]:::ingestion
        examplesDir["examples/"]:::ingestion
        mongoProv["mongo_provider.py"]:::ingestion
        scanProp["scan_proposal.py"]:::ingestion
        dbDyn["dynamo_utils.py"]:::ingestion
    end

    %% Core Engine
    subgraph "Core Engine"
        tradeLogic["trade_logic.py"]:::core
        deleteLive["delete_live_trade.py"]:::core
    end

    %% Machine Learning Models
    subgraph "ML Models"
        sentiment["sentiment.py"]:::models
        summarization["summarization.py"]:::models
        reasoning["reasoning.py"]:::models
        bullish["bullish_price.py"]:::models
        bearish["bearish_price.py"]:::models
    end

    %% Exchange Integration
    subgraph "Exchange Integration"
        binance["binance_api.py"]:::exchange
        priceMon["price_monitor.py"]:::exchange
        openStop["open_stop.py"]:::exchange
        coinMeta["coin.json"]:::exchange
        precisionMeta["precision.json"]:::exchange
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        MongoDB(("MongoDB")):::persistence
        DynamoDB(("DynamoDB")):::persistence
    end

    %% Notification Service
    subgraph "Notification Service"
        slackBot["slack_bot.py"]:::services
    end

    %% Utilities
    subgraph "Utilities"
        configLoader["config_loader.py"]:::utils
        loggingUtils["logging_utils.py"]:::utils
        cleanHTML["clean_html.py"]:::utils
        formatTime["format_time.py"]:::utils
        timeUtils["time_utils.py"]:::utils
        priceUtils["price_utils.py"]:::utils
        saveTrades["save_trades.py"]:::utils
        saveError["save_error.py"]:::utils
        btcCheck["btc_check.py"]:::utils
        textVerif["text_verification.py"]:::utils
    end

    %% Tests
    subgraph "Tests"
        testFactory["test_data_provider_factory.py"]:::tests
    end

    %% Relationships
    ext1 --> downloadModels
    ext1 --> scanProp
    ext2 --> priceMon

    downloadModels --> MongoDB
    downloadModels --> DynamoDB

    scanProp --> MongoDB
    scanProp --> DynamoDB

    dbDyn --> scanProp

    mongoProv --> MongoDB

    apiDir --> apiDyn
    apiDir --> MongoDB
    apiDir --> DynamoDB
    apiDir --> tradeLogic

    tradeLogic --> binance
    tradeLogic --> priceMon
    tradeLogic --> MongoDB
    tradeLogic --> DynamoDB
    tradeLogic --> slackBot

    deleteLive --> MongoDB
    deleteLive --> DynamoDB

    priceMon --> openStop
    openStop --> binance

    binance --> MongoDB
    binance --> DynamoDB

    tradeLogic --> sentiment
    tradeLogic --> summarization
    tradeLogic --> reasoning
    tradeLogic --> bullish
    tradeLogic --> bearish

    slackBot --> ext3["Slack"]:::external

    main --> tradeLogic
    cli --> tradeLogic

    configLoader --> tradeLogic
    configLoader --> apiDir
    configLoader --> binance

    saveTrades --> MongoDB
    saveTrades --> DynamoDB

    saveError --> MongoDB
    saveError --> DynamoDB

    examplesDir --> scanProp

    testFactory --> dbDyn
    testFactory --> mongoProv

    %% Click Events
    click main "https://github.com/agent-thor/governance-trading-agent/blob/main/main.py"
    click cli "https://github.com/agent-thor/governance-trading-agent/blob/main/__main__.py"
    click setupScript "https://github.com/agent-thor/governance-trading-agent/blob/main/setup.py"
    click installScript "https://github.com/agent-thor/governance-trading-agent/blob/main/install.sh"
    click apiDir "https://github.com/agent-thor/governance-trading-agent/tree/main/api/"
    click apiDyn "https://github.com/agent-thor/governance-trading-agent/blob/main/api/dynamo_utils.py"
    click tradeLogic "https://github.com/agent-thor/governance-trading-agent/blob/main/core/trade_logic.py"
    click deleteLive "https://github.com/agent-thor/governance-trading-agent/blob/main/core/delete_live_trade.py"
    click downloadModels "https://github.com/agent-thor/governance-trading-agent/blob/main/download_models.py"
    click examplesDir "https://github.com/agent-thor/governance-trading-agent/tree/main/examples/"
    click mongoProv "https://github.com/agent-thor/governance-trading-agent/blob/main/database/mongo_provider.py"
    click scanProp "https://github.com/agent-thor/governance-trading-agent/blob/main/database/scan_proposal.py"
    click dbDyn "https://github.com/agent-thor/governance-trading-agent/blob/main/database/dynamo_utils.py"
    click binance "https://github.com/agent-thor/governance-trading-agent/blob/main/exchange/binance_api.py"
    click priceMon "https://github.com/agent-thor/governance-trading-agent/blob/main/exchange/price_monitor.py"
    click openStop "https://github.com/agent-thor/governance-trading-agent/blob/main/exchange/open_stop.py"
    click coinMeta "https://github.com/agent-thor/governance-trading-agent/blob/main/exchange/coin.json"
    click precisionMeta "https://github.com/agent-thor/governance-trading-agent/blob/main/exchange/precision.json"
    click sentiment "https://github.com/agent-thor/governance-trading-agent/blob/main/models/sentiment.py"
    click summarization "https://github.com/agent-thor/governance-trading-agent/blob/main/models/summarization.py"
    click reasoning "https://github.com/agent-thor/governance-trading-agent/blob/main/models/reasoning.py"
    click bullish "https://github.com/agent-thor/governance-trading-agent/blob/main/models/bullish_price.py"
    click bearish "https://github.com/agent-thor/governance-trading-agent/blob/main/models/bearish_price.py"
    click slackBot "https://github.com/agent-thor/governance-trading-agent/blob/main/services/slack_bot.py"
    click configLoader "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/config_loader.py"
    click loggingUtils "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/logging_utils.py"
    click cleanHTML "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/clean_html.py"
    click formatTime "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/format_time.py"
    click timeUtils "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/time_utils.py"
    click priceUtils "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/price_utils.py"
    click saveTrades "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/save_trades.py"
    click saveError "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/save_error.py"
    click btcCheck "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/btc_check.py"
    click textVerif "https://github.com/agent-thor/governance-trading-agent/blob/main/utils/text_verification.py"
    click testFactory "https://github.com/agent-thor/governance-trading-agent/blob/main/tests/test_data_provider_factory.py"

    %% Styles
    classDef setup fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef api fill:#E3D5FF,stroke:#333,stroke-width:1px
    classDef ingestion fill:#D0E0FF,stroke:#333,stroke-width:1px
    classDef core fill:#BDD7EE,stroke:#333,stroke-width:1px
    classDef models fill:#9CC3E8,stroke:#333,stroke-width:1px
    classDef exchange fill:#F9CB9C,stroke:#333,stroke-width:1px
    classDef persistence fill:#C6E0B4,stroke:#333,stroke-width:1px
    classDef services fill:#FFE699,stroke:#333,stroke-width:1px
    classDef utils fill:#E7E6E6,stroke:#333,stroke-width:1px
    classDef tests fill:#F2F2F2,stroke:#333,stroke-width:1px
    classDef external fill:#FDE9D9,stroke:#333,stroke-width:1px
```
