# marvel420-code/voxmate_ai_assitant architecture

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

- Interactive diagram: https://gitdiagram.com/marvel420-code/voxmate_ai_assitant
- Repository: https://github.com/marvel420-code/voxmate_ai_assitant

## Overview

VoxMate’s main workflow starts with face authentication, then launches a LiveKit voice assistant that uses prompt-defined behavior and registered tools to answer requests or perform actions. The tool suite covers weather, web search, email, and browser-based YouTube and Instagram access. Face matching uses local authorized images and DeepFace; the assistant uses Google’s realtime model through LiveKit. The README describes these product capabilities; implementation links below are limited to relationships visible in the excerpts.

Main entry points: [`tools.py`](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py) (Tool suite), [`face_auth_deepface.py`](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/face_auth_deepface.py) (Face authentication), [`agent.py`](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py) (Assistant definition), [`prompts.py`](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/prompts.py) (Assistant prompts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and access"]
  node_launcher["App launcher<br/>[agent.py]"]
  node_face_auth["Face authentication"]
  node_authorized_faces[("Authorized images")]
end

subgraph group_assistant["Assistant runtime"]
  node_agent_entry["LiveKit entrypoint<br/>[agent.py]"]
  node_assistant_definition["Assistant definition<br/>[agent.py]"]
  node_prompts["Assistant prompts<br/>[prompts.py]"]
end

subgraph group_tools["Assistant tools"]
  node_tool_suite["Tool suite<br/>[tools.py]"]
  node_weather["Weather lookup<br/>[tools.py]"]
  node_web_search["Web search<br/>[tools.py]"]
  node_email["Email sending<br/>[tools.py]"]
  node_youtube["YouTube access<br/>[tools.py]"]
  node_instagram["Instagram access<br/>[tools.py]"]
end

subgraph group_integrations["External integrations"]
  node_webcam["Webcam"]
  node_deepface["DeepFace"]
  node_livekit["LiveKit session"]
  node_google_model["Google realtime model"]
  node_weather_service["wttr.in"]
  node_duckduckgo["DuckDuckGo search"]
  node_gmail["Gmail SMTP"]
  node_edge["Microsoft Edge"]
end

node_user(("User"))

node_user -->|"starts"| node_launcher
node_launcher -->|"authenticates first"| node_face_auth
node_face_auth -->|"loads images"| node_authorized_faces
node_face_auth -->|"captures frames"| node_webcam
node_face_auth -->|"verifies faces"| node_deepface
node_launcher -->|"starts worker"| node_agent_entry
node_agent_entry -->|"starts session"| node_assistant_definition
node_assistant_definition -->|"uses instructions"| node_prompts
node_assistant_definition -->|"registers tools"| node_tool_suite
node_agent_entry -->|"starts and connects"| node_livekit
node_assistant_definition -->|"configures model"| node_google_model
node_tool_suite -->|"provides lookup"| node_weather
node_tool_suite -->|"provides search"| node_web_search
node_tool_suite -->|"provides sending"| node_email
node_tool_suite -->|"provides access"| node_youtube
node_tool_suite -->|"provides access"| node_instagram
node_weather -->|"requests forecast"| node_weather_service
node_web_search -->|"runs search"| node_duckduckgo
node_email -->|"sends via SMTP"| node_gmail
node_youtube -->|"opens video"| node_edge
node_instagram -->|"opens site"| node_edge

click node_launcher "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py"
click node_face_auth "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/face_auth_deepface.py"
click node_authorized_faces "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/face_auth_deepface.py"
click node_agent_entry "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py"
click node_assistant_definition "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py"
click node_prompts "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/prompts.py"
click node_tool_suite "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py"
click node_weather "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py"
click node_web_search "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py"
click node_email "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py"
click node_youtube "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py"
click node_instagram "https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.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_launcher,node_face_auth,node_authorized_faces,node_user toneBlue
class node_agent_entry,node_assistant_definition,node_prompts toneAmber
class node_tool_suite,node_weather,node_web_search,node_email,node_youtube,node_instagram toneMint
class node_webcam,node_deepface,node_livekit,node_google_model,node_weather_service,node_duckduckgo,node_gmail,node_edge toneRose
```

## Components

### Startup and access

- [App launcher](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py): `agent.py`
- [Face authentication](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/face_auth_deepface.py): `face_auth_deepface.py`
- [Authorized images](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/face_auth_deepface.py): `face_auth_deepface.py`

### Assistant runtime

- [LiveKit entrypoint](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py): `agent.py`
- [Assistant definition](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/agent.py): `agent.py`
- [Assistant prompts](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/prompts.py): `prompts.py`

### Assistant tools

- [Tool suite](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py): `tools.py`
- [Weather lookup](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py): `tools.py`
- [Web search](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py): `tools.py`
- [Email sending](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py): `tools.py`
- [YouTube access](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py): `tools.py`
- [Instagram access](https://github.com/marvel420-code/voxmate_ai_assitant/blob/main/tools.py): `tools.py`

### External integrations

- **Webcam**
- **DeepFace**
- **LiveKit session**
- **Google realtime model**
- **wttr.in**
- **DuckDuckGo search**
- **Gmail SMTP**
- **Microsoft Edge**

### Other components

- **User**

## Connections

- User → App launcher: starts (evidence: `README.md`)
- App launcher → Face authentication: authenticates first (evidence: `agent.py`)
- Face authentication → Authorized images: loads images (evidence: `face_auth_deepface.py`)
- Face authentication → Webcam: captures frames (evidence: `face_auth_deepface.py`)
- Face authentication → DeepFace: verifies faces (evidence: `face_auth_deepface.py`)
- App launcher → LiveKit entrypoint: starts worker (evidence: `agent.py`)
- LiveKit entrypoint → Assistant definition: starts session (evidence: `agent.py`)
- Assistant definition → Assistant prompts: uses instructions (evidence: `agent.py`)
- Assistant definition → Tool suite: registers tools (evidence: `agent.py`)
- LiveKit entrypoint → LiveKit session: starts and connects (evidence: `agent.py`)
- Assistant definition → Google realtime model: configures model (evidence: `agent.py`)
- Tool suite → Weather lookup: provides lookup (evidence: `tools.py`)
- Tool suite → Web search: provides search (evidence: `tools.py`)
- Tool suite → Email sending: provides sending (evidence: `tools.py`)
- Tool suite → YouTube access: provides access (evidence: `tools.py`)
- Tool suite → Instagram access: provides access (evidence: `tools.py`)
- Weather lookup → wttr.in: requests forecast (evidence: `tools.py`)
- Web search → DuckDuckGo search: runs search (evidence: `tools.py`)
- Email sending → Gmail SMTP: sends via SMTP (evidence: `tools.py`)
- YouTube access → Microsoft Edge: opens video (evidence: `tools.py`)
- Instagram access → Microsoft Edge: opens site (evidence: `tools.py`)
