# razikus/supabase-nextjs-template architecture

> Architecture diagram of the GitHub repository razikus/supabase-nextjs-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/razikus/supabase-nextjs-template
- Repository: https://github.com/razikus/supabase-nextjs-template

## Overview

##### Project type and purpose
- This is a full-stack SaaS template:
- Frontend built with Next.js 15 (App Router) + React 19 + Tailwind CSS + shadcn/ui
- Backend provided by Supabase (PostgreSQL, Auth, Storage, RLS)
- Demo features: authentication, file storage demo, task management demo, legal docs

##### File structure
- Top-level:
- nextjs/ → all Next.js code (pages, components, api routes, config)
- supabase/ → database migrations, config.toml, storage policies
- Patterns:
- Next.js App Router + serverless API routes under nextjs/src/app/api
- Client-side components under nextjs/src/app and nextjs/src/components
- Supabase client vs. serverAdmin client for browser vs. server calls
- Config and deployment:
- nextjs/.env.template → environment variables for Supabase URL/keys and theme
- supabase/config.toml → site_url, redirect URLs
- supabase migrations → SQL files for schema, RLS policies

##### Extract insights from the README
- Tech stack summary (Frontend, Backend, Auth)
- Features map: authentication flows, MFA, OAuth, file/task demos
- Deployment instructions: supabase CLI for migrations + Vercel for frontend

