# abheytiwari/indica architecture

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

- Interactive diagram: https://gitdiagram.com/abheytiwari/indica
- Repository: https://github.com/abheytiwari/indica

## Overview

##### Project type and purpose
- INDICA is an open-source, Python-based voice-powered virtual assistant. It uses speech recognition (listener.py), Gemini LLM (ai_engine/gemini_engine.py), a modular action system (modules/ folder), and text-to-speech (tts.py) to “think, talk, and act.”
- Its goal is to parse voice commands, decide whether to invoke a knowledge task (LLM) or system task (apps, email, weather, etc.), maintain short- and long-term memory (logs/ and modules/LTM.py), then respond via voice.

##### File structure
- Top-level orchestration:
- main.py – application entry point
- listener.py – captures audio, STT
- dispatcher.py – routes intents to modules or AI engine
- tts.py – speaks replies
- config.py – API keys, settings
- AI Engine:
- ai_engine/gemini_engine.py – wraps Google Gemini API calls
- ai_engine/gemini_research.py – research-oriented prompts
- Modules folder: each file implements a discrete system action, e.g., email.py, weather.py, apps.py, memory.py, fun.py, wiki.py, etc. modules/LTM.py handles long-term memory persistence.
- Logs:
- logs/logs.txt – short-term memory of last 5 commands
- logs/LTM.json – long-term embeddings store (planned)
- research_outputs/ – stores artifact outputs from “research” tasks.
- requirements.txt – dependency list.

##### README insights
- User → STT → Intent Recognizer → Decision Engine → either RAG (LLM + Memory) or System Control (modules) → TTS → User
- It lists external integrations: Gemini API, weather API, email (SMTP), Wikipedia, pyjokes, webbrowser, subprocess for app launches.

##### Detail without overcomplicating
- Module group, the AI engine, memory stores, and the voice I/O clearly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input / Output
    subgraph "Input / Output"
        U["User"]:::io
        STT["Listener / STT"]:::io
        TTS["Text-to-Speech (TTS)"]:::io
    end

    %% Core Logic
    subgraph "Core Logic"
        Main["main.py"]:::core
        Parser["Intent Parser"]:::core
        Dispatcher["Dispatcher"]:::core
        Config["config.py"]:::core
    end

    %% AI Engine
    subgraph "AI Engine"
        GeminiEngine["Retrieval-Augmented Generator"]:::ai
        GeminiResearch["Research Prompting Engine"]:::ai
    end

    %% System Control Modules
    subgraph "System Control Modules"
        Apps["apps.py"]:::module
        Email["email.py"]:::module
        Weather["weather.py"]:::module
        Wiki["wiki.py"]:::module
        Fun["fun.py"]:::module
        Search["search.py"]:::module
        MemoryMod["memory.py"]:::module
        LTMmod["LTM.py"]:::module
        Clock["clock.py"]:::module
        Time["time.py"]:::module
        Location["location.py"]:::module
        Music["music.py"]:::module
        SystemMod["sytem.py"]:::module
        Wish["wish.py"]:::module
    end

    %% Memory Stores
    subgraph "Memory Stores"
        ShortMem["Short-Term Memory\n(logs/logs.txt)"]:::memory
        LongMem["Long-Term Memory\n(logs/LTM.json)"]:::memory
    end

    %% External Services/API
    subgraph "External Services/API"
        GeminiAPI["Gemini API"]:::external
        WeatherAPI["Weather API"]:::external
        SMTP["SMTP Email"]:::external
        WikiAPI["Wikipedia"]:::external
        Jokes["pyjokes"]:::external
        OSCmd["OS Commands"]:::external
        WebBrowser["Web Browser"]:::external
    end

    %% Main Flow
    U --> STT
    STT --> Parser
    Parser --> Dispatcher
    Dispatcher -->|"knowledge task"| GeminiEngine
    Dispatcher -->|"system task"| Apps
    Apps --> TTS
    GeminiEngine --> GeminiResearch
    GeminiResearch --> GeminiAPI
    GeminiEngine --> TTS
    TTS --> U

    %% Modules to External
    Apps --> SMTP
    Email --> SMTP
    Weather --> WeatherAPI
    Wiki --> WikiAPI
    Fun --> Jokes
    SystemMod --> OSCmd
    SystemMod --> WebBrowser

    %% Memory Logging
    Parser -->|"log"| ShortMem
    Parser -->|"log"| LongMem
    GeminiEngine -->|"log"| ShortMem
    GeminiEngine -->|"log"| LongMem
    Apps -->|"log"| ShortMem
    Apps -->|"log"| LongMem

    %% Click Events
    click Main "https://github.com/abheytiwari/indica/blob/main/main.py"
    click STT "https://github.com/abheytiwari/indica/blob/main/listener.py"
    click Dispatcher "https://github.com/abheytiwari/indica/blob/main/dispatcher.py"
    click Config "https://github.com/abheytiwari/indica/blob/main/config.py"
    click GeminiEngine "https://github.com/abheytiwari/indica/blob/main/ai_engine/gemini_engine.py"
    click GeminiResearch "https://github.com/abheytiwari/indica/blob/main/ai_engine/gemini_research.py"
    click TTS "https://github.com/abheytiwari/indica/blob/main/tts.py"
    click Apps "https://github.com/abheytiwari/indica/blob/main/modules/apps.py"
    click Email "https://github.com/abheytiwari/indica/blob/main/modules/email.py"
    click Weather "https://github.com/abheytiwari/indica/blob/main/modules/weather.py"
    click Wiki "https://github.com/abheytiwari/indica/blob/main/modules/wiki.py"
    click Fun "https://github.com/abheytiwari/indica/blob/main/modules/fun.py"
    click Search "https://github.com/abheytiwari/indica/blob/main/modules/search.py"
    click MemoryMod "https://github.com/abheytiwari/indica/blob/main/modules/memory.py"
    click LTMmod "https://github.com/abheytiwari/indica/blob/main/modules/LTM.py"
    click Clock "https://github.com/abheytiwari/indica/blob/main/modules/clock.py"
    click Time "https://github.com/abheytiwari/indica/blob/main/modules/time.py"
    click Location "https://github.com/abheytiwari/indica/blob/main/modules/location.py"
    click Music "https://github.com/abheytiwari/indica/blob/main/modules/music.py"
    click SystemMod "https://github.com/abheytiwari/indica/blob/main/modules/sytem.py"
    click Wish "https://github.com/abheytiwari/indica/blob/main/modules/wish.py"
    click ShortMem "https://github.com/abheytiwari/indica/blob/main/logs/logs.txt"
    click LongMem "https://github.com/abheytiwari/indica/blob/main/logs/LTM.json"
    click research_outputs "https://github.com/abheytiwari/indica/tree/main/research_outputs/"
    click invalid_research "https://github.com/abheytiwari/indica/blob/main/logs/research/invalid_response.txt"
    click requirements "https://github.com/abheytiwari/indica/blob/main/requirements.txt"

    %% Styles
    classDef io fill:#CDEDF6,stroke:#1E90FF,color:#000
    classDef core fill:#E8F1F2,stroke:#5A85AD,color:#000
    classDef ai fill:#FDEFF4,stroke:#E75480,color:#000
    classDef module fill:#FFF4E0,stroke:#FFA500,color:#000
    classDef memory fill:#E8FFE8,stroke:#32CD32,color:#000
    classDef external fill:#F0F0F0,stroke:#A9A9A9,color:#000
```
