# rhythmic-code/smart_scheduler architecture

> Architecture diagram of the GitHub repository rhythmic-code/smart_scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rhythmic-code/smart_scheduler
- Repository: https://github.com/rhythmic-code/smart_scheduler

## Overview

Smart Scheduler is a voice-driven meeting assistant. Its active `main.py` loop gathers spoken preferences, offers conflict-free calendar slots, and creates an event after confirmation. A separate conversation-agent implementation supports LLM-based intent extraction and calendar queries, but the sampled active loop does not invoke it. The README also documents voice I/O, timezone-aware scheduling, and calendar integration. The graph reflects these distinct paths; unsampled wiring is omitted.

Main entry points: [`services/calendar_service.py`](https://github.com/rhythmic-code/smart_scheduler/blob/main/services/calendar_service.py) (Calendar service), [`main.py`](https://github.com/rhythmic-code/smart_scheduler/blob/main/main.py) (Scheduler loop), [`agents/calendar_agent.py`](https://github.com/rhythmic-code/smart_scheduler/blob/main/agents/calendar_agent.py) (Calendar agent), [`config.py`](https://github.com/rhythmic-code/smart_scheduler/blob/main/config.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Voice interaction"]
  node_main["Scheduler loop<br/>[main.py]"]
  node_voice["Voice interface<br/>[voice_service.py]"]
end

subgraph group_conversation["Conversation intelligence"]
  node_agent["Conversation agent"]
  node_llm["LLM service<br/>[llm_service.py]"]
  node_time["Date parsing<br/>[time_utils.py]"]
end

subgraph group_calendar["Calendar scheduling"]
  node_calagent["Calendar agent<br/>[calendar_agent.py]"]
  node_calendarservice["Calendar service"]
end

subgraph group_foundation["Configuration and auth"]
  node_config["Runtime settings<br/>[config.py]"]
  node_auth["OAuth credentials<br/>[auth.py]"]
end

node_user(("User"))
node_google["Google Calendar"]

node_user -->|"speaks to"| node_main
node_main -->|"speaks response"| node_user
node_main -->|"checks slots"| node_calendarservice
node_main -->|"creates event"| node_calendarservice
node_user -.->|"provides audio"| node_voice
node_voice -.->|"plays speech"| node_user
node_agent -->|"extracts intent"| node_llm
node_agent -->|"queries events"| node_calagent
node_agent -->|"parses dates"| node_time
node_calagent -->|"parses constraints"| node_time
node_calagent -->|"finds slots"| node_calendarservice
node_calagent -->|"schedules event"| node_calendarservice
node_calendarservice -->|"reads and writes"| node_google
node_calendarservice -->|"reads settings"| node_config
node_llm -->|"reads settings"| node_config
node_voice -->|"reads settings"| node_config
node_auth -->|"reads credentials paths"| node_config

click node_main "https://github.com/rhythmic-code/smart_scheduler/blob/main/main.py"
click node_voice "https://github.com/rhythmic-code/smart_scheduler/blob/main/services/voice_service.py"
click node_agent "https://github.com/rhythmic-code/smart_scheduler/blob/main/agents/conversation_agent.py"
click node_llm "https://github.com/rhythmic-code/smart_scheduler/blob/main/services/llm_service.py"
click node_time "https://github.com/rhythmic-code/smart_scheduler/blob/main/utils/time_utils.py"
click node_calagent "https://github.com/rhythmic-code/smart_scheduler/blob/main/agents/calendar_agent.py"
click node_calendarservice "https://github.com/rhythmic-code/smart_scheduler/blob/main/services/calendar_service.py"
click node_config "https://github.com/rhythmic-code/smart_scheduler/blob/main/config.py"
click node_auth "https://github.com/rhythmic-code/smart_scheduler/blob/main/gcal/auth.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_voice,node_user toneBlue
class node_agent,node_llm,node_time toneAmber
class node_calagent,node_calendarservice toneMint
class node_config,node_auth toneRose
class node_google toneIndigo
```

## Components

### Voice interaction

- [Scheduler loop](https://github.com/rhythmic-code/smart_scheduler/blob/main/main.py): `main.py`
- [Voice interface](https://github.com/rhythmic-code/smart_scheduler/blob/main/services/voice_service.py): `services/voice_service.py`

### Conversation intelligence

- [Conversation agent](https://github.com/rhythmic-code/smart_scheduler/blob/main/agents/conversation_agent.py): `agents/conversation_agent.py`
- [LLM service](https://github.com/rhythmic-code/smart_scheduler/blob/main/services/llm_service.py): `services/llm_service.py`
- [Date parsing](https://github.com/rhythmic-code/smart_scheduler/blob/main/utils/time_utils.py): `utils/time_utils.py`

### Calendar scheduling

- [Calendar agent](https://github.com/rhythmic-code/smart_scheduler/blob/main/agents/calendar_agent.py): `agents/calendar_agent.py`
- [Calendar service](https://github.com/rhythmic-code/smart_scheduler/blob/main/services/calendar_service.py): `services/calendar_service.py`

### Configuration and auth

- [Runtime settings](https://github.com/rhythmic-code/smart_scheduler/blob/main/config.py): `config.py`
- [OAuth credentials](https://github.com/rhythmic-code/smart_scheduler/blob/main/gcal/auth.py): `gcal/auth.py`

### Other components

- **User**
- **Google Calendar**

## Connections

- User → Scheduler loop: speaks to
- Scheduler loop → User: speaks response
- Scheduler loop → Calendar service: checks slots
- Scheduler loop → Calendar service: creates event
- User → Voice interface: provides audio
- Voice interface → User: plays speech
- Conversation agent → LLM service: extracts intent
- Conversation agent → Calendar agent: queries events
- Conversation agent → Date parsing: parses dates
- Calendar agent → Date parsing: parses constraints
- Calendar agent → Calendar service: finds slots
- Calendar agent → Calendar service: schedules event
- Calendar service → Google Calendar: reads and writes
- Calendar service → Runtime settings: reads settings
- LLM service → Runtime settings: reads settings
- Voice interface → Runtime settings: reads settings
- OAuth credentials → Runtime settings: reads credentials paths