# nhockool1002/laos-self-learning architecture

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

- Interactive diagram: https://gitdiagram.com/nhockool1002/laos-self-learning
- Repository: https://github.com/nhockool1002/laos-self-learning

## Overview

##### Project type and purpose
- This is a full-stack-style, single-page application (SPA) with an optional desktop packaging layer (Electron).
- Its purpose is to teach Lao language with interactive lessons, quizzes, user authentication, progress tracking, and badges.

##### File structure
- Top-level:
- electron.js – entry point for Electron desktop wrapper
- webpack.config.js / tsconfig.json – build and compile configuration
- public/ – static assets (index.html, PWA manifest, badge images)
- src/ – all TypeScript/React source code
- Inside src/:
- pages/ – route-level components (Home, Lessons, Practice, Tests, WritingBoard)
- components/ – reusable UI components (FlashCard, Layout, LoginModal, etc.)
- contexts/ – React Contexts for global state (AuthContext)
- services/ – data-access/service layer (badgeService, supabase calls)
- config/ – environment and Supabase configuration
- data/ – static lesson and practice data
- i18n.ts – localization setup
- demo/ – sample scripts (createBadge)
- CI/CD: .github/workflows/ci.yml runs tests and builds.

##### README for additional insights
- Tech stack: React + TypeScript, Material-UI, React Router, i18next, Supabase (Auth + Storage), Electron for desktop.
- Functional modules: alphabet lessons, quizzes, scoring, badges, user auth and progress persistence.

