# rohan-hazari/chessmates architecture

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

- Interactive diagram: https://gitdiagram.com/rohan-hazari/chessmates
- Repository: https://github.com/rohan-hazari/chessmates

## Overview

##### Project type and purpose
- ChessMates is a full‑stack social media web application built with Next.js (13+ App Router), TypeScript, Prisma ORM, and NextAuth.
- It provides user authentication, community‑driven posts/comments/voting, chess puzzle creation, and file uploads.

##### File structure
- Top‑level config: next.config.js, tsconfig.json, tailwind.config.js, prisma/schema.prisma, vercel.json
- Frontend React code under src/app (layout.tsx, page.tsx, nested route folders) and src/components
- API layer as Next.js Route Handlers under src/app/api/**
- Business logic and utilities under src/lib (db.ts, auth.ts, validators, redis.ts, uploadthing.ts)
- Prisma migrations under prisma/migrations
- Hooks in src/hooks and shared types in src/types

##### Key insights from the README
- "ChessMates is a comprehensive social media platform for chess enthusiasts"
- Requires a database (Prisma migrations) and environment variables (OAuth, database URL, Redis)
- Uses NextAuth for authentication

##### Main components
a. Presentation Layer
- Next.js App Router (React Server & Client Components)
- UI Components (src/components/ui, shared, chess‑specific, post feeds, editor)
b. API Layer
- Next.js Route Handlers under src/app/api:
– Authentication (NextAuth)
– User registration, CAPTCHA verification
– Community: create/edit posts, comments, voting, subscribe/unsubscribe
– Chess puzzles: CRUD puzzle endpoints
– File uploads via Uploadthing
– Search & links
c. Business Logic / Services
- src/lib/auth.ts (session checks)
- src/lib/db.ts (Prisma client)
- src/lib/redis.ts (caching rate‑limits, leaderboards)
- src/lib/uploadthing.ts
- src/lib/validators (input validation per domain)
d. Data Layer
- PostgreSQL (or another SQL DB) accessed via Prisma Client
- Redis cache
e. Third‑Party / External Services
- OAuth providers (Google, GitHub, etc.) via NextAuth
- CAPTCHA service
- File storage (Uploadthing backend or S3)

##### Relationships and interactions
- Browser ↔ Next.js (UI & SSR)
- UI calls API endpoints (fetch, mutate)
- API → Business Logic (validators → auth checks → db calls)
- Business Logic → Data stores (Prisma → PostgreSQL, Redis)
- Authentication middleware → NextAuth OAuth flow → External OAuth provider → NextAuth callbacks → Session cookie
- Uploadthing route → External storage

##### Architectural patterns & design principles
- Single codebase for frontend & backend via Next.js App Router
- Serverless Route Handlers (Function-as‑a‑Service)
- Layered architecture: Presentation → API → Services → Data
- Validation at service boundaries (lib/validators)
- Stateless functions, cached state in Redis
- Prisma migrations enforce schema evolution

##### Elements
- Notes on authentication flow (session cookie, JWT, OAuth callbacks)
- Prisma migrations as part of deployment pipeline (optional)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    Browser["Web Browser"]:::frontend

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Layout["layout.tsx"]:::frontend
        Page["page.tsx"]:::frontend
        NotFound["not-found.tsx"]:::frontend
        SignIn["sign-in/page.tsx"]:::frontend
        SignUp["sign-up/page.tsx"]:::frontend
        CommunityPage["c/[slug]/page.tsx"]:::frontend
        ProtectedLayout["c/[slug]/(protected)/layout.tsx"]:::frontend
        EditDescription["c/[slug]/(protected)/edit-description/page.tsx"]:::frontend
        PuzzleSubmit["c/[slug]/(protected)/puzzle-submit/page.tsx"]:::frontend
        Submit["c/[slug]/(protected)/submit/page.tsx"]:::frontend
        UIComponents["UI Components"]:::frontend
        SharedComponents["Shared Components"]:::frontend
        ChessComponents["Chess Components"]:::frontend
        PostVoteComponents["PostVote Components"]:::frontend
    end

    %% API & Business Logic Layer
    subgraph "API & Business Logic" 
        direction TB
        subgraph "API Layer"
            direction TB
            AuthAPI["Auth API"]:::api
            RegisterAPI["Register API"]:::api
            CaptchaAPI["Captcha API"]:::api
            CommunityAPI["Community API"]:::api
            PuzzleAPI["Chess Puzzle API"]:::api
            UploadAPI["Uploadthing API"]:::api
            SearchAPI["Search & Links API"]:::api
        end
        subgraph "Business Logic"
            direction TB
            DBClient["Prisma Client"]:::api
            AuthService["Auth Service"]:::api
            RedisService["Redis Service"]:::api
            UploadService["Uploadthing Service"]:::api
            Validators["Validators"]:::api
        end
    end

    %% Data & External Layer
    subgraph "Data & External"
        direction TB
        subgraph "Data Layer"
            direction TB
            Postgres["PostgreSQL Database"]:::data
            RedisCache["Redis Cache"]:::data
            Migrations["Prisma Migrations"]:::data
        end
        subgraph "External Services"
            direction TB
            OAuthProvider["OAuth Provider"]:::external
            CaptchaService["CAPTCHA Service"]:::external
            FileStorage["File Storage"]:::external
        end
    end

    %% Connections
    Browser -->|"Requests"| Layout
    Browser -->|"Requests"| CommunityPage

    Layout -->|renders| UIComponents
    CommunityPage -->|renders| CoreComponents{"Core React Components"}:::frontend

    CoreComponents --> RegisterAPI
    CoreComponents --> AuthAPI
    CoreComponents --> CommunityAPI
    CoreComponents --> PuzzleAPI
    CoreComponents --> UploadAPI
    CoreComponents --> SearchAPI

    AuthAPI -->|uses| AuthService
    RegisterAPI -->|uses| AuthService
    CaptchaAPI -->|uses| Validators
    CommunityAPI -->|uses| Validators
    PuzzleAPI -->|uses| Validators
    UploadAPI -->|uses| UploadService
    SearchAPI -->|uses| DBClient

    AuthService -->|reads/writes| DBClient
    Validators -->|validates| DBClient
    DBClient -->|connects| Postgres
    RedisService -->|cache| RedisCache

    AuthService -->|OAuth flow| OAuthProvider
    CaptchaAPI -->|verify| CaptchaService
    UploadService -->|store files| FileStorage

    Migrations -->|schema| Postgres

    %% Click Events Presentation
    click Layout "https://github.com/rohan-hazari/chessmates/blob/main/src/app/layout.tsx"
    click Page "https://github.com/rohan-hazari/chessmates/blob/main/src/app/page.tsx"
    click NotFound "https://github.com/rohan-hazari/chessmates/blob/main/src/app/not-found.tsx"
    click SignIn "https://github.com/rohan-hazari/chessmates/blob/main/src/app/(auth)/sign-in/page.tsx"
    click SignUp "https://github.com/rohan-hazari/chessmates/blob/main/src/app/(auth)/sign-up/page.tsx"
    click CommunityPage "https://github.com/rohan-hazari/chessmates/blob/main/src/app/c/[slug]/page.tsx"
    click ProtectedLayout "https://github.com/rohan-hazari/chessmates/blob/main/src/app/c/[slug]/(protected)/layout.tsx"
    click EditDescription "https://github.com/rohan-hazari/chessmates/blob/main/src/app/c/[slug]/(protected)/edit-description/page.tsx"
    click PuzzleSubmit "https://github.com/rohan-hazari/chessmates/blob/main/src/app/c/[slug]/(protected)/puzzle-submit/page.tsx"
    click Submit "https://github.com/rohan-hazari/chessmates/blob/main/src/app/c/[slug]/(protected)/submit/page.tsx"
    click UIComponents "https://github.com/rohan-hazari/chessmates/tree/main/src/components/ui"
    click SharedComponents "https://github.com/rohan-hazari/chessmates/tree/main/src/components/shared"
    click ChessComponents "https://github.com/rohan-hazari/chessmates/tree/main/src/components/chess"
    click PostVoteComponents "https://github.com/rohan-hazari/chessmates/tree/main/src/components/post-vote"

    %% Click Events API
    click AuthAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/(auth)/auth/[...nextauth]/route.ts"
    click RegisterAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/(auth)/register/route.ts"
    click CaptchaAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/captcha-verify/route.ts"
    click CommunityAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/community/route.ts"
    click PuzzleAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/chess/puzzle/route.ts"
    click UploadAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/uploadthing/route.ts"
    click SearchAPI "https://github.com/rohan-hazari/chessmates/blob/main/src/app/api/search/route.ts"

    %% Click Events Business Logic
    click DBClient "https://github.com/rohan-hazari/chessmates/blob/main/src/lib/db.ts"
    click AuthService "https://github.com/rohan-hazari/chessmates/blob/main/src/lib/auth.ts"
    click RedisService "https://github.com/rohan-hazari/chessmates/blob/main/src/lib/redis.ts"
    click UploadService "https://github.com/rohan-hazari/chessmates/blob/main/src/lib/uploadthing.ts"
    click Validators "https://github.com/rohan-hazari/chessmates/tree/main/src/lib/validators"

    %% Click Events Data
    click Migrations "https://github.com/rohan-hazari/chessmates/tree/main/prisma/migrations"
    click Postgres "https://github.com/rohan-hazari/chessmates/blob/main/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#008000,stroke-width:1px
    classDef api fill:#cce5ff,stroke:#0000ff,stroke-width:1px
    classDef data fill:#ffe5cc,stroke:#ff6600,stroke-width:1px
    classDef external fill:#e5ccff,stroke:#800080,stroke-width:1px
```
