# gschurck/tradoge architecture

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

- Interactive diagram: https://gitdiagram.com/gschurck/tradoge
- Repository: https://github.com/gschurck/tradoge

## Overview

#### Purpose and Runtime

TraDOGE is a Go-based automated Binance isolated-margin trading bot. It polls Elon Musk’s Twitter/X posts for configured DOGE keywords, buys DOGE using available leveraged quote-currency balance, then sells after a configured delay. Its executable entry point is `tradoge.go`; normal deployment is containerized through `Dockerfile` and `docker-compose.yml`.

#### Bootstrap and Configuration

Startup loads operator-supplied credentials and trading settings from YAML, based on the checked-in template. Configuration is the central boundary for Twitter authentication, Binance API access, quote currencies/pairs, keywords, polling interval, leverage-dependent buying behavior, and sell timing.

- `tradoge.go`
- `internal/config/config_loading.go`
- `config/config.example.yaml`

Persistent/runtime data is expected under `data/`, mounted or retained by the container deployment rather than committed.

#### Application Orchestration

The main process composes configuration, logging, Twitter monitoring, trading, heartbeat, and server-facing functionality. Shared domain structures provide the contract between tweet detection and order execution rather than exposing provider-specific objects across the application.

- `tradoge.go`
- `internal/types/types.go`
- `internal/logger/logger.go`

#### Twitter/X Detection Stage

The Twitter integration authenticates and searches/polls posts from Elon Musk using configured DOGE-related terms. A qualifying new tweet is the primary event that initiates trading. The README’s query behavior excludes replies; detection should be treated as an external-service boundary subject to credentials, API availability, and polling latency.

- `internal/twitter/twitter.go`
- `internal/types/types.go`

#### Trading Decision and Execution

The trading layer consumes detection events and applies the configured trading-pair and timing policy. Binance margin execution is isolated behind a Binance-specific implementation: it determines usable isolated-margin funds, places DOGE purchase orders, and later performs the sell action. This boundary carries the financial side effects and depends on Binance margin permissions, account balances, and leverage configured at Binance.

- `internal/trading/trading.go`
- `internal/trading/binance_margin.go`
- `internal/types/types.go`

#### Service/Operational Interfaces

A lightweight server component and heartbeat subsystem provide operational process functionality alongside the bot loop; their exact external surface is implemented internally. Logging is the primary observed status channel in Docker usage. CI builds/tests the Go project through GitHub Actions.

- `internal/server/server.go`
- `internal/heartbeat/heartbeat.go`
- `.github/workflows/ci.yml`

#### Infrastructure and External Dependencies

The production runtime is Docker Compose, with configuration and data supplied from host directories. Material external services are Twitter/X for tweet retrieval and Binance for authenticated isolated-margin trading. The host must provide Docker; users must provision Twitter credentials and Binance API keys with margin-trading access.

- `docker-compose.yml`
- `Dockerfile`
- `config/config.example.yaml`

