# hemanthreddykunduru/locally-runnable-3d-character- architecture

> Architecture diagram of the GitHub repository hemanthreddykunduru/locally-runnable-3d-character-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hemanthreddykunduru/locally-runnable-3d-character-
- Repository: https://github.com/hemanthreddykunduru/locally-runnable-3d-character-

## Overview

This is a small Flask-backed VRM speech-avatar app. A user submits text to the speak API; the server converts it to IPA and speech, analyzes the generated audio, and returns audio plus timed phoneme/viseme cues for a client to animate an avatar. The source also exposes routes for the home page, VRM model, and vendor assets. The tree omits those served assets and the browser implementation, so their internal behavior and wiring cannot be mapped; relationships below follow only the sampled server code.

Main entry points: [`app.py`](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py) (Speak API), [`package.json`](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/package.json) (Three.js VRM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP interface"]
  node_speak["Speak API<br/>[app.py]"]
  node_site_routes["Site and asset routes<br/>[app.py]"]
  node_response["Speech response<br/>[app.py]"]
  node_vrm_model["VRM model route<br/>[app.py]"]
  node_static_assets["Vendor asset route<br/>[app.py]"]
end

subgraph group_speech["Speech processing"]
  node_ipa["IPA conversion"]
  node_phoneme_parse["Phoneme parsing<br/>[app.py]"]
  node_tts["Speech synthesis<br/>[app.py]"]
end

subgraph group_animation["Audio animation"]
  node_wav_read["WAV decoding<br/>[app.py]"]
  node_audio_analysis["Audio envelope<br/>[app.py]"]
  node_cue_builder["Viseme cue timing<br/>[app.py]"]
  node_emotion["Emotion detection<br/>[app.py]"]
end

node_user(("User"))
node_tts_engine["System TTS engine"]
node_avatar_client["Avatar client"]
node_three_vrm["Three.js VRM<br/>[package.json]"]

node_user -->|"submits text"| node_speak
node_speak -->|"converts text"| node_ipa
node_speak -->|"parses IPA"| node_phoneme_parse
node_speak -->|"requests speech"| node_tts
node_tts -->|"synthesizes audio"| node_tts_engine
node_tts -->|"decodes WAV"| node_wav_read
node_speak -->|"analyzes samples"| node_audio_analysis
node_speak -->|"builds cues"| node_cue_builder
node_speak -->|"detects emotion"| node_emotion
node_speak -->|"returns JSON"| node_response
node_response -->|"delivers audio and cues"| node_user
node_user -->|"requests assets"| node_site_routes
node_site_routes -->|"serves home page"| node_avatar_client
node_user -->|"requests model"| node_vrm_model
node_user -->|"requests vendor files"| node_static_assets
node_avatar_client -.->|"uses integration"| node_three_vrm

click node_speak "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_site_routes "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_phoneme_parse "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_tts "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_wav_read "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_audio_analysis "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_cue_builder "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_emotion "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_response "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_vrm_model "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_static_assets "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py"
click node_three_vrm "https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/package.json"

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_speak,node_site_routes,node_response,node_vrm_model,node_static_assets,node_user,node_avatar_client toneBlue
class node_ipa,node_phoneme_parse,node_tts toneAmber
class node_wav_read,node_audio_analysis,node_cue_builder,node_emotion toneMint
class node_tts_engine toneIndigo
class node_three_vrm toneTeal
```

## Components

### HTTP interface

- [Speak API](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Site and asset routes](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Speech response](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [VRM model route](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Vendor asset route](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`

### Speech processing

- **IPA conversion**
- [Phoneme parsing](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Speech synthesis](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`

### Audio animation

- [WAV decoding](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Audio envelope](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Viseme cue timing](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`
- [Emotion detection](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/app.py): `app.py`

### Other components

- **User**
- **System TTS engine**
- **Avatar client**
- [Three.js VRM](https://github.com/hemanthreddykunduru/locally-runnable-3d-character-/blob/main/package.json): `package.json`

## Connections

- User → Speak API: submits text
- Speak API → IPA conversion: converts text
- Speak API → Phoneme parsing: parses IPA
- Speak API → Speech synthesis: requests speech
- Speech synthesis → System TTS engine: synthesizes audio
- Speech synthesis → WAV decoding: decodes WAV
- Speak API → Audio envelope: analyzes samples
- Speak API → Viseme cue timing: builds cues
- Speak API → Emotion detection: detects emotion
- Speak API → Speech response: returns JSON
- Speech response → User: delivers audio and cues
- User → Site and asset routes: requests assets
- Site and asset routes → Avatar client: serves home page
- User → VRM model route: requests model
- User → Vendor asset route: requests vendor files
- Avatar client → Three.js VRM: uses integration