# kananyan2311/loona architecture

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

- Interactive diagram: https://gitdiagram.com/kananyan2311/loona
- Repository: https://github.com/kananyan2311/loona

## Overview

L.O.O.N.A. is a distributed companion rover: a Python brain coordinates vision, AI, memory, speech, music and navigation, with web and embedded controllers providing user interaction and physical control. The README documents the broader capabilities; sampled Python excerpts and the source index support the brain’s service relationships. Firmware and web UI internals were not sampled, so their connections are limited to documented architecture and capabilities.

Main entry points: [`module3_python_brain/main.py`](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/main.py) (Brain Server), [`module3_python_brain/memory_service.py`](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/memory_service.py) (Memory Vault), [`module1_head_cam/module1_head_cam.ino`](https://github.com/kananyan2311/loona/blob/main/module1_head_cam/module1_head_cam.ino) (Head Camera), [`module3_python_brain/vision_tracker.py`](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/vision_tracker.py) (Vision Tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_cockpit["Web Cockpit<br/>[index.html]"]
end

subgraph group_brain["Python Brain"]
  node_brain_server["Brain Server<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_services["Robot Services"]
  node_vision["Vision Tracking<br/>[vision_tracker.py]"]
  node_ai["AI Reasoning<br/>[ai_service.py]"]
  node_roam["Idle Roaming<br/>[roam_service.py]"]
  node_memory["Memory Vault<br/>[memory_service.py]"]
  node_database[("SQLite Memory<br/>[database.py]")]
  node_tts["Speech Synthesis<br/>[tts_service.py]"]
  node_spotify["Music Streaming<br/>[spotify_service.py]"]
  node_captures["Photo Captures"]
end

subgraph group_hardware["Embedded Hardware"]
  node_head["Head Camera"]
  node_camera_pins["Camera Pin Map<br/>[camera_pins.h]"]
  node_chassis["Chassis Motion"]
end

node_user(("User"))
node_gemini{{"Gemini AI"}}
node_music_service{{"Music Provider"}}

node_user -->|"operates"| node_cockpit
node_cockpit -.->|"controls via API"| node_brain_server
node_brain_server -->|"uses tracking"| node_vision
node_brain_server -->|"dispatches requests"| node_ai
node_brain_server -->|"coordinates roaming"| node_roam
node_brain_server -->|"updates vault"| node_memory
node_brain_server -->|"uses speech"| node_tts
node_brain_server -->|"controls playback"| node_spotify
node_brain_server -.->|"sends motion commands"| node_chassis
node_brain_server -.->|"coordinates streams"| node_head
node_brain_server -.->|"broadcasts telemetry"| node_cockpit
node_ai -->|"reads commands"| node_memory
node_memory -->|"reads and writes"| node_database
node_vision -->|"reads face records"| node_memory
node_ai -.->|"requests reasoning"| node_gemini
node_spotify -.->|"streams audio"| node_music_service
node_tts -.->|"streams speech audio"| node_head
node_head -.->|"uses pin definitions"| node_camera_pins
node_vision -.->|"receives camera feed"| node_head
node_brain_server -.->|"stores photos"| node_captures

click node_cockpit "https://github.com/kananyan2311/loona/blob/main/module4_webapp/index.html"
click node_brain_server "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/main.py"
click node_config "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/config.py"
click node_vision "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/vision_tracker.py"
click node_ai "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/ai_service.py"
click node_roam "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/roam_service.py"
click node_memory "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/memory_service.py"
click node_database "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/database.py"
click node_tts "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/tts_service.py"
click node_spotify "https://github.com/kananyan2311/loona/blob/main/module3_python_brain/spotify_service.py"
click node_head "https://github.com/kananyan2311/loona/blob/main/module1_head_cam/module1_head_cam.ino"
click node_camera_pins "https://github.com/kananyan2311/loona/blob/main/module1_head_cam/camera_pins.h"
click node_chassis "https://github.com/kananyan2311/loona/blob/main/module2_chassis_motion/module2_chassis_motion.ino"
click node_captures "https://github.com/kananyan2311/loona/tree/main/module3_python_brain/data/captures"

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_cockpit,node_user toneBlue
class node_brain_server,node_config toneAmber
class node_vision,node_ai,node_roam,node_memory,node_database,node_tts,node_spotify,node_captures toneMint
class node_head,node_camera_pins,node_chassis toneRose
class node_gemini,node_music_service toneIndigo
```

## Components

### User Interaction

- [Web Cockpit](https://github.com/kananyan2311/loona/blob/main/module4_webapp/index.html): `module4_webapp/index.html`

### Python Brain

- [Brain Server](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/main.py): `module3_python_brain/main.py`
- [Configuration](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/config.py): `module3_python_brain/config.py`

### Robot Services

- [Vision Tracking](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/vision_tracker.py): `module3_python_brain/vision_tracker.py`
- [AI Reasoning](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/ai_service.py): `module3_python_brain/ai_service.py`
- [Idle Roaming](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/roam_service.py): `module3_python_brain/roam_service.py`
- [Memory Vault](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/memory_service.py): `module3_python_brain/memory_service.py`
- [SQLite Memory](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/database.py): `module3_python_brain/database.py`
- [Speech Synthesis](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/tts_service.py): `module3_python_brain/tts_service.py`
- [Music Streaming](https://github.com/kananyan2311/loona/blob/main/module3_python_brain/spotify_service.py): `module3_python_brain/spotify_service.py`
- [Photo Captures](https://github.com/kananyan2311/loona/tree/main/module3_python_brain/data/captures): `module3_python_brain/data/captures`

### Embedded Hardware

- [Head Camera](https://github.com/kananyan2311/loona/blob/main/module1_head_cam/module1_head_cam.ino): `module1_head_cam/module1_head_cam.ino`
- [Camera Pin Map](https://github.com/kananyan2311/loona/blob/main/module1_head_cam/camera_pins.h): `module1_head_cam/camera_pins.h`
- [Chassis Motion](https://github.com/kananyan2311/loona/blob/main/module2_chassis_motion/module2_chassis_motion.ino): `module2_chassis_motion/module2_chassis_motion.ino`

### Other components

- **User**
- **Gemini AI**
- **Music Provider**

## Connections

- User → Web Cockpit: operates (evidence: `README.md`)
- Web Cockpit → Brain Server: controls via API (evidence: `README.md`)
- Brain Server → Vision Tracking: uses tracking (evidence: `module3_python_brain/main.py`)
- Brain Server → AI Reasoning: dispatches requests (evidence: `module3_python_brain/main.py`)
- Brain Server → Idle Roaming: coordinates roaming (evidence: `module3_python_brain/main.py`)
- Brain Server → Memory Vault: updates vault (evidence: `module3_python_brain/main.py`)
- Brain Server → Speech Synthesis: uses speech (evidence: `module3_python_brain/main.py`)
- Brain Server → Music Streaming: controls playback (evidence: `module3_python_brain/main.py`)
- Brain Server → Chassis Motion: sends motion commands (evidence: `README.md`)
- Brain Server → Head Camera: coordinates streams (evidence: `README.md`)
- Brain Server → Web Cockpit: broadcasts telemetry (evidence: `README.md`)
- AI Reasoning → Memory Vault: reads commands (evidence: `module3_python_brain/ai_service.py`)
- Memory Vault → SQLite Memory: reads and writes (evidence: `module3_python_brain/memory_service.py`)
- Vision Tracking → Memory Vault: reads face records (evidence: `module3_python_brain/vision_tracker.py`)
- AI Reasoning → Gemini AI: requests reasoning (evidence: `README.md`)
- Music Streaming → Music Provider: streams audio (evidence: `README.md`)
- Speech Synthesis → Head Camera: streams speech audio (evidence: `README.md`)
- Head Camera → Camera Pin Map: uses pin definitions (evidence: `README.md`)
- Vision Tracking → Head Camera: receives camera feed (evidence: `README.md`)
- Brain Server → Photo Captures: stores photos (evidence: `README.md`)