# franklyc/eidolon-assist architecture

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

- Interactive diagram: https://gitdiagram.com/franklyc/eidolon-assist
- Repository: https://github.com/franklyc/eidolon-assist

## Overview

##### Main Components
- User Interface (UI): This is represented by the web files (index.html, main.js, particles.js, styles.css) that provide a modern, gradient-rich, and blur-effect enhanced front-end.
- Application Entry Point & Core Logic: The eidolon_assist.py file is your main Python script that ties together the overall functionality.
- Configuration & Settings Module: Managed via dialogs from the application to set API keys, voice selections, hotkeys, and more. The pyproject.toml file also plays a role in project configuration.
- Multimodal Input Processors:
- Voice Input Module: Captures audio based on hotkeys (Ctrl+[ to start; Ctrl+] to stop) and channels it to the transcription service.
- Text Input Module: Processes typed queries from the UI.
- Image Input Module: Handles screenshot capture (triggered by Ctrl+P) for visual processing.
- External API Integrations:
- Transcription Service: Uses Groq API (Whisper model) to convert voice to text.
- AI Language Model Module: Interfaces with an OpenAI-compatible API for processing queries and generating responses.
- Text-to-Speech (TTS) Module: Utilizes Edge TTS (with adjustable speed and volume) to convert text responses into spoken audio.
- Conversation Management: Maintains conversation history and the assistant’s state (new conversation functionality).

##### Relationships and Interactions
- User Interaction Flow:
- The user interacts with the modern UI (web front-end integrated into the Python application via PyQt6 or related webview components).
- Input events (voice, text, screenshot) are captured and forwarded to the core logic in eidolon_assist.py.
- Data Flow:
- Voice Input: Audio is recorded → sent to the Transcription Service → converted to text → forwarded for processing.
- Text & Image Inputs are sent directly to the NLP Module.
- The NLP Module (AI language model) processes the sent text (or combined multimodal data) → generates a response.
- The response is then fed into the TTS Module to produce audio output.
- The UI displays the conversation history and current responses.
- Configuration Component:
- A settings module (invoked the first time or later from a dialog) manages API keys and other preferences, affecting how data flows to external services.

##### Architectural Patterns and Design Principles
- Modularity: The project is broken down into clear modules (UI, voice processing, NLP, TTS, configuration).
- Separation of Concerns: Frontend UI is separated from business logic and external integrations.
- Event-Driven Interaction: Utilizes hotkeys and other events to drive input capturing and processing.
- External Service Integration: Clearly delineated boundaries where external APIs are consumed, showcasing loose coupling between core logic and external dependencies.

- Labels: Clearly indicate components like “UI Layer”, “Voice Input Module”, “Text Input Module”, “Image Input Module”, “Transcription Service (Groq API)”, “NLP Engine (OpenAI API)”, “TTS Module (Edge TTS)”, and “Settings/Configuration”.
- Additional Information: Optionally include notes about hotkeys triggering specific modules or mention the integration of PyQt6 if it is used to combine web elements with Python’s backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User("User"):::external

    %% UI Layer
    subgraph "UI Layer"
        UI1["index.html"]:::ui
        UI2["main.js"]:::ui
        UI3["particles.js"]:::ui
        UI4["styles.css"]:::ui
    end

    %% Core Backend
    Core["eidolon_assist.py (Core Logic)"]:::core
    Settings["pyproject.toml (Configuration)"]:::config

    %% Input Modules
    Voice["Voice Input Module<br/>(Hotkeys: Ctrl+[ / Ctrl+])"]:::input
    Text["Text Input Module"]:::input
    Image["Image Input Module<br/>(Hotkey: Ctrl+P)"]:::input

    %% External Service Modules
    Transcription["Transcription Service (Groq API)"]:::external
    NLP["NLP Engine (OpenAI API)"]:::external
    TTS["TTS Module (Edge TTS)"]:::external

    %% Conversation Management
    Conversation["Conversation Management"]:::core

    %% Data Flow Connections
    User -->|"interacts"| UI1
    UI1 -->|"sends input"| Core

    Core -->|"dispatches"| Voice
    Core -->|"dispatches"| Text
    Core -->|"dispatches"| Image

    Voice -->|"captures-audio"| Transcription
    Transcription -->|"converts-to-text"| NLP

    Text -->|"sends-text"| NLP
    Image -->|"sends-image"| NLP

    NLP -->|"generates-response"| TTS
    NLP -->|"updates-history"| Conversation

    TTS -->|"outputs-audio"| UI1
    Conversation -->|"displayed-on"| UI1

    Core <-->|"uses"| Settings

    %% Styles
    classDef ui fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef input fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef config fill:#D6DBDF,stroke:#839192,stroke-width:2px;
    classDef externalActor fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click Events
    click UI1 "https://github.com/franklyc/eidolon-assist/blob/main/index.html"
    click UI2 "https://github.com/franklyc/eidolon-assist/blob/main/main.js"
    click UI3 "https://github.com/franklyc/eidolon-assist/blob/main/particles.js"
    click UI4 "https://github.com/franklyc/eidolon-assist/blob/main/styles.css"
    click Core "https://github.com/franklyc/eidolon-assist/blob/main/eidolon_assist.py"
    click Settings "https://github.com/franklyc/eidolon-assist/blob/main/pyproject.toml"
```
