# feligr/ar-avatar architecture

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

- Interactive diagram: https://gitdiagram.com/feligr/ar-avatar
- Repository: https://github.com/feligr/ar-avatar

## Overview

##### Project Type and Purpose
- This is a single‐page, full-stack-style frontend application built with React 18 that provides a 3D avatar creation, customization, and animation experience.
- It uses Babylon.js for real-time WebGL rendering and Ready Player Me API for avatar models, and it communicates with two external microservices (Persona Engine and Dialog Orchestrator) for AI-driven dialog and personality.
- The project is containerized via Docker and Docker Compose for consistent deployment.

##### File Structure
- Top-level config and tooling files:
- Dockerfile, docker-compose.yml, entrypoint.sh → container orchestration
- config-overrides.js, .prettierrc, .gitignore → build and lint rules
- public/ → static assets (GLB animations, models, environment maps, videos, index.html)
- src/ → React application code
- src/app/providers → global context providers
- src/features/… → feature modules (avatar, babylon-avatar, dialog, personality, voice)
– Each babylon-avatar module follows a Clean Architecture pattern with domain, application (use cases), infrastructure (controllers, repositories, services)
- src/services/api → HTTP wrappers for external services
- src/shared → common UI components and util functions
- src/styles → CSS modules and utility styles

##### README for Additional Insights
- The README confirms the tech stack (React, Babylon.js, Ready Player Me)
- Two external endpoints must be configured via environment variables:
REACT_APP_PERSONA_ENGINE_URL
REACT_APP_DIALOG_ORCHESTRATOR_URL
- Animations and assets are prepackaged in public/animations/…

##### Main Components & Their Relationships
a. Frontend Client (React SPA)
– Presentation Layer: AppProviders, feature UIs (AvatarViewer, DialogBox, PersonalityControls, etc.)
– Feature Services: voiceCommands.js, API wrappers
– State Management: React Contexts for avatar, dialog, personality
– 3D Engine: BabylonSceneManager and AnimationService within babylon-avatar feature
b. Static Asset Server
– Serves index.html, GLB models, animations and environment assets from public/
c. External AI Microservices (outside this repo)
– Persona Engine → supplies trait logic, customization data
– Dialog Orchestrator → processes user input, returns AI-generated text/audio
d. Third-Party API
– Ready Player Me API → avatar model creation & customization
e. Browser / User
– Interacts via UI, voice input, personality sliders, triggers animations

Relationships & Data Flow:
User actions → React UI → Context & Hooks → API calls (Persona Engine, Dialog Orchestrator) → responses drive state updates → call AnimationService & BabylonSceneManager → fetch GLB assets → render in WebGL canvas.
Voice input/output cycles through voiceCommands service and Dialog microservice.

##### Architectural Patterns & Principles
- Component-based UI (React)
- Clean Architecture in babylon-avatar feature: presentation (controllers), application (use cases), domain (entities), infrastructure (repositories & services)
- Context-based state management for cross-cutting concerns (avatar animations, dialog, personality)
- Separation of concerns: UI ↔ domain logic ↔ 3D engine ↔ external services
- Containerization for environment consistency

