# gaurav0973/lms architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav0973/lms
- Repository: https://github.com/gaurav0973/lms

## Overview

##### Project Type and Purpose
- This is a full-stack web application (LMS) built with Next.js (app router) that handles both frontend pages and backend API routes.
- It provides user authentication (GitHub & email), communicates with a PostgreSQL database via Prisma ORM, and sends emails via Resend.

##### File Structure
Top-level directories and files:
- app/ – Next.js app router directory, contains page routes and layouts for public and auth-protected areas.
- app/api/auth/[...all]/route.ts – Next.js API route implementing BetterAuth authentication middleware.
- components/ui/ – Reusable UI primitives (ShadCN components).
- lib/ – Business-logic helpers: arcjet (rate-limiting), auth (BetterAuth setup), auth-client, db (Prisma client), env, resend (Resend email wrapper), utils.
- prisma/schema.prisma – DB schema.
- public/ – Static assets.
- Configuration: next.config.ts, tailwind.config.ts, postcss.config.mjs, tsconfig.json, Docker setup implied for PostgreSQL.

##### README for Insights
- Tech stack confirms Next.js (full-stack), PostgreSQL in Docker, Prisma, BetterAuth, Resend, ShadCN.
- Features: GitHub & email login, email flows via Resend.
- Future: rate limiting with arcjet.

##### Main Components
a. Client (Browser / Next.js Frontend pages)
b. Next.js Server (Server-side rendering, API routes)
c. Authentication Layer (BetterAuth middleware / auth client)
d. Database (PostgreSQL container) accessed via Prisma ORM
e. Email Service (Resend)
f. External OAuth Provider (GitHub)
g. Rate-limiting component (arcjet)

##### Relationships & Data Flows
- Client ↔ Next.js Server: page requests (SSR/SSG) and API calls (fetch to /api/auth/*).
- Next.js Server → DB: Prisma executes SQL queries against PostgreSQL.
- Next.js Server → Resend API: sending verification & login emails.
- Next.js Server ↔ GitHub OAuth endpoints: redirect & callback for GitHub login.
- Next.js Server ↔ arcjet: rate-limit checks before processing auth/API calls.
- DB stores user, session, verification tokens.
- UI Components (ShadCN) sit within the Client/Next.js pages.

##### Architectural Patterns & Design Principles
- “App router” folder-based routing (Next.js)
- Separation of concerns: UI (components/ui), API routes (app/api), data access (lib/db), auth logic (lib/auth, lib/auth-client).
- Middleware pattern for authentication (BetterAuth) in API routes.
- Infrastructure as code: Dockerized DB, environment variables (lib/env).

[ ] All major components represented (Client, Next.js Server, DB, Resend, GitHub OAuth, arcjet)
[ ] Notes or annotations for critical paths (e.g., “Email login flow”, “OAuth callback”)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend Layer
  subgraph "Frontend" 
    direction TB
    ClientPublic["Public Page<br>app/(public)/page.tsx"]:::frontend
    ClientAuth["Auth-Protected Page<br>app/(auth)/login/page.tsx"]:::frontend
    RootLayout["Root Layout<br>app/layout.tsx"]:::frontend
    PublicLayout["Public Layout<br>app/(public)/layout.tsx"]:::frontend
    AuthLayout["Auth Layout<br>app/(auth)/layout.tsx"]:::frontend
    UIComponents["UI Components<br>components/ui/"]:::frontend
    GlobalCSS["Global Stylesheet<br>app/globals.css"]:::frontend
  end

  %% Backend Layer
  subgraph "Backend & Business Logic"
    direction TB
    NextServer["Next.js Server"]:::backend
    APIRoutes["Auth API Routes<br>app/api/auth/[...all]/route.ts"]:::backend
    AuthMiddleware["BetterAuth Middleware<br>lib/auth.ts"]:::backend
    AuthClient["Auth Client<br>lib/auth-client.ts"]:::backend
    DBClient["Prisma Client<br>lib/db.ts"]:::backend
    Env["Env Config<br>lib/env.ts"]:::backend
    Arcjet["Rate Limiting (arcjet)<br>lib/arcjet.ts"]:::backend
    ResendLib["Resend Integration<br>lib/resend.ts"]:::backend
  end

  %% External Services
  subgraph "External Services"
    direction TB
    GitHub["GitHub OAuth"]:::external
    ResendService["Resend Email Service"]:::external
  end

  %% Infrastructure
  subgraph "Infrastructure"
    direction TB
    Postgres[(PostgreSQL DB)]:::db
    DBSchema["Schema File<br>prisma/schema.prisma"]:::db
  end

  %% Connections - Frontend to Backend
  ClientPublic -->|"SSR/SSG"| RootLayout
  ClientAuth -->|"SSR/SSG"| RootLayout
  RootLayout --> PublicLayout
  RootLayout --> AuthLayout
  PublicLayout -->|"renders via"| NextServer
  AuthLayout -->|"renders via"| NextServer
  ClientPublic -->|"uses UI libs"| UIComponents
  ClientAuth -->|"uses UI libs"| UIComponents
  RootLayout --> GlobalCSS

  %% API Calls and Auth Flow
  ClientAuth -->|"API call /api/auth"| APIRoutes
  APIRoutes -->|"middleware"| AuthMiddleware
  AuthMiddleware -->|"rate-limit check"| Arcjet
  APIRoutes -->|"uses client"| AuthClient
  APIRoutes -->|"redirect/callback"| GitHub
  GitHub -->|"OAuth callback"| APIRoutes

  %% Backend to Services & DB
  NextServer -->|"executes queries"| DBClient
  DBClient -->|"reads/writes"| Postgres
  DBSchema --> Postgres
  NextServer -->|"sends email via"| ResendLib
  ResendLib -->|"API request"| ResendService
  NextServer --> Env

  %% Click Events
  click ClientPublic "https://github.com/gaurav0973/lms/blob/main/app/(public)/page.tsx"
  click ClientAuth "https://github.com/gaurav0973/lms/blob/main/app/(auth)/login/page.tsx"
  click RootLayout "https://github.com/gaurav0973/lms/blob/main/app/layout.tsx"
  click PublicLayout "https://github.com/gaurav0973/lms/blob/main/app/(public)/layout.tsx"
  click AuthLayout "https://github.com/gaurav0973/lms/blob/main/app/(auth)/layout.tsx"
  click APIRoutes "https://github.com/gaurav0973/lms/blob/main/app/api/auth/[...all]/route.ts"
  click AuthMiddleware "https://github.com/gaurav0973/lms/blob/main/lib/auth.ts"
  click AuthClient "https://github.com/gaurav0973/lms/blob/main/lib/auth-client.ts"
  click DBClient "https://github.com/gaurav0973/lms/blob/main/lib/db.ts"
  click DBSchema "https://github.com/gaurav0973/lms/blob/main/prisma/schema.prisma"
  click ResendLib "https://github.com/gaurav0973/lms/blob/main/lib/resend.ts"
  click Arcjet "https://github.com/gaurav0973/lms/blob/main/lib/arcjet.ts"
  click Env "https://github.com/gaurav0973/lms/blob/main/lib/env.ts"
  click UIComponents "https://github.com/gaurav0973/lms/tree/main/components/ui/"

  %% Styles
  classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
  classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
  classDef external fill:#FFF3E0,stroke:#E65100,color:#E65100
  classDef db fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
