# julesrubin/vigilauto architecture

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

- Interactive diagram: https://gitdiagram.com/julesrubin/vigilauto
- Repository: https://github.com/julesrubin/vigilauto

## Overview

##### Main Components
- Application Core: The entry point is “app.py”, which ties together all system modules.
- Computer Vision Module: Found in the “computer_vision” directory (e.g., train-vgg-model.ipynb) and potentially integrated into the core to analyze driver imagery for signs of intoxication.
- Conversational Agent (LLM Component): Under “src/VigilAuto/components/llm.py”, this module interfaces with the Groq Cloud API to run the Mixtral 8x7B model and generate conversation prompts/alerts.
- Speech Processing Modules:
- Speech-to-Text (STT) in “src/VigilAuto/components/stt.py” (utilizing Whisper).
- Text-to-Speech (TTS) in “src/VigilAuto/components/tts.py” (interacting with the ElevenLabs API).
- Configuration and Constants: Modules in “config” and “src/VigilAuto/config”, which provide the parameters and tuning for each component.
- Utility and Entity Layers: These assist with common functions, error handling, and packaging of data using files in "src/VigilAuto/utils" and "src/VigilAuto/entity".

##### Out Relationships and Interactions
- The system starts with real-time data capture (for instance, camera input or images) that is processed by the Computer Vision Module.
- The results of the vision analysis (indications of driver status) trigger a decision-making flow.
- The STT module may capture spoken elements (if the design includes interactive voice input), while the TTS module articulates the system’s alerts.
- The LLM component analyzes the situation and generates context-aware conversation prompts. It likely receives processed data from the vision/sensor modules and interfaces with external APIs (Groq Cloud for the language model and ElevenLabs for voice synthesis).
- Configurations (API keys, thresholds, and parameters) stored in configuration files direct the behavior of these major components.
- There is also an archival mechanism (as indicated by “traces_archive” and “tts_archive”) that suggests logging or storage of operational data.

##### Architectural Patterns and Technologies
- Modular design: Organize the different functionalities into discrete modules within “src/VigilAuto” (components, config, entity, and utils). This separation supports maintainability and extensibility.
- Containerization: Include a Docker container layer (indicated by Dockerfile) which suggests the system can be deployed in isolated environments.
- Experimentation: Note that research notebooks (in the “research” and “computer_vision” folders) support model training and tuning. These can be represented as supporting components for the main production pipeline.

##### Essential Elements
- Component labels: Each module should be clearly named (e.g., “Computer Vision Module”, “LLM Conversational Agent”, “Text-to-Speech (TTS) Engine”, “Speech-to-Text (STT) Processor”, “Configuration Manager”).
- Architectural patterns: Highlight how modularity and dependency injection (via configurations) are used.
- Optional: Indicate containerization (via Docker) and CI/CD integration using GitHub workflows.

## Diagram (Mermaid)

```mermaid
graph TD
  %% Data/Ingestion Layer
  subgraph "Data/Ingestion Layer"
    sensor("Camera & Microphone Inputs"):::ingest
  end

  %% Processing Layer
  subgraph "Processing Layer"
    app("Application Core"):::core
    cv("Computer Vision Module"):::module
    stt("Speech-to-Text Processor"):::module
    llm("LLM Conversational Agent"):::module
    sensor --> app
    app --> cv
    app --> stt
    app --> llm
    cv --> llm
    stt --> llm
  end

  %% Output Layer
  subgraph "Output Layer"
    tts("Text-to-Speech Engine"):::module
    llm --> tts
  end

  %% External Services
  subgraph "External Services"
    groq("Groq Cloud API (Mixtral 8x7B)"):::external
    eleve("ElevenLabs TTS Service"):::external
    llm --> groq
    tts --> eleve
  end

  %% Configuration & Utilities Layer
  subgraph "Configuration & Utilities"
    configYaml("Configuration (YAML)"):::config
    configModule("Configuration (Module)"):::config
    util("Utilities"):::config
    entity("Entities"):::config
    app --- configYaml
    cv --- configYaml
    stt --- configYaml
    llm --- configYaml
    tts --- configYaml
    app --- configModule
    cv --- configModule
    stt --- configModule
    llm --- configModule
    tts --- configModule
    app --- util
    app --- entity
  end

  %% Archival & Logging
  subgraph "Archival & Logging"
    traces("Traces Archive"):::archive
    ttsArchive("TTS Archive"):::archive
    app --- traces
    tts --- ttsArchive
  end

  %% Research & Deployment
  subgraph "Research & Deployment"
    research("Research/Experimentation"):::research
    research1("Trials Chat"):::research
    research2("Trials LLM"):::research
    research3("Trials STT"):::research
    research4("Trials TTS"):::research
    docker("Docker Container"):::deployment
    cicd("CI/CD Pipeline"):::deployment
    research --> research1
    research --> research2
    research --> research3
    research --> research4
    research --> app
    docker --> app
    cicd --> app
  end

  %% Click Events
  click app "https://github.com/julesrubin/vigilauto/blob/main/app.py"
  click cv "https://github.com/julesrubin/vigilauto/blob/main/computer_vision/train-vgg-model.ipynb"
  click stt "https://github.com/julesrubin/vigilauto/blob/main/src/VigilAuto/components/stt.py"
  click llm "https://github.com/julesrubin/vigilauto/blob/main/src/VigilAuto/components/llm.py"
  click tts "https://github.com/julesrubin/vigilauto/blob/main/src/VigilAuto/components/tts.py"
  click configYaml "https://github.com/julesrubin/vigilauto/blob/main/config/config.yaml"
  click configModule "https://github.com/julesrubin/vigilauto/blob/main/src/VigilAuto/config/configuration.py"
  click util "https://github.com/julesrubin/vigilauto/blob/main/src/VigilAuto/utils/common.py"
  click entity "https://github.com/julesrubin/vigilauto/blob/main/src/VigilAuto/entity/config_entity.py"
  click traces "https://github.com/julesrubin/vigilauto/tree/main/traces_archive"
  click ttsArchive "https://github.com/julesrubin/vigilauto/tree/main/tts_archive"
  click research "https://github.com/julesrubin/vigilauto/tree/main/research"
  click research1 "https://github.com/julesrubin/vigilauto/blob/main/research/trials_chat.ipynb"
  click research2 "https://github.com/julesrubin/vigilauto/blob/main/research/trials_llm.ipynb"
  click research3 "https://github.com/julesrubin/vigilauto/blob/main/research/trials_stt.ipynb"
  click research4 "https://github.com/julesrubin/vigilauto/blob/main/research/trials_tts.ipynb"
  click docker "https://github.com/julesrubin/vigilauto/tree/main/Dockerfile"
  click cicd "https://github.com/julesrubin/vigilauto/tree/main/.github/workflows"

  %% Styles
  classDef ingest fill:#ffe6e6,stroke:#333,stroke-width:2px;
  classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
  classDef module fill:#d5f5e3,stroke:#333,stroke-width:2px;
  classDef external fill:#fcf3cf,stroke:#333,stroke-width:2px;
  classDef config fill:#e8daef,stroke:#333,stroke-width:2px;
  classDef archive fill:#d1f2eb,stroke:#333,stroke-width:2px;
  classDef research fill:#f9e79f,stroke:#333,stroke-width:2px;
  classDef deployment fill:#fadbd8,stroke:#333,stroke-width:2px;
```