##### Essential Elements
- Clear, descriptive labels on every component
- A zoom-in inset for the babylon-avatar Clean Architecture layers (Presentation, UseCases, Domain, Infrastructure)

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef storage fill:#eee,stroke:#333,stroke-width:1px
    classDef external fill:#fcc,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#fdb,stroke:#333,stroke-width:1px
    classDef infra fill:#ddf,stroke:#333,stroke-width:1px

    Browser["Browser / User"]:::external

    subgraph "Docker Container"
        subgraph "React App"
            subgraph "Presentation Layer"
                AppProviders["AppProviders"]:::frontend
                AvatarViewer["AvatarViewer"]:::frontend
                ReadyPlayerMeAvatar["ReadyPlayerMeAvatar"]:::frontend
                DialogBox["DialogBox"]:::frontend
                MessageInput["MessageInput"]:::frontend
                MessageList["MessageList"]:::frontend
                TypingIndicator["TypingIndicator"]:::frontend
                VoiceInput["VoiceInput"]:::frontend
                PersonalityControls["PersonalityControls"]:::frontend
                TraitInfoModal["TraitInfoModal"]:::frontend
                TraitSlider["TraitSlider"]:::frontend
                VoiceUI["Voice UI"]:::frontend
            end
            subgraph "State Management"
                AvatarContext["AvatarContext"]:::frontend
                DialogContext["DialogContext"]:::frontend
                PersonalityContext["PersonalityContext"]:::frontend
            end
            subgraph "3D Engine"
                BabylonSceneManager["BabylonSceneManager"]:::frontend
                AnimationService["AnimationService"]:::frontend
                subgraph "babylon-avatar Clean Architecture"
                    Controllers["Controllers"]:::frontend
                    UseCases["UseCases"]:::frontend
                    Domain["Domain"]:::frontend
                    Infrastructure["Infrastructure"]:::frontend
                end
            end
            subgraph "API Client"
                APIClient["api.js / index.js"]:::frontend
                VoiceCommands["voiceCommands"]:::frontend
            end
        end
        StaticAsset["Static Asset Server"]:::storage
    end

    subgraph "External Services"
        PersonaEngine["Persona Engine"]:::backend
        DialogOrchestrator["Dialog Orchestrator"]:::backend
        ReadyPlayerMeAPI["Ready Player Me API"]:::thirdparty
    end

    Browser -->|user events| AppProviders
    AppProviders -->|renders| AvatarViewer
    AppProviders -->|renders| DialogBox
    AppProviders -->|renders| PersonalityControls
    AppProviders -->|renders| VoiceUI
    AvatarViewer -->|uses context| AvatarContext
    DialogBox -->|uses context| DialogContext
    PersonalityControls -->|uses context| PersonalityContext
    AvatarViewer -->|calls| APIClient
    ReadyPlayerMeAvatar -->|fetches avatar| ReadyPlayerMeAPI
    APIClient -->|HTTP JSON| PersonaEngine
    APIClient -->|HTTP JSON| DialogOrchestrator
    VoiceInput -->|voice data| VoiceCommands
    VoiceCommands -->|HTTP audio| DialogOrchestrator
    PersonaEngine -->|traits data| PersonalityContext
    DialogOrchestrator -->|dialog data| DialogContext
    AvatarContext -->|triggers| AnimationService
    DialogContext -->|triggers| AnimationService
    AnimationService -->|controls| BabylonSceneManager
    BabylonSceneManager -->|fetch GLB| StaticAsset
    StaticAsset -->|serves assets| Browser

    Dockerfile["Dockerfile"]:::infra
    Compose["docker-compose.yml"]:::infra
    Entrypoint["entrypoint.sh"]:::infra

    click AppProviders "https://github.com/feligr/ar-avatar/blob/main/src/app/providers/AppProviders.jsx"
    click AppProviders "https://github.com/feligr/ar-avatar/blob/main/src/app/providers/index.js"
    click AvatarViewer "https://github.com/feligr/ar-avatar/blob/main/src/features/avatar/components/AvatarViewer.jsx"
    click ReadyPlayerMeAvatar "https://github.com/feligr/ar-avatar/blob/main/src/features/avatar/components/ReadyPlayerMeAvatar.jsx"
    click DialogBox "https://github.com/feligr/ar-avatar/blob/main/src/features/dialog/DialogBox.jsx"
    click MessageInput "https://github.com/feligr/ar-avatar/blob/main/src/features/dialog/components/MessageInput.jsx"
    click MessageList "https://github.com/feligr/ar-avatar/blob/main/src/features/dialog/components/MessageList.jsx"
    click TypingIndicator "https://github.com/feligr/ar-avatar/blob/main/src/features/dialog/components/TypingIndicator.jsx"
    click VoiceInput "https://github.com/feligr/ar-avatar/blob/main/src/features/dialog/components/VoiceInput.jsx"
    click PersonalityControls "https://github.com/feligr/ar-avatar/blob/main/src/features/personality/PersonalityControls.jsx"
    click TraitInfoModal "https://github.com/feligr/ar-avatar/blob/main/src/features/personality/components/TraitInfoModal.jsx"
    click TraitSlider "https://github.com/feligr/ar-avatar/blob/main/src/features/personality/components/TraitSlider.jsx"
    click VoiceUI "https://github.com/feligr/ar-avatar/blob/main/src/features/voice/index.js"
    click AvatarContext "https://github.com/feligr/ar-avatar/blob/main/src/features/avatar/context/AvatarAnimationContext.js"
    click DialogContext "https://github.com/feligr/ar-avatar/blob/main/src/features/dialog/context/DialogContext.js"
    click PersonalityContext "https://github.com/feligr/ar-avatar/blob/main/src/features/personality/context/PersonalityContext.js"
    click BabylonSceneManager "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/infrastructure/services/BabylonSceneManager.js"
    click AnimationService "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/application/services/AnimationService.js"
    click Controllers "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/infrastructure/controllers/BabylonAnimationController.js"
    click Controllers "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/infrastructure/controllers/BabylonMorphTargetController.js"
    click UseCases "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/application/usecases/LoadCharacterUseCase.js"
    click UseCases "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/application/usecases/PlayIdleAnimationUseCase.js"
    click UseCases "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/application/usecases/PlayTalkingAnimationUseCase.js"
    click Infrastructure "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/infrastructure/repositories/BabylonAnimationRepository.js"
    click Domain "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/domain/entities/Animation.js"
    click Domain "https://github.com/feligr/ar-avatar/blob/main/src/features/babylon-avatar/domain/entities/Character.js"
    click Entrypoint "https://github.com/feligr/ar-avatar/blob/main/entrypoint.sh"
    click Dockerfile "https://github.com/feligr/ar-avatar/tree/main/Dockerfile"
    click Compose "https://github.com/feligr/ar-avatar/blob/main/docker-compose.yml"
```
