# sanidhyy/duolingo-clone architecture

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

- Interactive diagram: https://gitdiagram.com/sanidhyy/duolingo-clone
- Repository: https://github.com/sanidhyy/duolingo-clone

## Overview

##### Project Type and Purpose
- Full‑stack Next.js web application (app router) for interactive language learning, with user‑facing “main” and “marketing” sections, a “lesson” area, and a built‑in admin console.
- Features: course browsing, lessons with quizzes/challenges, user progress tracking (quests, leaderboard), a shop (Stripe payments), and administrative CRUD for courses, units, lessons, challenges.

##### File Structure
- Top‑level “app” directory holds all Next.js routes:
- (main) – user‑facing learning flows
- (marketing) – landing pages
- lesson – deep dive pages (quizzes, headers, footers)
- admin – react‑admin or custom CRUD UI
- api – RESTful endpoints (courses, lessons, challenges, units, Stripe webhooks)
- “db” folder with Drizzle‑ORM schema, queries, config.
- “lib” for utility wrappers (Clerk auth, Stripe client).
- “store” for client state (Zustand).
- “components” and “components/ui” for shared UI.
- “scripts” for seeding/migrations, “actions” for server actions.
- Config files: `.env`, Clerk & Stripe secrets, `next.config.mjs`, Tailwind.

##### README for Additional Insights
- Uses Clerk for authentication/authorization (NEXT_PUBLIC_CLERK_*, CLERK_SECRET_KEY).
- PostgreSQL (Neon) via Drizzle‑ORM.
- Stripe for payments and webhooks.
- Hosted on Vercel.
- Admin IDs stored in env to gate admin UI.

##### Main Components & Their Interactions
a. Client (Browser/Mobile)
- React/Next.js UI, Tailwind CSS, Zustand state, Sonner notifications.
- Two UI spheres: “Marketing” (static pages) and “Main” (authenticated learning).
- Admin UI under `/admin` (React‑Admin or custom).
b. Next.js Server
- App Router handles SSR/SSG, Server Actions (in “actions/”), API Routes under `app/api/*`.
- Auth middleware (Clerk).
- Business logic in `lib/` and `config/`.
c. Database
- PostgreSQL (Neon) with Drizzle‑ORM: tables for users, courses, units, lessons, challenges, options, progress, subscriptions.
d. External Services
- Clerk (Auth): token validation, user metadata, admin ID checks.
- Stripe (Payments): checkout sessions, webhooks to `app/api/webhooks/stripe/route.ts`.
e. CI/CD
- GitHub Actions (folder `.github/workflows`) for tests, lint, deploy to Vercel.
- Vercel for hosting front‑ and back‑end.

##### Architectural Patterns & Design Principles
- Next.js App Router (directory‑based routing; server vs. client components).
- RESTful API endpoints for each domain entity.
- Single codebase for frontend, backend, and admin console (monorepo‑style).
- Separation of concerns:
- UI components vs. page (route) components
- Server logic (API) vs. client logic (hooks/store)
- Domain modules (db schema, queries) vs. orchestration (Next.js routes)
- Drizzle‑ORM for type‑safe DB access.
- Zustand for lightweight global state (modals, progress).

