# aitrekker/jarvis architecture

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

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

## Overview

##### Project Type & Purpose
- Jarvis is a full-stack, modular AI voice-intelligence platform that captures live audio, transcribes it, summarizes content, indexes it semantically, and exposes both CLI and web UIs for retrieval and exploration.

##### Main Architectural Components
a. Audio Capture Module
- utils/recorder.py + debug/ui.py + platform FFmpeg binary
- Streams microphone input, preprocesses audio
b. Transcription Engine
- OpenAI Whisper integration (search/ollama_helper.py)
- search/search.py, search_engine.py for managing transcription jobs
c. Summarization Pipeline
- utils/summarize.py + Ollama phi4 model for local LLM summarization
- utils/periodic_tasks.py for scheduled summary jobs
d. Persistence Layer
- FileStore (storage/file_store.py) for raw transcripts
- ChromaDB vector store (storage/chroma_store.py, storage/chroma/) for embeddings & summaries
- storage/models.py defines metadata schemas
e. Semantic Search Engine
- search/search_engine.py + search_cli.py
- Embedding generation via nomic-embed-text
f. User Interfaces
- CLI: start_Jarvis.py, search/search_cli.py
- Web UI: Streamlit frontend (web/Jarvis_UI.py + web/components + web/web_utils)
g. Configuration & Logging
- config.py for global settings
- setup/logger.py + debug/logging.py for multi-level logs & diagnostics
h. Orchestration & Setup
- setup_Jarvis.py / setup/setup.py for bootstrap & env setup
- start_Jarvis.sh wrapper

##### Component Interactions & Data Flow
1. Microphone → Audio Capture Module → (FFmpeg) → Raw Audio Buffer
2. Buffer → Transcription Engine → Transcript Text
3. Transcript → FileStore → Raw transcript files
4. Batch transcripts → Summarization Pipeline → Summary Text
5. Summary + Transcript → Embedding Generator → Vector embeddings
6. Embeddings → ChromaDB → Indexed for similarity search
7. CLI / Web UI → Semantic Search Engine → Query ChromaDB → Results
8. Periodic Tasks Scheduler → triggers summarization & cleanup jobs

##### Architectural Patterns & Principles
- Clear separation of concerns: capture, processing, storage, UI
- Pipeline pattern: sequential processing stages (transcribe → summarize → index)
- Modular services: loosely coupled Python modules for easy extension
- Layered architecture: UI layer, service layer (transcribe, summarize, search), data layer

