# yeheskieltame/linggo-english-hub architecture

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

- Interactive diagram: https://gitdiagram.com/yeheskieltame/linggo-english-hub
- Repository: https://github.com/yeheskieltame/linggo-english-hub

## Overview

##### Project type and purpose
- This is a single-page web application (SPA) built with Vite, TypeScript, and React.
- Purpose: a language-learning platform (Lovable) that presents CEFR-based lessons, quizzes, reading/listening activities, conversation practice, and AI-driven feedback via the Groq LLM API.
- It uses Supabase for authentication and persistence and the browser’s Web Speech APIs for speech recognition and text-to-speech.

##### File structure
- Top-level:
- package.json, Vite/Tailwind/PostCSS configs → build & bundling
- supabase/ → local Supabase configuration & migration scripts
- public/ → static assets
- src/ → application code
- Under src/:
- pages/ → React Router pages (Dashboard, Lessons, Auth, Profile…)
- components/ → UI building blocks (shadcn-ui wrappers, page fragments, shared UI library)
- services/ → network and business-logic services (supabase client, llmService, conversationService, speechRecognition, textToSpeech, levelAssessmentService)
- integrations/supabase → supabase-js client initialization and types
- providers/AuthProvider.tsx → React Context for user auth state
- data/ → lesson content and mock data loaded at build time
- hooks/ → custom React hooks (useMobile, useToast)

