# bmorrisondev/quillmate architecture

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

- Interactive diagram: https://gitdiagram.com/bmorrisondev/quillmate
- Repository: https://github.com/bmorrisondev/quillmate

## Overview

##### Project Type and Purpose
- Full-stack web application
- Purpose: Collaborative writing with real-time updates, organization support, secure authentication.

##### File Structure
- Frontend:
– `src/app/…` (Next.js 15 App Router with public, auth, and protected routes)
– `src/components/…` (UI components)
– `src/hooks` & `src/lib` (client-side utilities, Supabase provider, custom hooks)
- Backend Services:
– Supabase (hosted PostgreSQL with RLS)
– Supabase Edge Functions (`supabase/functions`) for Clerk webhooks and any custom serverless logic
- Config & Deployment:
– `next.config.mjs`, `tailwind.config.ts`, `tsconfig.json`
– `supabase/config.toml`, migrations under `supabase/migrations/`

##### Key Architecture Insights from README
- Next.js 15 (App Router) powers both server-rendered and client-side UI.
- Clerk provides user/org authentication, integrated into Supabase.
- Supabase handles data storage, real-time subscriptions, and edge functions.

##### Main Components & Interactions
a. Client (Browser)
– Next.js React app (routing via `src/app`)
– UI components (`src/components/ui`) & Editor
– Clerk JS SDK for sign-in/up
– Supabase JS client for queries & real-time channels
b. Next.js Server
– SSR/SSG on protected routes
– Middleware (`src/middleware.ts`) to gate access based on Clerk session
– API proxies (if any) to Supabase or Edge Functions
c. Authentication Service
– Clerk (external) for sign-in/up, JWT issuance, org management
– Webhook listener in Supabase Edge Function for user/org sync
d. Data Layer
– Supabase PostgreSQL with RLS (tables created via migrations)
– Supabase Realtime (broadcasts live updates to clients)
– Edge Functions (`supabase/functions`) for custom endpoints (e.g., clerk-webhooks)

