# icantcodefyi/cattype architecture

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

- Interactive diagram: https://gitdiagram.com/icantcodefyi/cattype
- Repository: https://github.com/icantcodefyi/cattype

## Overview

##### Project type and purpose
– CatType is a full-stack, server-rendered React application built with Next.js 13 (App Router). Its purpose is to provide a typing practice app with customizable themes and code snippets, backed by a database for recording typing results and user sessions.

##### File structure
- Top-level:
– app/ – Next.js “App Router” directory containing page.tsx, layout.tsx, global CSS, and API route handlers under app/api
– components/ – reusable UI and provider components (session, theme, dialogs, etc.)
– lib/ – client-side utilities (auth-client, themes registry, code snippets), Prisma client setup, shared types, and utility functions
– prisma/ – Prisma schema and migrations for the database
– public/ – static assets (sounds, images)
– config files (next.config.ts, tailwind.config.ts, postcss.config.mjs, tsconfig.json)
– package.json & pnpm-lock.yaml – dependency declarations

##### README for additional insights
– Tech stack: Next.js 13 (React, SSR/ISR), TypeScript, TailwindCSS, Prisma (ORM), NextAuth (session management), pnpm
– Core features: themes (lib/themes), code snippets (lib/code-snippets), typing results API (app/api/typing-results), session-based authentication

a. Main components:
- Client (User’s Browser): renders pages, runs React components, interacts via REST/fetch
- Next.js Server (Node.js):
– SSR/SSG Renderer (app/page.tsx, app/layout.tsx)
– API Layer (app/api routes, e.g. typing-results, catch-all)
- Authentication Service: NextAuth session provider + custom auth logic (lib/auth-client.ts, lib/auth.ts, session-provider component)
- Database: PostgreSQL (or configured RDBMS) accessed via Prisma client (lib/prisma.ts, prisma/schema.prisma)
- Static Asset CDN: serves /public files (sounds, robots.txt, sitemap) and optimized fonts (next/font)
- External Services: Vercel (hosting, font optimization), optional OAuth providers

b. Relationships & interactions:
1. Browser → Next.js SSR: initial HTTP GET for page
2. Next.js SSR → Database via Prisma (to fetch user’s stats, snippets, themes)
3. SSR → Browser: sends HTML + CSS + JS bundle
4. Browser hydrates and invokes client-side React (components, hooks)
5. Client → API Layer (fetch /api/typing-results to save results, /api/[...all] if implemented)
6. API handlers → Prisma → Database (read/write typing-results, user/session data)
7. Session provider components call NextAuth endpoints under the API layer for login/logout
8. Static assets & fonts served directly from CDN

c. Architectural patterns & principles:
- Hybrid SSR/CSR (Next.js App Router)
- Atomic, composable UI (components/ui, shared dialogs, providers)
- Separation of concerns: presentation (components), business logic (lib/utils, hooks), persistence (Prisma)
- API-first design: serverless route handlers co-located under app/api
- Theming and snippet libraries as pure-function modules

