# devranbir/speechviber architecture

> Architecture diagram of the GitHub repository devranbir/speechviber, 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/devranbir/speechviber
- Repository: https://github.com/devranbir/speechviber

## Overview

##### Project Type and Purpose
- SpeechViber is a full-stack, single-page web application designed to improve communication skills via AI-driven, real-time feedback.
- It uses React.js on the client, Firebase (Authentication + Realtime Database) as the backend, and external AI APIs (Groq for NLP and AssemblyAI or similar for speech-to-text) plus client-side face-api.js models for visual analysis.

##### File Structure
- Top level:
- public/ – static assets including HTML, manifest, and face-api.js model shards
- src/ – main application code
- webpack.config.js & vite.config.js – build tools
- firebase.js & src/firebase/config.js – Firebase initialization
- src/components – reusable UI pieces and error/route handling
- src/pages – feature modules (SpeechAnalysis, GrammarCheck, Interview, etc.)
- src/services – wrappers for core domain logic: audioService.js, historyService.js
- src/contexts & src/context – React Contexts for Auth, Theme, Particle effects, User state
- src/hooks – custom hooks for audio recording, error handling
- src/utils – cross-cutting helpers (achievements, error handlers, profile cleanup)

##### README for Architecture Insights
- Frontend: React + Material-UI + Framer Motion
- Backend: Firebase Authentication + Realtime Database
- AI Integration: Groq APIs for NLP, Text-to-Speech, Speech-to-Text; face-api.js models for facial expression analysis
- Hosting: GitHub Pages / Vercel

##### Main Components and Relationships
a. Client Browser (User Interface)
- React SPA orchestrates pages, components, contexts, hooks
- Static assets served from public/ (index.html, face-api.js models)
b. Authentication Layer
- Firebase Auth handles sign-in/sign-up, token management
- PrivateRoute component enforces protected pages
c. Data Layer
- Firebase Realtime Database stores user profiles, session history, progress metrics, achievements
- historyService.js abstracts read/write operations
d. AI Services
- Groq API (NLP, feedback generation)
- AssemblyAI (speech-to-text conversion) or similar external endpoint
- face-api.js (client-side model files loaded from public/models for visual analysis)
e. Hosting & Build
- Vite/Webpack build outputs static files
- Deployment to GitHub Pages or Vercel

