How feligr/ar-avatar works
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)