# mohitxhkr/smart-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/mohitxhkr/smart-scheduler
- Repository: https://github.com/mohitxhkr/smart-scheduler

## Overview

##### Project type and purpose
- This is a full-stack “voice & text” scheduling assistant.
- It provides two frontends:
- Desktop/CLI voice agent (main.py + voice_agent.py + audio I/O libs)
- Web UI via Streamlit (app.py)
- It orchestrates speech-to-text (Whisper), intent understanding (OpenRouter LLM), date parsing, calendar integration (Google Calendar API), and text-to-speech (ElevenLabs).

##### File structure
- Top-level scripts:
- main.py – desktop entrypoint
- app.py – Streamlit web entrypoint
- Core modules:
- voice_agent.py – audio capture/playback and CLI loop
- llm_engine.py – OpenRouter LLM wrapper and intent extraction
- calendar_api.py – Google Calendar client and event creation
- calendar/date-parsing – uses dateparser & pytz (invoked in llm_engine or a helper)
- Config & dependencies:
- requirements.txt, .env for API keys, credentials.json for Google OAuth

##### README insights
- Pipeline stages are clearly defined (STT → NLU → parse → confirm → API call → TTS/UI feedback).
- Tech stack table highlights key libraries/services.
- Workflow section describes user interaction and sequencing.

##### Main components and their relationships
a. Frontend layer
- Voice/CLI frontend (main.py + voice_agent.py + sounddevice/pygame/scipy)
- Web frontend (app.py + Streamlit UI + chat history)
b. Application layer
- Orchestrator logic in main.py/app.py that drives the pipeline
c. Processing services
1. ASR Service – OpenAI Whisper
2. NLU/Intent Engine – OpenRouter via llm_engine.py
3. Date/Time Parser – dateparser & pytz (inline in llm_engine or helper)
4. Confirmation Flow – simple yes/no prompt in UI or voice
5. Calendar Integration – calendar_api.py talking to Google Calendar REST API
6. TTS Service – ElevenLabs
d. External services
- OpenRouter API
- Google Calendar API
- ElevenLabs TTS
- Whisper (local or OpenAI endpoint)
e. Configuration & Auth
- .env for LLM/TTS keys
- credentials.json for Google API

##### Architectural patterns & design principles
- Modular pipeline: each processing step is isolated in its own module
- Separation of concerns: UI layer vs. service layer vs. external integrations
- Single orchestrator per interface (desktop vs. web)
- Environment-driven configuration for secrets

##### Detail without over-complication
- Don’t merge ASR & LLM—show them as distinct processing steps.
- Both user pathways (voice vs. text) converging into the same pipeline.
- Keep the visual hierarchy: frontends on top, pipeline in middle, external services at edges, config store aside.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Presentation Layer"
        Desktop["Desktop Voice Agent\n(main.py + voice_agent.py)"]:::internal
        WebUI["Web Frontend\n(app.py)"]:::internal
    end

    Desktop -->|"voice/text input"| Orchestrator["Orchestrator\n(main.py / app.py)"]:::internal
    WebUI -->|"text input"| Orchestrator

    click Desktop "https://github.com/mohitxhkr/smart-scheduler/blob/main/main.py"
    click Desktop "https://github.com/mohitxhkr/smart-scheduler/blob/main/voice_agent.py"
    click WebUI "https://github.com/mohitxhkr/smart-scheduler/blob/main/app.py"
    click Orchestrator "https://github.com/mohitxhkr/smart-scheduler/blob/main/main.py"
    click Orchestrator "https://github.com/mohitxhkr/smart-scheduler/blob/main/app.py"

    subgraph "Processing Services"
        ASR["Whisper ASR"]:::thirdparty
        NLU["OpenRouter LLM\n(Intent Engine)"]:::internal
        DateParser["Date/Time Parser\n(dateparser + pytz)"]:::thirdparty
        Confirmation["Confirmation Flow"]:::internal
        CalendarClient["Google Calendar API Client"]:::internal
        TTS["ElevenLabs TTS"]:::thirdparty
    end

    Orchestrator --> ASR --> NLU --> DateParser --> Confirmation --> CalendarClient --> TTS -->|results| Orchestrator

    click ASR "https://github.com/mohitxhkr/smart-scheduler/blob/main/voice_agent.py"
    click NLU "https://github.com/mohitxhkr/smart-scheduler/blob/main/llm_engine.py"
    click DateParser "https://github.com/mohitxhkr/smart-scheduler/blob/main/llm_engine.py"
    click CalendarClient "https://github.com/mohitxhkr/smart-scheduler/blob/main/calendar_api.py"
    click TTS "https://github.com/mohitxhkr/smart-scheduler/blob/main/voice_agent.py"

    ASR -->|"calls Whisper service"| WhisperCloud[(Whisper Service)]:::external
    NLU -->|"calls OpenRouter API"| OpenRouterCloud[(OpenRouter API)]:::external
    TTS -->|"calls ElevenLabs API"| ElevenLabsCloud[(ElevenLabs TTS API)]:::external
    CalendarClient -->|"calls Google Calendar REST API"| GoogleCalCloud[(Google Calendar REST API)]:::external

    subgraph "Configuration & Auth"
        Env[".env"]:::config
        Credentials["credentials.json"]:::config
    end

    Env --> Orchestrator
    Credentials --> Orchestrator

    subgraph Legend
        L1["Internal Modules"]:::internal
        L2["Third-Party Libraries"]:::thirdparty
        L3["External Services"]:::external
        L4["Config & Auth"]:::config
    end

    classDef internal fill:#D0E6FF,stroke:#0055CC,stroke-width:1px
    classDef thirdparty fill:#E6FFE6,stroke:#00AA00,stroke-width:1px
    classDef external fill:#FFE6CC,stroke:#CC6600,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#666666,stroke-width:1px
```
