# gendevelopment/dkgcopytrade architecture

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

- Interactive diagram: https://gitdiagram.com/gendevelopment/dkgcopytrade
- Repository: https://github.com/gendevelopment/dkgcopytrade

## Overview

This repository appears to implement a Polymarket copy-trading system, with the core trading logic in Python and a thin PHP/browser layer for access, status, and scheduled operations.

1. **Core responsibility**
   - The project is centered on monitoring Polymarket activity, mirroring or reacting to trades, and keeping track of positions and outcomes.
   - The codebase suggests a mix of live automation, reporting, and post-trade settlement.

2. **External market integration**
   - `polymarket_api.py` and `polymarket_clob.py` are the main integration points to Polymarket.
   - One likely handles higher-level API calls and the other the CLOB/trading interface, which is the execution boundary for placing or managing orders.

3. **Tracking / signal ingestion**
   - `tracker.py` is probably the main watcher that detects relevant trader or market events and turns them into actionable signals.
   - `tracker_web3.py` suggests an alternate or complementary event source using Web3/on-chain data rather than only the standard API layer.

4. **Trade execution and orchestration**
   - `main.py` is likely the primary runtime entrypoint that wires the tracker, API clients, database, and execution logic together.
   - `manual_resolve.py` and `redeem.py` indicate separate operational paths for resolving markets or claiming settled value after outcomes are known.

5. **Persistence and configuration**
   - `database.py` is the persistence boundary for storing tracked data, trade state, and computed results.
   - `config.py` holds environment- or deployment-specific settings, likely including API credentials, account identifiers, and runtime options.
   - `setup_key.py` suggests a one-time or admin flow for initializing signing keys or secret material.

6. **Analytics subsystem**
   - `analytics.py` is the computation/reporting layer for performance metrics, trade summaries, or strategy analysis.
   - `analytics.html` is the corresponding static UI surface for viewing those results.

7. **Operational dashboard**
   - `dashboard.py` appears to serve a runtime dashboard or backend for operational visibility.
   - `dashboard_static.html` is the browser-facing presentation layer for that dashboard, likely fed by data from Python or PHP endpoints.

8. **PHP web/auth boundary**
   - `api.php` and `auth.php` provide a separate web/API layer, likely for browser access, session handling, or authenticated control actions.
   - This implies the system is split between Python for trading/analytics and PHP for lightweight web serving or integration with existing hosting.

9. **Scheduling / watchdog**
   - `watchdog_cron.php` is a cron-oriented health or maintenance hook.
   - It likely monitors process liveness, triggers periodic tasks, or ensures the trading system stays operational.

10. **Testing**
   - `test_clob.py` is a focused test module for the trading/exchange integration, which is the most critical and failure-prone boundary in the system.

11. **Main data flow**
   - External Polymarket data comes in through the API/Web3 trackers.
   - Python components normalize and persist state in the database.
   - Trading actions are executed through the CLOB client.
   - Analytics and dashboard code read from persisted state and expose results through HTML/PHP entrypoints.

12. **Architecture boundary summary**
   - The clearest boundary is: **Python = trading engine, tracking, analytics, persistence**, while **PHP/HTML = operator-facing web access and scheduled web-side automation**.
   - For an architecture diagram, the key nodes are the Polymarket integrations, the tracker/execution pipeline, the database, and the two UI layers (dashboard/analytics plus auth/API).

