# codedu-collective/kind-hands architecture

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

- Interactive diagram: https://gitdiagram.com/codedu-collective/kind-hands
- Repository: https://github.com/codedu-collective/kind-hands

## Overview

##### Project Type and Purpose
- Kind Hands is a full-stack, server-rendered web application built on Next.js 16 with TypeScript and Tailwind CSS.
- It’s a charity platform that connects donors and volunteers to causes, events, and team information, backed by a PostgreSQL database via Prisma ORM.

##### File Structure Analysis
- Top-level directories:
- app/ – Next.js App Router pages (server & client components).
- components/ – Reusable UI components organized by feature (landing, causes, event, layout, etc.).
- lib/ – Database client wrapper (Prisma).
- prisma/ – Database schema, migrations, seeds.
- utils/ – Data-fetching helpers (cause/event retrieval).
- Config files: next.config.ts, tsconfig.json, eslint.config.mjs, postcss.config.mjs.
- Build scripts and dependencies defined in package.json/pnpm-lock.yaml.

##### README Insights
- Confirms tech stack: Next.js App Router, React 19, TypeScript, Tailwind CSS.
- Lists setup of environment variables (DATABASE_URL, POSTGRES_URL, PRISMA_DATABASE_URL).
- No separate API folder: server components call Prisma client directly for data.

##### Main Components
a. Frontend Layer (Client Browser)
- React components (components/*)
- Tailwind CSS for styling
- Static assets from public/ via Next.js static file server
b. Next.js Server (Node.js)
- App Router (app/) for routing & rendering
- Server Components fetch data using utils/* → lib/prisma.ts
- Client Components for interactivity (ThemeToggle, subscribe forms, etc.)
c. Data Access Layer
- Prisma Client (lib/prisma.ts)
- TypeScript types (implicit in utils & Prisma schema)
d. Database Layer
- PostgreSQL instance (PRISMA_DATABASE_URL)
- Prisma schema and migrations (prisma/schema.prisma, prisma/migrations/)
e. Build & Deployment
- PNPM build pipeline (pnpm dev, build, start)
- Vercel (or other Node host) for serverless deployment
- Tailwind CSS/PostCSS during build

##### Relationships and Interactions
- Browser → HTTP Request → Next.js Server Router
- Router invokes Server Component (app/page.tsx or dynamic route)
- Server Component calls utils/get/* → Prisma Client → PostgreSQL
- Data returns to Server Component → HTML/JSON → Browser
- Client Components hydrate on the browser for interactivity
- Static assets served directly from public/ via CDN or Next.js

##### Architectural Patterns & Principles
- File-based routing with Next.js App Router (server-first, with selective client components).
- Layered architecture:
- Presentation (React UI)
- Business Logic (utils/get, server components)
- Data Access (Prisma)
- Persistence (PostgreSQL)
- Convention-over-configuration: Next.js, Prisma migrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Browser"
        direction TB
        Browser["Browser"]:::frontend
        subgraph "UI Components"
            direction TB
            UIComponents["React Components (components/)"]:::frontend
        end
        Assets["Static Assets (public/)"]:::assets
    end

    %% Server Layer
    subgraph "Next.js Server"
        direction TB
        AppRouter["Next.js App Router (app/)"]:::server
        Styles["Tailwind & Global Styles (app/globals.css, postcss.config.mjs)"]:::server
        Utils["Data Fetching Helpers (utils/get/)"]:::server
        PrismaClient["Prisma Client (lib/prisma.ts)"]:::server
        Config["Config & Build Scripts"]:::server
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        PrismaSchema["Prisma Schema & Migrations (prisma/)"]:::db
        DB["PostgreSQL"]:::db
    end

    %% Connections
    Browser -->|"HTTP Request"| AppRouter
    AppRouter -->|"loads Server Components"| AppRouter
    AppRouter -->|"fetch data via utils"| Utils
    Utils -->|"calls Prisma Client"| PrismaClient
    PrismaClient -->|"queries"| DB
    DB -->|"returns data"| PrismaClient
    PrismaClient -->|"returns results"| Utils
    Utils -->|"returns data"| AppRouter
    AppRouter -->|"renders HTML/JSON"| Browser
    Browser -->|"loads assets"| Assets
    AppRouter -->|"serves styles"| Styles
    Config -->|"build & deploy"| AppRouter
    PrismaSchema -->|"defines schema & migrations"| DB

    %% Click Events
    click AppRouter "https://github.com/codedu-collective/kind-hands/tree/main/app/"
    click UIComponents "https://github.com/codedu-collective/kind-hands/tree/main/components/"
    click Assets "https://github.com/codedu-collective/kind-hands/tree/main/public/"
    click Styles "https://github.com/codedu-collective/kind-hands/blob/main/app/globals.css"
    click PrismaClient "https://github.com/codedu-collective/kind-hands/blob/main/lib/prisma.ts"
    click Utils "https://github.com/codedu-collective/kind-hands/tree/main/utils/get/"
    click PrismaSchema "https://github.com/codedu-collective/kind-hands/tree/main/prisma/"
    click DB "https://github.com/codedu-collective/kind-hands/blob/main/prisma/schema.prisma"
    click Config "https://github.com/codedu-collective/kind-hands/blob/main/package.json"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef server fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef db fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef assets fill:#ECEFF1,stroke:#455A64,color:#455A64
```
