# lokeshmuruganandham/voice-receptionist-v1 architecture

> Architecture diagram of the GitHub repository lokeshmuruganandham/voice-receptionist-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lokeshmuruganandham/voice-receptionist-v1
- Repository: https://github.com/lokeshmuruganandham/voice-receptionist-v1

## Overview

This is a voice-based appointment receptionist for Pawz Styling. A customer speaks; the runtime recognizes speech, sends the conversation to Gemini with booking instructions, speaks the reply, and saves a confirmed appointment to an Excel workbook. The main runtime is implemented in one script, so several responsibilities share its path. The README is empty; the graph reflects the sampled runtime source, not the separate test scripts.

Main entry points: [`receptionist-v1.py`](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py) (Receptionist runtime), [`appointments-v1.xlsx`](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/appointments-v1.xlsx) (Appointments workbook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Voice conversation"]
  node_runtime["Receptionist runtime<br/>[receptionist-v1.py]"]
  node_speech_recognition["Speech recognition<br/>[receptionist-v1.py]"]
  node_gemini{{"Gemini"}}
  node_response_cleanup["Response cleanup<br/>[receptionist-v1.py]"]
  node_speech_output["Speech output<br/>[receptionist-v1.py]"]
end

subgraph group_booking["Appointment booking"]
  node_booking_prompt["Booking instructions<br/>[receptionist-v1.py]"]
  node_appointment_data["Appointment data<br/>[receptionist-v1.py]"]
end

subgraph group_storage["Appointment storage"]
  node_excel_writer["Excel writer<br/>[receptionist-v1.py]"]
  node_appointments_workbook[("Appointments workbook")]
end

node_customer(("Customer"))

node_customer -->|"speaks to"| node_runtime
node_runtime -->|"captures speech"| node_speech_recognition
node_runtime -->|"sends turns"| node_gemini
node_booking_prompt -->|"guides booking"| node_gemini
node_gemini -->|"returns response"| node_runtime
node_runtime -->|"extracts JSON"| node_appointment_data
node_runtime -->|"cleans reply"| node_response_cleanup
node_runtime -->|"speaks reply"| node_speech_output
node_runtime -->|"saves confirmed"| node_excel_writer
node_excel_writer -->|"appends row"| node_appointments_workbook

click node_runtime "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_speech_recognition "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_booking_prompt "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_appointment_data "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_response_cleanup "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_speech_output "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_excel_writer "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py"
click node_appointments_workbook "https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/appointments-v1.xlsx"

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_runtime,node_speech_recognition,node_gemini,node_response_cleanup,node_speech_output toneBlue
class node_booking_prompt,node_appointment_data toneAmber
class node_excel_writer,node_appointments_workbook toneMint
class node_customer toneIndigo
```

## Components

### Voice conversation

- [Receptionist runtime](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`
- [Speech recognition](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`
- **Gemini**
- [Response cleanup](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`
- [Speech output](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`

### Appointment booking

- [Booking instructions](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`
- [Appointment data](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`

### Appointment storage

- [Excel writer](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/receptionist-v1.py): `receptionist-v1.py`
- [Appointments workbook](https://github.com/lokeshmuruganandham/voice-receptionist-v1/blob/main/appointments-v1.xlsx): `appointments-v1.xlsx`

### Other components

- **Customer**

## Connections

- Customer → Receptionist runtime: speaks to (evidence: `receptionist-v1.py`)
- Receptionist runtime → Speech recognition: captures speech (evidence: `receptionist-v1.py`)
- Receptionist runtime → Gemini: sends turns (evidence: `receptionist-v1.py`)
- Booking instructions → Gemini: guides booking (evidence: `receptionist-v1.py`)
- Gemini → Receptionist runtime: returns response (evidence: `receptionist-v1.py`)
- Receptionist runtime → Appointment data: extracts JSON (evidence: `receptionist-v1.py`)
- Receptionist runtime → Response cleanup: cleans reply (evidence: `receptionist-v1.py`)
- Receptionist runtime → Speech output: speaks reply (evidence: `receptionist-v1.py`)
- Receptionist runtime → Excel writer: saves confirmed (evidence: `receptionist-v1.py`)
- Excel writer → Appointments workbook: appends row (evidence: `receptionist-v1.py`)