Main entry points: [`tradoge.go`](https://github.com/gschurck/tradoge/blob/main/tradoge.go) (TraDOGE process), [`docker-compose.yml`](https://github.com/gschurck/tradoge/blob/main/docker-compose.yml) (Docker Compose), [`internal/twitter/twitter.go`](https://github.com/gschurck/tradoge/blob/main/internal/twitter/twitter.go) (Twitter monitor), [`internal/trading/trading.go`](https://github.com/gschurck/tradoge/blob/main/internal/trading/trading.go) (Trading policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_entrypoint{{"TraDOGE process<br/>Go entrypoint<br/>[tradoge.go]"}}
  node_config_loader["Configuration loader<br/>YAML config<br/>[config_loading.go]"]
  node_domain_types["Shared domain types<br/>domain contract<br/>[types.go]"]
  node_twitter_monitor["Twitter monitor<br/>polling adapter<br/>[twitter.go]"]
  node_trading_service["Trading policy<br/>trade orchestrator<br/>[trading.go]"]
  node_binance_margin["Binance margin adapter<br/>exchange adapter<br/>[binance_margin.go]"]
  node_heartbeat["Heartbeat<br/>operational subsystem<br/>[heartbeat.go]"]
  node_server["Server<br/>operational interface<br/>[server.go]"]
  node_logger["Logging<br/>status output<br/>[logger.go]"]
end

subgraph group_integrations["External Services"]
  node_twitter_api(("Twitter/X API<br/>external API"))
  node_binance_api(("Binance isolated margin<br/>external exchange"))
end

subgraph group_deployment["Deployment &amp; CI"]
  node_config_template["Config template<br/>YAML template"]
  node_compose["Docker Compose<br/>container runtime<br/>[docker-compose.yml]"]
  node_dockerfile["Container image<br/>Docker build"]
  node_runtime_data[("Runtime data<br/>persistent data")]
  node_ci["GitHub Actions CI<br/>CI pipeline<br/>[ci.yml]"]
end

node_config_template -.->|"defines settings"| node_config_loader
node_config_loader -->|"loads at startup"| node_entrypoint
node_entrypoint -->|"starts polling"| node_twitter_monitor
node_entrypoint -->|"starts trading flow"| node_trading_service
node_entrypoint -->|"starts"| node_heartbeat
node_entrypoint -->|"starts"| node_server
node_entrypoint -->|"emits status"| node_logger
node_twitter_monitor -->|"searches posts"| node_twitter_api
node_twitter_monitor -->|"produces detections"| node_domain_types
node_domain_types -->|"qualifying tweet"| node_trading_service
node_trading_service -->|"buy then delayed sell"| node_binance_margin
node_binance_margin -->|"places margin orders"| node_binance_api
node_compose -->|"builds image"| node_dockerfile
node_compose -->|"runs container"| node_entrypoint
node_compose -.->|"mounts configuration"| node_config_template
node_compose -->|"retains data"| node_runtime_data
node_ci -->|"builds and tests"| node_entrypoint

click node_entrypoint "https://github.com/gschurck/tradoge/blob/main/tradoge.go"
click node_config_loader "https://github.com/gschurck/tradoge/blob/main/internal/config/config_loading.go"
click node_config_template "https://github.com/gschurck/tradoge/blob/main/config/config.example.yaml"
click node_domain_types "https://github.com/gschurck/tradoge/blob/main/internal/types/types.go"
click node_twitter_monitor "https://github.com/gschurck/tradoge/blob/main/internal/twitter/twitter.go"
click node_trading_service "https://github.com/gschurck/tradoge/blob/main/internal/trading/trading.go"
click node_binance_margin "https://github.com/gschurck/tradoge/blob/main/internal/trading/binance_margin.go"
click node_heartbeat "https://github.com/gschurck/tradoge/blob/main/internal/heartbeat/heartbeat.go"
click node_server "https://github.com/gschurck/tradoge/blob/main/internal/server/server.go"
click node_logger "https://github.com/gschurck/tradoge/blob/main/internal/logger/logger.go"
click node_compose "https://github.com/gschurck/tradoge/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/gschurck/tradoge/blob/main/Dockerfile"
click node_ci "https://github.com/gschurck/tradoge/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_entrypoint,node_config_loader,node_domain_types,node_twitter_monitor,node_trading_service,node_binance_margin,node_heartbeat,node_server,node_logger toneBlue
class node_twitter_api,node_binance_api toneAmber
class node_config_template,node_compose,node_dockerfile,node_runtime_data,node_ci toneMint
```

## Components

### Bot Runtime

- [TraDOGE process](https://github.com/gschurck/tradoge/blob/main/tradoge.go): Go entrypoint · Composes and runs the bot subsystems. · `tradoge.go`
- [Configuration loader](https://github.com/gschurck/tradoge/blob/main/internal/config/config_loading.go): YAML config · Loads credentials and trading policy. · `internal/config/config_loading.go`
- [Shared domain types](https://github.com/gschurck/tradoge/blob/main/internal/types/types.go): domain contract · Carries detection and trading data between subsystems. · `internal/types/types.go`
- [Twitter monitor](https://github.com/gschurck/tradoge/blob/main/internal/twitter/twitter.go): polling adapter · Polls Elon Musk posts for configured DOGE keywords. · `internal/twitter/twitter.go`
- [Trading policy](https://github.com/gschurck/tradoge/blob/main/internal/trading/trading.go): trade orchestrator · Applies pair, buy, and delayed-sell policy to detections. · `internal/trading/trading.go`
- [Binance margin adapter](https://github.com/gschurck/tradoge/blob/main/internal/trading/binance_margin.go): exchange adapter · Uses isolated-margin funds and places buy and sell orders. · `internal/trading/binance_margin.go`
- [Heartbeat](https://github.com/gschurck/tradoge/blob/main/internal/heartbeat/heartbeat.go): operational subsystem · `internal/heartbeat/heartbeat.go`
- [Server](https://github.com/gschurck/tradoge/blob/main/internal/server/server.go): operational interface · `internal/server/server.go`
- [Logging](https://github.com/gschurck/tradoge/blob/main/internal/logger/logger.go): status output · Primary observed status channel in Docker usage. · `internal/logger/logger.go`

### External Services

- **Twitter/X API**: external API · Authenticated post search and retrieval.
- **Binance isolated margin**: external exchange · Requires margin permissions, balances, and API keys.

### Deployment & CI

- [Config template](https://github.com/gschurck/tradoge/blob/main/config/config.example.yaml): YAML template · Operator-supplied runtime settings. · `config/config.example.yaml`
- [Docker Compose](https://github.com/gschurck/tradoge/blob/main/docker-compose.yml): container runtime · Supplies configuration and retains mounted runtime data. · `docker-compose.yml`
- [Container image](https://github.com/gschurck/tradoge/blob/main/Dockerfile): Docker build · `Dockerfile`
- **Runtime data**: persistent data · Host-mounted or retained operational data.
- [GitHub Actions CI](https://github.com/gschurck/tradoge/blob/main/.github/workflows/ci.yml): CI pipeline · Builds and tests the Go project. · `.github/workflows/ci.yml`

## Connections

- Config template → Configuration loader: defines settings
- Configuration loader → TraDOGE process: loads at startup
- TraDOGE process → Twitter monitor: starts polling
- TraDOGE process → Trading policy: starts trading flow
- TraDOGE process → Heartbeat: starts
- TraDOGE process → Server: starts
- TraDOGE process → Logging: emits status
- Twitter monitor → Twitter/X API: searches posts
- Twitter monitor → Shared domain types: produces detections
- Shared domain types → Trading policy: qualifying tweet
- Trading policy → Binance margin adapter: buy then delayed sell
- Binance margin adapter → Binance isolated margin: places margin orders
- Docker Compose → Container image: builds image
- Docker Compose → TraDOGE process: runs container
- Docker Compose → Config template: mounts configuration
- Docker Compose → Runtime data: retains data
- GitHub Actions CI → TraDOGE process: builds and tests