# mohamed-4rarh/next-supabase-starter architecture

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

- Interactive diagram: https://gitdiagram.com/mohamed-4rarh/next-supabase-starter
- Repository: https://github.com/mohamed-4rarh/next-supabase-starter

## Overview

##### Project Type and Purpose
- This is a full-stack web application starter built with Next.js 15, Supabase (Auth + Postgres), and React Query.
- It provides reusable UI components (ShadCN + Tailwind), custom React Query hooks for data fetching/mutations, Supabase authentication and middleware, and form validation with Zod.

##### File Structure
- Top-level “app” directory: Next.js App Router with two primary route groups:
- `(auth)`: login/register/confirm/error pages + auth actions + layout
- `(dashboard)`: protected dashboard pages + layout
- “components”: shared UI primitives (buttons, cards, form controls) + a query‐provider wrapper and Auth state component
- “hooks”: `use-client-fetch.ts` & `use-client-mutation.ts` wrapping React Query + Supabase
- “lib”: `auth-context.tsx` (React Context for user state) + misc utilities
- “supabase”: client config, server helpers, and Next.js middleware integration
- Configuration files: next.config.ts, middleware.ts, Tailwind/PostCSS, ESLint, TypeScript

##### README for Additional Insights
- Confirms tech stack: Next.js 15, Supabase Auth & Database, React Query, ShadCN, Tailwind, Zod.
- Illustrates usage patterns: AuthContext provider, client fetch/mutate hooks, route protection, form validation.

a. Main Components
- Frontend (Next.js App):
– Pages & Layouts (app/(auth), app/(dashboard), app/page.tsx)
– Shared UI Library (components/ui)
– React Query & Auth Wrappers (components/query-provider.tsx, lib/auth-context.tsx)
– Custom Hooks (hooks/use-client-fetch & use-client-mutation)
- API Layer (Next.js Server + Supabase Client):
– Next.js Middleware (middleware.ts)
– Supabase client (supabase/client.ts) for authenticated calls
– Supabase server helpers (supabase/server.ts) for edge/server components
- Data Layer
– Supabase Postgres Database (tables for users, posts, etc.)
– Supabase Auth Service
- Utilities & Config
– Zod (schema validation, used in forms)
– Tailwind/PostCSS styling pipeline
– TypeScript types & ESLint

b. Relationships & Data Flows
- User Browser → Next.js App (Client Components & Pages)
- Client Components → React Query Hooks → Supabase Client → Supabase Auth/DB
- Next.js Middleware intercepts requests to protect dashboard routes and forward auth tokens
- AuthContext wraps the tree, reading `supabase.auth.getUser()` via React Query
- Mutations & Queries flow: UI → `useClientFetch`/`useClientMutate` → Supabase → React Query cache → UI
- Public assets served from `/public`

c. Architectural Patterns & Principles
- Folder-based routing (Next.js App Router)
- Separation of concerns: UI, Data Fetching, Auth, API integration
- React Context for cross-cutting concerns (authentication)
- Hook composition for reusable data logic
- Edge/Server components for SSR/edge middleware

d. Key Technologies & Libraries
- Next.js 15 (App Router, Middleware, Server/Client Components)
- Supabase (Auth + Postgres Database)
- React Query (caching, stale-while-revalidate)
- ShadCN UI + Tailwind CSS (design system)
- Zod (runtime data validation)
- TypeScript

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser
    Browser["User Browser"]:::external

    %% Frontend Client
    subgraph "Frontend Client"
        direction TB
        NextApp["Next.js App (Client)"]:::client
        subgraph "Routes & Layouts"
            direction TB
            AuthRoutes["app/(auth)"]:::client
            DashboardRoutes["app/(dashboard)"]:::client
            Layout["app/layout.tsx"]:::client
            HomePage["app/page.tsx"]:::client
        end
        subgraph "UI & State"
            direction TB
            UIComponents["components/ui"]:::client
            QueryProvider["components/query-provider.tsx"]:::client
            UserAuthState["components/user-auth-state.tsx"]:::client
            AuthContext["lib/auth-context.tsx"]:::client
            Utils["lib/utils.ts"]:::client
        end
        subgraph "Custom Hooks"
            direction TB
            FetchHook["hooks/use-client-fetch.ts"]:::client
            MutateHook["hooks/use-client-mutation.ts"]:::client
        end
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Middleware["middleware.ts"]:::api
        SupabaseClient["supabase/client.ts"]:::api
        SupabaseMiddleware["supabase/middleware.ts"]:::api
        SupabaseServer["supabase/server.ts"]:::api
    end

    %% Data Layer
    subgraph "Supabase Services"
        direction TB
        AuthService["Supabase Auth Service"]:::external
        Database["Postgres DB"]:::db
    end

    %% Flows
    Browser -->|"HTTP Requests"| NextApp
    NextApp -->|"renders routes"| AuthRoutes
    NextApp -->|"renders routes"| DashboardRoutes
    NextApp -->|"uses layout"| Layout
    NextApp -->|"renders home"| HomePage

    NextApp -->|"imports"| UIComponents
    NextApp -->|"wraps with"| QueryProvider
    NextApp -.->|"provides context to"| AuthContext
    NextApp -->|"renders user state"| UserAuthState
    NextApp -->|"uses utils"| Utils

    UIComponents -->|"UI→Data"| FetchHook
    UIComponents -->|"UI→Data"| MutateHook
    AuthContext -->|"calls supabase.auth.getUser()"| FetchHook

    FetchHook -->|"calls"| SupabaseClient
    MutateHook -->|"calls"| SupabaseClient

    Middleware -->|"intercepts /dashboard"| DashboardRoutes
    Middleware -->|"passes auth token to"| SupabaseMiddleware

    SupabaseClient -->|"edge functions"| SupabaseServer
    SupabaseMiddleware -->|"integrates"| SupabaseClient
    SupabaseServer -->|"queries"| Database
    SupabaseServer -->|"auth operations"| AuthService

    %% Click Events
    click AuthRoutes "https://github.com/mohamed-4rarh/next-supabase-starter/tree/main/app/(auth)"
    click DashboardRoutes "https://github.com/mohamed-4rarh/next-supabase-starter/tree/main/app/(dashboard)"
    click Layout "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/app/layout.tsx"
    click HomePage "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/app/page.tsx"
    click UIComponents "https://github.com/mohamed-4rarh/next-supabase-starter/tree/main/components/ui"
    click QueryProvider "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/components/query-provider.tsx"
    click UserAuthState "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/components/user-auth-state.tsx"
    click AuthContext "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/lib/auth-context.tsx"
    click Utils "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/lib/utils.ts"
    click FetchHook "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/hooks/use-client-fetch.ts"
    click MutateHook "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/hooks/use-client-mutation.ts"
    click Middleware "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/middleware.ts"
    click SupabaseClient "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/supabase/client.ts"
    click SupabaseMiddleware "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/supabase/middleware.ts"
    click SupabaseServer "https://github.com/mohamed-4rarh/next-supabase-starter/blob/main/supabase/server.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#2b6cb0,color:#1e3a8a
    classDef api fill:#d4f7d4,stroke:#2f855a,color:#2f855a
    classDef external fill:#ffedd5,stroke:#dd6b20,color:#7c2d12
    classDef db fill:#e2e8f0,stroke:#4a5568,color:#2d3748
```
