# sanyamjain-16/educationchatbot architecture

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

- Interactive diagram: https://gitdiagram.com/sanyamjain-16/educationchatbot
- Repository: https://github.com/sanyamjain-16/educationchatbot

## Overview

1. This repository is a full-stack chatbot platform for a coaching centre use case: a public marketing site, an authenticated admin dashboard, an embeddable chat widget, and server-side APIs for chat, knowledge ingestion, and billing.

2. The app is organized around file-based routing in `src/routes`, with a public area (`index`, `login`, `signup`, `chat.$token`, `widget.js`) and a protected dashboard area under `src/routes/_authenticated`. The protected routes cover chatbot management, analytics, billing, leads, onboarding, settings, and admin views.

3. The frontend is a React app styled with a component library pattern (`src/components/ui`) and assembled into higher-level sections like hero, pricing, testimonials, FAQ, stats, footer, and trust blocks. These are mostly presentation layers for the landing site and dashboard screens.

4. Interactive product features are split into reusable UI subsystems: chatbot builder/demo/widget, custom cursor, 3D background/hero scenes, neural network visuals, device showcase, energy timeline, and embed-snippet generation. These are mostly client-side experience layers rather than backend logic.

5. Animation and motion behavior is centralized in `src/animations` and a set of hooks like `useLenis`, `useCursor`, `useMagnetic`, `useMousePosition`, and `useCountUp`. This suggests a highly interactive marketing experience with smooth scrolling, pointer effects, and animated sections.

6. The backend surface is exposed through route handlers in `src/routes/api`. The key flows are:
   - `api/knowledge.$chatbotId.ingest` for uploading or indexing knowledge into a chatbot,
   - `api/public/chat.$token` for serving public chatbot conversations,
   - `api/webhooks/razorpay` for payment events and subscription/billing updates.

7. Chat and retrieval logic are separated into `src/lib/api/rag.server.ts` and `src/lib/api/faq-cache.server.ts`. That indicates a retrieval-augmented generation flow: chatbot knowledge is ingested, cached/queried server-side, then used to answer public chat requests.

8. Authentication and persistence are centered on Supabase. The repo includes Supabase client/server helpers, auth middleware/attacher, generated types, and a `supabase/migrations` folder. This means auth, database schema, and likely row-level security are core architectural boundaries, not just incidental infrastructure.

9. Billing is a distinct subsystem backed by Razorpay, with server-side functions in `src/lib/api/billing.functions.ts` and a webhook handler. Billing likely gates premium chatbot or dashboard features, and the webhook is the source of truth for payment state changes.

10. Public access vs. authenticated access is an important boundary. Public users can interact with a chatbot via tokenized endpoints or embedded widget code, while authenticated staff manage chatbots, leads, analytics, and settings through the dashboard. The token-based chat route and widget script are the main distribution mechanisms for customer-facing chat.

11. Server/runtime entry points are `src/server.ts` and `src/start.ts`, with `vite.config.ts` and `routeTree.gen.ts` indicating a modern TypeScript web stack built around file-based routing and server-rendered/API-capable routes.

12. In an architecture diagram, the main boxes should be: marketing site/UI, authenticated dashboard UI, public chat widget, application server/routes, chatbot knowledge/RAG layer, Supabase auth/database, and Razorpay billing/webhooks. The primary data flow is: admin creates chatbot and uploads knowledge → server ingests/indexes data → public widget/chat hits tokenized chat endpoint → response is generated from stored knowledge → billing/auth updates flow through Supabase and Razorpay webhooks.

Main entry points: [`src/integrations/supabase/client.ts`](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/integrations/supabase/client.ts) (Supabase stack), [`src/router.tsx`](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/router.tsx) (Root router), [`src/routes/index.tsx`](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/index.tsx) (Marketing site), [`src/routes/_authenticated/dashboard.tsx`](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.tsx) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_frontend["Frontend surfaces"]
  node_n_marketing["Marketing site<br/>public UI<br/>[index.tsx]"]
  node_n_auth_pages["Auth pages<br/>public auth UI<br/>[login.tsx]"]
  node_n_dashboard["Dashboard shell<br/>protected UI<br/>[dashboard.tsx]"]
  node_n_chatbot_mgmt["Chatbot admin<br/>protected UI"]
  node_n_ops_views["Ops views<br/>protected UI"]
  node_n_chat_widget["Chat widget<br/>embeddable UI<br/>[widget[.]js.ts]"]
end

subgraph group_g_experience["Interactive UI layers"]
  node_n_ui_sections["Site sections<br/>presentational sections<br/>[HeroContent.tsx]"]
  node_n_product_ui["Product demos<br/>interactive components<br/>[ChatbotBuilder.tsx]"]
  node_n_motion["Motion system<br/>animation hooks<br/>[gsap.ts]"]
end

subgraph group_g_server["Server routes"]
  node_n_root_router["Root router<br/>route composition<br/>[router.tsx]"]
  node_n_public_chat_api["Public chat API<br/>route handler<br/>[chat.$token.ts]"]
  node_n_knowledge_api["Ingest API<br/>route handler"]
  node_n_webhook_api["Billing webhook<br/>route handler<br/>[razorpay.ts]"]
