# arpansarkar112/full_stack_ai_chat_application architecture

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

- Interactive diagram: https://gitdiagram.com/arpansarkar112/full_stack_ai_chat_application
- Repository: https://github.com/arpansarkar112/full_stack_ai_chat_application

## Overview

1. **Overall shape**
   - This is a two-tier application: a **React/Vite frontend** in the repo root and a **Python/FastAPI backend** under `backend/`.
   - Persistence and auth are centered on **Supabase**: the frontend uses the Supabase JS client, and the backend likely relies on Supabase Postgres tables and auth-related identity checks.

2. **Deployment boundaries**
   - The architecture is split for hosting: **frontend on Vercel**, **backend on Render**, with Supabase as the managed data/auth service.
   - `vercel.json` and `backend/requirements.txt` reinforce that the app is deployed as separate web and API services rather than a monolith.

3. **Frontend application shell**
   - `src/main.tsx`, `src/App.tsx`, and the `src/pages/` folder define the client-side page composition and routing.
   - Pages include `Landing`, `Auth`, `Dashboard`, `ChatSession`, `PastChats`, `Profile`, `Credit`, and `NotFound`, which suggests a multi-screen product with a post-login workspace, chat history, and account pages.

4. **Authentication and route protection**
   - Auth is handled in the frontend through `src/components/auth/AuthProvider.tsx`, `AuthForm.tsx`, and `src/components/ProtectedRoute.tsx`.
   - The auth boundary is client-facing: unauthenticated users are steered to the landing/auth flow, while protected pages are gated behind a route guard and user session state.

5. **Supabase integration layer**
   - `src/integrations/supabase/client.ts` and `types.ts` are the frontend’s typed access point to Supabase.
   - This layer isolates all Supabase-specific concerns from the rest of the app, making Supabase the main external dependency for login, profile data, and chat persistence.

6. **Chat workspace and agent interaction**
   - `src/components/chat/ChatInterface.tsx` is the core interaction surface for the AI agent.
   - The README indicates support for **message streaming**, **markdown rendering**, **dataset upload/download**, **dataset switching**, and **inline charts**, so the chat UI is not just text exchange; it is the operational console for data tasks.

7. **Session-aware dataset handling**
   - A key product boundary is that datasets are **scoped to a chat session** and uploads are guarded behind active sessions.
   - This means the frontend chat flow is tied to session state: a user selects or creates a session, then can attach CSVs and continue conversation with that session’s dataset context.

8. **Conversation history and lifecycle**
   - `PastChats` and `ChatSession` indicate that chats are durable entities, not ephemeral messages.
   - The README also calls out viewing full logs, deleting sessions, and resuming old conversations, so the data model includes session-level history plus delete policies.

9. **User dashboard and account pages**
   - `Dashboard`, `DashboardSidebar`, `DashboardStats`, and `RecentActivity` suggest an authenticated landing area that summarizes usage and recent work.
   - `Profile` is used for account-name management, while `Credit` likely represents a usage or entitlement page tied to the user account model.

10. **Shared UI and presentation system**
   - The large `src/components/ui/` directory is a reusable design-system layer built on **shadcn/ui** and **Radix UI** primitives.
   - Styling is driven by **Tailwind CSS**, with supporting utilities in `src/lib/utils.ts`, and the app also includes dark/light mode support via components like `mode-toggle`.

11. **Markdown, charts, and generated content rendering**
   - The frontend includes specialized rendering support in `src/components/chat/markdown.tsx` and chart-related UI in `src/components/ui/chart.tsx`.
   - This implies the agent can return structured outputs beyond plain text, and the client is responsible for making those outputs readable and visually useful.

12. **Backend API and agent execution**
   - `backend/main.py` is the FastAPI entry point, and `backend/agents/csv_agent.py` is the core domain agent for CSV automation.
   - The backend is therefore the execution boundary: it receives user requests, runs agent logic, talks to the model/service layer, and returns structured results for the chat UI.

13. **CSV-specific automation domain**
   - The README and filenames show the agent is intentionally specialized for **CSV files** rather than a general-purpose assistant.
   - The backend tests in `backend/tests/test_intent_detection.py` indicate an intent-routing layer, with supported operations including cell edits, row insertion/deletion, row math, and chart generation.

