Phase 1: REST (configuration)
  → create session/get token/list avatars/list voices
  → Bearer or x-api-key auth
  → Returns RTC credentials

Phase 2: WebRTC (real-time)
  → Join RTC channel with credentials from Phase 1
  → All media flows peer-to-peer via the RTC provider
  → Text messages flow over the data channel

POST /api/open/v4/liveAvatar/session/create   → Session { _id, credentials }
POST /api/open/v4/liveAvatar/session/close    → void
GET  /api/open/v3/language/list               → Language[]
GET  /api/open/v4/knowledge/list              → Knowledge[]
GET  /api/open/v4/voice/list?type=1|2         → Voice[]
GET  /api/open/v4/liveAvatar/avatar/list      → Avatar[]

POST /api/open/v3/getToken                    → { token }
GET  /api/open/v3/avatar/list                 → Avatar[]
GET  /api/open/v3/voice/list                  → Voice[]
POST /api/open/v3/tts/audio/create            → audio data (TTS)
POST /api/open/v3/talkingavatar/create        → async video generation
POST /api/open/v3/face-swap/create            → face swap result
POST /api/open/v3/liveAvatar/avatar/create    → create custom avatar
GET  /api/open/v3/liveAvatar/avatar/detail    → avatar status/details

[Browser mic]
     │
     ▼
getUserMedia({ audio: true })
     │
     ▼
AgoraRTC.createMicrophoneAudioTrack()
     │
     ▼
AI Denoiser (Agora SDK built-in)
     │
     ▼
client.publish(audioTrack)
     │
     ▼
═══ WebRTC to Agora channel ═══
     │
     ▼
[Akool server receives audio track]
     │
     ├── STT (speech-to-text)
     ├── LLM (knowledge-contextualized response)
     └── TTS (voice-cloned speech)
     │
     ▼
═══ WebRTC back to browser ═══
     │
     ▼
[Browser receives remote audio + video tracks]
     │
     ├── Audio → <audio> element
     └── Video  → <video> element (avatar animation)

┌─────────────────────────────────────┐
│ LAYER 1: Zustand Store              │  Persistent config (API keys, selected avatar/voice)
│ configurationStore.ts (235 lines)   │  localStorage-backed via zustand/middleware persist
├─────────────────────────────────────┤
│ LAYER 2: React Context              │  Streaming lifecycle state
│ StreamingContext.tsx (374 lines)    │  isJoined, isConnecting, isSpeaking, error, messages
├─────────────────────────────────────┤
│ LAYER 3: Custom Hooks               │  Orchestration logic
│ useStreamingSession.ts (381 lines)  │  Session creation → connect → setAvatarParams
│ useProviderAudioControls.ts         │  Mic/camera lifecycle
│ useProviderVideoCamera.ts           │  Camera capture
├─────────────────────────────────────┤
│ LAYER 4: ProviderManager            │  Singleton — switch/connect/disconnect providers
│ ProviderManager.ts (112 lines)     │  Bridges L3 ↔ L5 via EventBus
│ StreamingProviderFactory.ts         │  Creates typed providers from credentials
├─────────────────────────────────────┤
│ LAYER 5: Concrete Providers         │  Agora / LiveKit / TRTC
│ BaseStreamingProvider.ts (154 lines)│  Abstract class — state, EventBus, resource cleanup
│ AgoraStreamingProvider.ts           │  Agora SDK integration (6 controllers)
│ LiveKitStreamingProvider.ts         │  LiveKit SDK integration
│ TRTCStreamingProvider.ts            │  TRTC SDK integration
└─────────────────────────────────────┘

{
  isJoined: boolean,           // Connected to RTC channel?
  isConnecting: boolean,       // In progress?
  isSpeaking: boolean,         // Avatar currently speaking?
  participants: Participant[], // Who's in the channel?
  localParticipant: Participant | null,
  networkQuality: ConnectionQuality | null,
  error: Error | null,
}

// Typed event map (30+ events)
StreamingEventMap = {
  'connection:connected' | 'connection:disconnected' | 'connection:failed'
  'participant:joined'  | 'participant:left' | 'participant:speaking-changed'
  'media:video-published' | 'media:audio-published'
  'message:received' | 'message:sent'
  'avatar:response-interrupted'
  'system:error' | 'system:warning' | 'system:info'
}

// Instead of: const [callbacks, setCallbacks] = useState([])
const messageCallbacks = useRef<Set<(msg: ChatMessage) => void>>(new Set());
// Adding a listener does NOT trigger re-render