##### Technologies & Frameworks
- Python 3.11, FFmpeg (binaries/)
- OpenAI Whisper (speech-to-text)
- Ollama LLM (phi4) for summarization
- nomic-embed-text for embeddings
- ChromaDB for vector storage
- Streamlit for web UI
- pytest for automated testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Audio Capture Module
    subgraph "Audio Capture Module"
        Recorder["Recorder<br/>(utils/recorder.py)"]:::backend
        DebugUI["Debug UI<br/>(debug/ui.py)"]:::backend
        FFmpeg[(FFmpeg)]:::external
    end

    %% Transcription Engine
    subgraph "Transcription Engine"
        WhisperAPI[(OpenAI Whisper API)]:::external
        OllamaHelper["Ollama Helper<br/>(search/ollama_helper.py)"]:::backend
        SearchPY["search.py<br/>(search/search.py)"]:::backend
        Transcriber["Transcription Engine<br/>(search/search_engine.py)"]:::backend
    end

    %% Summarization Pipeline
    subgraph "Summarization Pipeline"
        Periodic["Scheduler<br/>(utils/periodic_tasks.py)"]:::backend
        Summarizer["Summarizer<br/>(utils/summarize.py)"]:::backend
        OllamaModel[(Ollama φ4 Model)]:::external
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        RawStore["FileStore<br/>(storage/file_store.py)"]:::data
        Models["Schemas<br/>(storage/models.py)"]:::data
        subgraph "ChromaDB Vector Store"
            Client["Chroma Client<br/>(storage/chroma/client.py)"]:::data
            ChromaStore["Chroma Store<br/>(storage/chroma_store.py)"]:::data
            TranscriptsDB["transcripts_db.py"]:::data
            SummariesDB["summaries_db.py"]:::data
        end
    end

    %% Semantic Search Engine
    SearchService["Semantic Search Engine<br/>(search/search_engine.py)"]:::backend

    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI UI<br/>(start_Jarvis.py)"]:::ui
        SearchCLIUI["Search CLI<br/>(search/search_cli.py)"]:::ui
        subgraph "Web UI"
            WebUI["Streamlit UI<br/>(web/Jarvis_UI.py)"]:::ui
            WebComponents["Components<br/>(web/components/*)"]:::ui
            WebUtils["Web Utils<br/>(web/web_utils/*)"]:::ui
        end
    end

    %% Configuration & Logging
    Config["Global Config<br/>(config.py)"]:::backend
    subgraph "Logging & Diagnostics"
        Logger["Logger<br/>(setup/logger.py)"]:::backend
        DebugLog["Debug Logging<br/>(debug/logging.py)"]:::backend
        LogStore[(Log Store)]:::data
    end

    %% Orchestration & Setup
    subgraph "Orchestration & Setup"
        SetupJarvis["Bootstrap<br/>(setup_Jarvis.py)"]:::backend
        SetupScript["Setup Script<br/>(setup/setup.py)"]:::backend
        StartScript["Start Script<br/>(start_Jarvis.sh)"]:::backend
    end

    %% Data Flow
    Recorder -->|"audio stream"| FFmpeg
    Recorder -->|"audio stream"| WhisperAPI
    FFmpeg --> Recorder
    WhisperAPI -->|"transcript text"| Transcriber
    Transcriber -->|"transcript text"| RawStore
    Transcriber -->|"metadata"| Models

    Periodic -->|"batch transcripts"| Summarizer
    Summarizer -->|"summary text"| OllamaModel
    Summarizer -->|"summary text"| Client

    Client -->|"index embeddings"| ChromaStore
    Client -->|"save transcripts"| TranscriptsDB
    Client -->|"save summaries"| SummariesDB

    CLI -->|"query"| SearchService
    SearchCLIUI -->|"query"| SearchService
    WebUI -->|"query"| SearchService
    SearchService -->|"vector query"| Client
    Client -->|"results"| SearchService
    SearchService --> CLI
    SearchService --> WebUI

    %% Scheduler triggers summarization
    Periodic --> Summarizer

    %% Logging channel
    Recorder -->|"logs"| LogStore
    Transcriber -->|"logs"| LogStore
    Summarizer -->|"logs"| LogStore
    SearchService -->|"logs"| LogStore
    CLI -->|"logs"| LogStore
    WebUI -->|"logs"| LogStore
    Periodic -->|"logs"| LogStore

    %% Orchestration dependencies
    SetupJarvis --> Config
    SetupJarvis --> Logger
    SetupScript --> Config
    StartScript --> SetupJarvis

    %% Click Events
    click Recorder "https://github.com/aitrekker/jarvis/blob/main/utils/recorder.py"
    click DebugUI "https://github.com/aitrekker/jarvis/blob/main/debug/ui.py"
    click FFmpeg "https://github.com/aitrekker/jarvis/tree/main/binaries/ffmpeg"
    click OllamaHelper "https://github.com/aitrekker/jarvis/blob/main/search/ollama_helper.py"
    click SearchPY "https://github.com/aitrekker/jarvis/blob/main/search/search.py"
    click Transcriber "https://github.com/aitrekker/jarvis/blob/main/search/search_engine.py"
    click Periodic "https://github.com/aitrekker/jarvis/blob/main/utils/periodic_tasks.py"
    click Summarizer "https://github.com/aitrekker/jarvis/blob/main/utils/summarize.py"
    click RawStore "https://github.com/aitrekker/jarvis/blob/main/storage/file_store.py"
    click Client "https://github.com/aitrekker/jarvis/blob/main/storage/chroma/client.py"
    click ChromaStore "https://github.com/aitrekker/jarvis/blob/main/storage/chroma_store.py"
    click TranscriptsDB "https://github.com/aitrekker/jarvis/blob/main/storage/chroma/transcripts_db.py"
    click SummariesDB "https://github.com/aitrekker/jarvis/blob/main/storage/chroma/summaries_db.py"
    click Models "https://github.com/aitrekker/jarvis/blob/main/storage/models.py"
    click SearchCLIUI "https://github.com/aitrekker/jarvis/blob/main/search/search_cli.py"
    click CLI "https://github.com/aitrekker/jarvis/blob/main/start_Jarvis.py"
    click WebUI "https://github.com/aitrekker/jarvis/blob/main/web/Jarvis_UI.py"
    click WebComponents "https://github.com/aitrekker/jarvis/tree/main/web/components"
    click WebUtils "https://github.com/aitrekker/jarvis/tree/main/web/web_utils"
    click Config "https://github.com/aitrekker/jarvis/blob/main/config.py"
    click Logger "https://github.com/aitrekker/jarvis/blob/main/setup/logger.py"
    click DebugLog "https://github.com/aitrekker/jarvis/blob/main/debug/logging.py"
    click SetupJarvis "https://github.com/aitrekker/jarvis/blob/main/setup_Jarvis.py"
    click SetupScript "https://github.com/aitrekker/jarvis/blob/main/setup/setup.py"
    click StartScript "https://github.com/aitrekker/jarvis/blob/main/start_Jarvis.sh"

    %% Styles
    classDef backend fill:#D0E1FF,stroke:#0366d6,color:#0366d6;
    classDef data fill:#E0F8E0,stroke:#28a745,color:#28a745;
    classDef ui fill:#FFE5CC,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#F0F0F0,stroke:#888888,color:#888888;
```
