# uheej0625/discordmate architecture

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

- Interactive diagram: https://gitdiagram.com/uheej0625/discordmate
- Repository: https://github.com/uheej0625/discordmate

## Overview

##### Project Type and Purpose
- DiscordMate is a conversational AI Discord bot.
- It listens to Discord gateway events, processes messages via an AI provider (Gemini), persists conversation history in a database, and replies back on Discord.

##### High-Level Components
A. Discord Gateway Integration
– Listens to events (messageCreate, interactionCreate, clientReady)
– Located in src/discord/{discord.js, events/*}
B. Event Handling Layer
– Routes raw Discord events into the business logic
– src/handler/messageHandler.js
C. Business Logic / Service Layer
– ChattingService: Orchestrates conversation flow
– AIService: Wraps prompt building and provider calls
– LogService: Optional logging/tracing
– src/services/*
D. AI Module
– Prompt building (src/ai/builders/promptBuilder.js)
– Prompt definitions (src/ai/prompts/*)
– Providers (src/ai/providers/gemini.js)
E. Persistence Layer
– Repositories (messageRepository, userRepository, modelRepository in src/repositories)
– Database connection and schemas (src/database)
F. Configuration
– Environment and JSON configs (src/config, config.json, .env.template)
G. Utility Functions
– Common helpers (delay, ISO conversion, JSON utils in src/utils)
H. Legacy Code (optional)
– Earlier versions in /legacy – can be omitted or shown as “archived”

##### Relationships and Data Flow
1. Discord Gateway → Event Handlers
- Discord API pushes “messageCreate” / “interactionCreate” events.
2. Event Handlers → MessageHandler
- Handlers extract payload and invoke the messageHandler.
3. MessageHandler → Services
- ChattingService.receiveMessage(...)
4. ChattingService → Repositories
- + userRepository.findOrCreate()
- + messageRepository.create()
- + modelRepository.lookup()
5. ChattingService → AIService
- AIService.buildPrompt(...) via promptBuilder → sends to Gemini provider
6. AI Provider → AIService → ChattingService
- Gemini returns a response
7. ChattingService → Repositories
- Save AI response via messageRepository
8. ChattingService → Discord Gateway
- Sends reply through discord.js client
9. Logging / Config
- All layers read from src/config and optionally log via LogService

##### Architectural Patterns & Design Principles
- Event-Driven: Discord events trigger flows.
- Layered Architecture:
– Transport (Discord Gateway)
– Handler Layer
– Service Layer
– Data Access Layer (Repositories)
- Separation of Concerns: AI logic is isolated from database logic.
- Repository Pattern for database interactions.
- Configuration Centralization: All credentials/config in /config and .env.

##### Must-Include Elements
- Clear labels (e.g., “Discord Gateway (discord.js client)”)
– Integration points, Services, Data stores, Utilities

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        DiscordClient["Discord Gateway\n(discord.js client)"]:::integration
        MessageEvent["messageCreate\nevent"]:::integration
        InteractionEvent["interactionCreate\nevent"]:::integration
        ReadyEvent["clientReady\nevent"]:::integration
    end

    %% Handler Layer
    subgraph "Handler Layer"
        direction TB
        MessageHandler["MessageHandler\n(src/handler/messageHandler.js)"]:::service
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ChattingService["ChattingService\n(src/services/chattingService.js)"]:::service
        AIService["AIService\n(src/services/aiService.js)"]:::service
        LogService["LogService\n(src/services/logService.js)"]:::service
    end

    %% AI Module
    subgraph "AI Module"
        direction TB
        AIModule["AI Core\n(src/ai/ai.js)"]:::ai
        PromptBuilder["promptBuilder\n(src/ai/builders/promptBuilder.js)"]:::ai
        PromptDefsSystem["Prompts System\n(src/ai/prompts/system/)"]:::ai
        PromptDefsUser["Prompts User\n(src/ai/prompts/user/)"]:::ai
        GeminiProvider["Gemini Provider\n(src/ai/providers/gemini.js)"]:::ai
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DBConn["Database Connection\n(src/database/database.js)"]:::storage
        Schemas["Schemas\n(src/database/schemas/)"]:::storage
        Repositories["Repositories\n(src/repositories/)"]:::storage
        MongoDB["MongoDB\n(External)"]:::external
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        direction TB
        ConfigIndex["Config\n(src/config/index.js,\nconfig.json,\n.env.template)"]:::config
        DiscordConfig["discord.js config\n(src/config/discord.js)"]:::config
        GeminiConfig["gemini config\n(src/config/gemini.js)"]:::config
        UtilsConvert["convertToISO\n(src/utils/convertToISO.js)"]:::config
        UtilsJSON["json utils\n(src/utils/json.js)"]:::config
        UtilsDelay["messageDelay\n(src/utils/messageDelay.js)"]:::config
    end

    %% Legacy Code
    subgraph "Legacy Code (Archived)" 
        direction TB
        Legacy["/legacy"]:::legacy
    end

    %% External API
    GeminiAPI["Gemini AI API"]:::external

    %% Flow Connections
    DiscordClient -->|on messageCreate| MessageHandler
    DiscordClient -->|on interactionCreate| MessageHandler
    DiscordClient -->|on clientReady| MessageHandler

    MessageHandler -->|calls| ChattingService
    ChattingService -->|reads/writes| Repositories
    ChattingService -->|use| AIService
    ChattingService -->|logs via| LogService
    ChattingService -->|replies through| DiscordClient

    AIService -->|buildPrompt| PromptBuilder
    PromptBuilder -->|uses| PromptDefsSystem
    PromptBuilder -->|uses| PromptDefsUser
    AIService -->|invoke| GeminiProvider
    GeminiProvider -->|calls| GeminiAPI
    GeminiAPI -->|response| GeminiProvider
    GeminiProvider -->|returns response| AIService

    Repositories -->|access| DBConn
    DBConn -->|manage| Schemas
    Schemas -->|persist in| MongoDB

    %% Config & Utils References
    MessageHandler -- reads --> ConfigIndex
    ChattingService -- reads --> ConfigIndex
    AIService -- reads --> GeminiConfig
    DiscordClient -- reads --> DiscordConfig
    allUtils[All Utilities]:::config
    UtilsConvert --> allUtils
    UtilsJSON --> allUtils
    UtilsDelay --> allUtils

    %% Click Events
    click DiscordClient "https://github.com/uheej0625/discordmate/blob/main/src/discord/discord.js"
    click MessageEvent "https://github.com/uheej0625/discordmate/blob/main/src/discord/events/messageCreate.js"
    click InteractionEvent "https://github.com/uheej0625/discordmate/blob/main/src/discord/events/interactionCreate.js"
    click ReadyEvent "https://github.com/uheej0625/discordmate/blob/main/src/discord/events/clientReady.js"
    click MessageHandler "https://github.com/uheej0625/discordmate/blob/main/src/handler/messageHandler.js"
    click ChattingService "https://github.com/uheej0625/discordmate/blob/main/src/services/chattingService.js"
    click AIService "https://github.com/uheej0625/discordmate/blob/main/src/services/aiService.js"
    click LogService "https://github.com/uheej0625/discordmate/blob/main/src/services/logService.js"
    click AIModule "https://github.com/uheej0625/discordmate/blob/main/src/ai/ai.js"
    click PromptBuilder "https://github.com/uheej0625/discordmate/blob/main/src/ai/builders/promptBuilder.js"
    click PromptDefsSystem "https://github.com/uheej0625/discordmate/tree/main/src/ai/prompts/system/"
    click PromptDefsUser "https://github.com/uheej0625/discordmate/tree/main/src/ai/prompts/user/"
    click GeminiProvider "https://github.com/uheej0625/discordmate/blob/main/src/ai/providers/gemini.js"
    click DBConn "https://github.com/uheej0625/discordmate/blob/main/src/database/database.js"
    click Schemas "https://github.com/uheej0625/discordmate/blob/main/src/database/schemas/index.js"
    click Repositories "https://github.com/uheej0625/discordmate/blob/main/src/repositories/messageRepository.js"
    click Repositories "https://github.com/uheej0625/discordmate/blob/main/src/repositories/userRepository.js"
    click Repositories "https://github.com/uheej0625/discordmate/blob/main/src/repositories/modelRepository.js"
    click ConfigIndex "https://github.com/uheej0625/discordmate/blob/main/src/config/index.js"
    click DiscordConfig "https://github.com/uheej0625/discordmate/blob/main/src/config/discord.js"
    click GeminiConfig "https://github.com/uheej0625/discordmate/blob/main/src/config/gemini.js"
    click UtilsConvert "https://github.com/uheej0625/discordmate/blob/main/src/utils/convertToISO.js"
    click UtilsJSON "https://github.com/uheej0625/discordmate/blob/main/src/utils/json.js"
    click UtilsDelay "https://github.com/uheej0625/discordmate/blob/main/src/utils/messageDelay.js"
    click Legacy "https://github.com/uheej0625/discordmate/tree/main/legacy/"

    %% Styles
    classDef integration fill:#cee7ff,stroke:#0366d6
    classDef service fill:#e6ffed,stroke:#28a745
    classDef ai fill:#fff5e6,stroke:#d37d00
    classDef storage fill:#ffe8e8,stroke:#d73a49
    classDef config fill:#f0f0f0,stroke:#999
    classDef external fill:#f5f5f5,stroke:#666
    classDef legacy fill:#f7f7f7,stroke:#aaa,stroke-dasharray: 5 5
```
