# harvinderkaur02/proton-voice-assistant architecture

> Architecture diagram of the GitHub repository harvinderkaur02/proton-voice-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harvinderkaur02/proton-voice-assistant
- Repository: https://github.com/harvinderkaur02/proton-voice-assistant

## Overview

##### Project Type and Purpose
- PROTON is a standalone, desktop‐based “voice assistant” application written in Python.
- It combines a GUI front end (using tkinter and a small local web interface) with a speech I/O layer, a core command‐processing engine, and a set of action modules (file navigation, web search, date/time retrieval, etc.).

##### File Structure
- Top Level:
- requirements.txt – lists all Python dependencies.
- memory.txt – simple persistent store for “memory” or context.
- demo_media/ – screenshots and assets for demos (not part of runtime).
- src/ directory:
- Proton.py – the heart of the application: listens for voice, dispatches commands, invokes modules, drives TTS.
- app.py – initializes and runs the GUI (tkinter window), loads the local web UI (src/web/index.html + CSS + JS).
- web/ – static assets (HTML, CSS, JS) providing a chat‐style UI embedded in the tkinter window.

##### Key Components
a. GUI Layer (Frontend)
- tkinter main window hosting a tiny embedded browser (or webview) that renders src/web/index.html
- JavaScript + CSS (jquery.convform) for interactive chat widget
b. Voice I/O Layer
- SpeechRecognition module captures microphone input
- pyttsx3 module synthesizes voice responses
c. Core Processing Engine
- Proton.py orchestrates:
- Voice input → speech‐to‐text
- Command parsing / intent recognition (keyword‐based)
- Dispatch to appropriate action module
- Text output → text‐to‐speech
- Date/Time module (datetime)
- Web Search module (webbrowser + wikipedia API)
- Location Finder module (webbrowser → Google Maps)
- File Navigator module (os, list & read directories)
- Automation module (pyautogui, keyboard for simulating mouse/keyboard)
- Memory module (simple read/write from memory.txt)
e. Concurrency
- Python threading used to prevent blocking UI during speech recognition and long‐running tasks
f. External Services
- Wikipedia API
- Google Search / Google Maps (via default web browser)

##### Relationships and Data Flows
- User speaks → Microphone → SpeechRecognition → Core Engine
- Core Engine parses → selects an Action Module → executes (e.g., opens browser, lists files)
- Action result → Core Engine → updates UI (chat HTML/JS) + sends text to pyttsx3 → audio response
- Core Engine optionally reads/writes memory.txt to store simple state
- UI events (button clicks, typed text) flow back into Core Engine via app.py

##### Architectural Patterns and Design Principles
- MVC-style separation:
- View = tkinter + web UI
- Controller = Proton.py (core engine)
- Model = Action Modules + memory.txt
- Plugin-style modularity: each “skill” is a self-contained module/function that the engine invokes
- Event-driven: voice OR UI events trigger the same central dispatcher
- Single-process, multi-threaded – no external servers or microservices

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User"]:::user
    User -->|"voice input"| SpeechRec
    User -->|"UI event"| GUI

    %% Voice I/O Layer
    SpeechRec["SpeechRecognition\n(microphone input)"]:::voiceIO
    VoiceSynth["pyttsx3\n(audio output)"]:::voiceIO

    %% Frontend Layer
    subgraph "Frontend (GUI + Web UI)"
        GUI["tkinter Window"]:::frontend
        WebUI["Embedded Browser\n(index.html)"]:::frontend
        CSS["jquery.convform.css"]:::frontend
        JS["main.js"]:::frontend
        AppInit["app.py"]:::frontend
    end

    %% Core Processing Engine
    Core["Proton.py\nCore Engine"]:::core

    %% Action Modules
    subgraph "Action Modules"
        DateTime["Date/Time Module"]:::action
        WebSearch["Web Search Module"]:::action
        Location["Location Finder Module"]:::action
        FileNav["File Navigator Module"]:::action
        Automation["Automation Module"]:::action
    end

    %% Persistence
    Memory["memory.txt"]:::storage

    %% External Services
    Wiki["Wikipedia API"]:::external
    Google["Google Search/Maps"]:::external

    %% Config & Assets
    Req["requirements.txt"]:::config
    Demo["demo_media/"]:::nonruntime
    StaticDir["src/web/"]:::nonruntime

    %% Data Flows
    SpeechRec -->|"text transcript"| Core
    GUI -->|"input event"| Core
    Core -->|"invoke module"| DateTime
    Core -->|"invoke module"| WebSearch
    Core -->|"invoke module"| Location
    Core -->|"invoke module"| FileNav
    Core -->|"invoke module"| Automation
    Core -->|"read/write"| Memory
    DateTime -->|"result data"| Core
    WebSearch -->|"API request"| Wiki
    WebSearch -->|"search result"| Core
    Location -->|"opens browser"| Google
    Location -->|"map result"| Core
    FileNav -->|"file list"| Core
    Automation -->|"action result"| Core
    Core -->|"update chat UI"| WebUI
    Core -->|"speak text"| VoiceSynth

    %% Click Events
    click AppInit "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/src/app.py"
    click WebUI "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/src/web/index.html"
    click CSS "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/src/web/css/jquery.convform.css"
    click JS "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/src/web/js/main.js"
    click Core "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/src/Proton.py"
    click Memory "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/memory.txt"
    click Req "https://github.com/harvinderkaur02/proton-voice-assistant/blob/main/requirements.txt"
    click Demo "https://github.com/harvinderkaur02/proton-voice-assistant/tree/main/demo_media/"
    click StaticDir "https://github.com/harvinderkaur02/proton-voice-assistant/tree/main/src/web/"

    %% Styles
    classDef user fill:#f2f2f2,stroke:#333;
    classDef frontend fill:#AED6F1,stroke:#1B4F72;
    classDef voiceIO fill:#ABEBC6,stroke:#1D8348;
    classDef core fill:#A9DFBF,stroke:#196F3D;
    classDef action fill:#D2B4DE,stroke:#6C3483;
    classDef storage fill:#F9E79F,stroke:#B9770E;
    classDef external fill:#D5DBDB,stroke:#566573,stroke-dasharray: 5 5;
    classDef config fill:#FADBD8,stroke:#C0392B;
    classDef nonruntime fill:#E5E7E9,stroke:#7B7D7D;
```