end

subgraph group_g_chat["Chat intelligence"]
  node_n_rag["RAG engine<br/>retrieval layer<br/>[rag.server.ts]"]
  node_n_faq_cache["FAQ cache<br/>retrieval cache"]
end

subgraph group_g_data["Auth and data"]
  node_n_supabase[("Supabase stack<br/>auth and database<br/>[client.ts]")]
  node_n_migrations["Schema migrations<br/>database migrations"]
end

subgraph group_g_billing["Billing"]
  node_n_billing_funcs["Billing functions<br/>billing logic"]
end

subgraph group_g_runtime["Runtime and bootstrap"]
  node_n_bootstrap["Server bootstrap<br/>runtime entrypoints<br/>[server.ts]"]
end

node_n_root_router -->|"routes to"| node_n_marketing
node_n_root_router -->|"routes to"| node_n_auth_pages
node_n_root_router -->|"routes to"| node_n_dashboard
node_n_dashboard -->|"contains"| node_n_chatbot_mgmt
node_n_dashboard -->|"contains"| node_n_ops_views
node_n_marketing -->|"renders"| node_n_ui_sections
node_n_marketing -->|"showcases"| node_n_product_ui
node_n_product_ui -->|"includes"| node_n_chat_widget
node_n_product_ui -->|"animates with"| node_n_motion
node_n_ui_sections -->|"animates with"| node_n_motion
node_n_chat_widget -->|"calls"| node_n_public_chat_api
node_n_public_chat_api -->|"generates via"| node_n_rag
node_n_knowledge_api -->|"feeds"| node_n_rag
node_n_rag -->|"queries"| node_n_faq_cache
node_n_knowledge_api -->|"stores in"| node_n_supabase
node_n_public_chat_api -->|"reads from"| node_n_supabase
node_n_supabase -->|"defined by"| node_n_migrations
node_n_webhook_api -->|"updates"| node_n_billing_funcs
node_n_billing_funcs -->|"persists to"| node_n_supabase
node_n_webhook_api -->|"verifies state"| node_n_supabase
node_n_bootstrap -->|"starts"| node_n_root_router
node_n_bootstrap -->|"initializes"| node_n_supabase

