# error0x0000001/glolang architecture

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

## Overview

##### Project type and purpose
- GloLang is a full-stack, Next.js 13 (App Router) web application for interactive language learning.
- It provides marketing pages, a “main” user area (courses, lessons, quests, shop, leaderboard), an admin console, and integrates with auth and payment services.

##### File structure (top-level components)
- app/
– (marketing): public marketing landing, header/footer layouts, static pages
– (main): authenticated user area—courses, learn, quests, shop, leaderboard
– admin: CRUD pages for challenges, courses, lessons, units
– api: Next.js serverless routes for challenges, courses, lessons, units, Stripe webhooks
– lesson: per-lesson UI components and layouts
- components/: shared React UI (modals, Sidebar, feed wrappers, ui library)
- actions/: server actions for challenge progress, user progress, subscriptions
- db/: Drizzle ORM setup, schema, and data queries
- lib/: wrappers for admin checks, Stripe SDK, utility functions
- store/: client state hooks (Zustand) for modal controls
- config/: environment‐driven configuration
- scripts/: database seed, reset, production build scripts
- middleware.ts: Clerk authentication enforcement
- next.config.mjs / drizzle.config.ts / tailwind.config.ts: build & styling configuration

##### README for additional insights
- Describes folder grouping, required environment variables including Clerk auth, Neon/PostgreSQL database, Stripe keys, and admin IDs.