14. **Backend identity and data files**
   - `backend/identity.py` suggests a backend-side identity/auth utility, likely used to validate or normalize the active user/session context.
   - `backend/data/` exists as a working directory for generated or temporary dataset artifacts, while the Supabase migrations under `supabase/migrations/` define the durable database schema for chats and profiles.

15. **External services and model dependency**
   - The backend README mentions **Google Gemini API** and `langchain-google-genai` / `semantic-kernel`, which indicates the AI behavior is model-backed and orchestrated rather than hardcoded.
   - In architecture terms, the backend sits between the frontend and the model provider, and also between the model and the CSV/data workspace.

16. **Schema evolution and operational tooling**
   - The `supabase/migrations/` folder contains migrations for `chat_sessions`, `profiles`, and delete policies, showing that access control and lifecycle behavior are enforced at the database level as well.
   - Tooling is standard modern web stack: Vite/TypeScript/Tailwind on the client, FastAPI/Python on the server, with local env files, ESLint, and Supabase CLI artifacts supporting development and deployment.

Main entry points: [`src/components/ProtectedRoute.tsx`](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/ProtectedRoute.tsx) (Protected Route), [`src/integrations/supabase/client.ts`](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/integrations/supabase/client.ts) (Supabase Client), [`backend/main.py`](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/main.py) (API), [`src/App.tsx`](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/App.tsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_landing["Landing<br/>route<br/>[Landing.tsx]"]
  node_auth_page["Auth<br/>route<br/>[Auth.tsx]"]
  node_app_shell["App Shell<br/>router<br/>[App.tsx]"]
  node_auth_provider(("Auth State<br/>session provider<br/>[AuthProvider.tsx]"))
  node_protected_route{{"Protected Route<br/>guard<br/>[ProtectedRoute.tsx]"}}
  node_dashboard["Dashboard<br/>workspace page<br/>[Dashboard.tsx]"]
  node_chat_session["Chat Session<br/>conversation page<br/>[ChatSession.tsx]"]
  node_past_chats["Past Chats<br/>history page<br/>[PastChats.tsx]"]
  node_profile["Profile<br/>account page<br/>[Profile.tsx]"]
  node_credit["Credit<br/>account page<br/>[Credit.tsx]"]
  node_chat_ui["Chat UI<br/>interaction surface<br/>[ChatInterface.tsx]"]
  node_dashboard_ui["Dashboard UI<br/>summary widgets"]
end

subgraph group_backend["Backend"]
  node_backend_main["API<br/>[main.py]"]
  node_csv_agent["CSV Agent<br/>domain agent<br/>[csv_agent.py]"]
  node_intent_detection["Intent Routing<br/>classifier"]
  node_identity["Identity<br/>auth utility<br/>[identity.py]"]
  node_data_dir[("Data Workspace<br/>file workspace")]
end

subgraph group_platform["Platform"]
  node_supabase_client["Supabase Client<br/>data gateway<br/>[client.ts]"]
  node_supabase_types["Supabase Types<br/>schema types<br/>[types.ts]"]
  node_supabase_db[("Supabase DB<br/>managed database")]
  node_vercel["Vercel<br/>hosting<br/>[vercel.json]"]
  node_render["Render<br/>hosting<br/>[requirements.txt]"]
  node_gemini(("Gemini API<br/>model provider"))
end

subgraph group_shared["Shared UI"]
  node_markdown["Markdown<br/>renderer<br/>[markdown.tsx]"]
  node_ui_kit["UI Kit<br/>design system"]
end

node_app_shell -->|"routes"| node_landing
node_app_shell -->|"routes"| node_auth_page
node_app_shell -->|"guards"| node_protected_route
node_protected_route -->|"allows"| node_dashboard
node_protected_route -->|"allows"| node_chat_session
node_protected_route -->|"allows"| node_past_chats
node_protected_route -->|"allows"| node_profile
node_protected_route -->|"allows"| node_credit
node_auth_provider -->|"uses"| node_supabase_client
node_auth_page -->|"consumes"| node_auth_provider
node_dashboard -->|"composes"| node_dashboard_ui
node_chat_session -->|"composes"| node_chat_ui
node_chat_ui -->|"renders"| node_markdown
node_chat_ui -->|"uses"| node_ui_kit
node_dashboard_ui -->|"uses"| node_ui_kit
node_profile -->|"reads/writes"| node_supabase_client
node_past_chats -->|"reads"| node_supabase_client
node_chat_session -->|"reads/writes"| node_supabase_client
node_supabase_client -->|"typed by"| node_supabase_types
node_backend_main -->|"delegates"| node_csv_agent
node_csv_agent -->|"routes"| node_intent_detection
node_backend_main -->|"checks"| node_identity
node_csv_agent -->|"uses"| node_data_dir
node_backend_main -->|"calls"| node_gemini
node_supabase_db -->|"serves"| node_supabase_client
node_supabase_db -->|"supports"| node_identity
node_vercel -->|"hosts"| node_app_shell
node_render -->|"hosts"| node_backend_main
node_backend_main -->|"persists"| node_supabase_db

click node_landing "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Landing.tsx"
click node_auth_page "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Auth.tsx"
click node_app_shell "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/App.tsx"
click node_auth_provider "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/auth/AuthProvider.tsx"
click node_protected_route "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/ProtectedRoute.tsx"
click node_dashboard "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Dashboard.tsx"
click node_chat_session "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/ChatSession.tsx"
click node_past_chats "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/PastChats.tsx"
click node_profile "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Profile.tsx"
click node_credit "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Credit.tsx"
click node_chat_ui "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/chat/ChatInterface.tsx"
click node_markdown "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/chat/markdown.tsx"
click node_dashboard_ui "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/dashboard/DashboardSidebar.tsx"
click node_ui_kit "https://github.com/arpansarkar112/full_stack_ai_chat_application/tree/main/src/components/ui"
click node_supabase_client "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/integrations/supabase/client.ts"
click node_supabase_types "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/integrations/supabase/types.ts"
click node_backend_main "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/main.py"
click node_csv_agent "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/agents/csv_agent.py"
click node_intent_detection "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/tests/test_intent_detection.py"
click node_identity "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/identity.py"
click node_data_dir "https://github.com/arpansarkar112/full_stack_ai_chat_application/tree/main/backend/data"
click node_supabase_db "https://github.com/arpansarkar112/full_stack_ai_chat_application/tree/main/supabase/migrations"
click node_vercel "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/vercel.json"
click node_render "https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/requirements.txt"

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_landing,node_auth_page,node_app_shell,node_auth_provider,node_protected_route,node_dashboard,node_chat_session,node_past_chats,node_profile,node_credit,node_chat_ui,node_dashboard_ui toneBlue
class node_backend_main,node_csv_agent,node_intent_detection,node_identity,node_data_dir toneAmber
class node_supabase_client,node_supabase_types,node_supabase_db,node_vercel,node_render,node_gemini toneMint
class node_markdown,node_ui_kit toneRose
```

## Components

### Frontend

React/Vite client app and UI composition.

- [Landing](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Landing.tsx): route · Public entry and marketing screen. · `src/pages/Landing.tsx`
- [Auth](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Auth.tsx): route · Login and sign-up screen. · `src/pages/Auth.tsx`
- [App Shell](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/App.tsx): router · Root app composition and client-side navigation. · `src/App.tsx`
- [Auth State](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/auth/AuthProvider.tsx): session provider · Supplies user session and auth context to the app. · `src/components/auth/AuthProvider.tsx`
- [Protected Route](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/ProtectedRoute.tsx): guard · Blocks unauthenticated access to private pages. · `src/components/ProtectedRoute.tsx`
- [Dashboard](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Dashboard.tsx): workspace page · Authenticated landing area with summary views. · `src/pages/Dashboard.tsx`
- [Chat Session](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/ChatSession.tsx): conversation page · Session-scoped chat workspace for dataset tasks. · `src/pages/ChatSession.tsx`
- [Past Chats](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/PastChats.tsx): history page · Browse, resume, and manage prior conversations. · `src/pages/PastChats.tsx`
- [Profile](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Profile.tsx): account page · User profile and name management. · `src/pages/Profile.tsx`
- [Credit](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/pages/Credit.tsx): account page · Usage or entitlement management screen. · `src/pages/Credit.tsx`
- [Chat UI](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/chat/ChatInterface.tsx): interaction surface · Streaming chat, uploads, dataset switching, and chart-aware responses. · `src/components/chat/ChatInterface.tsx`
- [Dashboard UI](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/dashboard/DashboardSidebar.tsx): summary widgets · Sidebar, stats, and recent activity components. · `src/components/dashboard/DashboardSidebar.tsx`

### Backend

FastAPI service and agent execution layer.

- [API](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/main.py): fastapi app · Backend entry point for requests and responses. · `backend/main.py`
- [CSV Agent](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/agents/csv_agent.py): domain agent · Core CSV automation and tool orchestration logic. · `backend/agents/csv_agent.py`
- [Intent Routing](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/tests/test_intent_detection.py): classifier · Routes chat requests to edit, math, delete, and chart actions. · `backend/tests/test_intent_detection.py`
- [Identity](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/identity.py): auth utility · Backend-side user/session identity handling. · `backend/identity.py`
- [Data Workspace](https://github.com/arpansarkar112/full_stack_ai_chat_application/tree/main/backend/data): file workspace · Temporary or generated dataset artifacts. · `backend/data`

### Platform

Supabase persistence/auth and deployment targets.

- [Supabase Client](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/integrations/supabase/client.ts): data gateway · Typed client for auth and database access. · `src/integrations/supabase/client.ts`
- [Supabase Types](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/integrations/supabase/types.ts): schema types · Generated database and auth type definitions. · `src/integrations/supabase/types.ts`
- [Supabase DB](https://github.com/arpansarkar112/full_stack_ai_chat_application/tree/main/supabase/migrations): managed database · Postgres-backed persistence for sessions, profiles, and policies. · `supabase/migrations`
- [Vercel](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/vercel.json): hosting · Frontend deployment target. · `vercel.json`
- [Render](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/backend/requirements.txt): hosting · Backend deployment target. · `backend/requirements.txt`
- **Gemini API**: model provider · External LLM service used by the backend.

### Shared UI

Reusable design system and presentation utilities.

- [Markdown](https://github.com/arpansarkar112/full_stack_ai_chat_application/blob/main/src/components/chat/markdown.tsx): renderer · Renders rich assistant responses and formatted content. · `src/components/chat/markdown.tsx`
- [UI Kit](https://github.com/arpansarkar112/full_stack_ai_chat_application/tree/main/src/components/ui): design system · Reusable shadcn/Radix component library and theme controls. · `src/components/ui`

## Connections

- App Shell → Landing: routes · Public entry route.
- App Shell → Auth: routes · Authentication route.
- App Shell → Protected Route: guards · Wraps private pages.
- Protected Route → Dashboard: allows · Authenticated workspace access.
- Protected Route → Chat Session: allows · Session workspace access.
- Protected Route → Past Chats: allows · Conversation history access.
- Protected Route → Profile: allows · Profile access.
- Protected Route → Credit: allows · Credit page access.
- Auth State → Supabase Client: uses · Reads and maintains session state.
- Auth → Auth State: consumes · Uses shared auth context.
- Dashboard → Dashboard UI: composes · Builds summary view from dashboard widgets.
- Chat Session → Chat UI: composes · Main conversation interface.
- Chat UI → Markdown: renders · Formats assistant output.
- Chat UI → UI Kit: uses · Relies on shared presentation components.
- Dashboard UI → UI Kit: uses · Built on the shared design system.
- Profile → Supabase Client: reads/writes · Updates account data through Supabase.
- Past Chats → Supabase Client: reads · Loads prior chat sessions.
- Chat Session → Supabase Client: reads/writes · Persists session chat state and datasets.
- Supabase Client → Supabase Types: typed by · Client calls are schema-aware.
- API → CSV Agent: delegates · Hands chat tasks to the CSV agent.
- CSV Agent → Intent Routing: routes · Chooses action type for requests.
- API → Identity: checks · Validates user/session context.
- CSV Agent → Data Workspace: uses · Reads and writes working dataset artifacts.
- API → Gemini API: calls · Uses LLM provider for generation and reasoning.
- Supabase DB → Supabase Client: serves · Persistent auth and application data.
- Supabase DB → Identity: supports · Identity and access constraints.
- Vercel → App Shell: hosts · Frontend deployment boundary.
- Render → API: hosts · Backend deployment boundary.
- API → Supabase DB: persists · Reads and writes application data.