# ari-han-t/explore-vit architecture

> Architecture diagram of the GitHub repository ari-han-t/explore-vit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ari-han-t/explore-vit
- Repository: https://github.com/ari-han-t/explore-vit

## Overview

1. **System shape**
   Explore VIT is a split frontend/backend app: a **Next.js 16 TypeScript UI** in the repo root, a **FastAPI recommendation service** in `backend/`, and **Supabase** for authentication, database, and realtime messaging. The frontend is the primary user-facing layer; the Python service is used only for domain guidance/recommendations.

2. **Frontend route structure**
   The `app/` directory uses the Next.js App Router and is organized by product area: `login`, `auth/callback`, `domains`, `mentor`, `mentors`, `chat`, `reflection`, `profile`, and `decision-support`. This suggests the UI is segmented by student onboarding, mentor discovery, chat, and reflection workflows rather than a single generic dashboard.

3. **Auth boundary**
   Authentication is centralized around Supabase auth, with two flows: **student Google OAuth** and **mentor email/password signup/login**. The `components/auth-provider.tsx` and `components/auth-callback-client.tsx` files indicate the app wraps auth state globally and handles OAuth redirects on the client. The README also shows a Supabase **Before User Created hook** controlling who can register.

4. **Role and access control**
   The repo includes `components/role-access.tsx`, which implies route-level or component-level gating based on user role. The app distinguishes **students** and **mentors** early, because they have different allowed sign-in methods, different profile fields, and different visibility into chat/session context.

5. **Supabase as operational data store**
   Supabase is the main persistence layer for user-facing data: mentor profiles, allowed email/domain lists, student reflections, chat/session records, and likely profile/interest state. The SQL files in `supabase/schema.sql` and `supabase/seed.sql` define the canonical schema and bootstrap data, so the architecture depends on those tables being present before the app runs.

6. **Data access layer in TypeScript**
   The `lib/` folder splits data concerns into reusable helpers:
   - `lib/supabase.ts` for client setup
   - `lib/supabase-data.ts` for Supabase-backed reads/writes
   - `lib/data.ts` and `lib/storage.ts` for local app data handling
   - `lib/types.ts` for shared domain models
   - `lib/recommendation.ts` for calling or shaping recommendation results  
   This indicates the UI does not talk to Supabase directly from every page; it goes through a small data-access layer.

7. **Mentor discovery flow**
   The `mentors` and `mentor` routes, together with the README’s “real mentor profiles from Supabase,” show a browse/detail pattern for mentors. Mentor profiles are not mock data only; they are stored in Supabase and likely filtered by specialization, availability, or allowlist status. This is a separate subsystem from chat, because users can discover mentors before starting a session.

8. **Reflection and profile capture**
   The `reflection` and `profile` pages are for capturing student context: interests, learning reflections, and personal profile details. This data feeds both the mentor experience and the recommendation service, so it acts as a bridge between user activity and guidance. In architecture terms, it is the “signal collection” layer for personalization.

9. **Chat and session handling**
   The `chat/` routes, including `chat/[sessionId]`, indicate chat is session-scoped rather than a single global room. The README calls out **realtime chat between students and mentors**, which means Supabase Realtime is likely used to stream message updates while Supabase tables persist session and message history. The mentor should see student context once a session starts, so chat is coupled to profile/reflection data.

10. **Recommendation service**
   The `backend/` FastAPI app is a separate Python service with `backend/main.py` and ML code under `backend/ml/`. The recommender uses **scikit-learn TF-IDF similarity** over domain profiles in `domain_profiles.py` and scoring logic in `recommender.py`. Its job is narrow: take student activity/context and return domain guidance, rather than serving the whole app.

11. **Frontend-to-backend flow**
   The frontend uses `NEXT_PUBLIC_API_BASE_URL` to reach the FastAPI service. That means domain advice is fetched over HTTP from the Next.js app, while user identity and realtime state remain in Supabase. This is a clean boundary: **UI and auth/data live in the web app/Supabase layer; recommendations live in Python**.

12. **Deployment and environment boundaries**
   The project is designed for three deployment surfaces: **Vercel** for the frontend, **Render** for the FastAPI service, and **Supabase** for auth/database/realtime. Environment variables define the integration points, including Supabase URL/keys, the site URL, the API base URL, and the allowed student email domain. Those env values are essential because they control auth redirects, API routing, and who is allowed to join.