a. Main components
1. Client (Browser / Mobile)
2. Next.js Application
– Frontend UI (React Server & Client Components in app/ and components/)
– API Layer (app/api/* serverless routes)
– Server Actions (actions/*)
– Middleware (Clerk auth checks)
3. Database (PostgreSQL via Drizzle ORM)
4. Authentication Service (Clerk)
5. Payment Service (Stripe + Webhooks)
6. Admin Console (Next.js admin pages)
b. Relationships and data flows
– Client → Next.js Frontend: HTTP(S) requests for SSR/SSG pages, client-side navigation
– Frontend → API Layer & Server Actions: fetch/update domain data (courses, lessons, progress)
– API Layer / Actions → Drizzle ORM → PostgreSQL: CRUD operations
– Middleware → Clerk: validate session, enforce protected routes
– Frontend & Server → Stripe SDK (lib/stripe.ts): create subscriptions, handle payments
– Stripe → Webhooks endpoint (app/api/webhooks/stripe/route.ts) → Actions → DB updates
c. Architectural patterns and principles
– Next.js App Router (layouts, nested routing, React Server Components)
– Server Actions for server-side logic collocated with UI
– Drizzle ORM for type-safe database access
– Middleware for cross-cutting concerns (auth enforcement)
– Zustand for lightweight client state management
– Separation of concerns: marketing vs. main app vs. admin
d. Key technologies and frameworks
– Next.js 13, React 18 (Server & Client Components)
– Drizzle ORM + PostgreSQL (Neon)
– Clerk (authentication)
– Stripe (billing & webhooks)
– Tailwind CSS
– TypeScript

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        client["Browser"]:::external
    end

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        direction TB
        Marketing["Marketing Pages"]:::internal
        MainUI["Main User Area"]:::internal
        LessonUI["Lesson Views"]:::internal
        SharedComp["Shared React Components"]:::internal
        Modals["UI Modals"]:::internal
        UILib["UI Library Components"]:::internal
        Store["Client State Management (Zustand)"]:::internal
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        direction TB

        subgraph "Domain APIs"
            direction TB
            COList["Challenge Options List API"]:::internal
            COItem["Challenge Option API"]:::internal
            ChList["Challenges List API"]:::internal
            ChItem["Challenge API"]:::internal
            CoursesList["Courses List API"]:::internal
            CourseItem["Course API"]:::internal
            LessonsList["Lessons List API"]:::internal
            LessonItem["Lesson API"]:::internal
            UnitsList["Units List API"]:::internal
            UnitItem["Unit API"]:::internal
            Webhook["Stripe Webhook Endpoint"]:::internal
        end

        subgraph "Server Actions"
            direction TB
            ActChallenge["Challenge Progress Action"]:::internal
            ActUserProg["User Progress Action"]:::internal
            ActSubscription["User Subscription Action"]:::internal
        end

        Middleware["Clerk Auth Middleware"]:::internal

        subgraph "Library & Utilities"
            direction TB
            AdminUtil["Admin Auth Utility"]:::internal
            StripeSDK["Stripe SDK Wrapper"]:::internal
            Utils["Utility Functions"]:::internal
        end

        subgraph "Database Layer"
            direction TB
            ORM["Drizzle ORM Setup"]:::internal
            Schema["Database Schema Definitions"]:::internal
            Queries["Database Queries"]:::internal
            DrizzleConf["Drizzle Configuration"]:::config
        end

        subgraph "Config & Scripts"
            direction TB
            ConfigEnv["Environment Config"]:::config
            Consts["Constants"]:::config
            NextConfig["Next.js Config"]:::config
            Tailwind["Tailwind Config"]:::config
            ProdScript["Production Script"]:::config
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ClerkAuth["Clerk Auth Service"]:::external
        StripeSvc["Stripe Service"]:::external
        Postgres["PostgreSQL Database"]:::external
    end

    %% Connections
    client --> Marketing
    client --> MainUI
    client --> LessonUI

    Marketing --> SharedComp
    MainUI --> SharedComp
    LessonUI --> SharedComp

    MainUI --> Modals
    MainUI --> UILib
    MainUI --> Store
    LessonUI --> Store

    MainUI --> COList
    MainUI --> ChList
    MainUI --> CoursesList
    MainUI --> LessonsList
    MainUI --> UnitsList

    MainUI --> ActChallenge
    MainUI --> ActUserProg
    MainUI --> ActSubscription

    COList --> ORM
    COItem --> ORM
    ChList --> ORM
    ChItem --> ORM
    CoursesList --> ORM
    CourseItem --> ORM
    LessonsList --> ORM
    LessonItem --> ORM
    UnitsList --> ORM
    UnitItem --> ORM

    Webhook -.-> ActSubscription
    Webhook -.-> ORM

    ORM --> Postgres
    ActChallenge --> ORM
    ActUserProg --> ORM
    ActSubscription --> ORM

    Middleware --> ClerkAuth
    MainUI -.->|protected routes| Middleware
    Marketing -.->|public routes| Middleware
    LessonUI -.-> Middleware

    MainUI --> StripeSDK
    ActSubscription --> StripeSDK
    StripeSDK --> StripeSvc
    StripeSvc -.-> Webhook

    %% Click Events
    click Marketing "https://github.com/error0x0000001/glolang/tree/main/app/(marketing)"
    click MainUI "https://github.com/error0x0000001/glolang/tree/main/app/(main)"
    click LessonUI "https://github.com/error0x0000001/glolang/tree/main/app/lesson"
    click SharedComp "https://github.com/error0x0000001/glolang/tree/main/components/"
    click Modals "https://github.com/error0x0000001/glolang/tree/main/components/modals"
    click UILib "https://github.com/error0x0000001/glolang/tree/main/components/ui"
    click Store "https://github.com/error0x0000001/glolang/tree/main/store/"
    click COList "https://github.com/error0x0000001/glolang/blob/main/app/api/challengeOptions/route.ts"
    click COItem "https://github.com/error0x0000001/glolang/blob/main/app/api/challengeOptions/[challengeOptionId]/route.ts"
    click ChList "https://github.com/error0x0000001/glolang/blob/main/app/api/challenges/route.ts"
    click ChItem "https://github.com/error0x0000001/glolang/blob/main/app/api/challenges/[challengeId]/route.ts"
    click CoursesList "https://github.com/error0x0000001/glolang/blob/main/app/api/courses/route.ts"
    click CourseItem "https://github.com/error0x0000001/glolang/blob/main/app/api/courses/[courseId]/route.ts"
    click LessonsList "https://github.com/error0x0000001/glolang/blob/main/app/api/lessons/route.ts"
    click LessonItem "https://github.com/error0x0000001/glolang/blob/main/app/api/lessons/[lessonId]/route.ts"
    click UnitsList "https://github.com/error0x0000001/glolang/blob/main/app/api/units/route.ts"
    click UnitItem "https://github.com/error0x0000001/glolang/blob/main/app/api/units/[unitId]/route.ts"
    click Webhook "https://github.com/error0x0000001/glolang/blob/main/app/api/webhooks/stripe/route.ts"
    click ActChallenge "https://github.com/error0x0000001/glolang/blob/main/actions/challenge-progress.ts"
    click ActUserProg "https://github.com/error0x0000001/glolang/blob/main/actions/user-progress.ts"
    click ActSubscription "https://github.com/error0x0000001/glolang/blob/main/actions/user-subscription.ts"
    click Middleware "https://github.com/error0x0000001/glolang/blob/main/middleware.ts"
    click ORM "https://github.com/error0x0000001/glolang/blob/main/db/drizzle.ts"
    click Schema "https://github.com/error0x0000001/glolang/blob/main/db/schema.ts"
    click Queries "https://github.com/error0x0000001/glolang/blob/main/db/queries.ts"
    click DrizzleConf "https://github.com/error0x0000001/glolang/blob/main/drizzle.config.ts"
    click AdminUtil "https://github.com/error0x0000001/glolang/blob/main/lib/admin.ts"
    click StripeSDK "https://github.com/error0x0000001/glolang/blob/main/lib/stripe.ts"
    click Utils "https://github.com/error0x0000001/glolang/blob/main/lib/utils.ts"
    click ConfigEnv "https://github.com/error0x0000001/glolang/blob/main/config/index.ts"
    click Consts "https://github.com/error0x0000001/glolang/blob/main/config/constants.ts"
    click NextConfig "https://github.com/error0x0000001/glolang/blob/main/next.config.mjs"
    click Tailwind "https://github.com/error0x0000001/glolang/blob/main/tailwind.config.ts"
    click ProdScript "https://github.com/error0x0000001/glolang/blob/main/scripts/prod.ts"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef config fill:#ffebcc,stroke:#333,stroke-width:1px;
```
