# shamitgautam/mindful-knowledge-chat architecture

> Architecture diagram of the GitHub repository shamitgautam/mindful-knowledge-chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shamitgautam/mindful-knowledge-chat
- Repository: https://github.com/shamitgautam/mindful-knowledge-chat

## Overview

1. **Overall shape**
   - This is a single-page React application built with **Vite + TypeScript**, with the UI rendered entirely on the client.
   - There is no traditional app server in the repo; the backend boundary is handled through **Supabase** for auth, database, and edge functions.

2. **Primary product domain**
   - The app is centered on a **knowledge chat** experience: authenticated users can chat, manage messages, and upload documents for processing.
   - The presence of `ChatArea`, `ChatInput`, `ChatSidebar`, `MessageBubble`, and `DocumentUploadModal` shows the app is organized around a multi-pane chat workspace rather than a generic content site.

3. **Entry points and routing**
   - `src/main.tsx` bootstraps the app, and `src/pages/*` contains the route-level screens.
   - The main page flow is split into `Auth.tsx`, `Index.tsx`, and `NotFound.tsx`, indicating a small route surface with authentication gating and a primary app screen.

4. **Frontend composition**
   - `src/App.tsx` is the top-level composition layer, likely wiring theme, routing, and app-wide layout.
   - `src/components/NavLink.tsx` and the chat components suggest the main screen is assembled from reusable UI sections rather than page-specific monoliths.

5. **Chat subsystem**
   - The chat feature is the main functional subsystem:
     - `ChatArea` likely renders the conversation timeline.
     - `ChatInput` handles user prompts and message submission.
     - `ChatSidebar` likely contains conversation history, document list, or navigation.
     - `MessageBubble` renders individual messages with user/assistant styling.
     - `DocumentUploadModal` is the entry point for attaching knowledge sources.
   - This subsystem is probably fed by a custom hook layer rather than direct service calls from components.

6. **State and behavior hooks**
   - `useChat`, `usePinnedMessages`, `useAuth`, and `useTheme` encapsulate feature state and side effects.
   - `use-mobile` suggests responsive behavior is abstracted at the hook level, likely to adapt layout between desktop and smaller screens.
   - These hooks are the main boundary between UI components and application logic.

7. **Supabase integration boundary**
   - `src/integrations/supabase/client.ts` and `types.ts` are the frontend’s typed access point to Supabase.
   - Supabase is the external platform for:
     - authentication,
     - database-backed app data,
     - and calling edge functions.
   - The frontend likely talks to Supabase directly rather than through a custom API server.

8. **Serverless backend functions**
   - `supabase/functions/chat/index.ts` and `supabase/functions/process-document/index.ts` define the backend processing layer.
   - This suggests two major asynchronous flows:
     - **chat completion / answer generation** via the `chat` function,
     - **document ingestion and processing** via `process-document`.
   - These functions form the computation boundary for anything too sensitive or heavy to run in the browser.

9. **Data and persistence model**
   - `src/types/chat.ts` and `src/data/mockData.ts` indicate the chat domain has explicit typed models and local sample data for development or fallback UI states.
   - The migrations in `supabase/migrations/*` show the app’s persistent schema is managed in versioned SQL, so database structure is part of the repo’s architecture.
   - The `.temp` Supabase files indicate the project is linked to a real Supabase project and uses the Supabase CLI workflow.

10. **UI system and design infrastructure**
    - The large `src/components/ui/*` set is a shadcn-style component library: dialogs, sheets, tabs, forms, tables, toasts, etc.
    - `components.json`, `tailwind.config.ts`, `postcss.config.js`, and `src/index.css` show the design system is built on **Tailwind CSS** with reusable primitives rather than custom CSS per screen.
    - `src/lib/utils.ts` likely provides small helpers for class composition and UI consistency.

11. **Cross-cutting concerns**
    - `src/hooks/use-toast.ts` plus `src/components/ui/toaster.tsx`/`toast.tsx` indicate global notification handling.
    - `useTheme` implies theme state is app-wide, not local to a page.
    - `src/components/ui/sidebar.tsx`, `sheet.tsx`, `drawer.tsx`, and `resizable.tsx` suggest the UI is responsive and panel-based, which matters for the chat layout.

