# pratik-aher-01/persona architecture

> Architecture diagram of the GitHub repository pratik-aher-01/persona, 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/pratik-aher-01/persona
- Repository: https://github.com/pratik-aher-01/persona

## Overview

Persona is a browser-native embodied interface for AI agents: people provide speech, an external agent reads the transcript and invokes WebMCP tools, and the page presents spoken/avatar responses plus structured mission progress and results. The principal path is microphone/STT through the app to the agent-facing tools, then tool effects on avatar, voice, and task state, rendered back to the person. The graph preserves documented avatar, voice, fallback, and mock-agent capabilities. Some connections rely on README descriptions because implementation excerpts are partial.

Main entry points: [`src/App.tsx`](https://github.com/pratik-aher-01/persona/blob/main/src/App.tsx) (Persona App), [`src/avatar/PersonaAvatarRuntime.ts`](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/PersonaAvatarRuntime.ts) (VRM Runtime), [`src/webmcp/registerTools.ts`](https://github.com/pratik-aher-01/persona/blob/main/src/webmcp/registerTools.ts) (WebMCP Tools), [`src/components/AgentMissionPanel.tsx`](https://github.com/pratik-aher-01/persona/blob/main/src/components/AgentMissionPanel.tsx) (Mission Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction Surface"]
  node_app["Persona App<br/>[App.tsx]"]
  node_tools["WebMCP Tools<br/>[registerTools.ts]"]
  node_agentlogic["Conversation Agent"]
  node_mockagent["Mock Agent<br/>[MockAgent.ts]"]
  node_mockconsole["Mock Console"]
  node_transcript["Transcript UI"]
end

subgraph group_voice["Speech Session"]
  node_session["Turn Session"]
  node_stt["Speech Recognition<br/>[stt.ts]"]
  node_voiceengine["Voice Manager<br/>[VoiceEngine.ts]"]
  node_browservoice["Browser TTS"]
end

subgraph group_embodiment["Avatar Embodiment"]
  node_avatarview["3D Avatar View<br/>[PersonaAvatar.tsx]"]
  node_runtime["VRM Runtime"]
  node_expressions["Expressions<br/>[expressions.ts]"]
  node_gaze["Gaze Tracking<br/>[gaze.ts]"]
  node_gestures["Gesture Animation<br/>[gestures.ts]"]
  node_idle["Idle Animation<br/>[idle.ts]"]
  node_behavior["Humanization"]
  node_fallback["2D Avatar<br/>[Avatar2D.tsx]"]
end

subgraph group_mission["Mission Workspace"]
  node_missionpanel["Mission Panel"]
  node_taskstore["Task Store<br/>[taskStore.ts]"]
  node_tasktypes["Task Models<br/>[taskTypes.ts]"]
  node_resultcard["Result Card"]
  node_sessionmemory["Session Memory<br/>[sessionMemory.ts]"]
end

node_person(("Human"))
node_agent(("External Agent"))

node_person -->|"speaks to"| node_stt
node_stt -->|"transcribes for"| node_app
node_app -->|"coordinates turns"| node_session
node_app -->|"renders"| node_transcript
node_agent -->|"calls tools"| node_tools
node_tools -->|"reads transcript"| node_stt
node_tools -->|"updates tasks"| node_taskstore
node_taskstore -->|"stores"| node_tasktypes
node_app -->|"renders"| node_missionpanel
node_missionpanel -->|"subscribes to"| node_taskstore
node_missionpanel -->|"renders"| node_resultcard
node_tools -->|"controls avatar"| node_runtime
node_tools -->|"requests speech"| node_voiceengine
node_app -->|"uses"| node_voiceengine
node_voiceengine -->|"delegates to"| node_browservoice
node_app -->|"renders"| node_avatarview
node_avatarview -->|"mounts"| node_runtime
node_runtime -->|"updates"| node_expressions
node_runtime -->|"updates"| node_gaze
node_runtime -->|"updates"| node_gestures
node_runtime -->|"updates"| node_idle
node_runtime -->|"updates"| node_behavior
node_behavior -->|"triggers"| node_gestures
node_app -->|"offers fallback"| node_fallback
node_app -->|"uses"| node_agentlogic
node_mockconsole -->|"hosts"| node_mockagent
node_mockagent -->|"exercises"| node_tools
node_app -->|"renders"| node_mockconsole

click node_app "https://github.com/pratik-aher-01/persona/blob/main/src/App.tsx"
click node_tools "https://github.com/pratik-aher-01/persona/blob/main/src/webmcp/registerTools.ts"
click node_agentlogic "https://github.com/pratik-aher-01/persona/blob/main/src/agent/ConversationAgent.ts"
click node_mockagent "https://github.com/pratik-aher-01/persona/blob/main/src/dev/MockAgent.ts"
click node_mockconsole "https://github.com/pratik-aher-01/persona/blob/main/src/dev/MockAgentConsole.tsx"
click node_transcript "https://github.com/pratik-aher-01/persona/blob/main/src/components/ConversationTranscript.tsx"
click node_session "https://github.com/pratik-aher-01/persona/blob/main/src/session/ConversationSession.ts"
click node_stt "https://github.com/pratik-aher-01/persona/blob/main/src/utils/stt.ts"
click node_voiceengine "https://github.com/pratik-aher-01/persona/blob/main/src/voice/VoiceEngine.ts"
click node_browservoice "https://github.com/pratik-aher-01/persona/blob/main/src/voice/BrowserVoiceEngine.ts"
click node_avatarview "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/PersonaAvatar.tsx"
click node_runtime "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/PersonaAvatarRuntime.ts"
click node_expressions "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/expressions.ts"
click node_gaze "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/gaze.ts"
click node_gestures "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/animation/gestures.ts"
click node_idle "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/animation/idle.ts"
click node_behavior "https://github.com/pratik-aher-01/persona/blob/main/src/avatar/behavior/humanizationEngine.ts"
click node_fallback "https://github.com/pratik-aher-01/persona/blob/main/src/components/Avatar2D.tsx"
click node_missionpanel "https://github.com/pratik-aher-01/persona/blob/main/src/components/AgentMissionPanel.tsx"
click node_taskstore "https://github.com/pratik-aher-01/persona/blob/main/src/tasks/taskStore.ts"
click node_tasktypes "https://github.com/pratik-aher-01/persona/blob/main/src/tasks/taskTypes.ts"
click node_resultcard "https://github.com/pratik-aher-01/persona/blob/main/src/components/ResultDisplayCard.tsx"
click node_sessionmemory "https://github.com/pratik-aher-01/persona/blob/main/src/memory/sessionMemory.ts"

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_tools,node_agentlogic,node_mockagent,node_mockconsole,node_transcript toneBlue
class node_session,node_stt,node_voiceengine,node_browservoice toneAmber
class node_avatarview,node_runtime,node_expressions,node_gaze,node_gestures,node_idle,node_behavior,node_fallback toneMint
class node_missionpanel,node_taskstore,node_tasktypes,node_resultcard,node_sessionmemory toneRose
class node_person,node_agent toneIndigo
```

## Components

### Interaction Surface

- [Persona App](https://github.com/pratik-aher-01/persona/blob/main/src/App.tsx): `src/App.tsx`
- [WebMCP Tools](https://github.com/pratik-aher-01/persona/blob/main/src/webmcp/registerTools.ts): `src/webmcp/registerTools.ts`
- [Conversation Agent](https://github.com/pratik-aher-01/persona/blob/main/src/agent/ConversationAgent.ts): `src/agent/ConversationAgent.ts`
- [Mock Agent](https://github.com/pratik-aher-01/persona/blob/main/src/dev/MockAgent.ts): `src/dev/MockAgent.ts`
- [Mock Console](https://github.com/pratik-aher-01/persona/blob/main/src/dev/MockAgentConsole.tsx): `src/dev/MockAgentConsole.tsx`
- [Transcript UI](https://github.com/pratik-aher-01/persona/blob/main/src/components/ConversationTranscript.tsx): `src/components/ConversationTranscript.tsx`

### Speech Session

- [Turn Session](https://github.com/pratik-aher-01/persona/blob/main/src/session/ConversationSession.ts): `src/session/ConversationSession.ts`
- [Speech Recognition](https://github.com/pratik-aher-01/persona/blob/main/src/utils/stt.ts): `src/utils/stt.ts`
- [Voice Manager](https://github.com/pratik-aher-01/persona/blob/main/src/voice/VoiceEngine.ts): `src/voice/VoiceEngine.ts`
- [Browser TTS](https://github.com/pratik-aher-01/persona/blob/main/src/voice/BrowserVoiceEngine.ts): `src/voice/BrowserVoiceEngine.ts`

### Avatar Embodiment

- [3D Avatar View](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/PersonaAvatar.tsx): `src/avatar/PersonaAvatar.tsx`
- [VRM Runtime](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/PersonaAvatarRuntime.ts): `src/avatar/PersonaAvatarRuntime.ts`
- [Expressions](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/expressions.ts): `src/avatar/expressions.ts`
- [Gaze Tracking](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/gaze.ts): `src/avatar/gaze.ts`
- [Gesture Animation](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/animation/gestures.ts): `src/avatar/animation/gestures.ts`
- [Idle Animation](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/animation/idle.ts): `src/avatar/animation/idle.ts`
- [Humanization](https://github.com/pratik-aher-01/persona/blob/main/src/avatar/behavior/humanizationEngine.ts): `src/avatar/behavior/humanizationEngine.ts`
- [2D Avatar](https://github.com/pratik-aher-01/persona/blob/main/src/components/Avatar2D.tsx): `src/components/Avatar2D.tsx`

### Mission Workspace

- [Mission Panel](https://github.com/pratik-aher-01/persona/blob/main/src/components/AgentMissionPanel.tsx): `src/components/AgentMissionPanel.tsx`
- [Task Store](https://github.com/pratik-aher-01/persona/blob/main/src/tasks/taskStore.ts): `src/tasks/taskStore.ts`
- [Task Models](https://github.com/pratik-aher-01/persona/blob/main/src/tasks/taskTypes.ts): `src/tasks/taskTypes.ts`
- [Result Card](https://github.com/pratik-aher-01/persona/blob/main/src/components/ResultDisplayCard.tsx): `src/components/ResultDisplayCard.tsx`
- [Session Memory](https://github.com/pratik-aher-01/persona/blob/main/src/memory/sessionMemory.ts): `src/memory/sessionMemory.ts`

### Other components

- **Human**
- **External Agent**

## Connections

- Human → Speech Recognition: speaks to (evidence: `README.md`)
- Speech Recognition → Persona App: transcribes for (evidence: `README.md`)
- Persona App → Turn Session: coordinates turns (evidence: `src/App.tsx`)
- Persona App → Transcript UI: renders (evidence: `src/App.tsx`)
- External Agent → WebMCP Tools: calls tools (evidence: `README.md`)
- WebMCP Tools → Speech Recognition: reads transcript (evidence: `README.md`)
- WebMCP Tools → Task Store: updates tasks (evidence: `src/webmcp/registerTools.ts`)
- Task Store → Task Models: stores (evidence: `src/tasks/taskStore.ts`)
- Persona App → Mission Panel: renders (evidence: `src/App.tsx`)
- Mission Panel → Task Store: subscribes to (evidence: `src/components/AgentMissionPanel.tsx`)
- Mission Panel → Result Card: renders (evidence: `src/components/AgentMissionPanel.tsx`)
- WebMCP Tools → VRM Runtime: controls avatar (evidence: `README.md`)
- WebMCP Tools → Voice Manager: requests speech (evidence: `README.md`)
- Persona App → Voice Manager: uses (evidence: `src/App.tsx`)
- Voice Manager → Browser TTS: delegates to (evidence: `src/voice/VoiceEngine.ts`)
- Persona App → 3D Avatar View: renders (evidence: `src/App.tsx`)
- 3D Avatar View → VRM Runtime: mounts (evidence: `src/avatar/PersonaAvatar.tsx`)
- VRM Runtime → Expressions: updates (evidence: `src/avatar/PersonaAvatarRuntime.ts`)
- VRM Runtime → Gaze Tracking: updates (evidence: `src/avatar/PersonaAvatarRuntime.ts`)
- VRM Runtime → Gesture Animation: updates (evidence: `src/avatar/PersonaAvatarRuntime.ts`)
- VRM Runtime → Idle Animation: updates (evidence: `src/avatar/PersonaAvatarRuntime.ts`)
- VRM Runtime → Humanization: updates (evidence: `src/avatar/PersonaAvatarRuntime.ts`)
- Humanization → Gesture Animation: triggers (evidence: `src/avatar/behavior/humanizationEngine.ts`)
- Persona App → 2D Avatar: offers fallback (evidence: `README.md`)
- Persona App → Conversation Agent: uses (evidence: `src/App.tsx`)
- Mock Console → Mock Agent: hosts (evidence: `src/dev/MockAgentConsole.tsx`)
- Mock Agent → WebMCP Tools: exercises (evidence: `src/dev/MockAgent.ts`)
- Persona App → Mock Console: renders (evidence: `src/App.tsx`)
