# krypton-byte/thundra architecture

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

- Interactive diagram: https://gitdiagram.com/krypton-byte/thundra
- Repository: https://github.com/krypton-byte/thundra

## Overview

##### Main Components
- Bot Framework Core: Represent the “thundra” package as the heart of the framework. Under this, highlight important modules such as:
– Core: Found in thundra/core (handles essentials like graph management, LLM integrations, and memory management).
– Agents: (thundra/agents.py and thundra/button/*) which encapsulate bot behaviors and different versions (v1, v2) for button interactions.
– Command & CLI: (thundra/command.py, thundra/cli.py) which are critical for interaction via the command-line interface and bot commands.
– Configuration: (thundra/config.py and the thundra.toml template in thundra/templates) for setting up WhatsApp account credentials and general settings.
– Middleware: (thundra/middleware.py) to process messages and manage pre- or post-processing tasks.
– Plugins & Extensions: (thundra/plugins.py) that allow extending core functionality.
– Storage & Profiling: Modules found in thundra/storage and thundra/profiler, which handle data persistence (for example, file based storage) and performance measurements.
– Utility and Execution Helpers: (e.g., thundra/workdir.py, thundra/utils.py) that support the framework operations.

##### File Structure for Architectural Patterns
- The directory structure suggests a modular approach: core logic, integration layers, templating (for generating starter apps), and extension points (such as plugins and middleware).
- Presence of a CLI and command execution flow indicates a design that supports both command-line and possibly programmatic interactions.
- The workflow files in the .github directory point to automated testing, documentation, and release processes – helpful for understanding deployment and continuous integration parts of the system.

##### Relationships and Data Flow
- The CLI module acts as an entry point, triggering commands and delegating tasks to underlying components.
- Data and message processing flow through middleware (processing hooks) before being sent to agents which encapsulate the bot logic.
- The core components (LLM, memory, graph) interact to manage decision-making or learning capabilities.
- Storage and profiler modules work adjacently, handling persistence of state and performance monitoring respectively.
- Template generation (in thundra/templates) is used to bootstrap new bot applications, which can then plug in various agents and commands.

##### Architectural Patterns and Technologies
- Modular Architecture: Each major functionality is isolated into its module (core, agents, CLI, etc.), making it easier to extend or modify.
- Abstraction Layer: The design abstracts away the WhatsApp API complexities so that bot logic remains simple and intuitive.
- Command and Middleware Patterns: Use of middleware for message processing and command patterns for CLI interactions suggest design principles optimizing for separation of concerns.
- Integration with External Tools: The README mentions compatibility with “LangChain” and “whatsmeow-wrapper,” indicating that the internal design might leverage external APIs or libraries for enhanced functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title: Thundra Framework Architecture
    %% Legend:
    %% core (blue): Bot Framework Core components
    %% interface (green): Interfaces and configuration
    %% utility (yellow): Support utilities and extensions
    %% external (pink): External systems (WhatsApp API)

    %% Interface Components
    A["Configuration"]:::interface
    B["Templates"]:::interface
    C["CLI/Command Interface"]:::interface

    %% Core Framework Components
    D["Bot Framework Core"]:::core
    E["Core (LLM, Memory, Graph)"]:::core
    F["Agents & Button Interactions"]:::core

    %% Utility & Support Components
    G["Middleware"]:::utility
    H["Plugins/Extensions"]:::utility
    I["Storage"]:::utility
    J["Profiler"]:::utility
    K["Utility & Helpers"]:::utility

    %% External System
    L["WhatsApp API"]:::external

    %% Relationships / Data Flow
    B --> C
    A --> D
    A --> C
    C --> D
    C --> G
    D --> E
    D --> F
    D --> H
    E --> I
    E --> J
    E --> K
    G --> F
    F --> L

    %% Classes / Styles
    classDef core fill:#DDEEFF,stroke:#000,stroke-width:2px;
    classDef interface fill:#CCFFCC,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFEEAA,stroke:#000,stroke-width:2px;
    classDef external fill:#ffd1dc,stroke:#000,stroke-width:2px;

    %% Click Events
    click D "https://github.com/krypton-byte/thundra/blob/master/thundra/__init__.py"
    click E "https://github.com/krypton-byte/thundra/tree/master/thundra/core/"
    click F "https://github.com/krypton-byte/thundra/blob/master/thundra/agents.py"
    click F "https://github.com/krypton-byte/thundra/tree/master/thundra/button/"
    click C "https://github.com/krypton-byte/thundra/blob/master/thundra/command.py"
    click C "https://github.com/krypton-byte/thundra/blob/master/thundra/cli.py"
    click A "https://github.com/krypton-byte/thundra/blob/master/thundra/config.py"
    click B "https://github.com/krypton-byte/thundra/blob/master/thundra/templates/thundra.toml"
    click G "https://github.com/krypton-byte/thundra/blob/master/thundra/middleware.py"
    click H "https://github.com/krypton-byte/thundra/blob/master/thundra/plugins.py"
    click I "https://github.com/krypton-byte/thundra/tree/master/thundra/storage/"
    click J "https://github.com/krypton-byte/thundra/tree/master/thundra/profiler/"
    click K "https://github.com/krypton-byte/thundra/blob/master/thundra/utils.py"
    click K "https://github.com/krypton-byte/thundra/blob/master/thundra/workdir.py"
```
