# nicolasmontone/chat-with-your-base architecture

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

- Interactive diagram: https://gitdiagram.com/nicolasmontone/chat-with-your-base
- Repository: https://github.com/nicolasmontone/chat-with-your-base

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered Next.js application (using the new app directory) that provides an AI-driven chat interface to inspect and query a Postgres database via Supabase.
- Key use cases:
- Authenticate users via Supabase Auth
- Generate database statistics and SQL via OpenAI
- Execute SQL statements against a Postgres DB

##### File structure
- app/… contains both page routes (React Server Components and Client Components) and API route handlers (e.g., app/api/chat/route.ts).
- actions/… are Next.js Server Actions invoked directly from client components (chart.ts, run-sql.ts, get-chats.ts, etc.).
- utils/supabase/… wraps Supabase client and middleware for server-side queries and auth enforcement.
- components/… houses UI building blocks (shadcn-powered, Tailwind CSS) and domain components (chat interface, SQL result, charts).
- lib/… holds helper functions (chart formatting, Recharts adapters, general utilities).
- middleware.ts enforces auth and redirects.
- state/index.ts and hooks/… implement client-side state (Zustand or React context) and custom hooks.
- Top-level config files (next.config.js, tsconfig.json, tailwind.config.ts) define build and styling pipelines.

##### README for additional insights
- The stack: Next.js, Supabase (DB + Auth), OpenAI, Vercel, Tailwind, shadcn UI.