a. Main components
- Client Application (React SPA)
- Electron Host (optional desktop container)
- Static Asset Server / CDN (serves index.html, JS bundle, images)
- Supabase Backend (Auth service, Postgres DB, Storage)
- External APIs (e.g., Google Sheets API if used, ResponsiveVoice TTS)
b. Relationships & data flows
- User ↔ React UI: user interactions trigger component logic
- React UI → Service layer: badgeService.ts, supabaseConfig.ts → Supabase SDK
- Supabase Auth ↔ React Context (AuthContext) manages login state
- React UI ↔ Supabase Database: fetch/save user progress, badges
- React UI loads static data from src/data (lessons, practice)
- Electron.js wraps the built SPA and communicates via IPC if needed
- CI Pipeline → Build → Deploy to hosting (optional)
c. Architectural patterns & design principles
- Layered Architecture: UI layer (components/pages) → Service layer → Data layer (Supabase + static JSON)
- Component-Based: reusable React components with single responsibility
- Context API for global state (authentication, theming)
- Client-side routing (React Router) for page navigation
- BaaS (Supabase) offloads backend responsibilities
d. Key technologies & libraries
- React, React Router, React Context, TypeScript
- Material-UI for styling, i18next for localization
- Supabase JS SDK for Auth & Database
- Electron for desktop packaging
- Webpack for bundling

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions"]:::infra
        Build["Build & Deploy"]:::infra
        CI --> Build
    end

    subgraph "Client Layer"
        subgraph "Electron Host"
            Electron["Electron Host"]:::infra
            click Electron "https://github.com/nhockool1002/laos-self-learning/blob/main/electron.js"
        end

        subgraph "React SPA"
            Entry["index.tsx"]:::frontend
            click Entry "https://github.com/nhockool1002/laos-self-learning/blob/main/src/index.tsx"
            App["App.tsx"]:::frontend
            click App "https://github.com/nhockool1002/laos-self-learning/blob/main/src/App.tsx"

            subgraph "Pages"
                Home["Home.tsx"]:::frontend
                click Home "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/Home.tsx"
                Lessons["Lessons.tsx"]:::frontend
                click Lessons "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/Lessons.tsx"
                Practice["Practice.tsx"]:::frontend
                click Practice "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/Practice.tsx"
                Tests["Tests.tsx"]:::frontend
                click Tests "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/Tests.tsx"
                Writing["WritingBoard.tsx"]:::frontend
                click Writing "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/WritingBoard.tsx"
                Alphabet["Alphabet.tsx"]:::frontend
                click Alphabet "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/Alphabet.tsx"
                Game["Game.tsx"]:::frontend
                click Game "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/Game.tsx"
                PaperPracticePg["PaperPractice.tsx"]:::frontend
                click PaperPracticePg "https://github.com/nhockool1002/laos-self-learning/blob/main/src/pages/PaperPractice.tsx"
            end

            subgraph "Components"
                FlashCard["FlashCard.tsx"]:::frontend
                click FlashCard "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/FlashCard.tsx"
                Layout["Layout.tsx"]:::frontend
                click Layout "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/Layout.tsx"
                LoginModal["LoginModal.tsx"]:::frontend
                click LoginModal "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/LoginModal.tsx"
                LoginButton["LoginButton.tsx"]:::frontend
                click LoginButton "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/LoginButton.tsx"
                Footer["Footer.tsx"]:::frontend
                click Footer "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/Footer.tsx"
                PaperPracticeCmp["PaperPractice.tsx"]:::frontend
                click PaperPracticeCmp "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/PaperPractice.tsx"
                UserRank["UserRank.tsx"]:::frontend
                click UserRank "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/UserRank.tsx"
                UserTooltip["UserTooltip.tsx"]:::frontend
                click UserTooltip "https://github.com/nhockool1002/laos-self-learning/blob/main/src/components/UserTooltip.tsx"
            end

            Entry --> App
            App --> Pages
            App --> Components
        end

        Electron --> Entry
    end

    subgraph "Context & Services"
        AuthContext["AuthContext.tsx"]:::service
        click AuthContext "https://github.com/nhockool1002/laos-self-learning/blob/main/src/contexts/AuthContext.tsx"
        BadgeService["badgeService.ts"]:::service
        click BadgeService "https://github.com/nhockool1002/laos-self-learning/blob/main/src/services/badgeService.ts"
        SupabaseConfig["supabaseConfig.ts"]:::service
        click SupabaseConfig "https://github.com/nhockool1002/laos-self-learning/blob/main/src/config/supabaseConfig.ts"
    end

    App --> AuthContext
    Pages --> BadgeService
    Components --> AuthContext

    BadgeService --> SupabaseConfig
    SupabaseConfig --> Supabase["Supabase SDK"]:::backend
    AuthContext --> Supabase

    subgraph "Data Layer"
        LessonsData["lessons/index.ts"]:::data
        click LessonsData "https://github.com/nhockool1002/laos-self-learning/blob/main/src/data/lessons/index.ts"
        PracticeData["practiceData.ts"]:::data
        click PracticeData "https://github.com/nhockool1002/laos-self-learning/blob/main/src/data/practiceData.ts"
        PracticeCfg["practiceConfig.json"]:::data
        click PracticeCfg "https://github.com/nhockool1002/laos-self-learning/blob/main/src/practiceConfig.json"
    end

    App --> LessonsData
    Practice --> PracticeData

    subgraph "Public / Static Assets"
        IndexHTML["index.html"]:::static
        click IndexHTML "https://github.com/nhockool1002/laos-self-learning/blob/main/public/index.html"
        Manifest["manifest.json"]:::static
        click Manifest "https://github.com/nhockool1002/laos-self-learning/blob/main/public/manifest.json"
        BadgesImg["public/badges"]:::static
        click BadgesImg "https://github.com/nhockool1002/laos-self-learning/tree/main/public/badges/"
    end

    Entry --> IndexHTML
    IndexHTML --> Manifest
    IndexHTML --> BadgesImg

    subgraph "Backend Services"
        SupabaseAuth["Supabase Auth"]:::backend
        SupabaseDB["Supabase Postgres"]:::backend
        SupabaseStorage["Supabase Storage"]:::backend
    end

    Supabase --> SupabaseAuth
    Supabase --> SupabaseDB
    Supabase --> SupabaseStorage

    subgraph "External Services"
        GoogleTTS["ResponsiveVoice TTS"]:::external
        GoogleSheets["Google Sheets API"]:::external
    end

    App --> GoogleTTS
    BadgeService --> GoogleSheets

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef backend fill:#32CD32,stroke:#333,stroke-width:1px
    classDef external fill:#98FB98,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef static fill:#E0FFFF,stroke:#333,stroke-width:1px
```