Main entry points: [`main.py`](https://github.com/gendevelopment/dkgcopytrade/blob/main/main.py) (Main runtime), [`database.py`](https://github.com/gendevelopment/dkgcopytrade/blob/main/database.py) (Database), [`polymarket_api.py`](https://github.com/gendevelopment/dkgcopytrade/blob/main/polymarket_api.py) (API client), [`polymarket_clob.py`](https://github.com/gendevelopment/dkgcopytrade/blob/main/polymarket_clob.py) (CLOB client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_core["Python core"]
  node_main["Main runtime<br/>orchestrator<br/>[main.py]"]
  node_tracker["Tracker<br/>signal watcher<br/>[tracker.py]"]
  node_tracker_web3["Web3 tracker<br/>chain watcher<br/>[tracker_web3.py]"]
  node_database[("Database<br/>persistence<br/>[database.py]")]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_analytics["Analytics<br/>reporting<br/>[analytics.py]"]
  node_manual_resolve["Resolve ops<br/>market ops<br/>[manual_resolve.py]"]
  node_redeem["Redeem ops<br/>settlement<br/>[redeem.py]"]
  node_setup_key["Key setup<br/>bootstrap<br/>[setup_key.py]"]
  node_test_clob["CLOB test<br/>[test_clob.py]"]
end

subgraph group_web_ops["Web ops"]
  node_dashboard["Dashboard<br/>runtime ui<br/>[dashboard.py]"]
  node_dashboard_static["Dashboard UI<br/>static ui"]
  node_analytics_ui["Analytics UI<br/>static ui<br/>[analytics.html]"]
  node_api_php["API layer<br/>php endpoint<br/>[api.php]"]
  node_auth_php["Auth layer<br/>php auth<br/>[auth.php]"]
  node_watchdog["Watchdog<br/>cron job<br/>[watchdog_cron.php]"]
end

subgraph group_polymarket_edge["Polymarket edge"]
  node_polymarket_api["API client<br/>market api<br/>[polymarket_api.py]"]
  node_polymarket_clob["CLOB client<br/>execution client<br/>[polymarket_clob.py]"]
end

node_main -->|"starts"| node_tracker
node_main -->|"uses"| node_tracker_web3
node_main -->|"reads market data"| node_polymarket_api
node_main -->|"places trades"| node_polymarket_clob
node_main -->|"persists state"| node_database
node_tracker -->|"queries"| node_polymarket_api
node_tracker_web3 -->|"correlates"| node_polymarket_api
node_tracker -->|"writes signals"| node_database
node_tracker_web3 -->|"writes signals"| node_database
node_polymarket_api -->|"feeds execution"| node_polymarket_clob
node_polymarket_clob -->|"records fills"| node_database
node_analytics -->|"reads history"| node_database
node_dashboard -->|"reads status"| node_database
node_dashboard_static -->|"views"| node_dashboard
node_analytics_ui -->|"views"| node_analytics
node_api_php -->|"checks auth"| node_auth_php
node_api_php -->|"controls"| node_dashboard
node_watchdog -->|"health checks"| node_dashboard
node_manual_resolve -->|"resolves"| node_polymarket_api
node_redeem -->|"settles"| node_polymarket_clob
node_setup_key -->|"initializes"| node_config
node_test_clob -->|"validates"| node_polymarket_clob
node_config -->|"configures"| node_main

click node_main "https://github.com/gendevelopment/dkgcopytrade/blob/main/main.py"
click node_tracker "https://github.com/gendevelopment/dkgcopytrade/blob/main/tracker.py"
click node_tracker_web3 "https://github.com/gendevelopment/dkgcopytrade/blob/main/tracker_web3.py"
click node_polymarket_api "https://github.com/gendevelopment/dkgcopytrade/blob/main/polymarket_api.py"
click node_polymarket_clob "https://github.com/gendevelopment/dkgcopytrade/blob/main/polymarket_clob.py"
click node_database "https://github.com/gendevelopment/dkgcopytrade/blob/main/database.py"
click node_config "https://github.com/gendevelopment/dkgcopytrade/blob/main/config.py"
click node_analytics "https://github.com/gendevelopment/dkgcopytrade/blob/main/analytics.py"
click node_dashboard "https://github.com/gendevelopment/dkgcopytrade/blob/main/dashboard.py"
click node_dashboard_static "https://github.com/gendevelopment/dkgcopytrade/blob/main/dashboard_static.html"
click node_analytics_ui "https://github.com/gendevelopment/dkgcopytrade/blob/main/analytics.html"
click node_api_php "https://github.com/gendevelopment/dkgcopytrade/blob/main/api.php"
click node_auth_php "https://github.com/gendevelopment/dkgcopytrade/blob/main/auth.php"
click node_watchdog "https://github.com/gendevelopment/dkgcopytrade/blob/main/watchdog_cron.php"
click node_manual_resolve "https://github.com/gendevelopment/dkgcopytrade/blob/main/manual_resolve.py"
click node_redeem "https://github.com/gendevelopment/dkgcopytrade/blob/main/redeem.py"
click node_setup_key "https://github.com/gendevelopment/dkgcopytrade/blob/main/setup_key.py"
click node_test_clob "https://github.com/gendevelopment/dkgcopytrade/blob/main/test_clob.py"

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_main,node_tracker,node_tracker_web3,node_database,node_config,node_analytics,node_manual_resolve,node_redeem,node_setup_key,node_test_clob toneBlue
class node_dashboard,node_dashboard_static,node_analytics_ui,node_api_php,node_auth_php,node_watchdog toneAmber
class node_polymarket_api,node_polymarket_clob toneMint
```

## Components

### Python core

Trading engine, tracking, persistence, and analytics.

- [Main runtime](https://github.com/gendevelopment/dkgcopytrade/blob/main/main.py): orchestrator · Primary entrypoint that wires tracking, execution, and storage. · `main.py`
- [Tracker](https://github.com/gendevelopment/dkgcopytrade/blob/main/tracker.py): signal watcher · Monitors trader and market activity for copy-trading signals. · `tracker.py`
- [Web3 tracker](https://github.com/gendevelopment/dkgcopytrade/blob/main/tracker_web3.py): chain watcher · Alternate event source using Web3/on-chain data. · `tracker_web3.py`
- [Database](https://github.com/gendevelopment/dkgcopytrade/blob/main/database.py): persistence · Stores tracked state, positions, and computed results. · `database.py`
- [Config](https://github.com/gendevelopment/dkgcopytrade/blob/main/config.py): settings · Runtime configuration and environment-specific values. · `config.py`
- [Analytics](https://github.com/gendevelopment/dkgcopytrade/blob/main/analytics.py): reporting · Computes performance metrics and trade summaries. · `analytics.py`
- [Resolve ops](https://github.com/gendevelopment/dkgcopytrade/blob/main/manual_resolve.py): market ops · Manual market resolution workflow. · `manual_resolve.py`
- [Redeem ops](https://github.com/gendevelopment/dkgcopytrade/blob/main/redeem.py): settlement · Claims settled value after market outcomes are known. · `redeem.py`
- [Key setup](https://github.com/gendevelopment/dkgcopytrade/blob/main/setup_key.py): bootstrap · One-time or admin setup for signing keys and secret material. · `setup_key.py`
- [CLOB test](https://github.com/gendevelopment/dkgcopytrade/blob/main/test_clob.py): test · Focused test coverage for the trading execution boundary. · `test_clob.py`

### Web ops

PHP and HTML surfaces for operator access and scheduled web-side tasks.

- [Dashboard](https://github.com/gendevelopment/dkgcopytrade/blob/main/dashboard.py): runtime ui · Backend for operational visibility and status access. · `dashboard.py`
- [Dashboard UI](https://github.com/gendevelopment/dkgcopytrade/blob/main/dashboard_static.html): static ui · Browser-facing dashboard surface. · `dashboard_static.html`
- [Analytics UI](https://github.com/gendevelopment/dkgcopytrade/blob/main/analytics.html): static ui · Browser-facing results and reporting surface. · `analytics.html`
- [API layer](https://github.com/gendevelopment/dkgcopytrade/blob/main/api.php): php endpoint · Web/API boundary for browser access and control actions. · `api.php`
- [Auth layer](https://github.com/gendevelopment/dkgcopytrade/blob/main/auth.php): php auth · Authentication and session boundary for web access. · `auth.php`
- [Watchdog](https://github.com/gendevelopment/dkgcopytrade/blob/main/watchdog_cron.php): cron job · Periodic health and maintenance hook. · `watchdog_cron.php`

### Polymarket edge

Integration boundaries to Polymarket and execution.

- [API client](https://github.com/gendevelopment/dkgcopytrade/blob/main/polymarket_api.py): market api · Higher-level Polymarket API integration. · `polymarket_api.py`
- [CLOB client](https://github.com/gendevelopment/dkgcopytrade/blob/main/polymarket_clob.py): execution client · Trading and order execution boundary for Polymarket. · `polymarket_clob.py`

## Connections

- Main runtime → Tracker: starts · Runs the primary signal watcher.
- Main runtime → Web3 tracker: uses · Optionally consumes on-chain event signals.
- Main runtime → API client: reads market data · Fetches market and account information.
- Main runtime → CLOB client: places trades · Sends orders and execution requests.
- Main runtime → Database: persists state · Stores tracked positions and runtime state.
- Tracker → API client: queries · Looks up markets, traders, and activity.
- Web3 tracker → API client: correlates · Maps chain events to market context.
- Tracker → Database: writes signals · Stores detected opportunities and state.
- Web3 tracker → Database: writes signals · Persists web3-derived tracking data.
- API client → CLOB client: feeds execution · Provides context needed for order placement.
- CLOB client → Database: records fills · Persists execution results and position changes.
- Analytics → Database: reads history · Analyzes stored trades and outcomes.
- Dashboard → Database: reads status · Serves operational state to the UI.
- Dashboard UI → Dashboard: views · Browser UI presents dashboard data.
- Analytics UI → Analytics: views · Static report surface presents analytics output.
- API layer → Auth layer: checks auth · Uses authentication/session controls.
- API layer → Dashboard: controls · Exposes operator-facing actions and status.
- Watchdog → Dashboard: health checks · Monitors runtime availability and maintenance signals.
- Resolve ops → API client: resolves · Performs manual market resolution operations.
- Redeem ops → CLOB client: settles · Claims or finalizes settled positions.
- Key setup → Config: initializes · Bootstraps key material and configuration.
- CLOB test → CLOB client: validates · Tests the execution client boundary.
- Config → Main runtime: configures · Provides runtime settings to the orchestrator.