# shai-mohan/tutortots architecture

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

- Interactive diagram: https://gitdiagram.com/shai-mohan/tutortots
- Repository: https://github.com/shai-mohan/tutortots

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-role web application (“TutorTots”) built with Next.js (App Router) that connects Sunway University students and tutors.
- Frontend: React pages/components with Tailwind CSS and shadcn/ui.
- Backend services: Supabase for authentication, PostgreSQL database, and serverless functions accessed via the Supabase client library.

##### File-Structure Analysis
- app/ – Next.js “App Router” directory with role-based subpaths (admin, student, tutor, about, tutors, test-connection).
- components/ – Shared React components (auth-provider, forms, UI primitives under ui/).
- hooks/ – Custom React hooks (use-toast, use-mobile).
- lib/ – Utility modules and Supabase client initialization (supabase.ts), recommendation logic, sentiment analysis.
- public/ – Static assets (images, videos, Lottie animations).
- scripts/ – SQL scripts for DB schema, RLS, seeding, functions (points system, availability, feedback).
- config files – next.config.mjs, tailwind.config.ts, tsconfig.json.

##### README Insights
- Tech stack confirms Next.js + TypeScript, Tailwind, Supabase (DB & Auth), React Hook Form + Zod, Framer Motion, Recharts.
- Deployed to Vercel.

a. Main Components
- Next.js Frontend (UI Layer)
– App Router pages (Role-based routes: /student, /tutor, /admin)
– Shared components & UI library (shadcn/ui, Radix)
– State management (React Hook Form, Zod, custom hooks)
- Business Logic Layer (lib/)
– Recommendation engine (lib/recommendation.ts)
– Sentiment analysis (lib/local-sentiment.ts)
– Utility functions (lib/utils.ts)
- Backend Services
– Supabase Auth (email/password, magic link)
– Supabase PostgreSQL database (tables for users, tutors, students, rewards, availability, feedback, points)
– Supabase Functions (via SQL scripts or Supabase Edge functions if used)
- External Services
– Vercel (hosting & Serverless Functions)
– Lottie (animation JSON assets)
– Recharts for chart rendering

b. Relationships & Data Flow
1. User interacts with Next.js UI → React Hook Form triggers validation (Zod) → on submit calls lib/supabase client.
2. Supabase client → Auth API or Database RPCs → reads/writes Postgres via RLS policies.
3. lib/ modules perform computations (recommendation, sentiment) either client-side or server-side.
4. UI renders charts (Recharts) and animations (Framer Motion, Lottie) based on fetched data.
5. Deployment → Vercel serves SSR/ISR pages and static assets; environment variables connect to Supabase.

c. Architectural Patterns & Principles
- Component-based UI (atomic UI primitives under components/ui).
- Role-based routing using Next.js App Router conventions.
- Separation of concerns: UI (components), state/validation (hooks/forms), business logic (lib), data persistence (Supabase).
- Secure data access with Supabase Row Level Security and SQL migration scripts.
- Serverless deployment model (Vercel + Supabase).

d. Key Technologies
- Next.js (React 19, App Router)
- TypeScript
- Tailwind CSS
- shadcn/ui & Radix UI for primitives
- React Hook Form + Zod
- Supabase (Auth + Database + Functions)
- Framer Motion, Lottie, Recharts

## Diagram (Mermaid)