##### Architectural Patterns & Design Principles
- Single-Page Application pattern with React Router for page navigation
- Separation of concerns:
- UI layer (components/pages/styles)
- Business logic (services, hooks)
- State management (contexts)
- BaaS pattern using Firebase for auth and realtime data
- Client-heavy AI integration: static models + runtime API calls

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Container
    subgraph "Browser / Client"
        direction TB
        subgraph "React SPA" 
            direction TB
            Index["src/index.js"]:::frontend
            App["src/App.js"]:::frontend
            subgraph "UI Components"
                direction TB
                Layout["Layout"]:::frontend
                CustomLoader["CustomLoader"]:::frontend
                ErrorBoundaryComp["ErrorBoundary"]:::frontend
                ParticleCursor["ParticleCursor"]:::frontend
                SessionTimer["SessionTimer"]:::frontend
            end
            subgraph "Pages"
                direction TB
                AnalysisPage["SpeechAnalysis (Analysis/index.js)"]:::frontend
                GrammarPage["GrammarCheck (GrammarCheck/index.js)"]:::frontend
                InterviewPage["Interview (Interview/index.js)"]:::frontend
            end
            subgraph "Contexts"
                direction TB
                AuthContext["AuthContext"]:::frontend
                ThemeContext["ThemeContext"]:::frontend
                UserContext["UserContext"]:::frontend
                ParticleContext["ParticleContext"]:::frontend
            end
            subgraph "Hooks"
                direction TB
                AudioHook["useAudioRecorder"]:::frontend
                ErrorHandlerHook["useErrorHandler"]:::frontend
                ErrorBoundaryHook["useErrorBoundary"]:::frontend
            end
            subgraph "Services"
                direction TB
                AudioService["audioService.js"]:::frontend
                HistoryService["historyService.js"]:::frontend
            end
            subgraph "Utils"
                direction TB
                ErrorUtils["errorHandler.js"]:::frontend
                AchievementUtils["achievementUtils.js"]:::frontend
                ProfileCleanup["profileCleanup.js"]:::frontend
                UserScores["userScores.js"]:::frontend
            end
            StaticModels["face-api.js models"]:::static
        end
    end

    %% External Services
    Auth["Firebase Authentication"]:::baas
    Database["Firebase Realtime Database"]:::baas
    GroqAPI["Groq NLP API"]:::api
    SpeechAPI["Speech-to-Text API"]:::api
    Hosting["Hosting CDN (GitHub Pages/Vercel)"]:::static

    %% Connections
    Hosting -->|"serves index.html & static files"| Index
    Index -->|"loads App component"| App
    App -->|"uses Layout, Routes"| Layout
    App -->|"renders pages"| AnalysisPage
    App -->|"renders pages"| GrammarPage
    App -->|"renders pages"| InterviewPage
    App -->|"provides contexts"| AuthContext
    App -->|"provides contexts"| ThemeContext
    App -->|"provides contexts"| UserContext
    App -->|"provides contexts"| ParticleContext
    App -->|"uses hooks"| AudioHook
    App -->|"uses hooks"| ErrorHandlerHook
    App -->|"uses hooks"| ErrorBoundaryHook
    AudioHook -->|"calls audioService"| AudioService
    HistoryService -->|"read/write sessions"| Database
    AudioService -->|"POST /speech-to-text"| SpeechAPI
    SpeechAPI -->|"returns transcript"| AudioService
    AudioService -->|"sends text for analysis"| GroqAPI
    GroqAPI -->|"returns feedback"| AudioService
    AudioService -->|"provides data to UI"| AnalysisPage
    ErrorBoundaryComp -->|"catches errors"| ErrorHandlerHook
    AnalysisPage -->|"loads models"| StaticModels
    StaticModels -->|"served from public/models"| Hosting
    App -->|"auth flows"| Auth
    Auth -->|"issues tokens"| App
    HistoryService -->|"sync real-time updates"| Database

    %% Click Events
    click Index "https://github.com/devranbir/speechviber/blob/main/src/index.js"
    click App "https://github.com/devranbir/speechviber/blob/main/src/App.js"
    click Layout "https://github.com/devranbir/speechviber/blob/main/src/components/Layout/index.js"
    click CustomLoader "https://github.com/devranbir/speechviber/blob/main/src/components/CustomLoader/index.js"
    click ErrorBoundaryComp "https://github.com/devranbir/speechviber/blob/main/src/components/ErrorBoundary/index.js"
    click ParticleCursor "https://github.com/devranbir/speechviber/blob/main/src/components/ParticleCursor/index.js"
    click SessionTimer "https://github.com/devranbir/speechviber/blob/main/src/components/SessionTimer.js"
    click AnalysisPage "https://github.com/devranbir/speechviber/blob/main/src/pages/Analysis/index.js"
    click GrammarPage "https://github.com/devranbir/speechviber/blob/main/src/pages/GrammarCheck/index.js"
    click InterviewPage "https://github.com/devranbir/speechviber/blob/main/src/pages/Interview/index.js"
    click AudioService "https://github.com/devranbir/speechviber/blob/main/src/services/audioService.js"
    click HistoryService "https://github.com/devranbir/speechviber/blob/main/src/services/historyService.js"
    click AuthContext "https://github.com/devranbir/speechviber/blob/main/src/contexts/AuthContext.js"
    click ThemeContext "https://github.com/devranbir/speechviber/blob/main/src/context/ThemeContext.js"
    click UserContext "https://github.com/devranbir/speechviber/blob/main/src/context/UserContext.jsx"
    click ParticleContext "https://github.com/devranbir/speechviber/blob/main/src/contexts/ParticleContext.js"
    click AudioHook "https://github.com/devranbir/speechviber/blob/main/src/hooks/useAudioRecorder.jsx"
    click ErrorHandlerHook "https://github.com/devranbir/speechviber/blob/main/src/hooks/useErrorHandler.js"
    click ErrorBoundaryHook "https://github.com/devranbir/speechviber/blob/main/src/hooks/useErrorBoundary.js"
    click ErrorUtils "https://github.com/devranbir/speechviber/blob/main/src/utils/errorHandler.js"
    click AchievementUtils "https://github.com/devranbir/speechviber/blob/main/src/utils/achievementUtils.js"
    click ProfileCleanup "https://github.com/devranbir/speechviber/blob/main/src/utils/profileCleanup.js"
    click UserScores "https://github.com/devranbir/speechviber/blob/main/src/utils/userScores.js"
    click StaticModels "https://github.com/devranbir/speechviber/tree/main/public/models/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef baas fill:#90EE90,stroke:#000;
    classDef api fill:#FFA500,stroke:#000;
    classDef static fill:#D3D3D3,stroke:#000;
```
