# mannahalpara/axon architecture

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

- Interactive diagram: https://gitdiagram.com/mannahalpara/axon
- Repository: https://github.com/mannahalpara/axon

## Overview

##### Project type and purpose
- This is a Python-based personal voice assistant for Windows (Axon).
- It supports voice/text input, uses AI (Gemini & Llama) to interpret commands or answer questions, and can perform local actions (open apps, summarize Wikipedia, describe the screen).

##### File structure
- No sub-directories; all modules live at the top level.
- Key scripts:
- app.py – orchestrator (input mode selection, main loop)
- command.py – sends user commands to Gemini AI; handles screen analysis
- ask_ai.py – handles general question/answer via Llama Meta
- open_app.py – launches UWP/traditional Windows apps
- wikipedia.py – fetches & summarizes Wikipedia articles
- requirements.txt defines dependencies (pyttsx3, gTTS, openai/other API libs, image-processing).

##### Extract additional architecture clues from README
- Input modes → voice (speech-to-text) or keyboard.
- AI backends:
- Gemini AI (command intent parsing)
- Llama by Meta (general Q&A)
- Output modes: text (console), voice (pyttsx3/gTTS).
- Logging: all interactions written to log.txt.

##### Main components and their interactions
a. Input Layer
- Voice Input Module (microphone → STT)
- Text Input Module (console prompt)
b. Core Orchestrator (app.py)
- Dispatches input to Command Handler or AI QA
- Collects responses for output & logging
c. Command Handler (command.py)
- Sends natural language to Gemini AI for intent extraction
- Routes intents to local executors:
- App Launcher (open_app.py)
- Wikipedia Summarizer (wikipedia.py)
- Screen Analyzer (image capture + description)
d. AI QA Module (ask_ai.py)
- For “Ask AI:” commands → sends prompt to Llama endpoint → formats response
e. Output Layer
- Text-to-Speech Engine (pyttsx3 primary, gTTS fallback)
- Console/Text display
f. Logging (built into orchestrator)
- Appends timestamped interactions and results to log.txt
g. External Services
- Gemini AI API (requires GEMINI_API_KEY)
- Llama Meta endpoint/token
- Wikipedia API
- (Optionally Google/YouTube for search commands)

##### Architectural patterns and design principles
- Modular separation: Input, Processing, Execution, Output, Logging
- Single orchestrator “director” pattern (app.py)
- Clear plugin-style executors for actions (open_app, wikipedia, screen analysis)
- External AI services decoupled behind thin wrapper modules

- Clear labels on each component (e.g., “Gemini AI API”, “Screen Analyzer”)
- Configuration points (GEMINI_API_KEY, Llama token, requirements)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Input Layer"
        VM["Voice Input Module"]:::local
        TM["Text Input Module"]:::local
    end

    subgraph "Core"
        OR["Core Orchestrator"]:::local
    end

    subgraph "Processing Modules"
        CH["Command Handler"]:::local
        QA["AI QA Module"]:::local
    end

    subgraph "Action Executors"
        AL["App Launcher"]:::local
        WS["Wikipedia Summarizer"]:::local
        SA["Screen Analyzer"]:::local
    end

    subgraph "Output Layer"
        TS["Text-to-Speech Engine"]:::local
        CD["Console Display"]:::local
    end

    LOG["Interaction Log\n(log.txt)"]:::datastore
    REQ["Dependency Definitions\n(requirements.txt)"]:::datastore
    READ["Project Documentation\n(README.md)"]:::datastore

    subgraph "External Services"
        GA["Gemini AI API"]:::external
        LA["Llama Meta Endpoint"]:::external
        WAPI["Wikipedia API"]:::external
    end

    VM -->|"audio stream"| OR
    TM -->|"text input"| OR

    OR -->|"command"| CH
    OR -->|"ask ai"| QA

    CH -->|"intent request"| GA
    CH -->|"intent: launch app"| AL
    CH -->|"intent: wiki"| WS
    CH -->|"intent: screen analyze"| SA

    QA -->|"qa request"| LA

    WS -->|"wiki fetch"| WAPI

    OR -->|"response"| TS
    OR -->|"response"| CD

    OR -->|"log entry"| LOG

    OR -->|"config load"| REQ
    OR -->|"docs reference"| READ

    classDef local fill:#AED6F1,stroke:#1B4F72,stroke-width:1px
    classDef external fill:#A9DFBF,stroke:#145A32,stroke-width:1px
    classDef datastore fill:#F9E79F,stroke:#7D6608,stroke-width:1px

    click VM "https://github.com/mannahalpara/axon/blob/main/app.py"
    click TM "https://github.com/mannahalpara/axon/blob/main/app.py"
    click OR "https://github.com/mannahalpara/axon/blob/main/app.py"
    click CH "https://github.com/mannahalpara/axon/blob/main/command.py"
    click QA "https://github.com/mannahalpara/axon/blob/main/ask_ai.py"
    click AL "https://github.com/mannahalpara/axon/blob/main/open_app.py"
    click WS "https://github.com/mannahalpara/axon/blob/main/wikipedia.py"
    click REQ "https://github.com/mannahalpara/axon/blob/main/requirements.txt"
    click READ "https://github.com/mannahalpara/axon/blob/main/README.md"
```