##### Be Detailed but Structured
- **Group related routes** (e.g., all `/api/courses/*` endpoints).
- **Annotate** key technologies next to each component (e.g., “Next.js 14 App Router, TypeScript, Tailwind”).
- **Highlight** the serverless nature of API routes (Vercel Functions).
- **Call out** the real‑time/reactive UX (Zustand store, Sonner notifications, progress updates).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Browser)" 
        direction TB
        Marketing["Marketing Frontend\n(app/(marketing))\nNext.js App Router\nTailwind CSS"]:::client
        Main["Main Frontend\n(app/(main))\nAuth‑protected Learning\nReact/Next.js\nZustand"]:::client
        Lesson["Lesson Deep‑Dive\n(app/lesson)\nLayouts & Quiz UI"]:::client
        AdminUI["Admin Console UI\n(app/admin)\nCRUD for Courses, Units,\nLessons, Challenges"]:::client
    end

    %% Main Frontend Features
    subgraph "Main Features" 
        direction TB
        Browse["Course Browsing\n(app/(main)/courses)"]:::client
        Leaderboard["Leaderboard\n(app/(main)/leaderboard)"]:::client
        Learn["Units & Lessons\n(app/(main)/learn)"]:::client
        Quests["Quests\n(app/(main)/quests)"]:::client
        Shop["Shop (Stripe)\n(app/(main)/shop)"]:::client
    end

    Marketing -->|views pages| NextServer
    Main -->|views pages| NextServer
    Lesson -->|views deep pages| NextServer
    AdminUI -->|CRUD requests| NextServer

    Main --> Browse
    Main --> Leaderboard
    Main --> Learn
    Main --> Quests
    Main --> Shop

    %% Server Side
    subgraph "Next.js Server" 
        direction TB
        NextServer["Next.js Server\nApp Router, SSR/SSG,\nServer Actions, Middleware"]:::server

        subgraph "API Routes" 
            direction TB
            API_Courses["/api/courses/*"]:::api
            API_Units["/api/units/*"]:::api
            API_Lessons["/api/lessons/*"]:::api
            API_Challenges["/api/challenges/*"]:::api
            API_Options["/api/challengeOptions/*"]:::api
            API_Webhooks["/api/webhooks/stripe"]:::api
        end

        subgraph "Server Actions & Utils"
            direction TB
            Actions["Server Actions\n(actions/*)"]:::server
            Utils["Utilities\n(lib/utils.ts)"]:::server
            Config["Config & Constants\n(config/index.ts)"]:::server
            AuthWrapper["Admin Auth Wrapper\n(lib/admin.ts)"]:::server
            StripeClient["Stripe Client\n(lib/stripe.ts)"]:::server
            DBConfig["Drizzle Config\n(drizzle.config.ts)"]:::server
        end
    end

    NextServer -->|calls| API_Courses
    NextServer -->|calls| API_Units
    NextServer -->|calls| API_Lessons
    NextServer -->|calls| API_Challenges
    NextServer -->|calls| API_Options
    NextServer -->|receives webhook| API_Webhooks

    NextServer --> Actions
    NextServer --> Utils
    NextServer --> Config
    NextServer --> AuthWrapper
    NextServer --> StripeClient
    NextServer --> DBConfig

    %% Database
    subgraph "Database (PostgreSQL + Drizzle)" 
        direction TB
        Schema["Schema Definitions\n(db/schema.ts)"]:::db
        Queries["Query Helpers\n(db/queries.ts)"]:::db
    end

    DBConfig --> Schema
    DBConfig --> Queries
    NextServer -->|SQL via Drizzle| Schema

    %% External Services
    Clerk["Clerk Auth\n(token validation,\nuser metadata)"]:::external
    Stripe["Stripe Payments\nCheckout & Webhooks"]:::external

    NextServer -->|auth calls| Clerk
    NextServer -->|payment calls| Stripe
    API_Webhooks -->|webhook callback| Stripe

    %% CI/CD & Hosting
    subgraph "CI/CD & Hosting"
        direction TB
        GHActions["GitHub Actions\n(.github/workflows)"]:::cicd
        Vercel["Vercel Hosting\n(Next.js Serverless)"]:::cicd
    end

    GHActions -->|CI: test/lint/deploy| Vercel
    Vercel -->|hosts| NextServer

    %% Click Events
    click Marketing "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(marketing)"
    click Main "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(main)"
    click Browse "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(main)/courses"
    click Leaderboard "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(main)/leaderboard"
    click Learn "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(main)/learn"
    click Quests "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(main)/quests"
    click Shop "https://github.com/sanidhyy/duolingo-clone/tree/main/app/(main)/shop"
    click Lesson "https://github.com/sanidhyy/duolingo-clone/tree/main/app/lesson"
    click AdminUI "https://github.com/sanidhyy/duolingo-clone/tree/main/app/admin"
    click API_Courses "https://github.com/sanidhyy/duolingo-clone/blob/main/app/api/courses/route.ts"
    click API_Units "https://github.com/sanidhyy/duolingo-clone/blob/main/app/api/units/route.ts"
    click API_Lessons "https://github.com/sanidhyy/duolingo-clone/blob/main/app/api/lessons/route.ts"
    click API_Challenges "https://github.com/sanidhyy/duolingo-clone/blob/main/app/api/challenges/route.ts"
    click API_Options "https://github.com/sanidhyy/duolingo-clone/blob/main/app/api/challengeOptions/route.ts"
    click API_Webhooks "https://github.com/sanidhyy/duolingo-clone/blob/main/app/api/webhooks/stripe/route.ts"
    click Schema "https://github.com/sanidhyy/duolingo-clone/blob/main/db/schema.ts"
    click Queries "https://github.com/sanidhyy/duolingo-clone/blob/main/db/queries.ts"
    click AuthWrapper "https://github.com/sanidhyy/duolingo-clone/blob/main/lib/admin.ts"
    click StripeClient "https://github.com/sanidhyy/duolingo-clone/blob/main/lib/stripe.ts"
    click Actions "https://github.com/sanidhyy/duolingo-clone/blob/main/actions/challenge-progress.ts"
    click Utils "https://github.com/sanidhyy/duolingo-clone/blob/main/lib/utils.ts"
    click Config "https://github.com/sanidhyy/duolingo-clone/blob/main/config/index.ts"
    click DBConfig "https://github.com/sanidhyy/duolingo-clone/blob/main/drizzle.config.ts"
    click GHActions "https://github.com/sanidhyy/duolingo-clone/tree/main/.github/workflows"
    click Vercel "https://github.com/sanidhyy/duolingo-clone/blob/main/next.config.mjs"

    %% Styles
    classDef client fill:#add8e6,stroke:#000,stroke-width:1px
    classDef server fill:#90ee90,stroke:#000,stroke-width:1px
    classDef api fill:#90ee90,stroke-dasharray: 5 5,stroke:#000
    classDef db fill:#ffcc99,stroke:#000,stroke-width:1px
    classDef external fill:#d8bfd8,stroke:#000,stroke-width:1px
    classDef cicd fill:#d3d3d3,stroke:#000,stroke-width:1px
```
