# them1n9/stella architecture

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

- Interactive diagram: https://gitdiagram.com/them1n9/stella
- Repository: https://github.com/them1n9/stella

## Overview

##### Project Type and Its Purpose
- Project Type: Intelligent Voice Assistant.
- Purpose: To interact with users through voice commands, perform tasks (like opening/closing apps, performing web searches, managing files, sending emails, calendar and task management), and leverage external APIs (e.g., Google Generative AI, Gmail, Calendar).

##### File Structure to Determine Main Components
- Main Application Files: “app.py”, “assistant.py” and “web_assistant.py” serve as entry points. They likely contain the logic for capturing voice input, processing commands, and rendering a web UI.
- Features Directory (“features/”): Contains distinct modules for each specific function – such as file management, calendar fetching, web search, email handling, task management and more.
- Memory Directory (“memory/”): Holds JSON files and modules to manage conversation history, reminders, and tasks. This is a state-persistence layer for maintaining context.
- Credentials Directory (“credentials/”): Contains modules to manage authentication (e.g., “google_credentials.py”) for external services.
- Settings Directory (“settings/”): Likely contains configuration and safety-related parameters.
- Static & Templates Directories (“static/” and “templates/”): Represent the front-end resources (CSS, images, HTML) for the web-based user interface, hinting at some level of full-stack design.
- Supporting Files: “requirements.txt” (dependencies) and “.gitignore” for version control hints.

##### Detail the Main Components and Their Interactions
- User Input & Output:
- Voice Input Module: Handles capturing user commands via a microphone.
- Speech Processing: “listen()” to capture input and “speak(text)” for text-to-speech output.
- Command Processing Core:
- An orchestrator function (likely in “assistant.py” or “personal_assistant()”) that routes the voice inputs to the correct module.
- The “call_function()” mechanism that analyzes commands and decides which feature module to call.
- Feature Modules (within “features/”):
- Memory Management:
- A dedicated component for conversational context and state persistence. Use “memory.py” and JSON files (conversation_history.json, reminders.json, tasks.json) to represent this layer.
- External API & Credential Integration:
- Integrate “credentials/google_credentials.py” along with modules for accessing Google Generative AI, Gmail, and Calendar APIs.
- UI/Frontend:
- The web aspect of the assistant (managed by “web_assistant.py”) along with static files and templates. This provides an alternative interface.
- Configuration & Safety Settings:
- “settings/safety_settings.py” as part of the configuration layer that may influence the assistant’s behavior and safety protocols.

##### Relationships and Architectural Interactions
- From user (via voice or web interface) → Input processing (listen()) → Command processing/core interpreter.
- Memory modules should appear as a shared/storage component connected to the command processing core.
- External API integrations (Gmail, Calendar, Google AI) should be represented as connected services that the application accesses via the credentials handler.
- Dependencies, for instance, the use of Google APIs requires both the credentials module and network outbound connections.

