# lachsfilet/quizzly architecture

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

- Interactive diagram: https://gitdiagram.com/lachsfilet/quizzly
- Repository: https://github.com/lachsfilet/quizzly

## Overview

##### Project Type and Purpose
- Full-stack web application built with Next.js (App Router).
- Core features: user registration/login via NextAuth, quiz creation, quiz discovery & playing, password reset, email verification.
- Uses Prisma ORM for database access, Tailwind CSS for UI, server actions for form handling, and a mail service to send tokens.

##### File Structure
- Top-level “app/” directory: Next.js routes and React Server/Client Components.
- “actions/” folder: Next.js server actions handling form submissions (register, login, reset, etc.).
- “app/api/auth/…[...nextauth]”: NextAuth endpoint for session management.
- “components/”: hundreds of React components (UI primitives, quiz cards, forms, modals).
- “lib/”: shared utilities (db connection, token logic, mailer).
- “prisma/schema.prisma”: data model for users, quizzes, tokens.
- Config files: next.config.js, tailwind.config.ts, tsconfig.json.

##### README (empty here)
- No extra architecture section; deduce from code and conventions.

##### Main Components & Relationships

A. User’s Browser (Client)
– React Client Components (hooks, form UI, quiz viewer)
– Static assets from “public/”

B. Next.js Server (App Router)
– React Server Components under “app/”
– API Routes /auth endpoints (NextAuth)
– Server Actions in “actions/” for POST handling (register.ts, login.ts, reset.ts, etc.)

C. Authentication Layer
– NextAuth middleware/adapter calling Prisma for session storage
– auth.config.ts + “/app/api/auth” route

D. Business Logic & Utilities
– lib/db.ts establishes connection to Postgres via Prisma Client
– lib/tokens.ts handles JWT or random token generation
– lib/mail.ts sends emails via external SMTP/SendGrid

E. Database
– Postgres (or another SQL) storing Users, Quizzes, Questions, Options, Tokens
– Prisma ORM as the single point of access

F. External Services
– Email provider (SMTP)
– Optional OAuth providers (if configured in NextAuth)

##### Interactions & Data Flow
1) User opens UI → Browser fetches SSR HTML/JSON from Next.js.
2) Client Component invokes server action (e.g. register) → HTTP POST to Next.js server action → lib/db and lib/mail → database write + email send → response.
3) User logs in → NextAuth endpoint → validates credentials via Prisma → issues session cookie/JWT → browser stores cookie.
4) Authenticated requests (quiz creation, fetch user) → Next.js Server Components read session via NextAuth → fetch data from DB via Prisma → render pages.
5) Public routes (discover quizzes) → data fetch from DB without session.
6) Password reset flow: user requests reset → server action writes token in DB → lib/mail sends reset email → user clicks link → server action verifies token → updates password.

##### Architectural Patterns & Principles
- 3-Tier architecture: Presentation (React), Application (Next.js + server actions + NextAuth), Data (Prisma + DB).
- Server-Client Component split (Next.js App Router) for SSR & hydration.
- Single source of truth for config in “prisma/schema.prisma” and NextAuth config.
- Separation of concerns: UI (“components/”), logic (“lib/”), data models (“prisma/” & “schemas/”), configuration.
- Utilize server-side actions and edge functions for auth flows.