12. **Operational and build boundary**
    - `vite.config.ts`, `tsconfig*.json`, `eslint.config.js`, and the lockfiles indicate a standard front-end build/test toolchain with TypeScript checks and linting.
    - `public/robots.txt` and `index.html` show this is deployed as static frontend assets, with runtime behavior layered on top through Supabase and browser-side React.
    - `upload-test.pdf` is likely a local test fixture for validating the document upload flow.

13. **Architecture diagram guidance**
    - A good diagram would place the **React SPA** in the center, with internal modules for **chat UI**, **auth/pages**, **hooks/state**, and **shared UI components**.
    - Draw Supabase as the external backend platform with two distinct paths: **client SDK access** from the browser and **edge functions** for chat/document processing.
    - Show migrations as the schema-management path into Supabase Postgres, and treat document upload as a separate ingestion flow feeding the `process-document` function before results are reflected back in the chat experience.

Main entry points: [`src/pages/Index.tsx`](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/Index.tsx) (Chat page), [`src/App.tsx`](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/App.tsx) (App shell), [`src/integrations/supabase/client.ts`](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/integrations/supabase/client.ts) (Supabase client), [`src/hooks/useAuth.ts`](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/hooks/useAuth.ts) (App hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_main["Main entry<br/>bootstrap<br/>[main.tsx]"]
  node_app["App shell<br/>layout/router<br/>[App.tsx]"]
  node_auth_page["Auth page<br/>route screen<br/>[Auth.tsx]"]
  node_index_page["Chat page<br/>route screen<br/>[Index.tsx]"]
  node_notfound_page["Not found<br/>route screen<br/>[NotFound.tsx]"]
  node_chat_area["Chat area<br/>conversation UI<br/>[ChatArea.tsx]"]
  node_chat_input["Chat input<br/>composer<br/>[ChatInput.tsx]"]
  node_chat_sidebar["Chat sidebar<br/>navigation panel<br/>[ChatSidebar.tsx]"]
  node_message_bubble["Message bubble<br/>message renderer<br/>[MessageBubble.tsx]"]
  node_upload_modal["Upload modal<br/>document intake"]
  node_hooks["App hooks<br/>state/behavior<br/>[useAuth.ts]"]
  node_ui_kit["UI kit<br/>component library<br/>[button.tsx]"]
  node_nav_link["Nav link<br/>shared component<br/>[NavLink.tsx]"]
  node_mock_data["Mock data<br/>sample data<br/>[mockData.ts]"]
  node_types_chat["Chat types<br/>domain model<br/>[chat.ts]"]
  node_lib_api["API helpers<br/>integration helper<br/>[api.ts]"]
end

subgraph group_backend["Supabase Backend"]
  node_supabase_client["Supabase client<br/>typed sdk<br/>[client.ts]"]
  node_supabase_types["Supabase types<br/>schema types<br/>[types.ts]"]
  node_edge_chat["Chat function<br/>edge function<br/>[index.ts]"]
  node_edge_process["Process document<br/>edge function<br/>[index.ts]"]
  node_migrations["Migrations<br/>schema migration"]
end

subgraph group_tooling["Build & Style"]
  node_theme_css["Styling setup<br/>design system<br/>[index.css]"]
  node_build_cfg["Build config<br/>tooling<br/>[vite.config.ts]"]
end

node_main -->|"boots"| node_app
node_app -->|"routes"| node_auth_page
node_app -->|"routes"| node_index_page
node_app -->|"fallback"| node_notfound_page
node_index_page -->|"composes"| node_chat_area
node_index_page -->|"composes"| node_chat_sidebar
node_index_page -->|"composes"| node_chat_input
node_chat_area -->|"renders"| node_message_bubble
node_chat_input -->|"uses"| node_hooks
node_chat_sidebar -->|"uses"| node_hooks
node_chat_area -->|"uses"| node_hooks
node_chat_input -->|"opens"| node_upload_modal
node_upload_modal -->|"uploads"| node_edge_process
node_hooks -->|"calls"| node_supabase_client
node_supabase_client -->|"typed by"| node_supabase_types
node_supabase_client -->|"invokes"| node_edge_chat
node_supabase_client -->|"invokes"| node_edge_process
node_edge_chat -.->|"persists to"| node_migrations
node_edge_process -.->|"persists to"| node_migrations
node_migrations -.->|"generates"| node_supabase_types
node_index_page -.->|"falls back to"| node_mock_data
node_index_page -->|"models"| node_types_chat
node_mock_data -.->|"shaped by"| node_types_chat
node_index_page -->|"uses"| node_nav_link
node_ui_kit -->|"styled by"| node_theme_css
node_app -->|"uses"| node_ui_kit
node_index_page -->|"uses"| node_ui_kit
node_build_cfg -->|"configures"| node_theme_css

click node_main "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/main.tsx"
click node_app "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/App.tsx"
click node_auth_page "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/Auth.tsx"
click node_index_page "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/Index.tsx"
click node_notfound_page "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/NotFound.tsx"
click node_chat_area "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/ChatArea.tsx"
click node_chat_input "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/ChatInput.tsx"
click node_chat_sidebar "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/ChatSidebar.tsx"
click node_message_bubble "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/MessageBubble.tsx"
click node_upload_modal "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/DocumentUploadModal.tsx"
click node_hooks "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/hooks/useAuth.ts"
click node_ui_kit "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/ui/button.tsx"
click node_nav_link "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/NavLink.tsx"
click node_supabase_client "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/integrations/supabase/client.ts"
click node_supabase_types "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/integrations/supabase/types.ts"
click node_edge_chat "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/supabase/functions/chat/index.ts"
click node_edge_process "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/supabase/functions/process-document/index.ts"
click node_migrations "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/supabase/migrations/20251222131737_9d6f8d5f-71e5-43a1-ba4f-aebec9c41b5f.sql"
click node_mock_data "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/data/mockData.ts"
click node_types_chat "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/types/chat.ts"
click node_lib_api "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/lib/api.ts"
click node_theme_css "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/index.css"
click node_build_cfg "https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/vite.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_auth_page,node_index_page,node_notfound_page,node_chat_area,node_chat_input,node_chat_sidebar,node_message_bubble,node_upload_modal,node_hooks,node_ui_kit,node_nav_link,node_mock_data,node_types_chat,node_lib_api toneBlue
class node_supabase_client,node_supabase_types,node_edge_chat,node_edge_process,node_migrations toneAmber
class node_theme_css,node_build_cfg toneMint
```

## Components

### React SPA

Client-side application, pages, chat UI, hooks, and shared components.

- [Main entry](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/main.tsx): bootstrap · Vite entrypoint that mounts the React app. · `src/main.tsx`
- [App shell](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/App.tsx): layout/router · Top-level composition layer for routing, theme, and app layout. · `src/App.tsx`
- [Auth page](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/Auth.tsx): route screen · Authentication screen for signed-out users. · `src/pages/Auth.tsx`
- [Chat page](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/Index.tsx): route screen · Primary authenticated workspace screen. · `src/pages/Index.tsx`
- [Not found](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/pages/NotFound.tsx): route screen · Fallback route for unknown paths. · `src/pages/NotFound.tsx`
- [Chat area](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/ChatArea.tsx): conversation UI · Main message timeline and conversation workspace. · `src/components/chat/ChatArea.tsx`
- [Chat input](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/ChatInput.tsx): composer · User prompt entry and message submission. · `src/components/chat/ChatInput.tsx`
- [Chat sidebar](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/ChatSidebar.tsx): navigation panel · Conversation list and related chat navigation. · `src/components/chat/ChatSidebar.tsx`
- [Message bubble](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/MessageBubble.tsx): message renderer · Renders individual user and assistant messages. · `src/components/chat/MessageBubble.tsx`
- [Upload modal](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/chat/DocumentUploadModal.tsx): document intake · Dialog for attaching documents to the knowledge flow. · `src/components/chat/DocumentUploadModal.tsx`
- [App hooks](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/hooks/useAuth.ts): state/behavior · Shared state and side-effect hooks for auth, chat, theme, pinned messages, and responsiveness. · `src/hooks/useAuth.ts`
- [UI kit](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/ui/button.tsx): component library · Reusable shadcn-style primitives used across the interface. · `src/components/ui/button.tsx`
- [Nav link](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/components/NavLink.tsx): shared component · Reusable navigation link helper for app chrome. · `src/components/NavLink.tsx`
- [Mock data](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/data/mockData.ts): sample data · Local sample chat data for development and fallback states. · `src/data/mockData.ts`
- [Chat types](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/types/chat.ts): domain model · Typed chat domain models used by the frontend. · `src/types/chat.ts`
- [API helpers](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/lib/api.ts): integration helper · Shared helpers for calling backend services from the frontend. · `src/lib/api.ts`

### Supabase Backend

Typed client access, edge functions, and database migrations.

- [Supabase client](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/integrations/supabase/client.ts): typed sdk · Frontend access point for auth, database, and edge functions. · `src/integrations/supabase/client.ts`
- [Supabase types](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/integrations/supabase/types.ts): schema types · Generated TypeScript types for the Supabase backend. · `src/integrations/supabase/types.ts`
- [Chat function](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/supabase/functions/chat/index.ts): edge function · Serverless chat completion and answer generation. · `supabase/functions/chat/index.ts`
- [Process document](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/supabase/functions/process-document/index.ts): edge function · Serverless document ingestion and processing pipeline. · `supabase/functions/process-document/index.ts`
- [Migrations](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/supabase/migrations/20251222131737_9d6f8d5f-71e5-43a1-ba4f-aebec9c41b5f.sql): schema migration · Versioned SQL schema for persisted app data. · `supabase/migrations/20251222131737_9d6f8d5f-71e5-43a1-ba4f-aebec9c41b5f.sql`

### Build & Style

Project-level build, styling, and runtime configuration.

- [Styling setup](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/src/index.css): design system · Tailwind and app-wide CSS foundation for the UI. · `src/index.css`
- [Build config](https://github.com/shamitgautam/mindful-knowledge-chat/blob/main/vite.config.ts): tooling · Vite, TypeScript, lint, and styling configuration for the app. · `vite.config.ts`

## Connections

- Main entry → App shell: boots · The entrypoint mounts the application shell.
- App shell → Auth page: routes · App shell renders the sign-in flow when unauthenticated.
- App shell → Chat page: routes · App shell renders the main chat workspace when authenticated.
- App shell → Not found: fallback · Unknown routes resolve to the not-found screen.
- Chat page → Chat area: composes · The main page assembles the conversation viewport.
- Chat page → Chat sidebar: composes · The main page includes sidebar navigation and history.
- Chat page → Chat input: composes · The main page includes the prompt composer.
- Chat area → Message bubble: renders · Conversation timeline is built from message bubbles.
- Chat input → App hooks: uses · Composer relies on chat state and submission behavior.
- Chat sidebar → App hooks: uses · Sidebar reads app state for conversations and pinned items.
- Chat area → App hooks: uses · Conversation rendering is driven by chat and theme state.
- Chat input → Upload modal: opens · Composer can trigger document attachment flow.
- Upload modal → Process document: uploads · Uploaded documents are sent to the processing function.
- App hooks → Supabase client: calls · Hooks bridge UI state to Supabase-backed data and auth.
- Supabase client → Supabase types: typed by · Client access is guided by generated backend types.
- Supabase client → Chat function: invokes · Frontend calls the chat edge function for completion flow.
- Supabase client → Process document: invokes · Frontend calls the document-processing edge function.
- Chat function → Migrations: persists to · Chat function operates over the managed database schema.
- Process document → Migrations: persists to · Document processing updates persisted backend records.
- Migrations → Supabase types: generates · Database schema informs typed frontend integration.
- Chat page → Mock data: falls back to · Sample data supports development or empty states.
- Chat page → Chat types: models · Chat page and hooks share explicit domain types.
- Mock data → Chat types: shaped by · Local samples follow the chat domain model.
- Chat page → Nav link: uses · Page chrome includes reusable navigation links.
- UI kit → Styling setup: styled by · Shared primitives depend on the Tailwind/CSS foundation.
- App shell → UI kit: uses · Top-level layout is built from shared UI primitives.
- Chat page → UI kit: uses · Primary workspace is composed from shared UI primitives.
- Build config → Styling setup: configures · Tooling defines how the UI styling system is built.