##### Architectural Patterns & Design Principles
- Separation of concerns:
– Presentation (Next.js + React)
– Auth (Clerk)
– Data (Supabase DB & Realtime)
– Business logic (Edge Functions)
- Real-time collaboration: Supabase subscriptions
- Middleware for auth enforcement (Next.js middleware)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        direction TB
        AppRouter["App Router"]:::frontend
        Editor["Editor Component"]:::frontend
        Sidebar["Sidebar Component"]:::frontend
        SignIn["Sign-In Page"]:::frontend
        SignUp["Sign-Up Page"]:::frontend
        UIlib["UI Component Library"]:::frontend
        FeatureGrid["Feature Grid Component"]:::frontend
        GlobalsCSS["Global Styles"]:::frontend
        SupabaseProvider["Supabase Client Provider"]:::frontend
        UseArticles["Articles Hook"]:::frontend
        UseDebouncedSave["Debounced Save Hook"]:::frontend
        UtilsContent["Utils: content"]:::frontend
        UtilsUpload["Utils: upload"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Server"
        direction TB
        SSR["SSR/SSG Routes"]:::server
        MiddlewareAuth["Middleware (Auth Enforcement)"]:::server
        MiddlewareSBA["Secondary Middleware (Supabase Auth)"]:::server
    end

    %% Auth Layer
    subgraph "Authentication (Clerk Service)"
        direction TB
        ClerkAuthAPI["Clerk Auth API"]:::auth
        ClerkDashboard["Clerk Dashboard"]:::auth
    end

    %% Backend Layer
    subgraph "Backend/Data (Supabase)"
        direction TB
        PostgreSQL["PostgreSQL + RLS"]:::backend
        Realtime["Realtime Server"]:::backend
        EdgeFunctions["Edge Functions (clerk-webhooks)"]:::backend
        SupabaseConfig["Supabase Config"]:::backend
        Migrations["Database Migrations"]:::backend
    end

    %% Config Box
    Config["Config Files"]:::config

    %% Interactions
    User["User"]:::external
    User -->|"interacts via UI"| AppRouter
    AppRouter -->|"HTTP: fetch pages"| SSR
    AppRouter -->|"uses SDK"| ClerkAuthAPI
    AppRouter -->|"HTTP: sign-in/up"| SignIn
    AppRouter -->|"HTTP: sign-in/up"| SignUp
    SSR -->|"enforce"| MiddlewareAuth
    SSR -->|"validate"| MiddlewareSBA
    MiddlewareAuth -->|"redirects"| SignIn
    SSR -->|"queries"| PostgreSQL
    SupabaseProvider -->|"initializes"| PostgreSQL
    SupabaseProvider -->|"connects"| Realtime
    Realtime -->|"WS push updates"| UseArticles
    Editor -->|"calls hooks"| UseArticles
    Editor -->|"calls hooks"| UseDebouncedSave
    UseDebouncedSave -->|"uses utils"| UtilsContent
    UseDebouncedSave -->|"uses utils"| UtilsUpload
    ClerkDashboard -->|"event"| EdgeFunctions
    EdgeFunctions -->|"writes"| PostgreSQL
    Config -->|"provides env"| ClerkAuthAPI
    Config -->|"provides env"| PostgreSQL

    %% Click Events
    click AppRouter "https://github.com/bmorrisondev/quillmate/tree/main/src/app"
    click Editor "https://github.com/bmorrisondev/quillmate/blob/main/src/app/(protected)/components/editor.tsx"
    click Sidebar "https://github.com/bmorrisondev/quillmate/blob/main/src/app/(protected)/components/sidebar.tsx"
    click SignIn "https://github.com/bmorrisondev/quillmate/blob/main/src/app/sign-in/[[...sign-in]]/page.tsx"
    click SignUp "https://github.com/bmorrisondev/quillmate/blob/main/src/app/sign-up/[[...sign-up]]/page.tsx"
    click UIlib "https://github.com/bmorrisondev/quillmate/tree/main/src/components/ui"
    click FeatureGrid "https://github.com/bmorrisondev/quillmate/blob/main/src/components/features-grid.tsx"
    click GlobalsCSS "https://github.com/bmorrisondev/quillmate/blob/main/src/app/globals.css"
    click SupabaseProvider "https://github.com/bmorrisondev/quillmate/blob/main/src/lib/supabase-provider.tsx"
    click UseArticles "https://github.com/bmorrisondev/quillmate/blob/main/src/lib/hooks/use-articles.ts"
    click UseDebouncedSave "https://github.com/bmorrisondev/quillmate/blob/main/src/lib/hooks/use-debounced-save.ts"
    click UtilsContent "https://github.com/bmorrisondev/quillmate/blob/main/src/lib/utils/content.ts"
    click UtilsUpload "https://github.com/bmorrisondev/quillmate/blob/main/src/lib/utils/upload.ts"
    click MiddlewareAuth "https://github.com/bmorrisondev/quillmate/blob/main/src/middleware.ts"
    click MiddlewareSBA "https://github.com/bmorrisondev/quillmate/blob/main/src/middleware-sba.ts"
    click EdgeFunctions "https://github.com/bmorrisondev/quillmate/blob/main/supabase/functions/clerk-webhooks/index.ts"
    click SupabaseConfig "https://github.com/bmorrisondev/quillmate/blob/main/supabase/config.toml"
    click Migrations "https://github.com/bmorrisondev/quillmate/blob/main/supabase/migrations/*.sql"
    click Config "https://github.com/bmorrisondev/quillmate/blob/main/next.config.mjs"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef server fill:#E8FFD0,stroke:#333,stroke-width:1px
    classDef auth fill:#FFE8D0,stroke:#333,stroke-width:1px
    classDef backend fill:#E8D0FF,stroke:#333,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