##### Final Checklist
– Separate Frontend vs. Backend zones.
– Identify all Next.js subsystems (App Router, Server Actions, API routes, Middleware).
– Highlight Prisma-DB interactions.
– Show external email service.
– Annotate technology stacks (TypeScript, Tailwind, NextAuth).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (UI)" 
        direction TB
        Browser["User's Browser"]:::frontend
        UI["UI Components"]:::frontend
        Assets["Static Assets"]:::frontend
        Styles["Global Styles (Tailwind)"]:::frontend
        Layouts["App Layout & Root Pages"]:::frontend

        Browser -->|loads| UI
        Browser -->|loads| Assets
        UI -->|uses| Styles
        UI -->|renders| Layouts
    end

    %% Backend Layer
    subgraph "Backend (Next.js App)" 
        direction TB
        SC["Next.js Server Components (app/)"]:::backend
        SA["Server Actions (actions/)"]:::backend
        NAE["NextAuth Endpoint"]:::backend
        NAC["NextAuth Config"]:::backend

        SC -->|invokes| SA
        SC -->|handles auth| NAE
        NAE -->|reads config| NAC
    end

    %% Auth & Quiz Actions
    subgraph "Auth & Quiz Modules"
        direction TB
        RegAct["Register Action"]:::backend
        LoginAct["Login Action"]:::backend
        LogoutAct["Logout Action"]:::backend
        ResetAct["Password Reset Actions"]:::backend
        NewVerif["Email Verification Action"]:::backend
        QuizAct["Quiz Actions"]:::backend

        SA --> RegAct
        SA --> LoginAct
        SA --> LogoutAct
        SA --> ResetAct
        SA --> NewVerif
        SA --> QuizAct
        NAE --> LoginAct
    end

    %% Routes
    subgraph "App Routes & Pages"
        direction TB
        QuizRoutes["Quiz Discovery & Viewing Routes"]:::frontend
        UserProfile["User Profile Route"]:::frontend

        SC --> QuizRoutes
        SC --> UserProfile
    end

    %% Utilities Layer
    subgraph "Utilities & Services"
        direction TB
        DBConn["DB Connection (lib/db.ts)"]:::data
        Token["Token Logic (lib/tokens.ts)"]:::backend
        MailUtil["Email Sending Utility (lib/mail.ts)"]:::backend

        SA --> DBConn
        NAE --> DBConn
        SA --> Token
        SA --> MailUtil
        Token --> MailUtil
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ORM["Prisma ORM (schema.prisma)"]:::data
        DB[(Postgres DB)]:::data

        DBConn --> ORM
        ORM -->|SQL queries| DB
    end

    %% External Services
    subgraph "External Services"
        direction TB
        EmailExt["Email Provider (SMTP/SendGrid)"]:::external
        OAuth["OAuth Providers"]:::external

        MailUtil -->|sends email| EmailExt
        NAE -->|optional OAuth| OAuth
    end

    %% Client-Server Interaction
    Browser -->|HTTP GET/POST| SC
    Browser -->|session cookie| NAE
    SC -->|renders HTML/JSON| Browser

    %% Click Events
    click UI "https://github.com/lachsfilet/quizzly/tree/main/components/"
    click Assets "https://github.com/lachsfilet/quizzly/tree/main/public/"
    click SC "https://github.com/lachsfilet/quizzly/tree/main/app/"
    click SA "https://github.com/lachsfilet/quizzly/tree/main/actions/"
    click NAE "https://github.com/lachsfilet/quizzly/blob/main/app/api/auth/[...nextauth]/route.ts"
    click NAC "https://github.com/lachsfilet/quizzly/blob/main/auth.config.ts"
    click ORM "https://github.com/lachsfilet/quizzly/blob/main/prisma/schema.prisma"
    click DBConn "https://github.com/lachsfilet/quizzly/blob/main/lib/db.ts"
    click Token "https://github.com/lachsfilet/quizzly/blob/main/lib/tokens.ts"
    click MailUtil "https://github.com/lachsfilet/quizzly/blob/main/lib/mail.ts"
    click QuizAct "https://github.com/lachsfilet/quizzly/blob/main/actions/quiz.ts"
    click ResetAct "https://github.com/lachsfilet/quizzly/blob/main/actions/auth/new-password.ts"
    click ResetAct "https://github.com/lachsfilet/quizzly/blob/main/actions/auth/reset.ts"
    click NewVerif "https://github.com/lachsfilet/quizzly/blob/main/actions/auth/new-verification.ts"
    click RegAct "https://github.com/lachsfilet/quizzly/blob/main/actions/auth/register.ts"
    click LoginAct "https://github.com/lachsfilet/quizzly/blob/main/actions/auth/login.ts"
    click LogoutAct "https://github.com/lachsfilet/quizzly/blob/main/actions/auth/logout.ts"
    click Styles "https://github.com/lachsfilet/quizzly/blob/main/app/globals.css"
    click Styles "https://github.com/lachsfilet/quizzly/blob/main/tailwind.config.ts"
    click Layouts "https://github.com/lachsfilet/quizzly/blob/main/app/layout.tsx"
    click Layouts "https://github.com/lachsfilet/quizzly/blob/main/app/page.tsx"
    click QuizRoutes "https://github.com/lachsfilet/quizzly/blob/main/app/(root)/(routes)/discover/page.tsx"
    click QuizRoutes "https://github.com/lachsfilet/quizzly/blob/main/app/(root)/(routes)/quiz/[quizId]/page.tsx"
    click UserProfile "https://github.com/lachsfilet/quizzly/blob/main/app/(root)/(routes)/user/[id]/page.tsx"

    %% Styles
    classDef frontend fill:#e0f7ff,stroke:#0066cc,color:#000;
    classDef backend fill:#e6ffe6,stroke:#008000,color:#000;
    classDef data fill:#fff0b3,stroke:#e68a00,color:#000;
    classDef external fill:#f2f2f2,stroke:#666666,color:#000;
```
