# jeancdevx/duolingo-clone architecture

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

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

## Overview

##### Project type and purpose
- This is “Lingo,” a Duolingo-style full-stack web application built on Next.js’s App Router.
- It offers user authentication, course browsing and learning flows, admin CRUD pages, real-time progress tracking, payment/subscription via Stripe, and persistent storage in PostgreSQL.

##### File structure
- Top-level folders
- app/ – Next.js pages and API routes (App Router)
– (auth), (main), (marketing), admin UI under app/admin
– RESTful API subfolders under app/api
- components/ – React UI components, organized by feature
- db/ – Drizzle ORM config, schema, and queries
- lib/ – helper modules (admin enforcement, Stripe integration, utils)
- store/ – Zustand hooks for controlling modals
- scripts/ – data-seeding and production scripts
- public/ – static assets (SVGs, audio, images)
- middleware.ts – Next.js middleware (likely auth or routing)
- next.config.mjs, tailwind.config.ts, postcss.config.mjs – build and styling configs
- Key configuration:
- Clerk for auth (env keys)
- Stripe for payments (webhooks under app/api/webhooks/stripe)
- Neon/PostgreSQL via DATABASE_URL
- Drizzle ORM for type-safe DB access

##### Main components
a. Frontend (User-Facing)
- Next.js UI (app/(marketing), app/(auth), app/(main))
- React components (components/, pages under app/)
- Client-side state/hooks (store/)
b. Backend / Serverless
- Next.js API routes (app/api/*) deployed as serverless functions on Vercel
- Middleware (middleware.ts) for auth/session handling
c. Database
- PostgreSQL (Neon) accessed via Drizzle ORM (db/)
- Schema for users, courses, units, lessons, challenges, progress
d. External Services
- Clerk – user authentication & admin check (lib/admin.ts)
- Stripe – payment processing, webhook handler (lib/stripe.ts, app/api/webhooks/stripe)
e. Deployment Platform
- Vercel hosting for both frontend and serverless API

##### Relationships & data flows
- User → Next.js frontend (SSR/SSR + client-side hydration)
- Frontend ↔ API routes
- API routes → Drizzle ORM → PostgreSQL
- API routes → Stripe SDK → Stripe backend (create subscriptions, listen to webhooks)
- Middleware → Clerk APIs → enforce authentication/authorization
- Scripts (seed.ts, production.ts) → Drizzle → populate DB

##### Architectural patterns & design principles
- Monolithic Frontend/Backend in one Next.js repo using App Router
- “Feature folder” structure: grouping UI and logic by domain (courses, lessons, admin)
- Serverless functions for each API resource (RESTful endpoints)
- Middleware pattern for auth gating
- Type-safe DB access with Drizzle ORM
- Separation of concerns: UI (components/) vs data access (db/) vs business logic (lib/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Marketing["Marketing Pages"]:::frontend
        Auth["Auth Routes"]:::frontend
        MainUI["Main User UI"]:::frontend
        AdminUI["Admin UI"]:::frontend
        ReactComp["React UI Components"]:::frontend
        StateHooks["Client-Side State Hooks"]:::frontend
    end

    %% Serverless Layer
    subgraph "Serverless Layer (Vercel)"
        direction TB
        subgraph "API Routes"
            direction TB
            CoursesAPI["API: /api/courses"]:::backend
            UnitsAPI["API: /api/units"]:::backend
            LessonsAPI["API: /api/lessons"]:::backend
            ChallengesAPI["API: /api/challenges"]:::backend
            ChallengeOptsAPI["API: /api/challengeOptions"]:::backend
            StripeWebhook["API: /api/webhooks/stripe"]:::backend
        end
        Middleware["Middleware"]:::backend
        BackgroundActions["Background Actions"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DrizzleConfig["Drizzle ORM"]:::db
        Postgres["PostgreSQL (Neon)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth"]:::external
        Stripe["Stripe Payments"]:::external
    end

    %% Scripts
    Scripts["Data & Production Scripts"]:::script

    %% Connections
    Marketing -->|"SSR & API calls"| CoursesAPI
    Auth -->|"Auth checks"| Middleware
    MainUI -->|"Data fetch"| CoursesAPI
    AdminUI -->|"Admin CRUD calls"| CoursesAPI
    ReactComp -->|"UI interactions"| CoursesAPI
    StateHooks -->|"State management"| ReactComp

    CoursesAPI -->|"ORM queries"| DrizzleConfig
    UnitsAPI -->|"ORM queries"| DrizzleConfig
    LessonsAPI -->|"ORM queries"| DrizzleConfig
    ChallengesAPI -->|"ORM queries"| DrizzleConfig
    ChallengeOptsAPI -->|"ORM queries"| DrizzleConfig

    DrizzleConfig -->|"SQL read/write"| Postgres
    BackgroundActions -->|"Progress & subscription updates"| DrizzleConfig
    Scripts -->|"Seed & reset DB"| DrizzleConfig

    Middleware -->|"User session enforcement"| Clerk
    StripeWebhook -->|"Webhook events"| Stripe
    CoursesAPI -->|"Create subscription"| Stripe
    BackgroundActions -->|"Subscription status"| Stripe

    %% Click Events
    click Marketing "https://github.com/jeancdevx/duolingo-clone/tree/master/app/(marketing)"
    click Auth "https://github.com/jeancdevx/duolingo-clone/tree/master/app/(auth)"
    click MainUI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/(main)"
    click AdminUI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/admin"
    click CoursesAPI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/api/courses"
    click UnitsAPI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/api/units"
    click LessonsAPI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/api/lessons"
    click ChallengesAPI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/api/challenges"
    click ChallengeOptsAPI "https://github.com/jeancdevx/duolingo-clone/tree/master/app/api/challengeOptions"
    click StripeWebhook "https://github.com/jeancdevx/duolingo-clone/blob/master/app/api/webhooks/stripe/route.ts"
    click Middleware "https://github.com/jeancdevx/duolingo-clone/blob/master/middleware.ts"
    click DrizzleConfig "https://github.com/jeancdevx/duolingo-clone/tree/master/db"
    click Postgres "https://github.com/jeancdevx/duolingo-clone/tree/master/db"
    click Clerk "https://github.com/jeancdevx/duolingo-clone/blob/master/lib/admin.ts"
    click Stripe "https://github.com/jeancdevx/duolingo-clone/blob/master/lib/stripe.ts"
    click Scripts "https://github.com/jeancdevx/duolingo-clone/tree/master/scripts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef db fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef external fill:#ECEFF1,stroke:#546E7A,color:#37474F
    classDef script fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