Main entry points: [`lib/supabase-data.ts`](https://github.com/ari-han-t/explore-vit/blob/master/lib/supabase-data.ts) (Supabase data), [`app/page.tsx`](https://github.com/ari-han-t/explore-vit/blob/master/app/page.tsx) (UI shell), [`app/login/page.tsx`](https://github.com/ari-han-t/explore-vit/blob/master/app/login/page.tsx) (Login), [`components/auth-provider.tsx`](https://github.com/ari-han-t/explore-vit/blob/master/components/auth-provider.tsx) (Auth provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js app"]
  node_app_root["UI shell<br/>Next.js App Router<br/>[page.tsx]"]
  node_login["Login<br/>auth route<br/>[page.tsx]"]
  node_auth_callback["Auth callback<br/>OAuth redirect<br/>[page.tsx]"]
  node_domains["Domains<br/>discovery route<br/>[page.tsx]"]
  node_mentors["Mentors<br/>browse route<br/>[page.tsx]"]
  node_mentor_detail["Mentor detail<br/>profile route<br/>[page.tsx]"]
  node_chat_session["Chat session<br/>session route<br/>[page.tsx]"]
  node_reflection["Reflection<br/>context capture<br/>[page.tsx]"]
  node_profile["Profile<br/>[page.tsx]"]
  node_decision_support["Decision support<br/>recommendation UI<br/>[page.tsx]"]
  node_auth_provider["Auth provider<br/>auth state<br/>[auth-provider.tsx]"]
  node_role_access["Role access<br/>access control<br/>[role-access.tsx]"]
  node_supabase_client["Supabase client<br/>data client<br/>[supabase.ts]"]
  node_supabase_data["Supabase data<br/>data access<br/>[supabase-data.ts]"]
  node_app_data["App data<br/>local data<br/>[data.ts]"]
  node_storage["Storage<br/>[storage.ts]"]
  node_recommendation_lib["Recommendations<br/>service client<br/>[recommendation.ts]"]
end

subgraph group_backend["Python service"]
  node_api_main["API server<br/>FastAPI app<br/>[main.py]"]
  node_recommender["Recommender<br/>ML scoring<br/>[recommender.py]"]
  node_domain_profiles["Domain profiles<br/>ML corpus<br/>[domain_profiles.py]"]
end

subgraph group_platform["Supabase"]
  node_schema[("Schema<br/>[schema.sql]")]
  node_seed["Seed data<br/>bootstrap data<br/>[seed.sql]"]
end

node_app_root -->|"wraps"| node_auth_provider
node_app_root -->|"guards"| node_role_access
node_app_root -->|"routes to"| node_login
node_login -->|"redirects"| node_auth_callback
node_auth_callback -->|"updates"| node_auth_provider
node_mentors -->|"opens"| node_mentor_detail
node_chat_session -->|"uses context"| node_profile
node_chat_session -->|"uses context"| node_reflection
node_profile -->|"reads/writes"| node_supabase_data
node_reflection -->|"reads/writes"| node_supabase_data
node_mentors -->|"loads"| node_supabase_data
node_mentor_detail -->|"loads"| node_supabase_data
node_supabase_data -->|"uses"| node_supabase_client
node_supabase_client -->|"targets"| node_schema
node_schema -->|"bootstraps"| node_seed
node_decision_support -->|"calls"| node_recommendation_lib
node_recommendation_lib -->|"HTTP calls"| node_api_main
node_api_main -->|"uses"| node_recommender
node_recommender -->|"scores against"| node_domain_profiles
node_domains -->|"surfaces"| node_decision_support
node_role_access -.->|"restricts"| node_login
node_auth_provider -->|"authenticates"| node_supabase_client
node_storage -.->|"supports"| node_app_data

click node_app_root "https://github.com/ari-han-t/explore-vit/blob/master/app/page.tsx"
click node_login "https://github.com/ari-han-t/explore-vit/blob/master/app/login/page.tsx"
click node_auth_callback "https://github.com/ari-han-t/explore-vit/blob/master/app/auth/callback/page.tsx"
click node_domains "https://github.com/ari-han-t/explore-vit/blob/master/app/domains/page.tsx"
click node_mentors "https://github.com/ari-han-t/explore-vit/blob/master/app/mentors/page.tsx"
click node_mentor_detail "https://github.com/ari-han-t/explore-vit/blob/master/app/mentor/page.tsx"
click node_chat_session "https://github.com/ari-han-t/explore-vit/blob/master/app/chat/[sessionId]/page.tsx"
click node_reflection "https://github.com/ari-han-t/explore-vit/blob/master/app/reflection/page.tsx"
click node_profile "https://github.com/ari-han-t/explore-vit/blob/master/app/profile/page.tsx"
click node_decision_support "https://github.com/ari-han-t/explore-vit/blob/master/app/decision-support/page.tsx"
click node_auth_provider "https://github.com/ari-han-t/explore-vit/blob/master/components/auth-provider.tsx"
click node_role_access "https://github.com/ari-han-t/explore-vit/blob/master/components/role-access.tsx"
click node_supabase_client "https://github.com/ari-han-t/explore-vit/blob/master/lib/supabase.ts"
click node_supabase_data "https://github.com/ari-han-t/explore-vit/blob/master/lib/supabase-data.ts"
click node_app_data "https://github.com/ari-han-t/explore-vit/blob/master/lib/data.ts"
click node_storage "https://github.com/ari-han-t/explore-vit/blob/master/lib/storage.ts"
click node_recommendation_lib "https://github.com/ari-han-t/explore-vit/blob/master/lib/recommendation.ts"
click node_api_main "https://github.com/ari-han-t/explore-vit/blob/master/backend/main.py"
click node_recommender "https://github.com/ari-han-t/explore-vit/blob/master/backend/ml/recommender.py"
click node_domain_profiles "https://github.com/ari-han-t/explore-vit/blob/master/backend/ml/domain_profiles.py"
click node_schema "https://github.com/ari-han-t/explore-vit/blob/master/supabase/schema.sql"
click node_seed "https://github.com/ari-han-t/explore-vit/blob/master/supabase/seed.sql"

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_app_root,node_login,node_auth_callback,node_domains,node_mentors,node_mentor_detail,node_chat_session,node_reflection,node_profile,node_decision_support,node_auth_provider,node_role_access,node_supabase_client,node_supabase_data,node_app_data,node_storage,node_recommendation_lib toneBlue
class node_api_main,node_recommender,node_domain_profiles toneAmber
class node_schema,node_seed toneMint
```

## Components

### Next.js app

User-facing TypeScript UI in the repository root.

- [UI shell](https://github.com/ari-han-t/explore-vit/blob/master/app/page.tsx): Next.js App Router · Top-level application entry and route composition. · `app/page.tsx`
- [Login](https://github.com/ari-han-t/explore-vit/blob/master/app/login/page.tsx): auth route · Entry point for student and mentor sign-in flows. · `app/login/page.tsx`
- [Auth callback](https://github.com/ari-han-t/explore-vit/blob/master/app/auth/callback/page.tsx): OAuth redirect · Handles Supabase OAuth return and session completion. · `app/auth/callback/page.tsx`
- [Domains](https://github.com/ari-han-t/explore-vit/blob/master/app/domains/page.tsx): discovery route · Domain exploration and guidance entry page. · `app/domains/page.tsx`
- [Mentors](https://github.com/ari-han-t/explore-vit/blob/master/app/mentors/page.tsx): browse route · Mentor listing and discovery surface. · `app/mentors/page.tsx`
- [Mentor detail](https://github.com/ari-han-t/explore-vit/blob/master/app/mentor/page.tsx): profile route · Individual mentor profile and context view. · `app/mentor/page.tsx`
- [Chat session](https://github.com/ari-han-t/explore-vit/blob/master/app/chat/[sessionId]/page.tsx): session route · Session-scoped chat view for student-mentor conversation. · `app/chat/[sessionId]/page.tsx`
- [Reflection](https://github.com/ari-han-t/explore-vit/blob/master/app/reflection/page.tsx): context capture · Student reflection and learning signal capture. · `app/reflection/page.tsx`
- [Profile](https://github.com/ari-han-t/explore-vit/blob/master/app/profile/page.tsx): student profile · Personal profile and preference capture for recommendations. · `app/profile/page.tsx`
- [Decision support](https://github.com/ari-han-t/explore-vit/blob/master/app/decision-support/page.tsx): recommendation UI · Frontend surface for domain guidance and recommendation results. · `app/decision-support/page.tsx`
- [Auth provider](https://github.com/ari-han-t/explore-vit/blob/master/components/auth-provider.tsx): auth state · Global Supabase auth state wrapper used across the app. · `components/auth-provider.tsx`
- [Role access](https://github.com/ari-han-t/explore-vit/blob/master/components/role-access.tsx): access control · Role-based gating for student and mentor visibility. · `components/role-access.tsx`
- [Supabase client](https://github.com/ari-han-t/explore-vit/blob/master/lib/supabase.ts): data client · Shared client configuration for web access to Supabase. · `lib/supabase.ts`
- [Supabase data](https://github.com/ari-han-t/explore-vit/blob/master/lib/supabase-data.ts): data access · Reusable Supabase-backed reads and writes for app state. · `lib/supabase-data.ts`
- [App data](https://github.com/ari-han-t/explore-vit/blob/master/lib/data.ts): local data · Local data handling and app-side persistence helpers. · `lib/data.ts`
- [Storage](https://github.com/ari-han-t/explore-vit/blob/master/lib/storage.ts): client storage · Client-side storage helpers for app state. · `lib/storage.ts`
- [Recommendations](https://github.com/ari-han-t/explore-vit/blob/master/lib/recommendation.ts): service client · Frontend adapter for domain recommendation requests and shaping. · `lib/recommendation.ts`

### Python service

FastAPI recommendation service and ML logic.

- [API server](https://github.com/ari-han-t/explore-vit/blob/master/backend/main.py): FastAPI app · Python service entrypoint exposing recommendation endpoints. · `backend/main.py`
- [Recommender](https://github.com/ari-han-t/explore-vit/blob/master/backend/ml/recommender.py): ML scoring · Scoring and ranking logic for guidance output. · `backend/ml/recommender.py`
- [Domain profiles](https://github.com/ari-han-t/explore-vit/blob/master/backend/ml/domain_profiles.py): ML corpus · Domain profile definitions used by TF-IDF similarity. · `backend/ml/domain_profiles.py`

### Supabase

Auth, database, realtime, and schema/bootstrap layer.

- [Schema](https://github.com/ari-han-t/explore-vit/blob/master/supabase/schema.sql): database schema · Canonical Supabase tables and relationships. · `supabase/schema.sql`
- [Seed data](https://github.com/ari-han-t/explore-vit/blob/master/supabase/seed.sql): bootstrap data · Initial allowlists and starter records for Supabase. · `supabase/seed.sql`

## Connections

- UI shell → Auth provider: wraps · The app is globally wrapped with auth state.
- UI shell → Role access: guards · Role-based UI access is applied around protected areas.
- UI shell → Login: routes to · Users enter through the login flow.
- Login → Auth callback: redirects · OAuth sign-in completes through the callback page.
- Auth callback → Auth provider: updates · Callback finalizes session state in the client.
- Mentors → Mentor detail: opens · Mentor browsing leads into detail views.
- Chat session → Profile: uses context · Chat sessions depend on student profile context.
- Chat session → Reflection: uses context · Chat sessions incorporate reflection signals.
- Profile → Supabase data: reads/writes · Profile state is persisted through the data layer.
- Reflection → Supabase data: reads/writes · Reflection data is stored through the data layer.
- Mentors → Supabase data: loads · Mentor discovery reads persisted mentor profiles.
- Mentor detail → Supabase data: loads · Mentor detail views fetch stored profile data.
- Supabase data → Supabase client: uses · Data access is built on the shared Supabase client.
- Supabase client → Schema: targets · Client operations map to the canonical Supabase schema.
- Schema → Seed data: bootstraps · Seed data initializes key schema content and allowlists.
- Decision support → Recommendations: calls · The UI fetches guidance through the recommendation adapter.
- Recommendations → API server: HTTP calls · Frontend requests are sent to the Python service.
- API server → Recommender: uses · The FastAPI app delegates scoring to the recommender.
- Recommender → Domain profiles: scores against · Recommendation ranking compares student context to domain profiles.
- Domains → Decision support: surfaces · Domain exploration connects to decision support workflows.
- Role access → Login: restricts · Authentication and role selection gate sign-in surfaces.
- Auth provider → Supabase client: authenticates · Global auth state is sourced from Supabase.
- Storage → App data: supports · Local storage and app data helpers complement each other.
