# thevickypedia/jarvis architecture

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

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

## Overview

##### Project Type and Purpose
- This is a standalone, voice-activated, natural-language user interface (Jarvis). It exposes both a CLI/Python API and an HTTP API. Internally it’s an event-driven, modular “core” (listener, scheduler, executors) that interacts with OS peripherals (mic, camera), local resources (file I/O, database), and external services (Telegram, Robinhood, email).

##### File-Structure Analysis
- Top-level:
- dev_scripts, docker-compose.yml, pre_commit.sh, pyproject.toml – setup, CI/CD, packaging
- docs, docs_gen – Sphinx-based documentation and GitHub Pages
- jarvis/ – the Python package
- jarvis/ subpackages:
- api/ – FastAPI (routers, models, server), SQUIRE scheduler
- executors/ – concrete action implementations (alarm, lights, VPN, etc.)
- modules/ – low-level interfaces (audio, camera, database, Telegram bot, TTS/STT)
- lib/ – installer scripts, requirements files
- indicators/ – UI audio cues
- scripts/ – AppleScript integrations
- main.py – entry point that wires everything together
- tests/ – unit tests for core modules

##### README Insights
- Jarvis is installed via pip, initialized via `jarvis start` or `import jarvis; jarvis.start()`
- Under the hood it registers permissions (mic, camera, automation), then spins up:
- A listener thread for speech recognition
- A TTS engine for responses
- An internal scheduler (SQUIRE) for timed jobs
- A FastAPI server with routers for remote control
- A registry of “executors” to perform tasks

##### Components
a. Main Components
1. Jarvis CLI / Python API (frontend trigger)
2. Jarvis Core Orchestrator (jarvis.main)
3. Event Bus / Command Dispatcher
4. Listener Module (speech-to-text)
5. NLU / Keyword Handler (preexec)
6. Scheduler (SQUIRE)
7. Executors (action layer)
8. Modules (hardware & service adapters)
9. API Server (FastAPI + routers)
10. Data Store (settings, logs)
11. External Services (Telegram, Robinhood, Email, Webhooks)

b. Relationships and Data Flows
- CLI/API → Core Orchestrator → Event Bus
- Listener Module → Event Bus
- Event Bus → Keyword Handler → Triggers
- Triggers → Scheduler or Direct Executor Invocation
- Executors → Modules → OS / External Services
- API Server ←→ Core Orchestrator (HTTP endpoints call into command dispatcher or scheduler)
- Modules (database) ↔ Data Store
- Scheduler → Executors at scheduled times

c. Architectural Patterns & Principles
- Modular / Plugin architecture: executors & modules are discoverable by registry
- Event-driven: commands dispatched via an internal bus
- Layered separation: input (listener, CLI), processing (dispatcher, scheduler), actions (executors, modules)
- Adapter pattern: modules abstract OS/peripheral/service specifics

d. Key Technologies & Frameworks
- Python 3.10+, FastAPI (HTTP API), pydantic models (api/models)
- Speech recognition & TTS libraries (jarvis/modules/audio)
- Sphinx for docs, pre-commit hooks, Docker Compose for environment

