# mralihasan/sophia-ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/mralihasan/sophia-ai-assistant
- Repository: https://github.com/mralihasan/sophia-ai-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack desktop AI assistant application.
- Purpose: Provide conversational AI features (via Hugging Face API), voice/text activation, OS automation (apps, websites, calls), and multimedia control, all wrapped in a local Python server + HTML/JS frontend.

##### File Structure
- Top‐level:
- engine/ — core Python logic (command parsing, configuration, DB access, feature implementations)
- main.py — launches the Python server (Eel or Bottle/Flask) and initializes the engine
- sophia.db — SQLite database for storing configuration, user data, custom apps/websites
- www/ — static frontend (HTML, CSS, JS, audio assets, vendor libraries)
- Key config files: engine/config.py
- Build/deploy: the Python runtime bundles the www folder via Eel (or Flask + bottle-websocket) to render a Chromium window as the UI.

##### Additional Insights from README
- Backend: Python + Eel (for desktop GUI) and/or Flask + bottle-websocket to serve API endpoints.
- Frontend: HTML/CSS/JS (uses Bootstrap, vendor scripts for text animation).
- Database: SQLite.
- External services: Hugging Face API for chat, OS APIs for speech recognition (pyaudio, pocketsphinx), automation (PyAutoGUI, PyGetWindow), telephony (pywhatkit).

##### Main Components
a. Frontend UI
- Browser window (Eel) hosting www/index.html, controller.js, main.js
- Assets: CSS (www/style.css), audio cues, vendor animations
b. Backend Server
- main.py → initializes Eel/Flask server
- HTTP/WebSocket endpoints (bottle-websocket or eel.expose) for user commands
- Speech recognition and TTS modules (PyAudio, pvporcupine, pyttsx3)
c. Engine Modules (engine/)
- command.py: maps textual commands to feature calls
- features.py: implements actions (open app, search YouTube, make calls, etc.)
- db.py: CRUD interface to sophia.db
- config.py: loads/stores configuration
d. Database
- SQLite file (sophia.db) storing user preferences, custom apps/websites
e. External Services
- Hugging Face API
- Operating System (Windows) for app control
- Web browsers (for site navigation / YouTube)
- Telephony/WhatsApp via pywhatkit

##### Relationships and Data Flow
- User speaks or types → Frontend captures input → Sent via WebSocket/HTTP to Backend
- Backend → SpeechRecognition (if voice) → engine.command.parse() → engine.features.execute()
- If NLP: Backend → Hugging Face API → engine.command receives response
- engine.features may read/write sophia.db via engine.db
- Result (text reply, OS action) returned → Backend sends it back to Frontend → UI updates + TTS speaks

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Presentation layer (www/)
- Application layer (Python server & engine)
- Data layer (SQLite)
- Modular design: engine components decoupled (config, db, features)
- Event-driven communication: WebSocket or Eel RPC for real-time interactions
- Extensibility: add new features by extending engine/features.py and wiring commands in command.py

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend UI" 
        direction TB
        Index["index.html"]:::frontend
        Controller["controller.js"]:::frontend
        MainJS["main.js"]:::frontend
        Style["style.css"]:::frontend
        AudioAssets["Audio Assets"]:::frontend
        ImgAssets["Image Assets"]:::frontend
        VendorLibs["Vendor Libraries"]:::frontend
    end

    %% Backend & Engine Layer
    subgraph "Backend & Engine" 
        direction TB
        Server["Eel/Flask Server\n(main.py)"]:::backend
        Endpoints["WebSocket/HTTP Endpoints"]:::backend
        subgraph "Engine Modules"
            direction TB
            Config["Config Module\n(engine/config.py)"]:::backend
            Command["Command Parser\n(engine/command.py)"]:::backend
            Features["Features Executor\n(engine/features.py)"]:::backend
            DBModule["DB Interface\n(engine/db.py)"]:::backend
        end
    end

    %% Database
    DB["SQLite Database\n(sophia.db)"]:::db

    %% External Services
    subgraph "External Services"
        direction TB
        HF["Hugging Face API"]:::external
        OSAuto["OS Automation"]:::external
        Telephony["Telephony/WhatsApp"]:::external
        BrowserExt["Web Browser Control"]:::external
    end

    %% Connections
    Index -->|WebSocket/HTTP| Endpoints
    Controller -->|WebSocket/HTTP| Endpoints
    MainJS -->|WebSocket/HTTP| Endpoints

    Endpoints -->|RPC calls| Command
    Endpoints -->|HTTP/WebSocket| Server
    Server -->|parses| Command
    Server -->|uses| Config

    Command -->|invoke| Features
    Command -->|load config| Config

    Features -->|CRUD| DBModule
    DBModule -->|reads/writes| DB

    Features -->|NLP request| HF
    HF -->|response| Command

    Features -->|automate| OSAuto
    Features -->|control browser| BrowserExt
    Features -->|call/send| Telephony

    Features -->|response| Server
    Server -->|send result| Endpoints
    Endpoints -->|update UI| MainJS

    %% Click Events
    click Index "https://github.com/mralihasan/sophia-ai-assistant/blob/master/www/index.html"
    click Controller "https://github.com/mralihasan/sophia-ai-assistant/blob/master/www/controller.js"
    click MainJS "https://github.com/mralihasan/sophia-ai-assistant/blob/master/www/main.js"
    click Style "https://github.com/mralihasan/sophia-ai-assistant/blob/master/www/style.css"
    click AudioAssets "https://github.com/mralihasan/sophia-ai-assistant/tree/master/www/assets/audio/"
    click ImgAssets "https://github.com/mralihasan/sophia-ai-assistant/tree/master/www/assets/img/"
    click VendorLibs "https://github.com/mralihasan/sophia-ai-assistant/tree/master/www/assets/vendore/texllate/"
    click Server "https://github.com/mralihasan/sophia-ai-assistant/blob/master/main.py"
    click Command "https://github.com/mralihasan/sophia-ai-assistant/blob/master/engine/command.py"
    click Features "https://github.com/mralihasan/sophia-ai-assistant/blob/master/engine/features.py"
    click DBModule "https://github.com/mralihasan/sophia-ai-assistant/blob/master/engine/db.py"
    click Config "https://github.com/mralihasan/sophia-ai-assistant/blob/master/engine/config.py"
    click DB "https://github.com/mralihasan/sophia-ai-assistant/blob/master/sophia.db"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef db fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