d. Key technologies & libraries:
- Next.js 13 (React 18, App Router)
- TypeScript
- TailwindCSS & PostCSS
- Prisma ORM & PostgreSQL
- NextAuth (session management)
- pnpm (package manager)
- Vercel (deployment)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Browser / Client"
        direction TB
        Browser["Browser\n(Client)"]:::client
        UI["UI Component Library"]:::ui
        CoreUI["Core Components & Providers"]:::ui
        Hooks["Custom Hooks"]:::client
    end

    %% SSR Renderer
    subgraph "Next.js SSR Renderer"
        direction TB
        Page["app/page.tsx"]:::server
        Layout["app/layout.tsx"]:::server
        GlobalsCSS["app/globals.css"]:::server
    end

    %% API Layer
    subgraph "API Layer (Serverless Routes)"
        direction TB
        TypingResults["app/api/typing-results/route.ts"]:::api
        CatchAll["app/api/[...all]/route.ts"]:::api
    end

    %% Authentication Service
    subgraph "Authentication Service"
        direction TB
        AuthLib["lib/auth.ts"]:::auth
        AuthClient["lib/auth-client.ts"]:::auth
        SessionProvider["components/providers/session-provider.tsx"]:::auth
    end

    %% Prisma / Database
    subgraph "Prisma Client & Database"
        direction TB
        PrismaClient["lib/prisma.ts"]:::dbclient
        Schema["prisma/schema.prisma"]:::dbclient
        Migration["prisma/migrations/20250215000619_init/migration.sql"]:::dbclient
        DB["Database\n(PostgreSQL)"]:::database
    end

    %% Libraries
    subgraph "Configuration Libraries"
        direction TB
        ThemesRegistry["lib/themes.ts"]:::lib
        ThemesReg["lib/themes/registry.ts"]:::lib
        ThemesLoader["lib/themes/loader.ts"]:::lib
        DefaultThemes["lib/themes/default-themes.ts"]:::lib
        ThemeTypes["lib/themes/types.ts"]:::lib
        Snippets["lib/code-snippets.ts"]:::lib
        UtilsMain["lib/utils.ts"]:::lib
        ImageCapture["lib/utils/image-capture.ts"]:::lib
        StatsUtil["lib/utils/stats.ts"]:::lib
        StatsTypes["lib/types/stats.ts"]:::lib
    end

    %% Static Assets & CDN
    subgraph "Static Assets & CDN"
        direction TB
        PublicAssets["public/"]:::cdn
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Vercel["Vercel\n(Hosting & CDN)"]:::cloud
        OAuth["OAuth Providers"]:::cloud
    end

    %% Interactions
    Browser -->|"HTTP GET\nInitial Page"| Page
    Page -->|"Includes Layout & CSS"| Layout
    Page --> GlobalsCSS
    Page -->|"ServerRender\nfetch data"| PrismaClient
    Layout --> PrismaClient
    PrismaClient -.->|Reads/Writes| DB
    Page -->|"Sends HTML/CSS/JS"| Browser
    Browser -->|"Hydrate React"| UI
    Browser --> UI
    Browser --> CoreUI
    Browser --> Hooks
    Browser -->|"fetch /api/typing-results"| TypingResults
    Browser -->|"fetch /api/[...all]"| CatchAll
    TypingResults -->|"Uses Prisma Client"| PrismaClient
    CatchAll --> PrismaClient
    TypingResults --> AuthLib
    CatchAll --> AuthLib
    AuthLib --> DB
    AuthClient --> AuthLib
    SessionProvider --> AuthClient
    %% Both SSR & Client use themes, snippets, utils
    Page --> ThemesRegistry
    Page --> Snippets
    Page --> UtilsMain
    Browser --> ThemesRegistry
    Browser --> Snippets
    Browser --> UtilsMain
    ThemesRegistry --> ThemesReg
    ThemesRegistry --> ThemesLoader
    ThemesRegistry --> DefaultThemes
    ThemesRegistry --> ThemeTypes
    UtilsMain --> ImageCapture
    UtilsMain --> StatsUtil
    StatsUtil --> StatsTypes

    Browser -->|"Load static assets"| PublicAssets
    Page --> PublicAssets
    Layout --> PublicAssets

    Vercel --> Page
    Vercel --> PublicAssets
    OAuth --> AuthLib

    %% Click Events
    click Page "https://github.com/icantcodefyi/cattype/blob/main/app/page.tsx"
    click Layout "https://github.com/icantcodefyi/cattype/blob/main/app/layout.tsx"
    click GlobalsCSS "https://github.com/icantcodefyi/cattype/blob/main/app/globals.css"
    click TypingResults "https://github.com/icantcodefyi/cattype/blob/main/app/api/typing-results/route.ts"
    click CatchAll "https://github.com/icantcodefyi/cattype/blob/main/app/api/[...all]/route.ts"
    click AuthLib "https://github.com/icantcodefyi/cattype/blob/main/lib/auth.ts"
    click AuthClient "https://github.com/icantcodefyi/cattype/blob/main/lib/auth-client.ts"
    click SessionProvider "https://github.com/icantcodefyi/cattype/blob/main/components/providers/session-provider.tsx"
    click PrismaClient "https://github.com/icantcodefyi/cattype/blob/main/lib/prisma.ts"
    click Schema "https://github.com/icantcodefyi/cattype/blob/main/prisma/schema.prisma"
    click Migration "https://github.com/icantcodefyi/cattype/blob/main/prisma/migrations/20250215000619_init/migration.sql"
    click ThemesRegistry "https://github.com/icantcodefyi/cattype/blob/main/lib/themes.ts"
    click ThemesReg "https://github.com/icantcodefyi/cattype/blob/main/lib/themes/registry.ts"
    click ThemesLoader "https://github.com/icantcodefyi/cattype/blob/main/lib/themes/loader.ts"
    click DefaultThemes "https://github.com/icantcodefyi/cattype/blob/main/lib/themes/default-themes.ts"
    click ThemeTypes "https://github.com/icantcodefyi/cattype/blob/main/lib/themes/types.ts"
    click Snippets "https://github.com/icantcodefyi/cattype/blob/main/lib/code-snippets.ts"
    click UtilsMain "https://github.com/icantcodefyi/cattype/blob/main/lib/utils.ts"
    click ImageCapture "https://github.com/icantcodefyi/cattype/blob/main/lib/utils/image-capture.ts"
    click StatsUtil "https://github.com/icantcodefyi/cattype/blob/main/lib/utils/stats.ts"
    click StatsTypes "https://github.com/icantcodefyi/cattype/blob/main/lib/types/stats.ts"
    click PublicAssets "https://github.com/icantcodefyi/cattype/tree/main/public/"
    click SessionProvider "https://github.com/icantcodefyi/cattype/blob/main/components/providers/session-provider.tsx"

    %% Styles
    classDef client fill:#D6E9FE,stroke:#1E4A78,color:#1E4A78
    classDef server fill:#E3F6D5,stroke:#2F8F1D,color:#2F8F1D
    classDef api fill:#FFF4CF,stroke:#CC9A00,color:#CC9A00
    classDef auth fill:#FEE2E2,stroke:#B91C1C,color:#B91C1C
    classDef dbclient fill:#E0F2FE,stroke:#0369A1,color:#0369A1
    classDef database fill:#C8F7C5,stroke:#2C662D,color:#2C662D
    classDef lib fill:#F3E8FF,stroke:#6D28D9,color:#6D28D9
    classDef ui fill:#FEF3C7,stroke:#B45309,color:#B45309
    classDef cdn fill:#E8F0FE,stroke:#1E40AF,color:#1E40AF
    classDef cloud fill:#E0E7FF,stroke:#4338CA,color:#4338CA
```