##### Main components and their relationships
a. Frontend (Browser)
- Next.js React pages & components
- Client Components invoke Server Actions or fetch API routes
b. Server layer (hosted on Vercel)
- Next.js Server Components & API route handlers (app/api/…)
- Server Actions (actions/*.ts) for chart data, SQL execution, chat history
- Supabase middleware for auth/session injection
c. Database & Auth
- Supabase Postgres instance (NEXT_PUBLIC_SUPABASE_URL + ANON_KEY)
- Supabase Auth callbacks (app/api/auth/callback/route.ts)
d. AI Service
- OpenAI API (OPENAI_API_KEY) used by chat and SQL-generation endpoints
e. Client-side state & utilities
- Zustand or context via state/index.ts
- Custom hooks (use-toast, use-app-local-storage, etc.)

##### Architectural patterns
- Jamstack/SSR hybrid: UI delivered by Next.js, with server-side logic via API routes and Server Actions.
- “Backend for Frontend”: all AI and DB calls are funneled through Next.js server logic, never from the client directly.
- Separation of concerns: UI components, data-fetch actions, DB client wrappers, and utility libs are modularized.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "1) Browser UI"
    U["User"]:::external
    B["Browser"]:::external
    subgraph "Client Components"
      ChatUI["Chat Interface"]:::component
      SQLRes["SQL Result"]:::component
      DynChart["Dynamic Chart"]:::component
      State["Zustand Store"]:::state
      Hooks["Custom Hooks"]:::hook
    end
  end

  subgraph "2) Next.js Frontend"
    LoginPg["Login Page"]:::page
    Dashboard["Dashboard Page"]:::page
    ChatSession["Chat Session Page"]:::page
    MiddlewareGlobal["Next.js Middleware"]:::middleware
  end

  subgraph "3) Next.js Server"
    subgraph "Server Actions"
      ChartAct["Generate Chart Data"]:::action
      RunSQL["Execute SQL"]:::action
      GetChats["Fetch Chat History"]:::action
      ChatName["Generate Chat Name"]:::action
      ValDB["Validate DB Connection"]:::action
      ValAI["Validate OpenAI Key"]:::action
      Logout["Logout"]:::action
    end
    subgraph "API Routes"
      ChatAPI["Chat Handler"]:::api
      ChatUtils["Chat Utils"]:::utility
      AuthCallback["Supabase Auth Callback"]:::api
    end
    SupClient["Supabase Client"]:::service
    SupServer["Supabase Server Helper"]:::service
    SupMiddleware["Supabase Middleware"]:::service
    LibChart["Chart Formatting Lib"]:::library
    LibUtils["General Utils"]:::library
  end

  subgraph "4) External Services"
    SUPPG["Supabase\nDB & Auth"]:::external
    OPENAI["OpenAI API"]:::external
    VERCEL["Vercel Hosting"]:::external
  end

  U --> B
  B --> ChatUI
  B --> SQLRes
  B --> DynChart
  B --> State
  B --> Hooks

  B --> LoginPg
  B --> Dashboard
  B --> ChatSession

  ChatUI -->|invokes| ChartAct
  ChatUI -->|invokes| GetChats
  SQLRes -->|invokes| RunSQL
  DynChart -->|invokes| ChartAct

  LoginPg -->|uses| ValDB
  ChatSession -->|calls API| ChatAPI

  ChartAct --> SupClient
  RunSQL --> SupClient
  GetChats --> SupClient
  ChatName --> SupClient
  ValDB --> SupClient
  ValAI --> OPENAI
  Logout --> SupMiddleware

  ChartAct --> LibChart
  ChartAct --> LibUtils

  ChatAPI --> ChatUtils
  ChatAPI --> SupServer
  AuthCallback --> SupMiddleware

  SupClient --> SUPPG
  SupServer --> SUPPG
  OPENAI --> ChartAct
  OPENAI --> ChatAPI

  VERCEL --> Dashboard
  VERCEL --> ChartAct

  click ChatUI "https://github.com/nicolasmontone/chat-with-your-base/blob/main/components/chat-interface.tsx"
  click SQLRes "https://github.com/nicolasmontone/chat-with-your-base/blob/main/components/sql-result.tsx"
  click DynChart "https://github.com/nicolasmontone/chat-with-your-base/blob/main/components/dynamic-chart.tsx"
  click ChartAct "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/chart.ts"
  click RunSQL "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/run-sql.ts"
  click GetChats "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/get-chats.ts"
  click ChatName "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/chat-name.ts"
  click ValDB "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/validate-db-connection.ts"
  click ValAI "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/validate-openai-key.ts"
  click Logout "https://github.com/nicolasmontone/chat-with-your-base/blob/main/actions/logout.ts"
  click ChatAPI "https://github.com/nicolasmontone/chat-with-your-base/blob/main/app/api/chat/route.ts"
  click ChatUtils "https://github.com/nicolasmontone/chat-with-your-base/blob/main/app/api/chat/utils.ts"
  click AuthCallback "https://github.com/nicolasmontone/chat-with-your-base/blob/main/app/api/auth/callback/route.ts"
  click SupClient "https://github.com/nicolasmontone/chat-with-your-base/blob/main/utils/supabase/client.ts"
  click SupServer "https://github.com/nicolasmontone/chat-with-your-base/blob/main/utils/supabase/server.ts"
  click SupMiddleware "https://github.com/nicolasmontone/chat-with-your-base/blob/main/utils/supabase/middleware.ts"
  click LibChart "https://github.com/nicolasmontone/chat-with-your-base/blob/main/lib/rechart-format.ts"
  click LibUtils "https://github.com/nicolasmontone/chat-with-your-base/blob/main/lib/utils.ts"
  click State "https://github.com/nicolasmontone/chat-with-your-base/blob/main/state/index.ts"
  click Hooks "https://github.com/nicolasmontone/chat-with-your-base/tree/main/hooks/"
  click MiddlewareGlobal "https://github.com/nicolasmontone/chat-with-your-base/blob/main/middleware.ts"
  click LoginPg "https://github.com/nicolasmontone/chat-with-your-base/blob/main/app/(auth-pages)/login/page.tsx"
  click Dashboard "https://github.com/nicolasmontone/chat-with-your-base/blob/main/app/app/page.tsx"
  click ChatSession "https://github.com/nicolasmontone/chat-with-your-base/blob/main/app/app/[id]/page.tsx"

  classDef component fill:#f9f,stroke:#333
  classDef state fill:#ccf,stroke:#333
  classDef hook fill:#cfc,stroke:#333
  classDef page fill:#fcf,stroke:#333
  classDef middleware fill:#fcc,stroke:#333
  classDef action fill:#ff9,stroke:#333
  classDef api fill:#9ff,stroke:#333
  classDef utility fill:#ddf,stroke:#333
  classDef service fill:#cff,stroke:#333
  classDef library fill:#fc9,stroke:#333
  classDef external fill:#efe,stroke:#333,stroke-dasharray:5 5
```
