# shaunwei/realchar architecture

> Architecture diagram of the GitHub repository shaunwei/realchar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shaunwei/realchar
- Repository: https://github.com/shaunwei/realchar

## Overview

##### Project type and purpose
- This is a full-stack, multi-platform “Realtime AI Character” application.
- Purpose: let end users create, customize and converse with AI characters via Web (Next.js), Mobile (Android/Swift), CLI, and Twilio phone calls, all in real time.

##### File structure
- Root
- realtime_ai_character/ → FastAPI backend, business logic, WebSocket & REST routes, audio/LLM modules, Alembic migrations, SQLite/Postgres support, Twilio integration
- cli.py → entry point for running backend, dev servers, terminal client
- Dockerfile, docker-compose.yaml, sample_cloud_deployment/ → containerization and k8s manifests
- client/next-web/ → Next.js React web app, SSR, WebSocket client, uses Zustand for state, Tailwind, Firebase auth
- client/mobile/android/RealChar → Android Kotlin app (Jetpack Compose, WebSockets)
- client/mobile/ios/rac → iOS SwiftUI app (WebSockets)
- client/cli.py → optional terminal chat client
- alembic/ → database migration scripts
- requirements.txt, pyproject.toml → Python dependencies

##### README
- Tech stack summary: React, Swift/Kotlin, FastAPI, SQLite, Docker, LlamaIndex/Chroma, LangChain, OpenAI/Anthropic/ReByte, Whisper/WhisperX/Google STT, ElevenLabs/EdgeTTS/Google TTS, Twilio
- Deployment instructions: Docker Compose or direct Python + Uvicorn, optional Firebase OAuth
- Modular design emphasis: pluggable modules for STT, TTS, LLM, character catalog

##### Be as detailed as possible
- Alembic migration layer as part of data initialization

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        WebClient["Web Client\n(Next.js)"]:::client
        AndroidClient["Mobile Client\n(Android)"]:::client
        IOSClient["Mobile Client\n(iOS)"]:::client
        CLIClient["CLI Client\n(Terminal)"]:::client
    end

    %% Backend Layer
    subgraph "Backend Services" 
        direction TB
        Main["FastAPI Server\n(main.py)"]:::backend
        subgraph "API Endpoints"
            direction TB
            REST["REST API\n(routes)"]:::backend
            WS["WebSocket API\n(routes)"]:::backend
        end
        subgraph "Audio Pipeline"
            direction TB
            STT["Speech-to-Text\nModules"]:::backend
            TTS["Text-to-Speech\nModules"]:::backend
        end
        subgraph "LLM Orchestrator"
            direction TB
            Orchestrator["Orchestrator & Providers"]:::backend
            PromptGen["System Prompt\nGenerator"]:::backend
        end
        CatCatalog["Character Catalog\nLoader"]:::backend
        DBLayer["Database Access\n& ORM"]:::backend
        TwilioInt["Twilio Integration"]:::backend
        Utils["Utility Functions"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        RelDB["Relational DB\n(SQLite/Postgres)"]:::datastore
        VecDB["Vector DB\n(Chroma)"]:::datastore
        FileStore["File Storage\n(audio samples)"]:::datastore
        Migrations["Alembic Migrations"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMAPIs["LLM APIs\n(OpenAI, Anthropic, ReByte)"]:::external
        STTService["Cloud STT\n(Google)"]:::external
        TTSService["Cloud TTS\n(Google, ElevenLabs)"]:::external
        VoiceClone["Voice Cloning\n(ElevenLabs)"]:::external
        FirebaseAuth["Firebase Auth"]:::external
        TwilioAPI["Twilio API"]:::external
    end

    %% Client to Backend
    WebClient -->|HTTP/WS| REST
    WebClient -->|WebSocket| WS
    AndroidClient -->|WS| WS
    IOSClient -->|WS| WS
    CLIClient -->|WS/HTTP| REST

    %% Backend internal flows
    Main --> REST
    Main --> WS
    REST --> Utils
    WS --> Utils
    WS --> STT
    STT --> Orchestrator
    Orchestrator --> PromptGen
    PromptGen --> Orchestrator
    Orchestrator --> TTS
    TTS --> WS
    REST --> CatCatalog
    REST --> DBLayer
    WS --> DBLayer
    DBLayer --> RelDB
    DBLayer --> VecDB
    DBLayer --> FileStore
    Migrations --> RelDB

    %% Twilio call flow
    CLIClient -->|/call cmd| TwilioInt
    WebClient -->|/call cmd| TwilioInt
    TwilioInt -->|API/WS| TwilioAPI
    TwilioAPI --> WS

    %% Orchestrator external calls
    STT --> STTService
    TTS --> TTSService
    Orchestrator --> LLMAPIs
    Orchestrator --> VoiceClone
    WebClient --> FirebaseAuth

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d

    %% Click Events
    click WebClient "https://github.com/shaunwei/realchar/tree/main/client/next-web"
    click AndroidClient "https://github.com/shaunwei/realchar/tree/main/client/mobile/android/RealChar/app"
    click IOSClient "https://github.com/shaunwei/realchar/tree/main/client/mobile/ios/rac/rac"
    click CLIClient "https://github.com/shaunwei/realchar/blob/main/client/cli.py"
    click Main "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/main.py"
    click REST "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/restful_routes.py"
    click WS "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/websocket_routes.py"
    click STT "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/audio/speech_to_text/*.py"
    click TTS "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/audio/text_to_speech/*.py"
    click FileStore "https://github.com/shaunwei/realchar/tree/main/realtime_ai_character/audio/training_data"
    click Orchestrator "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/llm/*.py"
    click PromptGen "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/llm/system_prompt_generator.py"
    click CatCatalog "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/character_catalog/catalog_manager.py"
    click DBLayer "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/database/connection.py"
    click DBLayer "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/database/base.py"
    click VecDB "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/database/chroma.py"
    click Migrations "https://github.com/shaunwei/realchar/blob/main/alembic/versions/*.py"
    click TwilioInt "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/twilio/twilio_outgoing_call.py"
    click TwilioInt "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/twilio/websocket.py"
    click Utils "https://github.com/shaunwei/realchar/blob/main/realtime_ai_character/utils.py"
    click cli "https://github.com/shaunwei/realchar/blob/main/cli.py"
    click Docker "https://github.com/shaunwei/realchar/tree/main/Dockerfile"
    click Compose "https://github.com/shaunwei/realchar/blob/main/docker-compose.yaml"
    click K8s "https://github.com/shaunwei/realchar/blob/main/sample_cloud_deployment/*.yaml"
```
