# daniel-c-silva/clanka architecture

> Architecture diagram of the GitHub repository daniel-c-silva/clanka, 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/daniel-c-silva/clanka
- Repository: https://github.com/daniel-c-silva/clanka

## Overview

Clanka combines a browser-based voice chat interface with a Flask conversational backend and a separate motor-control path for the physical robot. The primary interaction is user speech → browser transcription → `/chat` → Mistral answer and emotion plus session memory → browser speech playback. The backend retains the last five exchanges per session. Motor commands travel through Python serial helpers to Arduino stepper drivers, but the shown backend does not connect that path to chat. README-documented hardware and interface capabilities are represented; unsampled implementation details are not inferred.

Main entry points: [`backend/main.py`](https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py) (Response generation), [`frontend/src/App.jsx`](https://github.com/daniel-c-silva/clanka/blob/main/frontend/src/App.jsx) (Voice chat UI), [`backend/movement.py`](https://github.com/daniel-c-silva/clanka/blob/main/backend/movement.py) (Serial movement helpers), [`arduino/main.cpp`](https://github.com/daniel-c-silva/clanka/blob/main/arduino/main.cpp) (Motor command firmware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Voice interface"]
  node_app["Voice chat UI<br/>[App.jsx]"]
  node_speech["Browser speech APIs"]
  node_session[("Session ID storage")]
end

subgraph group_backend["Chat backend"]
  node_route["Chat endpoint<br/>[main.py]"]
  node_response["Response generation<br/>[main.py]"]
  node_context["Conversation context<br/>[main.py]"]
  node_memory[("Session memory<br/>[main.py]")]
end

subgraph group_robot["Robot motion"]
  node_movement["Serial movement helpers<br/>[movement.py]"]
  node_serial["USB serial link"]
  node_arduino["Motor command firmware<br/>[main.cpp]"]
end

node_user(("User"))
node_mistral["Mistral AI"]
node_raspberry["Raspberry Pi"]
node_motors["Stepper motors"]

node_user -->|"speaks to"| node_app
node_app -->|"transcribes and speaks"| node_speech
node_app -->|"reads and writes"| node_session
node_app -->|"POSTs chat"| node_route
node_route -->|"invokes"| node_response
node_response -->|"loads"| node_context
node_context -->|"reads recent turns"| node_memory
node_response -->|"requests answer and emotion"| node_mistral
node_response -->|"stores exchange"| node_memory
node_response -->|"returns answer and emotion"| node_route
node_route -->|"returns JSON"| node_app
node_raspberry -.->|"runs"| node_movement
node_movement -->|"writes commands"| node_serial
node_serial -->|"transmits commands"| node_arduino
node_arduino -->|"steps drivers"| node_motors

click node_app "https://github.com/daniel-c-silva/clanka/blob/main/frontend/src/App.jsx"
click node_route "https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py"
click node_response "https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py"
click node_context "https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py"
click node_memory "https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py"
click node_movement "https://github.com/daniel-c-silva/clanka/blob/main/backend/movement.py"
click node_arduino "https://github.com/daniel-c-silva/clanka/blob/main/arduino/main.cpp"

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_app,node_speech,node_session,node_user toneBlue
class node_route,node_response,node_context,node_memory toneAmber
class node_movement,node_serial,node_arduino toneMint
class node_mistral,node_raspberry,node_motors toneIndigo
```

## Components

### Voice interface

- [Voice chat UI](https://github.com/daniel-c-silva/clanka/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- **Browser speech APIs**
- **Session ID storage**

### Chat backend

- [Chat endpoint](https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py): `backend/main.py`
- [Response generation](https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py): `backend/main.py`
- [Conversation context](https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py): `backend/main.py`
- [Session memory](https://github.com/daniel-c-silva/clanka/blob/main/backend/main.py): `backend/main.py`

### Robot motion

- [Serial movement helpers](https://github.com/daniel-c-silva/clanka/blob/main/backend/movement.py): `backend/movement.py`
- **USB serial link**
- [Motor command firmware](https://github.com/daniel-c-silva/clanka/blob/main/arduino/main.cpp): `arduino/main.cpp`

### Other components

- **User**
- **Mistral AI**
- **Raspberry Pi**
- **Stepper motors**

## Connections

- User → Voice chat UI: speaks to (evidence: `frontend/src/App.jsx`)
- Voice chat UI → Browser speech APIs: transcribes and speaks (evidence: `frontend/src/App.jsx`)
- Voice chat UI → Session ID storage: reads and writes (evidence: `frontend/src/App.jsx`)
- Voice chat UI → Chat endpoint: POSTs chat (evidence: `frontend/src/App.jsx`)
- Chat endpoint → Response generation: invokes (evidence: `backend/main.py`)
- Response generation → Conversation context: loads (evidence: `backend/main.py`)
- Conversation context → Session memory: reads recent turns (evidence: `backend/main.py`)
- Response generation → Mistral AI: requests answer and emotion (evidence: `backend/main.py`)
- Response generation → Session memory: stores exchange (evidence: `backend/main.py`)
- Response generation → Chat endpoint: returns answer and emotion (evidence: `backend/main.py`)
- Chat endpoint → Voice chat UI: returns JSON (evidence: `frontend/src/App.jsx`)
- Raspberry Pi → Serial movement helpers: runs
- Serial movement helpers → USB serial link: writes commands (evidence: `backend/movement.py`)
- USB serial link → Motor command firmware: transmits commands (evidence: `arduino/main.cpp`)
- Motor command firmware → Stepper motors: steps drivers (evidence: `arduino/main.cpp`)