##### Architectural patterns & principles
- Client-Server separation: React UI vs. serverless API vs. BaaS
- App Router (Next.js 15) for nested layouts and route-based code splitting
- Edge vs. Server-only code: Supabase client in browser, serverAdminKeys on server
- Security via RLS and middleware guard in Next.js
- CI/CD pipeline: GitHub → supabase migrations & Vercel deploy

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer"
    direction TB
    Browser["User's Browser"]:::ui
    AppPages["Next.js App Router Pages"]:::ui
    AuthPages["Authentication Pages"]:::ui
    FileStoragePage["File Storage Demo Page"]:::ui
    TaskMgmtPage["Task Management Demo Page"]:::ui
    UserSettingsPage["User Settings Page"]:::ui
    LegalDocs["Legal Documents Static Content"]:::ui
    PublicTerms["Public Terms (Static)"]:::ui
    SharedComponents["Shared React Components"]:::ui
    UIComponents["UI Components (shadcn/ui)"]:::ui
    MainLayout["Main Layout"]:::ui
    AppLayout["App Layout"]:::ui
    GlobalStyles["Global Styles"]:::ui
  end

  %% Application Layer
  subgraph "Application Layer"
    direction TB
    Middleware["Middleware (Auth/Session)"]:::api
    APIRouteAuthCallback["API Route /api/auth/callback"]:::api
    SupabaseClientBrowser["Supabase Client Init (Browser)"]:::api
    SupabaseMiddlewareEdge["Supabase Middleware Integration (Edge)"]:::api
    SupabaseUnified["Supabase Unified Export"]:::api
    SupabaseServerClient["Supabase Server Client"]:::api
    SupabaseAdminClient["Supabase Server Admin Client"]:::api
    Types["Supabase Types"]:::api
    Utils["Utilities"]:::api
    EnvConfig["Env Configuration (.env.template)"]:::api
    NextConfig["Next Config (next.config.ts)"]:::api
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    SupabaseAuth["Supabase Auth Service"]:::data
    Postgres["PostgreSQL Database"]:::data
    StorageBuckets["Storage Buckets"]:::data
    Realtime["Realtime Service"]:::data
    ConfigToml["Supabase Config (config.toml)"]:::data
    MigrationsCore["Core Migrations"]:::data
    MigrationsLegacy["Legacy Migrations"]:::data
    SupabaseCLI["Supabase CLI & Migration Pipeline"]:::data
  end

  %% External Services
  subgraph "External Services"
    direction TB
    OAuthProviders["OAuth Providers"]:::external
    Vercel["Vercel Hosting"]:::external
    CDN["CDN for Static Docs"]:::external
  end

  %% Connections
  Browser --> AppPages
  Browser --> AuthPages
  Browser --> FileStoragePage
  Browser --> TaskMgmtPage
  Browser --> UserSettingsPage
  Browser --> LegalDocs
  Browser --> PublicTerms
  Browser --> SupabaseClientBrowser
  Browser --> SupabaseMiddlewareEdge

  AppPages --> APIRouteAuthCallback
  Middleware --> APIRouteAuthCallback
  APIRouteAuthCallback --> SupabaseServerClient
  APIRouteAuthCallback --> SupabaseUnified

  SupabaseClientBrowser --> SupabaseAuth
  SupabaseClientBrowser --> Postgres

  SupabaseUnified --> SupabaseServerClient
  SupabaseUnified --> SupabaseAdminClient

  SupabaseServerClient --> SupabaseAuth
  SupabaseServerClient --> Postgres
  SupabaseServerClient --> StorageBuckets
  SupabaseServerClient --> Realtime

  SupabaseCLI --> ConfigToml
  SupabaseCLI --> MigrationsCore
  SupabaseCLI --> MigrationsLegacy
  ConfigToml --> SupabaseAuth
  MigrationsCore --> Postgres
  MigrationsLegacy --> Postgres

  SupabaseAuth <--> OAuthProviders
  Vercel --> AppPages
  Vercel --> APIRouteAuthCallback
  CDN --> LegalDocs
  CDN --> PublicTerms

  %% Click Events
  click AppPages "https://github.com/razikus/supabase-nextjs-template/tree/main/nextjs/src/app"
  click AuthPages "https://github.com/razikus/supabase-nextjs-template/tree/main/nextjs/src/app/auth"
  click FileStoragePage "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/app/app/storage/page.tsx"
  click TaskMgmtPage "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/app/app/table/page.tsx"
  click UserSettingsPage "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/app/app/user-settings/page.tsx"
  click LegalDocs "https://github.com/razikus/supabase-nextjs-template/tree/main/nextjs/src/app/legal"
  click PublicTerms "https://github.com/razikus/supabase-nextjs-template/tree/main/nextjs/public/terms"
  click SharedComponents "https://github.com/razikus/supabase-nextjs-template/tree/main/nextjs/src/components"
  click UIComponents "https://github.com/razikus/supabase-nextjs-template/tree/main/nextjs/src/components/ui"
  click MainLayout "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/app/layout.tsx"
  click AppLayout "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/components/AppLayout.tsx"
  click GlobalStyles "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/app/globals.css"
  click Middleware "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/middleware.ts"
  click SupabaseClientBrowser "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/supabase/client.ts"
  click SupabaseMiddlewareEdge "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/supabase/middleware.ts"
  click SupabaseUnified "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/supabase/unified.ts"
  click SupabaseServerClient "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/supabase/server.ts"
  click SupabaseAdminClient "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/supabase/serverAdminClient.ts"
  click Types "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/types.ts"
  click Utils "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/lib/utils.ts"
  click APIRouteAuthCallback "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/src/app/api/auth/callback/route.ts"
  click EnvConfig "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/.env.template"
  click NextConfig "https://github.com/razikus/supabase-nextjs-template/blob/main/nextjs/next.config.ts"
  click ConfigToml "https://github.com/razikus/supabase-nextjs-template/blob/main/supabase/config.toml"
  click MigrationsCore "https://github.com/razikus/supabase-nextjs-template/blob/main/supabase/migrations/*.sql"
  click MigrationsLegacy "https://github.com/razikus/supabase-nextjs-template/blob/main/supabase/migrations_for_old/*.sql"

  %% Styles
  classDef ui fill:#E0F7FA,stroke:#006064
  classDef api fill:#E1BEE7,stroke:#4A148C
  classDef data fill:#C8E6C9,stroke:#1B5E20
  classDef external fill:#CFD8DC,stroke:#455A64
```
