# ofgeha-gelana/emocharbot architecture

> Architecture diagram of the GitHub repository ofgeha-gelana/emocharbot, 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/ofgeha-gelana/emocharbot
- Repository: https://github.com/ofgeha-gelana/emocharbot

## Overview

##### Project Purpose and Type
- This is a full-stack application that focuses on interactive AI-driven character simulations. It enables users to extract characters from text and chat with them through a web interface (built with Streamlit).
- Key features include character extraction from documents, AI-based conversation (powered by Google Gemini-Pro), and persistent conversation storage via ChromaDB.

##### Main Components
a. Frontend (UI Layer):
- Represented primarily by the Streamlit application (e.g., app.py, ui.py).
- This is where users upload texts, select characters, and chat with them.
b. Backend / Business Logic:
- Core Python modules such as main.py, ch.py, character_manager.py, man.py, and tell.py coordinate the application logic.
- The lib directory (with files like character.py, file_processor.py, and memory.py) encapsulates core functionality for character extraction, text processing, and conversation memory management.
c. External Services and Integrations:
- Google Gemini-Pro: The AI model service to generate dynamic character responses.
- ChromaDB: A database dedicated to storing and managing conversation histories. The file tree shows a chroma_db directory containing the SQLite3 database file.
d. Configuration and Environment:
- The .env file is crucial for storing sensitive information like the Google API Key.
- requirements.txt and .gitignore indicate dependency management and source control practices.

##### Relationships and Data Flow
- User Interaction: The user interacts with the frontend (Streamlit UI). User inputs (text uploads, character selections, chat messages) are sent directly from the UI.
- Processing Layer: The UI calls backend functions (in app.py and related modules like character_manager.py) where text processing and character extraction are handled (using lib/file_processor.py for parsing and lib/memory.py for handling conversation memory).
- AI Interaction: The backend then calls Google Gemini-Pro to generate character-specific responses based on the character traits extracted from input text.
- Persistence: Conversations are stored in ChromaDB. The system maintains conversation history through modules that interface with the chroma_db (e.g., function calls from chroma.py).

##### Key Architectural Patterns and Design Principles
- Separation of Concerns: The design separates the UI from business logic (data processing and conversation handling) and external service integrations.
- Modular Design: Using distinct modules and libraries (the lib/ directory and individual Python scripts) allows for easier testing and extensibility.
- Dependency Injection (Implicitly): The code structure allows for integration with external services (Google Gemini-Pro and ChromaDB) by isolating their communication to individual components.

##### Detailed Elements
- Use clear labels for each component:
- “Streamlit UI” for the frontend.
- “Character Extraction & Management” for modules like character_manager.py and lib/character.py.
- “Text Processing Module” for lib/file_processor.py.
- “Conversation Memory Management” for lib/memory.py.
- “AI Service: Google Gemini-Pro” to indicate AI response generation.
- “Conversation Database: ChromaDB” representing persistent storage.
- Flow from “User Input” at the UI through processing modules to AI service, then responses back to UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User Input"]:::external

    subgraph "Frontend (Streamlit UI)"
        FA1["app.py"]:::frontend
        FA2["ui.py"]:::frontend
    end

    subgraph "Backend / Business Logic"
        subgraph "Core Modules"
            BM1["main.py"]:::backend
            BM2["ch.py"]:::backend
            BM3["character_manager.py"]:::backend
            BM4["man.py"]:::backend
            BM5["tell.py"]:::backend
        end
        subgraph "Supporting Libraries"
            BL1["lib/character.py"]:::backend
            BL2["lib/file_processor.py"]:::backend
            BL3["lib/memory.py"]:::backend
        end
    end

    subgraph "External Services"
        ES1["AI Service: Google Gemini-Pro"]:::external
        ES2["Conversation Database: ChromaDB"]:::external
        subgraph "ChromaDB Files"
            EDF1["chroma.py"]:::external
            EDF2["chroma_db/chroma.sqlite3"]:::external
        end
    end

    subgraph "Configuration & Environment"
        C1[".env"]:::config
        C2["requirements.txt"]:::config
        C3[".gitignore"]:::config
    end

    %% Connections
    A -->|"text_input"| FA1
    FA1 -->|"process_request"| BM3
    BM3 -->|"extract_character"| BL1
    BM2 -->|"process_text"| BL2
    BM5 -->|"handle_memory"| BL3
    BM3 -->|"generate_response"| ES1
    BM4 -->|"store_conversation"| ES2
    ES2 -->|"retrieve_conversation"| BM4
    BM1 -->|"send_response"| FA1
    BM1 -->|"read_config"| C1
    BM1 -->|"dependency_check"| C2
    BM1 -->|"dependency_check"| C3

    %% Click Events for Frontend
    click FA1 "https://github.com/ofgeha-gelana/emocharbot/blob/main/app.py"
    click FA2 "https://github.com/ofgeha-gelana/emocharbot/blob/main/ui.py"

    %% Click Events for Backend / Core Modules
    click BM1 "https://github.com/ofgeha-gelana/emocharbot/blob/main/main.py"
    click BM2 "https://github.com/ofgeha-gelana/emocharbot/blob/main/ch.py"
    click BM3 "https://github.com/ofgeha-gelana/emocharbot/blob/main/character_manager.py"
    click BM4 "https://github.com/ofgeha-gelana/emocharbot/blob/main/man.py"
    click BM5 "https://github.com/ofgeha-gelana/emocharbot/blob/main/tell.py"

    %% Click Events for Supporting Libraries
    click BL1 "https://github.com/ofgeha-gelana/emocharbot/blob/main/lib/character.py"
    click BL2 "https://github.com/ofgeha-gelana/emocharbot/blob/main/lib/file_processor.py"
    click BL3 "https://github.com/ofgeha-gelana/emocharbot/blob/main/lib/memory.py"

    %% Click Events for External Services
    click EDF1 "https://github.com/ofgeha-gelana/emocharbot/blob/main/chroma.py"
    click EDF2 "https://github.com/ofgeha-gelana/emocharbot/blob/main/chroma_db/chroma.sqlite3"

    %% Click Events for Configuration
    click C1 "https://github.com/ofgeha-gelana/emocharbot/blob/main/.env"
    click C2 "https://github.com/ofgeha-gelana/emocharbot/blob/main/requirements.txt"
    click C3 "https://github.com/ofgeha-gelana/emocharbot/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
```