```mermaid
graph TD
  %% User
  User["User Browser"]:::external

  %% Frontend Layer
  subgraph "Frontend"
    direction TB

    subgraph "Pages & Routing"
      direction TB
      NextApp["Next.js App Router"]:::frontend
      subgraph "Student Routes"
        direction TB
        StuHome["/student/page.tsx"]:::frontend
        StuCalendar["/student/calendar/page.tsx"]:::frontend
        StuProfile["/student/profile/page.tsx"]:::frontend
        StuRewards["/student/rewards/page.tsx"]:::frontend
        StuTutor["/student/tutor/[id]/page.tsx"]:::frontend
      end
      subgraph "Tutor Routes"
        direction TB
        TutHome["/tutor/page.tsx"]:::frontend
        TutAvail["/tutor/availability/page.tsx"]:::frontend
        TutFeedback["/tutor/feedback/page.tsx"]:::frontend
        TutProfile["/tutor/profile/page.tsx"]:::frontend
        TutRewards["/tutor/rewards/page.tsx"]:::frontend
      end
      subgraph "Admin & Public Routes"
        direction TB
        AdminHome["/admin/page.tsx"]:::frontend
        About["/about/page.tsx"]:::frontend
        Tutors["/tutors/page.tsx"]:::frontend
        TestConn["/test-connection/page.tsx"]:::frontend
        Home["/page.tsx"]:::frontend
      end
    end

    subgraph "Shared Components"
      direction TB
      SharedComp["Shared React Components"]:::frontend
      subgraph "Auth & Theme Providers"
        direction TB
        AuthProv["auth-provider.tsx"]:::frontend
        ThemeProv["theme-provider.tsx"]:::frontend
      end
      subgraph "Forms & Uploads"
        direction TB
        LoginForm["login-form.tsx"]:::frontend
        RegForm["register-form.tsx"]:::frontend
        FeedbackForm["feedback-form.tsx"]:::frontend
        UploadComp["profile-photo-upload.tsx"]:::frontend
      end
      UIPrims["UI Primitives Library"]:::frontend
      ChartComp["Chart Component (chart.tsx)"]:::frontend
    end

    subgraph "State & Validation"
      direction TB
      UseToast["use-toast.ts"]:::frontend
      UseMobile["use-mobile.tsx"]:::frontend
    end

    subgraph "Business Logic Clients"
      direction TB
      SupaClient["Supabase Client Init (supabase.ts)"]:::business
      RecEngine["Recommendation Engine (recommendation.ts)"]:::business
      Sentiment["Sentiment Analysis (local-sentiment.ts)"]:::business
      Utils["Utilities (utils.ts)"]:::business
    end
  end

  %% Backend Layer
  subgraph "Backend (Supabase Cloud)"
    direction TB
    AuthSvc["Supabase Auth"]:::backend
    DB["Supabase PostgreSQL DB"]:::db
    Scripts["SQL Migration & Functions (scripts/)"]:::backend
  end

  %% External Services
  subgraph "External Services"
    direction TB
    Vercel["Vercel Hosting"]:::external
    Lottie["Lottie Animations"]:::external
    Recharts["Recharts Library"]:::external
  end

  %% Connections
  User --> NextApp
  NextApp -->|renders Routes| StuHome
  NextApp --> StuCalendar
  NextApp --> StuProfile
  NextApp --> StuRewards
  NextApp --> StuTutor
  NextApp --> TutHome
  NextApp --> TutAvail
  NextApp --> TutFeedback
  NextApp --> TutProfile
  NextApp --> TutRewards
  NextApp --> AdminHome
  NextApp --> About
  NextApp --> Tutors
  NextApp --> TestConn
  NextApp --> Home

  StuHome --> SupaClient
  StuCalendar --> SupaClient
  StuProfile --> SupaClient
  StuRewards --> SupaClient
  StuTutor --> SupaClient
  TutHome --> SupaClient
  TutAvail --> SupaClient
  TutFeedback --> SupaClient
  TutProfile --> SupaClient
  TutRewards --> SupaClient
  AdminHome --> SupaClient
  About --> SupaClient
  Tutors --> SupaClient
  TestConn --> SupaClient
  Home --> SupaClient

  SharedComp --> SupaClient
  AuthProv --> SupaClient
  ThemeProv --> NextApp
  LoginForm --> SupaClient
  RegForm --> SupaClient
  FeedbackForm --> SupaClient
  UploadComp --> SupaClient

  SupaClient --> AuthSvc
  SupaClient --> DB
  SupaClient --> Scripts

  RecEngine --> DB
  Sentiment --> DB
  Utils --> DB

  ChartComp --> Recharts
  NextApp --> Lottie
  Vercel --> NextApp
  Vercel --> SupaClient
  Vercel --> Scripts

  %% Click Events
  click NextApp "https://github.com/shai-mohan/tutortots/tree/main/app/"
  click StuHome "https://github.com/shai-mohan/tutortots/blob/main/app/student/page.tsx"
  click StuCalendar "https://github.com/shai-mohan/tutortots/blob/main/app/student/calendar/page.tsx"
  click StuProfile "https://github.com/shai-mohan/tutortots/blob/main/app/student/profile/page.tsx"
  click StuRewards "https://github.com/shai-mohan/tutortots/blob/main/app/student/rewards/page.tsx"
  click StuTutor "https://github.com/shai-mohan/tutortots/blob/main/app/student/tutor/[id]/page.tsx"
  click TutHome "https://github.com/shai-mohan/tutortots/blob/main/app/tutor/page.tsx"
  click TutAvail "https://github.com/shai-mohan/tutortots/blob/main/app/tutor/availability/page.tsx"
  click TutFeedback "https://github.com/shai-mohan/tutortots/blob/main/app/tutor/feedback/page.tsx"
  click TutProfile "https://github.com/shai-mohan/tutortots/blob/main/app/tutor/profile/page.tsx"
  click TutRewards "https://github.com/shai-mohan/tutortots/blob/main/app/tutor/rewards/page.tsx"
  click AdminHome "https://github.com/shai-mohan/tutortots/blob/main/app/admin/page.tsx"
  click About "https://github.com/shai-mohan/tutortots/blob/main/app/about/page.tsx"
  click Tutors "https://github.com/shai-mohan/tutortots/blob/main/app/tutors/page.tsx"
  click TestConn "https://github.com/shai-mohan/tutortots/blob/main/app/test-connection/page.tsx"
  click Home "https://github.com/shai-mohan/tutortots/blob/main/app/page.tsx"
  click SharedComp "https://github.com/shai-mohan/tutortots/tree/main/components/"
  click AuthProv "https://github.com/shai-mohan/tutortots/blob/main/components/auth-provider.tsx"
  click ThemeProv "https://github.com/shai-mohan/tutortots/blob/main/components/theme-provider.tsx"
  click LoginForm "https://github.com/shai-mohan/tutortots/blob/main/components/login-form.tsx"
  click RegForm "https://github.com/shai-mohan/tutortots/blob/main/components/register-form.tsx"
  click FeedbackForm "https://github.com/shai-mohan/tutortots/blob/main/components/feedback-form.tsx"
  click UploadComp "https://github.com/shai-mohan/tutortots/blob/main/components/profile-photo-upload.tsx"
  click UIPrims "https://github.com/shai-mohan/tutortots/tree/main/components/ui/"
  click ChartComp "https://github.com/shai-mohan/tutortots/blob/main/components/ui/chart.tsx"
  click UseToast "https://github.com/shai-mohan/tutortots/blob/main/hooks/use-toast.ts"
  click UseMobile "https://github.com/shai-mohan/tutortots/blob/main/hooks/use-mobile.tsx"
  click SupaClient "https://github.com/shai-mohan/tutortots/blob/main/lib/supabase.ts"
  click RecEngine "https://github.com/shai-mohan/tutortots/blob/main/lib/recommendation.ts"
  click Sentiment "https://github.com/shai-mohan/tutortots/blob/main/lib/local-sentiment.ts"
  click Utils "https://github.com/shai-mohan/tutortots/blob/main/lib/utils.ts"
  click Scripts "https://github.com/shai-mohan/tutortots/tree/main/scripts/"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#03396c
  classDef backend fill:#D1FFD0,stroke:#28a745,color:#056524
  classDef db fill:#C8FACC,stroke:#228B22,color:#006400
  classDef business fill:#FFE8A1,stroke:#FFB347,color:#B35900
  classDef external fill:#E8E8E8,stroke:#666666,color:#333333
```
