# x3nooo/twinkleshine architecture

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

- Interactive diagram: https://gitdiagram.com/x3nooo/twinkleshine
- Repository: https://github.com/x3nooo/twinkleshine

## Overview

##### Main Components

a) Discord Interface Layer:
- Discord Bot component (from /discord directory)
- Command handling system (from /commands directory)

b) AI Processing Layer:
- AI core components (from /ai directory)
- RAG (Retrieval-Augmented Generation) system
- Query and memory components (based on query.go and remember.go)

c) Configuration & Environment:
- Configuration management (config.yaml)
- Environment variables (.env)

**[Discord API] <---> [Discord Bot Layer] <---> [Command Handler] <---> [AI Processing Layer]**

- [Memory System]

##### Specific Component Details

a) External Services Layer (Top):
- Discord API integration point
- Any external AI services (if applicable)

b) Application Core (Middle):
- Discord Bot (discord/bot.go)
- Command Router (commands/commands.go)
- Command Implementations:
- Ask Command
- Remember Command
- About Command

c) AI Processing (Bottom):
- AI Core (ai/ai.go)
- Query Processing (ai/query.go)
- Memory Management (ai/remember.go)

##### Flow Representation

- Incoming Discord messages → Bot
- Bot → Command Router
- Command Router → Specific Command Handlers
- Command Handlers → AI Processing
- AI Processing → Memory System (bidirectional)
- Responses flowing back to Discord

##### Additional Elements

Architectural aspects:
- Security layer (commands/utils/security.go)
- Thread handling (commands/utils/threads.go)
- Embed message formatting (commands/utils/embeds.go)

##### Containerization Layer

Docker-related components:
- Docker container boundary
- Docker Compose services
- Environment configuration

Key Considerations:
- Clear separation of concerns between Discord interface, command handling, and AI processing
- RAG system's integration points
- Memory/remembering capability as a distinct feature
- Security and thread handling as cross-cutting concerns

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph External
        DiscordAPI[Discord API]
    end

    %% Discord Interface Layer
    subgraph DiscordLayer
        Bot["Discord Bot"]:::discord
        Security["Security Layer"]:::security
    end

    %% Command Handling Layer
    subgraph CommandLayer
        CmdHandler["Command Handler"]:::command
        ThreadHandler["Thread Handler"]:::utility
        MsgFormatter["Message Formatter"]:::utility
        
        subgraph Commands
            AskCmd["Ask Command"]:::command
            RememberCmd["Remember Command"]:::command
            AboutCmd["About Command"]:::command
        end
    end

    %% AI Processing Layer
    subgraph AILayer
        AICore["AI Core"]:::ai
        QuerySystem["Query System"]:::ai
        MemorySystem["Memory System"]:::memory
    end

    %% Configuration
    subgraph Config
        EnvConfig[".env"]:::config
        AppConfig["config.yaml"]:::config
        Docker["Dockerfile"]:::container
        DockerCompose["docker-compose.yml"]:::container
    end

    %% Relationships
    DiscordAPI <--> Bot
    Bot --> Security
    Security --> CmdHandler
    CmdHandler --> ThreadHandler
    CmdHandler --> Commands
    Commands --> MsgFormatter
    AskCmd --> AICore
    RememberCmd --> AICore
    AICore --> QuerySystem
    AICore <--> MemorySystem

    %% Click Events
    click Bot "https://github.com/X3NOOO/twinkleshine/blob/master/discord/bot.go"
    click CmdHandler "https://github.com/X3NOOO/twinkleshine/blob/master/commands/commads.go"
    click AICore "https://github.com/X3NOOO/twinkleshine/blob/master/ai/ai.go"
    click QuerySystem "https://github.com/X3NOOO/twinkleshine/blob/master/ai/query.go"
    click MemorySystem "https://github.com/X3NOOO/twinkleshine/blob/master/ai/remember.go"
    click AskCmd "https://github.com/X3NOOO/twinkleshine/blob/master/commands/ask.go"
    click RememberCmd "https://github.com/X3NOOO/twinkleshine/blob/master/commands/remember.go"
    click AboutCmd "https://github.com/X3NOOO/twinkleshine/blob/master/commands/about.go"
    click Security "https://github.com/X3NOOO/twinkleshine/blob/master/commands/utils/security.go"
    click ThreadHandler "https://github.com/X3NOOO/twinkleshine/blob/master/commands/utils/threads.go"
    click MsgFormatter "https://github.com/X3NOOO/twinkleshine/blob/master/commands/utils/embeds.go"
    click EnvConfig "https://github.com/X3NOOO/twinkleshine/blob/master/.env.example"
    click AppConfig "https://github.com/X3NOOO/twinkleshine/blob/master/config.yaml.example"
    click Docker "https://github.com/X3NOOO/twinkleshine/tree/master/Dockerfile"
    click DockerCompose "https://github.com/X3NOOO/twinkleshine/blob/master/docker-compose.yml"

    %% Styling
    classDef discord fill:#3498db
    classDef command fill:#2ecc71
    classDef ai fill:#9b59b6
    classDef memory fill:#e67e22
    classDef utility fill:#95a5a6
    classDef config fill:#7f8c8d
    classDef container fill:#34495e
    classDef security fill:#e74c3c
```