##### README for additional insights
- Tech stack: Vite, React, TypeScript, Tailwind CSS, shadcn-ui, Groq LLM API, Supabase.
- No custom Node-based backend; all “backend” functionality is offloaded to Supabase and external HTTP APIs.
- Environment variables: VITE_GROQ_API_KEY for AI calls.
- Deployment via Lovable (static hosting + functions) or any generic static host with environment support.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser SPA Container
    subgraph "Browser SPA (React App)"
        direction TB

        %% UI Layer
        subgraph "UI Layer" 
            direction TB
            CustomComponents["Custom Components"]:::frontend
            shadcnUI["shadcn-ui Components"]:::frontend
        end

        %% Routing Layer
        Routing["React Router Pages"]:::frontend

        %% State & Context Layer
        AuthContext["AuthProvider Context"]:::frontend

        %% Services Layer
        subgraph "Services Layer"
            direction TB
            SupabaseClient["Supabase Client Integration"]:::service
            SupabaseTypes["Supabase Types"]:::service
            LLMService["llmService (Groq API)"]:::service
            ConversationService["conversationService"]:::service
            SpeechRecog["speechRecognition Service"]:::service
            TextToSpeech["textToSpeech Service"]:::service
            LevelAssessment["levelAssessmentService"]:::service
        end

        %% Data Layer
        subgraph "Static & Mock Data" 
            direction TB
            a1["a1LessonData.ts"]:::data
            a2["a2LessonData.ts"]:::data
            b1["b1LessonData.ts"]:::data
            b2["b2LessonData.ts"]:::data
            c1["c1LessonData.ts"]:::data
            c2["c2LessonData.ts"]:::data
            reading["readingActivities.ts"]:::data
            listening["listeningActivities.ts"]:::data
            convScenarios["conversationScenarios.ts"]:::data
            lessonStages["lessonStagesData.ts"]:::data
            prompts["practicePrompts.ts"]:::data
            mockData["mockData.ts"]:::data
        end

        %% Utilities & Hooks
        subgraph "Utilities & Hooks"
            direction TB
            HooksMobile["use-mobile.tsx"]:::frontend
            HooksToast["use-toast.tsx"]:::frontend
            Utils["utils.ts"]:::frontend
        end

        Entry["Application Entry Point (main.tsx)"]:::frontend

        Styling["Styling & Theming"]:::config
        Configs["Build & Bundling Configs"]:::config
        Public["Public Static Assets"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Supabase["Supabase (Auth & DB)"]:::external
        GroqAPI["Groq LLM API"]:::external
        WebSpeechSR["Browser SpeechRecognition API"]:::external
        WebSpeechTTS["Browser TextToSpeech API"]:::external
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        Vite["Vite (Dev & Build)"]:::config
        StaticHost["Static Hosting"]:::external
    end

    %% Relationships
    CustomComponents -->|renders| Routing
    shadcnUI -->|renders| Routing
    Routing -->|uses| AuthContext
    AuthContext -->|provides auth| SupabaseClient
    SupabaseClient -->|calls| Supabase
    SupabaseTypes -->|types for| SupabaseClient

    Routing -->|calls| LLMService
    Routing -->|calls| ConversationService

    LLMService -->|HTTP POST| GroqAPI
    ConversationService -->|uses| SpeechRecog
    ConversationService -->|uses| TextToSpeech

    SpeechRecog -->|wraps| WebSpeechSR
    TextToSpeech -->|wraps| WebSpeechTTS

    ServicesLayer -->|fetches lesson| a1 & a2 & b1 & b2 & c1 & c2
    ServicesLayer -->|fetches activities| reading & listening
    ServicesLayer -->|fetches scenarios| convScenarios
    ServicesLayer -->|fetches stages| lessonStages
    ServicesLayer -->|fetches prompts| prompts
    ServicesLayer -->|uses mock| mockData

    Entry -->|imports| CustomComponents & Routing & AuthContext & SupabaseClient & LLMService & Utils
    Entry -->|bootstraps| Styling

    Vite -->|bundles| BrowserSPA
    Vite -->|injects env| GroqAPI & SupabaseClient
    StaticHost -->|serves| BrowserSPA

    %% Click Events
    click CustomComponents "https://github.com/yeheskieltame/linggo-english-hub/tree/main/src/components"
    click shadcnUI "https://github.com/yeheskieltame/linggo-english-hub/tree/main/src/components/ui"
    click Routing "https://github.com/yeheskieltame/linggo-english-hub/tree/main/src/pages"
    click AuthContext "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/providers/AuthProvider.tsx"
    click SupabaseClient "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/integrations/supabase/client.ts"
    click SupabaseTypes "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/integrations/supabase/types.ts"
    click LLMService "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/services/llmService.ts"
    click ConversationService "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/services/conversationService.ts"
    click SpeechRecog "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/services/speechRecognition.ts"
    click TextToSpeech "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/services/textToSpeech.ts"
    click LevelAssessment "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/services/levelAssessmentService.ts"
    click a1 "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/a1LessonData.ts"
    click a2 "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/a2LessonData.ts"
    click b1 "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/b1LessonData.ts"
    click b2 "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/b2LessonData.ts"
    click c1 "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/c1LessonData.ts"
    click c2 "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/c2LessonData.ts"
    click reading "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/readingActivities.ts"
    click listening "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/listeningActivities.ts"
    click convScenarios "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/conversationScenarios.ts"
    click lessonStages "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/lessonStagesData.ts"
    click prompts "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/practicePrompts.ts"
    click mockData "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/data/mockData.ts"
    click HooksMobile "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/hooks/use-mobile.tsx"
    click HooksToast "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/hooks/use-toast.ts"
    click Utils "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/lib/utils.ts"
    click Entry "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/main.tsx"
    click Styling "https://github.com/yeheskieltame/linggo-english-hub/blob/main/src/styles/theme.ts"
    click Configs "https://github.com/yeheskieltame/linggo-english-hub/blob/main/vite.config.ts"
    click Configs "https://github.com/yeheskieltame/linggo-english-hub/blob/main/tsconfig.json"
    click Configs "https://github.com/yeheskieltame/linggo-english-hub/blob/main/package.json"
    click Public "https://github.com/yeheskieltame/linggo-english-hub/tree/main/public/"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef service fill:#B3E5FC,stroke:#01579B,color:#01579B
    classDef external fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef data fill:#E0E0E0,stroke:#424242,color:#424242
    classDef config fill:#D1C4E9,stroke:#4A148C,color:#4A148C
```
