How ari-han-t/explore-vit works
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: supabase-data.ts Supabase data · app/page.tsx UI shell · login/page.tsx Login · auth-provider.tsx Auth provider
Components 22
Next.js app
User-facing TypeScript UI in the repository root.
- UI shell · Top-level application entry and route composition.
app/page.tsx - Login · Entry point for student and mentor sign-in flows.
app/login/page.tsx - Auth callback · Handles Supabase OAuth return and session completion.
app/auth/callback/page.tsx - Domains · Domain exploration and guidance entry page.
app/domains/page.tsx - Mentors · Mentor listing and discovery surface.
app/mentors/page.tsx - Mentor detail · Individual mentor profile and context view.
app/mentor/page.tsx - Chat session · Session-scoped chat view for student-mentor conversation.
app/chat/[sessionId]/page.tsx - Reflection · Student reflection and learning signal capture.
app/reflection/page.tsx - Profile · Personal profile and preference capture for recommendations.
app/profile/page.tsx - Decision support · Frontend surface for domain guidance and recommendation results.
app/decision-support/page.tsx - Auth provider · Global Supabase auth state wrapper used across the app.
components/auth-provider.tsx - Role access · Role-based gating for student and mentor visibility.
components/role-access.tsx - Supabase client · Shared client configuration for web access to Supabase.
lib/supabase.ts - Supabase data · Reusable Supabase-backed reads and writes for app state.
lib/supabase-data.ts - App data · Local data handling and app-side persistence helpers.
lib/data.ts - Storage · Client-side storage helpers for app state.
lib/storage.ts - Recommendations · Frontend adapter for domain recommendation requests and shaping.
lib/recommendation.ts
Python service
FastAPI recommendation service and ML logic.
- API server · Python service entrypoint exposing recommendation endpoints.
backend/main.py - Recommender · Scoring and ranking logic for guidance output.
backend/ml/recommender.py - Domain profiles · Domain profile definitions used by TF-IDF similarity.
backend/ml/domain_profiles.py
Connections 23
- 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.