IDLE → LISTENING → PROCESSING → SPEAKING → IDLE
  │        │           │           │
  └────────┴───────────┴───────────┴── ERROR → IDLE

              ┌──────────────────┐
              │  ProviderManager  │  Singleton — lifecycle orchestration
              │  (singleton)      │  switchProvider(type, creds, handlers)
              └────────┬─────────┘
                       │
              ┌────────▼─────────┐
              │ ProviderFactory   │  Registry pattern
              │ (singleton)       │  createProviderWithCredentials(type, creds)
              └────────┬─────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
    ┌─────────┐  ┌──────────┐  ┌──────────┐
    │ Agora   │  │ LiveKit  │  │  TRTC    │
    │Provider │  │ Provider │  │ Provider │
    └────┬────┘  └────┬─────┘  └────┬─────┘
         │            │             │
    ┌────▼────┐  ┌────▼─────┐  ┌────▼─────┐
    │6 Ctrls  │  │6 Ctrls   │  │6 Ctrls   │
    │3 Strat. │  │3 Strat.  │  │3 Strat.  │
    └─────────┘  └──────────┘  └──────────┘

Akool's pattern:              Our extension:
───────────────              ──────────────
StreamingProvider             AvatarProvider (interface)
├── AgoraProvider             ├── AkoolProvider
├── LiveKitProvider           ├── HeyGenProvider
└── TRTCProvider              ├── D-IDProvider
                              └── CustomThreeJSProvider (our own renderer)

App.tsx (181 lines — thin orchestrator)
├── ConfigurationPanel        API keys, avatar/voice selection, provider picker
├── VideoDisplay
│   ├── MainVideoArea
│   │   ├── AvatarContent      Renders remote avatar video stream
│   │   └── RemoteVideo         Provider-specific rendering (strategy pattern)
│   └── VideoOverlay            Speaking indicator, connection status
├── ChatInterface
│   ├── MessageList             Chat history
│   ├── ChatControls            Text input, send, interrupt
│   └── useMessageHandlers      Message routing hook
├── NetworkQuality              Connection quality indicator
├── ModalContainer              JSON editor modals, voice previews
└── NotificationContainer       Error/warning toasts

POST /api/open/v3/face-swap/create
  { target_image, source_image, token }
→ async result with swapped face image

interface AvatarProvider {
  // Lifecycle
  connect(config: AvatarConfig): Promise<void>;
  disconnect(): Promise<void>;

  // Persona management
  setPersona(persona: Persona): Promise<void>;
  getPersonas(): Persona[];

  // Media
  sendAudio(track: AudioTrack): Promise<void>;
  sendText(message: string): Promise<void>;

  // State
  state: AvatarState;  // { isConnected, isSpeaking, currentPersona, ... }
  subscribe(callback: (state: AvatarState) => void): () => void;
}

IDLE → LISTENING → THINKING → SPEAKING
                    ↑            │
                    └────────────┘ (auto-return after speech)
Any state → PERSONA_SWITCHING → IDLE (with new persona)
Any state → ERROR → IDLE (after timeout or user action)

interface Persona {
  id: string;
  name: string;
  avatarConfig: {
    provider: string;        // 'akool' | 'heygen' | 'local'
    avatarId: string;        // Provider-specific ID
    faceImage?: string;      // For dynamic face swap
  };
  voiceConfig: {
    provider: string;
    voiceId: string;
    speed?: number;
    pitch?: number;
  };
  knowledgeBase: {
    id: string;
    systemPrompt: string;    // Personality definition
    context?: string;        // Background knowledge
  };
  visualConfig: {
    background?: string;
    animationStyle?: 'talking' | 'gesturing' | 'idle-only';
  };
}

src/apiService.ts                    — Typed REST client (Bearer/x-api-key)
src/App.tsx                          — Thin orchestrator (181 lines)
src/core/EventBus.ts                 — Typed pub/sub (copy directly)
src/core/ResourceManager.ts          — Cleanup registry (copy directly)
src/core/Logger.ts                   — Structured logging (copy directly)
src/stores/configurationStore.ts     — Zustand + persist config
src/contexts/StreamingContext.tsx     — React Context for streaming lifecycle
src/hooks/useStreamingSession.ts     — Session orchestration hook
src/hooks/useProviderAudioControls.ts— Mic lifecycle
src/providers/BaseStreamingProvider.ts— Abstract provider (adapt)
src/providers/ProviderManager.ts     — Singleton provider lifecycle
src/providers/StreamingProviderFactory.ts— Provider registry
src/providers/agora/                 — Agora provider (6 controllers, 3 strategies)
src/providers/livekit/               — LiveKit provider
src/providers/trtc/                  — TRTC provider
src/providers/common/                — Shared controllers/strategies/types
src/types/event.types.ts             — Typed event map
src/types/streaming.types.ts         — Core state types
src/types/provider.interfaces.ts     — Provider interface contract

talking-avatar-frontend/src/App.tsx          — 889-line monolith (API reference only)
talking-avatar-frontend/src/components/      — LanguageSelector only
talking_avatar_webhook/app.py                — Flask webhook (127 lines, AES decrypt)