##### Detailed Breakdown to Capture All Elements
- Jarvis CLI / Python API → invokes `jarvis.start()`
- Listener Thread → STT module → Event Bus
- Keyword Handler → maps to executor commands
- Scheduler (SQUIRE) → triggers time-based tasks
- API Server (FastAPI) → routers (basics, fileio, stock_analysis, telegram, etc.) → pydantic models
- Executor Registry → executor classes (alarm, lights, TV, vpn_server…)
- Modules: audio (listener, speaker), camera, database, telegram bot, internet, robinhood, email templates
- Data Store: settings.json, logs, sqlite or files
- External: Telegram API, Robinhood API, email SMTP, system calls (AppleScript), OS peripherals

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        CLI["Jarvis CLI / Python API"]:::frontend
        HTTP["HTTP API (FastAPI)"]:::frontend
    end

    %% Core Orchestrator Layer
    subgraph "Core (Orchestrator)" 
        Orchestrator["Core Orchestrator"]:::core
        Bus["Event Bus / Dispatcher"]:::core
        Preexec["NLU / Keyword Handler"]:::core
        subgraph "Scheduler (SQUIRE)" 
            Scheduler["Scheduler"]:::core
            Disc["Discover Jobs"]:::core
            SA["Stock Analysis SQUIRE"]:::core
            SM["Stock Monitor SQUIRE"]:::core
            SU["Surveillance SQUIRE"]:::core
            TO["Timeout OTP"]:::core
        end
    end

    %% Executors Layer
    subgraph "Executors" 
        ExecRegistry["Executor Registry"]:::executors
        Execs["Executors (alarm, lights, vpn, robinhood, telegram, etc.)"]:::executors
    end

    %% Modules Layer
    subgraph "Modules (Adapters)" 
        Listener["Listener Module (Speech-to-Text)"]:::modules
        TTS["TTS Engine"]:::modules
        Camera["Camera Module"]:::modules
        DBModule["Database Module"]:::modules
        TeleBot["Telegram Bot Module"]:::modules
        Templates["Email Templates"]:::modules
        Logger["Logging Utility"]:::modules
        OtherMods["Other Adapters"]:::modules
    end

    %% Data Store Layer
    subgraph "Data Store" 
        Settings["Settings.json"]:::datastore
        Logs["Logs"]:::datastore
        DB["SQLite Database"]:::datastore
    end

    %% External Services Layer
    subgraph "External Services & OS" 
        TelegramExt["Telegram API"]:::external
        RobinhoodExt["Robinhood API"]:::external
        EmailSMTP["Email SMTP"]:::external
        OS["OS / Peripherals"]:::external
    end

    %% Connections
    CLI -->|"start()/commands"| Orchestrator
    HTTP -->|"HTTP request"| Orchestrator
    Orchestrator -->|register| Bus
    Listener -->|"speech input"| Bus
    Bus -->|"dispatch"| Preexec
    Preexec -->|"trigger"| Scheduler
    Preexec -->|"trigger"| ExecRegistry
    Scheduler -->|"schedule tasks"| Disc
    Scheduler -->|trigger jobs| SA
    Scheduler -->|trigger jobs| SM
    Scheduler -->|trigger jobs| SU
    Scheduler -->|trigger jobs| TO
    SA -->|"timed job"| ExecRegistry
    SM -->|"timed job"| ExecRegistry
    SU -->|"timed job"| ExecRegistry
    TO -->|"timed job"| ExecRegistry
    Scheduler -->|"invoke executor"| ExecRegistry
    ExecRegistry -->|"invoke action"| Execs
    Execs -->|"calls"| Listener
    Execs -->|"calls"| TTS
    Execs -->|"calls"| Camera
    Execs -->|"calls"| DBModule
    Execs -->|"calls"| TeleBot
    Execs -->|"calls"| Templates
    Execs -->|"calls"| OtherMods
    Listener -->|"mic I/O"| OS
    TTS -->|"speaker I/O"| OS
    Camera -->|"capture"| OS
    OtherMods -->|"system calls"| OS
    DBModule -->|"read/write"| DB
    DBModule -->|"read/write"| Settings
    DBModule -->|"read/write"| Logs
    TeleBot -->|"send/receive"| TelegramExt
    Execs -->|"trade"| RobinhoodExt
    Templates -->|"SMTP"| EmailSMTP

    %% Click Events
    click CLI "https://github.com/thevickypedia/jarvis/blob/master/jarvis/main.py"
    click Orchestrator "https://github.com/thevickypedia/jarvis/blob/master/jarvis/main.py"
    click Preexec "https://github.com/thevickypedia/jarvis/blob/master/jarvis/_preexec/keywords_handler.py"
    click Listener "https://github.com/thevickypedia/jarvis/blob/master/jarvis/modules/audio/listener.py"
    click TTS "https://github.com/thevickypedia/jarvis/blob/master/jarvis/modules/audio/tts_stt.py"
    click Scheduler "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/squire/scheduler.py"
    click Disc "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/squire/discover.py"
    click SA "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/squire/stockanalysis_squire.py"
    click SM "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/squire/stockmonitor_squire.py"
    click SU "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/squire/surveillance_squire.py"
    click TO "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/squire/timeout_otp.py"
    click HTTP "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/server.py"
    click HTTP "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/main.py"
    click Execs "https://github.com/thevickypedia/jarvis/tree/master/jarvis/executors/"
    click DBModule "https://github.com/thevickypedia/jarvis/blob/master/jarvis/modules/database/database.py"
    click Camera "https://github.com/thevickypedia/jarvis/blob/master/jarvis/modules/camera/camera.py"
    click TeleBot "https://github.com/thevickypedia/jarvis/tree/master/jarvis/modules/telegram/"
    click Templates "https://github.com/thevickypedia/jarvis/tree/master/jarvis/modules/templates/"
    click Logger "https://github.com/thevickypedia/jarvis/blob/master/jarvis/modules/logger.py"
    click Settings "https://github.com/thevickypedia/jarvis/blob/master/jarvis/api/models/settings.py"
    click OtherMods "https://github.com/thevickypedia/jarvis/tree/master/jarvis/scripts/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#69AADD,stroke-width:2px
    classDef core fill:#DFFFE0,stroke:#88CC44,stroke-width:2px
    classDef executors fill:#FFE5B4,stroke:#FFAA22,stroke-width:2px
    classDef modules fill:#FFF5CC,stroke:#E5B800,stroke-width:2px
    classDef datastore fill:#E8D0FF,stroke:#AA66CC,stroke-width:2px
    classDef external fill:#EEEEEE,stroke:#BBBBBB,stroke-width:2px
```