##### Architectural Patterns
- Modular Design: Each feature in “features/” is independent and can be extended.
- Clear Layering: Input layer (voice / UI), Processing layer (command routing, NLP, decision making), and Integration layer (APIs and external services).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        User["User"]:::input
        VoiceEntrypoint["app.py (Voice Input)"]:::entry
        WebEntrypoint["web_assistant.py (Web UI)"]:::entry
        User -->|"voice"| VoiceEntrypoint
        User -->|"web"| WebEntrypoint
    end

    %% Processing Layer
    subgraph "Processing Layer"
        CommandProcessor["assistant.py (Command Processor)"]:::processing
        VoiceEntrypoint -->|"processes"| CommandProcessor
        WebEntrypoint -->|"processes"| CommandProcessor
    end

    %% Features Layer
    subgraph "Features Modules"
        FileManagement["file_management.py"]:::feature
        GetCalendar["get_calendar.py"]:::feature
        InternetSearch["internet_search.py"]:::feature
        MailService["mail.py"]:::feature
        AppControl["open_close_app.py"]:::feature
        Remainder["remainder.py"]:::feature
        SelfResponse["self_response.py"]:::feature
        SpeakFeature["speak.py"]:::feature
        TaskManagement["task_management.py"]:::feature
    end

    %% Memory Layer
    subgraph "Memory Management"
        MemoryModule["memory.py"]:::memory
        ConversationHistory["conversation_history.json"]:::memory
        Reminders["reminders.json"]:::memory
        Tasks["tasks.json"]:::memory
        MemoryModule --- ConversationHistory
        MemoryModule --- Reminders
        MemoryModule --- Tasks
    end

    %% External API & Credentials
    subgraph "External API Integration"
        GoogleCredentials["google_credentials.py"]:::external
    end

    %% Configuration Layer
    subgraph "Configuration & Safety"
        SafetySettings["safety_settings.py"]:::config
    end

    %% UI/Frontend Layer
    subgraph "UI/Frontend"
        StaticRes["static/ (CSS, Images)"]:::frontend
        Templates["templates/index.html"]:::frontend
        WebEntrypoint --- Templates
        WebEntrypoint --- StaticRes
    end

    %% Connections from Processing Layer to Features, Memory, External API and Config
    CommandProcessor -->|"activates"| FileManagement
    CommandProcessor -->|"activates"| GetCalendar
    CommandProcessor -->|"activates"| InternetSearch
    CommandProcessor -->|"activates"| MailService
    CommandProcessor -->|"activates"| AppControl
    CommandProcessor -->|"activates"| Remainder
    CommandProcessor -->|"activates"| SelfResponse
    CommandProcessor -->|"activates"| SpeakFeature
    CommandProcessor -->|"activates"| TaskManagement

    CommandProcessor <-->|"stores/retrieves"| MemoryModule
    CommandProcessor -->|"authenticates via"| GoogleCredentials
    CommandProcessor -->|"reads config"| SafetySettings

    %% Class Definitions for Colors
    classDef input fill:#f9e79f,stroke:#af7ac5,stroke-width:2px;
    classDef entry fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef processing fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef feature fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef memory fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef external fill:#f9cce1,stroke:#c0392b,stroke-width:2px;
    classDef config fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef frontend fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;

    %% Click Events for Entrypoints
    click VoiceEntrypoint "https://github.com/them1n9/stella/blob/main/app.py"
    click WebEntrypoint "https://github.com/them1n9/stella/blob/main/web_assistant.py"
    click CommandProcessor "https://github.com/them1n9/stella/blob/main/assistant.py"

    %% Click Events for Feature Modules
    click FileManagement "https://github.com/them1n9/stella/blob/main/features/file_management.py"
    click GetCalendar "https://github.com/them1n9/stella/blob/main/features/get_calendar.py"
    click InternetSearch "https://github.com/them1n9/stella/blob/main/features/internet_search.py"
    click MailService "https://github.com/them1n9/stella/blob/main/features/mail.py"
    click AppControl "https://github.com/them1n9/stella/blob/main/features/open_close_app.py"
    click Remainder "https://github.com/them1n9/stella/blob/main/features/remainder.py"
    click SelfResponse "https://github.com/them1n9/stella/blob/main/features/self_response.py"
    click SpeakFeature "https://github.com/them1n9/stella/blob/main/features/speak.py"
    click TaskManagement "https://github.com/them1n9/stella/blob/main/features/task_management.py"

    %% Click Events for Memory Management
    click MemoryModule "https://github.com/them1n9/stella/blob/main/memory/memory.py"
    click ConversationHistory "https://github.com/them1n9/stella/blob/main/memory/conversation_history.json"
    click Reminders "https://github.com/them1n9/stella/blob/main/memory/reminders.json"
    click Tasks "https://github.com/them1n9/stella/blob/main/memory/tasks.json"

    %% Click Event for External API
    click GoogleCredentials "https://github.com/them1n9/stella/blob/main/credentials/google_credentials.py"

    %% Click Event for Configuration
    click SafetySettings "https://github.com/them1n9/stella/blob/main/settings/safety_settings.py"

    %% Click Events for UI Resources
    click StaticRes "https://github.com/them1n9/stella/tree/main/static/"
    click Templates "https://github.com/them1n9/stella/blob/main/templates/index.html"
```
