# zenpaiang/wos-bot architecture

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

- Interactive diagram: https://gitdiagram.com/zenpaiang/wos-bot
- Repository: https://github.com/zenpaiang/wos-bot

## Overview

##### Project type and purpose
- This is a Python-based Discord utility bot (wos-bot) for “Whiteout Survival” giftcode redemption, captcha detection (via an ONNX OCR model), and various in-game utility commands.
- It follows a modular “cogs” pattern on top of a Discord interactions library and uses JSON files for persistent storage.

##### File structure
- Top-level:
- bot.py – entry point that spins up the Discord client and loads cogs.
- config.example.json / players.example.json – sample configuration + user database.
- requirements.txt – Python dependencies (including ddddocr).
- migration_tool.py – stand-alone script to migrate v1 player data.
- commands_and_features.md – human-readable feature list.
- “cogs/” directory: each file (calculate.py, database.py, giftcode.py, settings.py) implements a distinct slash-command category.
- “lib/” directory: core shared services (api.py for external calls, cfg.py for config loading, client.py for the Discord client wrapper, funcs.py for utility functions).
- “database/” directory: JSON files storing game data (e.g., chief_charm.json, fire_crystals.json).
- players.json (runtime) – file-based store for linked Discord users.

##### Key insights from README
- Uses onnx-based OCR (~50 MB) for captcha; no GPU requirement.
- Configuration values control admin locks, auto-rename, syncing features.
- Migration tool handles data upgrade from v1.

a. Main components:
- Discord Gateway & Events (external service)
- Bot Core (bot.py + lib/client.py)
- Cog Modules (cogs/)
- OCR Service (ddddocr ONNX model)
- Persistence Layer (JSON files: players.json + database/*.json)
- Migration Tool (migration_tool.py)
b. Relationships & interactions:
1. Discord Gateway → Bot Core: incoming events (slash-commands, messages).
2. Bot Core → Cog Modules: dispatch events to relevant command handlers.
3. Cog Modules → Lib Services:
- cfg.py loads config.json
- api.py calls external game APIs if needed
- funcs.py for shared logic (e.g., parsing giftcodes)
4. OCR Service: invoked by giftcode cog to solve captchas.
5. Cog Modules → Persistence Layer: read/write players.json and game-data JSONs.
6. Migration Tool (offline) → Persistence Layer: upgrades old players.json schema.
c. Architectural patterns & design principles:
- Modular “cogs” plugin pattern for commands
- Separation of concerns: CLI / config loader / API / utility functions in lib/
- File-based lightweight persistence (no DB server)
- Single process, event-driven architecture
d. Relevant technologies & libraries:
- Python 3.x, interactions.py (Discord API wrapper)
- ddddocr (ONNX based OCR)
- JSON file handling (built-in)
- Standard Python modules (asyncio, json, os)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    DG["Discord Gateway & Events"]:::external

    %% Core Components
    BC["Bot Core"]:::core

    %% Cog Modules Group
    subgraph "Cog Modules"
        Calc["Calculate Cog"]:::cogs
        DBcog["Database Cog"]:::cogs
        Gift["Giftcode Cog"]:::cogs
        Set["Settings Cog"]:::cogs
    end

    %% Library Services
    subgraph "Lib Services"
        Cfg["Configuration Loader"]:::core
        API["External API Service"]:::core
        Func["Utility Functions"]:::core
    end

    %% OCR Service
    OCR["OCR Service (ONNX ddddocr)"]:::service

    %% Persistence Layer
    subgraph "Persistence Layer"
        Players["players.json"]:::storage
        DC1["chief_charm.json"]:::storage
        DC2["chief_gear.json"]:::storage
        DC3["fire_crystals.json"]:::storage
    end

    %% Migration Tool
    MT["Migration Tool"]:::service

    %% Documentation & Manifest
    subgraph "Documentation & Manifest"
        Doc1["commands_and_features.md"]:::storage
        Doc2["README.md"]:::storage
        Req["requirements.txt"]:::storage
    end

    %% Flow
    DG -->|"/slash-command event"| BC
    BC -->|"dispatch events"| Calc
    BC -->|"dispatch events"| DBcog
    BC -->|"dispatch events"| Gift
    BC -->|"dispatch events"| Set

    Calc -->|"load config"| Cfg
    Calc -->|"util logic"| Func

    DBcog -->|"read/write user data"| Players
    DBcog -->|"read game data"| DC1
    DBcog -->|"read game data"| DC2
    DBcog -->|"read game data"| DC3

    Gift -->|"invoke OCR inference"| OCR
    Gift -->|"load config"| Cfg
    Gift -->|"external API calls"| API
    Gift -->|"util logic"| Func
    OCR -->|"returns text"| Gift

    Set -->|"load config"| Cfg

    MT -->|"upgrade schema"| Players

    %% Click Events
    click DG "https://github.com/zenpaiang/wos-bot/blob/main/bot.py"
    click BC "https://github.com/zenpaiang/wos-bot/blob/main/lib/client.py"
    click Cfg "https://github.com/zenpaiang/wos-bot/blob/main/lib/cfg.py"
    click Cfg "https://github.com/zenpaiang/wos-bot/blob/main/config.example.json"
    click Calc "https://github.com/zenpaiang/wos-bot/blob/main/cogs/calculate.py"
    click DBcog "https://github.com/zenpaiang/wos-bot/blob/main/cogs/database.py"
    click Gift "https://github.com/zenpaiang/wos-bot/blob/main/cogs/giftcode.py"
    click Set "https://github.com/zenpaiang/wos-bot/blob/main/cogs/settings.py"
    click API "https://github.com/zenpaiang/wos-bot/blob/main/lib/api.py"
    click Func "https://github.com/zenpaiang/wos-bot/blob/main/lib/funcs.py"
    click Players "https://github.com/zenpaiang/wos-bot/blob/main/players.json"
    click DC1 "https://github.com/zenpaiang/wos-bot/blob/main/database/chief_charm.json"
    click DC2 "https://github.com/zenpaiang/wos-bot/blob/main/database/chief_gear.json"
    click DC3 "https://github.com/zenpaiang/wos-bot/blob/main/database/fire_crystals.json"
    click MT "https://github.com/zenpaiang/wos-bot/blob/main/migration_tool.py"
    click Doc1 "https://github.com/zenpaiang/wos-bot/blob/main/commands_and_features.md"
    click Doc2 "https://github.com/zenpaiang/wos-bot/blob/main/README.md"
    click Req "https://github.com/zenpaiang/wos-bot/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#F0D0FF,stroke:#333,stroke-width:1px
    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef cogs fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef service fill:#FFE0A0,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
```
