# itachi-1824/jarvis architecture

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

- Interactive diagram: https://gitdiagram.com/itachi-1824/jarvis
- Repository: https://github.com/itachi-1824/jarvis

## Overview

##### Project type and purpose
- Jarvis is a real-time AI personal assistant written in Python. It provides voice/video interaction, handles weather lookups, web searches, and email management by orchestrating multiple external AI and communication services.
- It is primarily a single-process backend application with a real-time communication frontend (via LiveKit) and integrations with Google AI, DuckDuckGo, and Gmail.

##### File structure
- Top-level files:
- agent.py       → Core runtime: connects to LiveKit, handles incoming voice/video, orchestrates commands.
- prompts.py     → Defines instruction and personality prompts for the AI model.
- tools.py       → Implements “tool” functions: weather API calls, search, email sending.
- .env.example   → Template for API keys and secrets.
- requirements.txt → Lists Python dependencies (LiveKit, google-api, requests, dotenv).
- No separate “frontend” folder because the LiveKit client acts as the frontend; the application acts as a server and client in one.

##### README for additional insights
- Architecture is described in prose: LiveKit handles real-time voice/video streaming, Google AI powers speech recognition/synthesis and natural language understanding, DuckDuckGo and Gmail are used via REST.
- Environment variables configure connections to external services.

##### Detailed capture of architectural elements
- Module with key libraries (e.g., “livekit-sdk” in the LiveKit Connector).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal components (blue)
    subgraph "Jarvis Internal"
        direction TB
        A["Backend Orchestrator\n(agent.py)"]:::internal
        B["Prompt Manager\n(prompts.py)"]:::internal
        C["Tools Layer\n(tools.py)"]:::internal
    end

    %% External services (green)
    LiveKitClient((LiveKit Client)):::external
    GoogleSTT((Google AI STT)):::external
    GoogleLLM((Google AI LLM)):::external
    GoogleTTS((Google AI TTS)):::external
    DuckDuckGo((DuckDuckGo Search API)):::external
    WeatherAPI((Weather Service API)):::external
    GmailAPI((Gmail SMTP API)):::external

    %% Configuration & Documentation (yellow)
    Env["Environment Config\n(.env.example)"]:::config
    Deps["Dependencies\n(requirements.txt)"]:::config
    Docs["Documentation\n(README.md)"]:::config

    %% Data flows
    LiveKitClient -->|"Audio RTP"| A
    A -->|"Send audio"| GoogleSTT
    GoogleSTT -->|"Transcribed text"| A
    A -->|"load prompts"| B
    B -->|"Prompts"| A
    A -->|"Text + prompts"| GoogleLLM
    GoogleLLM -->|"LLM response"| A
    A -->|"Invoke tool"| C
    C -->|"Search request"| DuckDuckGo
    C -->|"Weather request"| WeatherAPI
    C -->|"Email send"| GmailAPI
    DuckDuckGo -->|"Search results"| C
    WeatherAPI -->|"Weather data"| C
    GmailAPI -->|"Email status"| C
    C -->|"Tool data"| A
    A -->|"TTS request"| GoogleTTS
    GoogleTTS -->|"Audio RTP"| A
    A -->|"Audio RTP"| LiveKitClient

    %% Config and docs connections
    Env -.->|"API_KEYS"| A
    Deps -.-> A
    Docs -.-> A

    %% Click events
    click A "https://github.com/itachi-1824/jarvis/blob/main/agent.py"
    click B "https://github.com/itachi-1824/jarvis/blob/main/prompts.py"
    click C "https://github.com/itachi-1824/jarvis/blob/main/tools.py"
    click Env "https://github.com/itachi-1824/jarvis/blob/main/.env.example"
    click Deps "https://github.com/itachi-1824/jarvis/blob/main/requirements.txt"
    click Docs "https://github.com/itachi-1824/jarvis/blob/main/README.md"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef config fill:#FFFFE0,stroke:#000,stroke-width:1px;
```
