# flashgnash/ordis architecture

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

- Interactive diagram: https://gitdiagram.com/flashgnash/ordis
- Repository: https://github.com/flashgnash/ordis

## Overview

##### Project type and purpose
- Ordis is a single-service Discord bot written in Rust.
- It exposes slash commands, context menu actions, event handlers, and integrates with a PostgreSQL database and external APIs (OpenAI/GPT and DALL·E).

##### File structure for high-level components
- src/main.rs: entrypoint, connects to Discord gateway, registers commands.
- src/admin, src/games, src/llm, src/rpg, src/voice: command- and event-handling modules.
- src/db + migrations/: Diesel ORM layer for PostgreSQL.
- http_client.rs: wrapper for HTTP calls (used by LLM integrations).
- resources/: static files (emojis, dictionaries).

##### README for architecture hints
- Uses OpenAI tokens and DALL·E for LLM features.
- Requires database setup via Diesel.
- Maintains state (characters, spells, mana) persistently in Postgres.
- Responds to Discord events and REST calls.

##### Main components
a. Discord Platform
- Gateway (WebSocket) for real-time events.
- REST API for slash commands.
b. Ordis Bot Service (Rust)
- Command Router / Event Loop (main.rs).
- Module Layer:
- Admin Module (auto_react, auto_threads, nickname, colour_picker)
- Games Module (Wordle, Russian Roulette)
- LLM Module (content_filter, translator, reply_handler)
- RPG Module (Mir event handlers, stat block, spells)
- Voice Module (music streaming)
- Database Layer (db.rs + db/{characters, users, models, schema}.rs)
- HTTP Client (http_client.rs)
- Shared Utilities (base.rs, common.rs, dictionary.rs, dice.rs)
- Static Resources Loader (resources/dictionary_*.txt, resources/emojis)
c. PostgreSQL Database
- Tables: users, characters, stat_blocks, spells, messages references.
- Handled via Diesel (diesel.toml, migrations/).
d. External APIs
- OpenAI API (chat completion for parsing, image generation).
- Discord REST for images, embeds.

##### Relationships and interactions
- Discord Gateway → Bot Service (receives events: slash command invoked, message reactions)
- Bot Service → Discord REST (register commands, send replies, context menu actions)
- Bot Service → PostgreSQL (read/write user, character, mana, spell data)
- Bot Service reads from local resources (dictionaries and emojis) for spell checks, emoji responses.

##### Architectural patterns and principles
- Modular decomposition: each feature (admin, games, llm, rpg, voice) isolated under src/
- Layered design: CLI/Event Loop → Modules → Data Access → Persistence
- Single process / monolith service, externalizing state to DB and 3rd-party APIs
- Use of Diesel migrations for schema evolution

##### Technologies, frameworks, and libraries
- Rust language, Cargo/Nix for build
- Serenity or Twilight (implied) for Discord integration
- Diesel ORM for PostgreSQL
- tokio (async runtime)
- reqwest or similar via http_client.rs
- OpenAI REST API (GPT models, DALL·E)
- Nix/flakes for reproducible dev environment

##### Essential elements
- Notes on runtime (async/tokio), build (Cargo/Nix), and persistence (Diesel).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DiscordGateway["Discord Gateway\n(WebSocket)"]:::external
    DiscordREST["Discord REST API"]:::external
    OpenAIApi["OpenAI API\n(chat & DALL·E)"]:::external
    DB["PostgreSQL Database"]:::db

    %% Ordis Bot Service
    subgraph "Ordis Bot Service"
        Main["Command Router / Event Loop\n(src/main.rs)"]:::bot
        Admin["Admin Module\n(src/admin/)"]:::bot
        Games["Games Module\n(src/games/)"]:::bot
        LLM["LLM Module\n(src/llm/)"]:::bot
        RPG["RPG Module\n(src/rpg/)"]:::bot
        Voice["Voice Module\n(src/voice/)"]:::bot
        DBLayer["Database Layer\n(src/db.rs + src/db/*, diesel.toml, migrations/)"]:::bot
        HTTPClient["HTTP Client\n(http_client.rs)"]:::bot
        Utils["Shared Utilities\n(src/base.rs, common.rs, dictionary.rs, dice.rs)"]:::bot
        StaticRes["Static Resources\n(resources/)"]:::resource
    end

    %% Data Flows
    DiscordGateway -->|"WebSocket Event"| Main
    DiscordREST -->|"REST JSON"| Main

    Main -->|"route command"| Admin
    Main -->|"route command"| Games
    Main -->|"route command"| LLM
    Main -->|"route command"| RPG
    Main -->|"route command"| Voice

    Admin -->|"SQL Query"| DBLayer
    Games -->|"SQL Query"| DBLayer
    LLM -->|"SQL Query"| DBLayer
    RPG -->|"SQL Query"| DBLayer
    Voice -->|"SQL Query"| DBLayer

    Admin -->|"HTTP Request"| HTTPClient
    Games -->|"HTTP Request"| HTTPClient
    LLM -->|"HTTP Request"| HTTPClient
    RPG -->|"HTTP Request"| HTTPClient
    Voice -->|"HTTP Request"| HTTPClient

    HTTPClient -->|"HTTP POST JSON"| OpenAIApi
    DBLayer -->|"SQL Query"| DB

    Main -->|"load files"| StaticRes
    Admin -->|"use utils"| Utils
    Games -->|"use utils"| Utils
    LLM -->|"use utils"| Utils
    RPG -->|"use utils"| Utils
    Voice -->|"use utils"| Utils

    Admin -->|"send reply"| DiscordREST
    Games -->|"send reply"| DiscordREST
    LLM -->|"send reply"| DiscordREST
    RPG -->|"send reply"| DiscordREST
    Voice -->|"send reply"| DiscordREST

    %% Click Events
    click Main "https://github.com/flashgnash/ordis/blob/master/src/main.rs"
    click Admin "https://github.com/flashgnash/ordis/tree/master/src/admin/"
    click Games "https://github.com/flashgnash/ordis/tree/master/src/games/"
    click LLM "https://github.com/flashgnash/ordis/tree/master/src/llm/"
    click RPG "https://github.com/flashgnash/ordis/tree/master/src/rpg/"
    click Voice "https://github.com/flashgnash/ordis/tree/master/src/voice/"
    click DBLayer "https://github.com/flashgnash/ordis/blob/master/src/db.rs"
    click HTTPClient "https://github.com/flashgnash/ordis/blob/master/http_client.rs"
    click Utils "https://github.com/flashgnash/ordis/blob/master/src/base.rs"
    click StaticRes "https://github.com/flashgnash/ordis/tree/master/resources/"

    %% Legend
    subgraph Legend
        E["External Services"]:::external
        B["Bot Service Components"]:::bot
        D["Database"]:::db
        R["Static Resources"]:::resource
    end

    %% Styles
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef bot fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#FFA500,stroke:#333,stroke-width:1px
    classDef resource fill:#98FB98,stroke:#333,stroke-width:1px
```