click node_n_marketing "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/index.tsx"
click node_n_auth_pages "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/login.tsx"
click node_n_dashboard "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.tsx"
click node_n_chatbot_mgmt "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.chatbots.tsx"
click node_n_ops_views "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.analytics.tsx"
click node_n_chat_widget "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/widget[.]js.ts"
click node_n_ui_sections "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/components/hero/HeroContent.tsx"
click node_n_product_ui "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/components/ChatbotBuilder.tsx"
click node_n_motion "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/animations/gsap.ts"
click node_n_root_router "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/router.tsx"
click node_n_public_chat_api "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/api/public/chat.$token.ts"
click node_n_knowledge_api "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/api/knowledge.$chatbotId.ingest.ts"
click node_n_webhook_api "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/api/webhooks/razorpay.ts"
click node_n_rag "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/lib/api/rag.server.ts"
click node_n_faq_cache "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/lib/api/faq-cache.server.ts"
click node_n_supabase "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/integrations/supabase/client.ts"
click node_n_migrations "https://github.com/sanyamjain-16/educationchatbot/blob/main/supabase/migrations/20260616000200_vector_search_helper.sql"
click node_n_billing_funcs "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/lib/api/billing.functions.ts"
click node_n_bootstrap "https://github.com/sanyamjain-16/educationchatbot/blob/main/src/server.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_n_marketing,node_n_auth_pages,node_n_dashboard,node_n_chatbot_mgmt,node_n_ops_views,node_n_chat_widget,node_n_bootstrap toneBlue
class node_n_ui_sections,node_n_product_ui,node_n_motion toneAmber
class node_n_root_router,node_n_public_chat_api,node_n_knowledge_api,node_n_webhook_api toneMint
class node_n_rag,node_n_faq_cache toneRose
class node_n_supabase,node_n_migrations toneIndigo
class node_n_billing_funcs toneTeal
```

## Components

### Frontend surfaces

Public marketing site, dashboard UI, and embeddable chat entrypoints.

- [Marketing site](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/index.tsx): public UI · Public landing pages, onboarding entrypoints, and marketing content. · `src/routes/index.tsx`
- [Auth pages](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/login.tsx): public auth UI · Login and signup surfaces for account access. · `src/routes/login.tsx`
- [Dashboard shell](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.tsx): protected UI · Authenticated dashboard layout and navigation for staff workflows. · `src/routes/_authenticated/dashboard.tsx`
- [Chatbot admin](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.chatbots.tsx): protected UI · Dashboard screens for creating, editing, and viewing chatbots. · `src/routes/_authenticated/dashboard.chatbots.tsx`
- [Ops views](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/_authenticated/dashboard.analytics.tsx): protected UI · Analytics, billing, leads, onboarding, settings, and admin screens. · `src/routes/_authenticated/dashboard.analytics.tsx`
- [Chat widget](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/widget[.]js.ts): embeddable UI · Client-side embeddable widget and tokenized chat experience. · `src/routes/widget[.]js.ts`

### Interactive UI layers

Client-side experience components and motion systems used across the product.

- [Site sections](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/components/hero/HeroContent.tsx): presentational sections · Hero, pricing, testimonials, FAQ, stats, trust, footer, and similar page sections. · `src/components/hero/HeroContent.tsx`
- [Product demos](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/components/ChatbotBuilder.tsx): interactive components · Chatbot builder, demo, widget, embed snippets, and device/showcase experiences. · `src/components/ChatbotBuilder.tsx`
- [Motion system](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/animations/gsap.ts): animation hooks · Centralized animations, scroll behavior, pointer effects, and count-up/magnetic interactions. · `src/animations/gsap.ts`

### Server routes

File-based routes and API handlers that serve pages and backend actions.

- [Root router](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/router.tsx): route composition · Top-level route tree and router setup for file-based navigation. · `src/router.tsx`
- [Public chat API](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/api/public/chat.$token.ts): route handler · Token-based public conversation endpoint used by the widget and chat page. · `src/routes/api/public/chat.$token.ts`
- [Ingest API](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/api/knowledge.$chatbotId.ingest.ts): route handler · Knowledge upload and indexing endpoint for chatbot content ingestion. · `src/routes/api/knowledge.$chatbotId.ingest.ts`
- [Billing webhook](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/routes/api/webhooks/razorpay.ts): route handler · Razorpay webhook receiver for payment events and billing state changes. · `src/routes/api/webhooks/razorpay.ts`

### Chat intelligence

Knowledge ingestion, retrieval, and public chat response generation.

- [RAG engine](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/lib/api/rag.server.ts): retrieval layer · Server-side retrieval-augmented generation flow for answering chat requests. · `src/lib/api/rag.server.ts`
- [FAQ cache](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/lib/api/faq-cache.server.ts): retrieval cache · Cached FAQ and knowledge lookup layer supporting chat responses. · `src/lib/api/faq-cache.server.ts`

### Auth and data

Supabase-backed authentication, persistence, and schema migrations.

- [Supabase stack](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/integrations/supabase/client.ts): auth and database · Supabase client/server helpers, auth middleware, generated types, and persistence boundary. · `src/integrations/supabase/client.ts`
- [Schema migrations](https://github.com/sanyamjain-16/educationchatbot/blob/main/supabase/migrations/20260616000200_vector_search_helper.sql): database migrations · Supabase migration history defining schema, security, ownership, and vector search support. · `supabase/migrations/20260616000200_vector_search_helper.sql`

### Billing

Razorpay payment and subscription update flow.

- [Billing functions](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/lib/api/billing.functions.ts): billing logic · Server-side billing helpers and subscription state coordination. · `src/lib/api/billing.functions.ts`

### Runtime and bootstrap

Application startup and build-time routing/runtime setup.

- [Server bootstrap](https://github.com/sanyamjain-16/educationchatbot/blob/main/src/server.ts): runtime entrypoints · Application startup and server entry files for the Vite/TypeScript runtime. · `src/server.ts`

## Connections

- Root router → Marketing site: routes to · Root router composes the public marketing routes.
- Root router → Auth pages: routes to · Root router composes auth entry pages.
- Root router → Dashboard shell: routes to · Root router mounts the authenticated dashboard subtree.
- Dashboard shell → Chatbot admin: contains · Dashboard shell frames chatbot management screens.
- Dashboard shell → Ops views: contains · Dashboard shell frames analytics, billing, leads, and settings views.
- Marketing site → Site sections: renders · Landing pages are assembled from reusable site sections.
- Marketing site → Product demos: showcases · Marketing pages surface demos and product experience blocks.
- Product demos → Chat widget: includes · Product UI includes the embeddable chatbot experience.
- Product demos → Motion system: animates with · Interactive product modules use shared motion behavior.
- Site sections → Motion system: animates with · Landing page sections use shared animation primitives.
- Chat widget → Public chat API: calls · Widget sends conversation traffic to the public chat endpoint.
- Public chat API → RAG engine: generates via · Public chat responses are produced through retrieval-augmented generation.
- Ingest API → RAG engine: feeds · Ingestion endpoint prepares content for the retrieval layer.
- RAG engine → FAQ cache: queries · RAG flow consults cached FAQ and knowledge results.
- Ingest API → Supabase stack: stores in · Ingested chatbot knowledge is persisted through Supabase.
- Public chat API → Supabase stack: reads from · Chat endpoint relies on persisted chatbot, token, and session data.
- Supabase stack → Schema migrations: defined by · Schema and security behavior are established by migrations.
- Billing webhook → Billing functions: updates · Webhook events are translated into billing state changes.
- Billing functions → Supabase stack: persists to · Billing state and subscription data are stored in Supabase.
- Billing webhook → Supabase stack: verifies state · Webhook processing depends on persisted customer and subscription records.
- Server bootstrap → Root router: starts · Server bootstrap launches the routed application.
- Server bootstrap → Supabase stack: initializes · Runtime bootstraps Supabase-backed auth and database access.