# vietducc/brainy-kids-frontend architecture

> Architecture diagram of the GitHub repository vietducc/brainy-kids-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vietducc/brainy-kids-frontend
- Repository: https://github.com/vietducc/brainy-kids-frontend

## Overview

##### Main Components
- Frontend UI Layer: This is primarily in the “app” and “components” directories. The “app” folder holds the major pages and layouts (e.g., homepage, courses, learn, leaderboard) while the “components” folder contains reusable UI components (landing sections, headers, buttons, sidebars, etc.).
- Business Logic & Utilities: The “actions”, “lib”, “utils”, and “types” directories house business logic, utility functions, and type definitions.
- Static Assets: The “public” folder includes assets (like audio files) used by the application.
- Configuration & Build: Files such as next.config.ts, tsconfig.json, tailwind.config.ts, and others represent deployment, build configurations, and styling setups.

##### Relationships and Interactions
- User Interface pages (for example, courses and lessons) are rendered via components and layouts, and they then interact with backend API endpoints to fetch or update data.
- UI Elements such as course cards, lesson screens, and sidebars will trigger calls (using the actions and/or utilities) to the API routes.
- The API routes encapsulate business logic, connecting the UI with the underlying data processing.
- There is a shared logic layer (in “utils”, “lib”, and “actions”) that is used by both the UI and API endpoints.
- The Next.js middleware and global configurations (e.g., next.config.ts) handle request routing and overall application behavior.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Notice how the project cleanly separates the frontend UI (pages/layouts/components) from the backend business logic (API routes).
- Modular Design: Reusable components are placed in a dedicated “components” directory. The API routes are modularly organized per resource (courses, lessons, progress).
- Next.js App Router Pattern: Leveraging file-based routing with “app/(main)” and “app/api” directories allows for a clear delineation between server-side and client-side code.
- Type Safety: Use of TypeScript with type definitions in the “types” folder ensures data consistency across the application.

##### Relevant Technologies & Frameworks
- Next.js: For full-stack React development using server components and file-based routing.
- Tailwind CSS: Implied by tailwind.config.ts for styling.
- TypeScript: For type-checking across components, API routes, and utilities.
- ESLint: For code quality, evidenced by .eslintrc.json and eslint.config.mjs.

○ Client Side Rendering: Modules for “UI Components” (components, pages, layouts).
○ API Layer: Blocks representing API routes for courses, lessons, lesson-progress, user-progress.
○ Utilities & Business Logic: Separate module representing “actions”, “lib”, “utils”, and “types”.
○ Configuration Layer: A smaller block for config files (next.config.ts, tailwind.config.ts, etc.).
○ Public Assets: Represented as a resource that the UI can access.
○ The flow from user interactions with the UI to API calls.
○ Data flow from the API to the business logic/utilities.
○ How static assets are integrated into the frontend.
- If needed, include annotations to describe how middleware and global application configurations affect requests.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend UI Layer
    subgraph "Frontend UI Layer"
        PagesLayouts["Pages & Layouts"]:::frontend
        ReusableComponents["Reusable UI Components"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        CoursesAPI["Courses API"]:::api
        LessonsAPI["Lessons API"]:::api
        LessonProgressAPI["Lesson Progress API"]:::api
        UserProgressAPI["User Progress API"]:::api
        UnitsAPI["Units API"]:::api
    end

    %% Business Logic & Utilities
    subgraph "Business Logic & Utilities"
        Actions["Actions"]:::logic
        AppUtils["App Utilities"]:::logic
        ProjectUtils["Project Utilities"]:::logic
        LibUtilities["Lib Utilities"]:::logic
        TypeDefinitions["Type Definitions"]:::logic
    end

    %% Global Configurations & Static Assets
    subgraph "Configuration & Assets"
        GlobalConfig["Global Configurations"]:::config
        StaticAssets["Static Assets"]:::config
    end

    %% Connections from Frontend UI to API Layer
    PagesLayouts -->|"fetch_data"| CoursesAPI
    PagesLayouts -->|"fetch_data"| LessonsAPI
    PagesLayouts -->|"fetch_data"| LessonProgressAPI
    PagesLayouts -->|"fetch_data"| UserProgressAPI
    PagesLayouts -->|"fetch_data"| UnitsAPI

    %% Connection from Frontend UI Components to Actions
    ReusableComponents -->|"trigger_actions"| Actions

    %% Connections from API Layer to Business Logic
    CoursesAPI -->|"process"| Actions
    LessonsAPI -->|"process"| Actions
    LessonProgressAPI -->|"process"| Actions
    UserProgressAPI -->|"process"| Actions
    UnitsAPI -->|"process"| Actions

    %% Actions utilizing utilities
    Actions -->|"utilize"| AppUtils
    Actions -->|"utilize"| ProjectUtils
    Actions -->|"utilize"| LibUtilities

    %% Utilities use type definitions
    AppUtils -->|"typed_by"| TypeDefinitions
    ProjectUtils -->|"typed_by"| TypeDefinitions
    LibUtilities -->|"typed_by"| TypeDefinitions

    %% Global configurations influence Frontend and API
    GlobalConfig -->|"configures"| PagesLayouts
    GlobalConfig -->|"configures"| CoursesAPI
    GlobalConfig -->|"configures"| LessonsAPI
    GlobalConfig -->|"configures"| LessonProgressAPI
    GlobalConfig -->|"configures"| UserProgressAPI
    GlobalConfig -->|"configures"| UnitsAPI

    %% Static assets feed into Frontend UI
    StaticAssets -->|"assets_for"| PagesLayouts

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef api fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef logic fill:#ABEBC6,stroke:#239B56,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

    %% Click Events
    click PagesLayouts "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/(main)"
    click ReusableComponents "https://github.com/vietducc/brainy-kids-frontend/tree/main/components"
    click CoursesAPI "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/api/courses"
    click LessonsAPI "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/api/lessons"
    click LessonProgressAPI "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/api/lesson-progress"
    click UserProgressAPI "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/api/user-progress"
    click UnitsAPI "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/api/units"
    click Actions "https://github.com/vietducc/brainy-kids-frontend/tree/main/actions"
    click AppUtils "https://github.com/vietducc/brainy-kids-frontend/tree/main/app/utils"
    click ProjectUtils "https://github.com/vietducc/brainy-kids-frontend/tree/main/utils"
    click LibUtilities "https://github.com/vietducc/brainy-kids-frontend/tree/main/lib"
    click TypeDefinitions "https://github.com/vietducc/brainy-kids-frontend/tree/main/types"
    click StaticAssets "https://github.com/vietducc/brainy-kids-frontend/tree/main/public"
    click GlobalConfig "https://github.com/vietducc/brainy-kids-frontend/blob/main/next.config.ts"
```
