# rammeshgar/digital-twin-demo architecture

> Architecture diagram of the GitHub repository rammeshgar/digital-twin-demo, 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/rammeshgar/digital-twin-demo
- Repository: https://github.com/rammeshgar/digital-twin-demo

## Overview

Sadeq’s Interactive 3D Digital Twin is a browser-based portfolio guide. Visitors ask questions by text or voice; the browser can recognize speech or send a recording for transcription, then requests a grounded AI response. The interface presents the answer as chat and speech, coordinating lip movement and blended gestures while rendering the character. The graph preserves the documented animation, transcription, responsive, and fallback capabilities. Some links rely on README documentation because the corresponding browser request-handling code was not included in the excerpts.

Main entry points: [`mascot.js`](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js) (Experience controller), [`netlify/functions/chat.js`](https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/chat.js) (Chat service), [`index.html`](https://github.com/rammeshgar/digital-twin-demo/blob/main/index.html) (Chat interface), [`movement.mjs`](https://github.com/rammeshgar/digital-twin-demo/blob/main/movement.mjs) (Gesture blending)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_interface["Chat interface<br/>[index.html]"]
  node_experience["Experience controller<br/>[mascot.js]"]
  node_speech_recognition["Speech recognition<br/>[mascot.js]"]
  node_audio_capture["Audio capture<br/>[mascot.js]"]
  node_chat_transcript["Chat transcript<br/>[mascot.js]"]
  node_speech_playback["Speech playback<br/>[mascot.js]"]
  node_responsive_styles["Responsive styling<br/>[style.css]"]
end

subgraph group_character["Character animation"]
  node_lip_sync["Viseme lip sync<br/>[mascot.js]"]
  node_character_render["3D rendering<br/>[mascot.js]"]
  node_character_refinement["Character refinement"]
  node_character_model["Digital twin model"]
  node_movement["Gesture blending<br/>[movement.mjs]"]
  node_gesture_library["Gesture library<br/>[gestures.json]"]
  node_presence["Idle presence<br/>[presence.mjs]"]
end

subgraph group_backend["Serverless services"]
  node_transcription["Audio transcription<br/>[transcribe.js]"]
  node_chat_api["Chat service<br/>[chat.js]"]
end

subgraph group_knowledge["Grounded knowledge"]
  node_knowledge_context["Knowledge context<br/>[chat.js]"]
  node_persona["Persona guidance<br/>[persona.md]"]
  node_source_truth["Professional source"]
end

node_visitor(("Visitor"))
node_gemini["Gemini"]
node_elevenlabs["ElevenLabs"]

node_visitor -->|"asks"| node_interface
node_interface -->|"controls"| node_experience
node_experience -->|"starts recognition"| node_speech_recognition
node_experience -->|"records audio"| node_audio_capture
node_audio_capture -->|"submits recording"| node_transcription
node_speech_recognition -->|"provides text"| node_experience
node_transcription -->|"returns transcript"| node_experience
node_experience -->|"sends question"| node_chat_api
node_chat_api -->|"builds context"| node_knowledge_context
node_knowledge_context -->|"reads"| node_persona
node_knowledge_context -->|"reads"| node_source_truth
node_chat_api -->|"requests response"| node_gemini
node_chat_api -->|"requests speech"| node_elevenlabs
node_chat_api -->|"returns answer"| node_experience
node_experience -->|"updates transcript"| node_chat_transcript
node_experience -->|"plays response"| node_speech_playback
node_speech_playback -->|"drives mouth"| node_lip_sync
node_experience -->|"updates scene"| node_character_render
node_character_render -->|"loads"| node_character_model
node_character_render -->|"refines model"| node_character_refinement
node_experience -->|"creates movement"| node_movement
node_movement -->|"loads clips"| node_gesture_library
node_movement -->|"creates presence"| node_presence
node_interface -.->|"uses styles"| node_responsive_styles

click node_interface "https://github.com/rammeshgar/digital-twin-demo/blob/main/index.html"
click node_experience "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_speech_recognition "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_audio_capture "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_transcription "https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/transcribe.js"
click node_chat_api "https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/chat.js"
click node_knowledge_context "https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/chat.js"
click node_persona "https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/persona.md"
click node_source_truth "https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/sadeq-source-of-truth.md"
click node_chat_transcript "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_speech_playback "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_lip_sync "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_character_render "https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js"
click node_character_refinement "https://github.com/rammeshgar/digital-twin-demo/blob/main/character-refinement.mjs"
click node_character_model "https://github.com/rammeshgar/digital-twin-demo/blob/main/assets/sadeq-digital-twin.meshopt.glb"
click node_movement "https://github.com/rammeshgar/digital-twin-demo/blob/main/movement.mjs"
click node_gesture_library "https://github.com/rammeshgar/digital-twin-demo/blob/main/gestures.json"
click node_presence "https://github.com/rammeshgar/digital-twin-demo/blob/main/presence.mjs"
click node_responsive_styles "https://github.com/rammeshgar/digital-twin-demo/blob/main/style.css"

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_interface,node_experience,node_speech_recognition,node_audio_capture,node_chat_transcript,node_speech_playback,node_responsive_styles toneBlue
class node_lip_sync,node_character_render,node_character_refinement,node_character_model,node_movement,node_gesture_library,node_presence toneAmber
class node_transcription,node_chat_api toneMint
class node_knowledge_context,node_persona,node_source_truth toneRose
class node_visitor,node_gemini,node_elevenlabs toneIndigo
```

## Components

### Browser experience

- [Chat interface](https://github.com/rammeshgar/digital-twin-demo/blob/main/index.html): `index.html`
- [Experience controller](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [Speech recognition](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [Audio capture](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [Chat transcript](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [Speech playback](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [Responsive styling](https://github.com/rammeshgar/digital-twin-demo/blob/main/style.css): `style.css`

### Character animation

- [Viseme lip sync](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [3D rendering](https://github.com/rammeshgar/digital-twin-demo/blob/main/mascot.js): `mascot.js`
- [Character refinement](https://github.com/rammeshgar/digital-twin-demo/blob/main/character-refinement.mjs): `character-refinement.mjs`
- [Digital twin model](https://github.com/rammeshgar/digital-twin-demo/blob/main/assets/sadeq-digital-twin.meshopt.glb): `assets/sadeq-digital-twin.meshopt.glb`
- [Gesture blending](https://github.com/rammeshgar/digital-twin-demo/blob/main/movement.mjs): `movement.mjs`
- [Gesture library](https://github.com/rammeshgar/digital-twin-demo/blob/main/gestures.json): `gestures.json`
- [Idle presence](https://github.com/rammeshgar/digital-twin-demo/blob/main/presence.mjs): `presence.mjs`

### Serverless services

- [Audio transcription](https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/transcribe.js): `netlify/functions/transcribe.js`
- [Chat service](https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/chat.js): `netlify/functions/chat.js`

### Grounded knowledge

- [Knowledge context](https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/chat.js): `netlify/functions/chat.js`
- [Persona guidance](https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/persona.md): `netlify/functions/persona.md`
- [Professional source](https://github.com/rammeshgar/digital-twin-demo/blob/main/netlify/functions/sadeq-source-of-truth.md): `netlify/functions/sadeq-source-of-truth.md`

### Other components

- **Visitor**
- **Gemini**
- **ElevenLabs**

## Connections

- Visitor → Chat interface: asks (evidence: `README.md`)
- Chat interface → Experience controller: controls (evidence: `mascot.js`)
- Experience controller → Speech recognition: starts recognition (evidence: `README.md`)
- Experience controller → Audio capture: records audio (evidence: `README.md`)
- Audio capture → Audio transcription: submits recording (evidence: `README.md`)
- Speech recognition → Experience controller: provides text (evidence: `README.md`)
- Audio transcription → Experience controller: returns transcript (evidence: `README.md`)
- Experience controller → Chat service: sends question (evidence: `README.md`)
- Chat service → Knowledge context: builds context (evidence: `netlify/functions/chat.js`)
- Knowledge context → Persona guidance: reads (evidence: `netlify/functions/chat.js`)
- Knowledge context → Professional source: reads (evidence: `netlify/functions/chat.js`)
- Chat service → Gemini: requests response (evidence: `netlify/functions/chat.js`)
- Chat service → ElevenLabs: requests speech (evidence: `netlify/functions/chat.js`)
- Chat service → Experience controller: returns answer (evidence: `README.md`)
- Experience controller → Chat transcript: updates transcript (evidence: `README.md`)
- Experience controller → Speech playback: plays response (evidence: `mascot.js`)
- Speech playback → Viseme lip sync: drives mouth (evidence: `README.md`)
- Experience controller → 3D rendering: updates scene (evidence: `mascot.js`)
- 3D rendering → Digital twin model: loads (evidence: `mascot.js`)
- 3D rendering → Character refinement: refines model (evidence: `mascot.js`)
- Experience controller → Gesture blending: creates movement (evidence: `mascot.js`)
- Gesture blending → Gesture library: loads clips (evidence: `movement.mjs`)
- Gesture blending → Idle presence: creates presence (evidence: `movement.mjs`)
- Chat interface → Responsive styling: uses styles
