# yashwinbuilds/kcet-college-predictor architecture

> Architecture diagram of the GitHub repository yashwinbuilds/kcet-college-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yashwinbuilds/kcet-college-predictor
- Repository: https://github.com/yashwinbuilds/kcet-college-predictor

## Overview

KCET College Predictor is a counseling and college-discovery platform for Karnataka exam aspirants. Its main workflow combines live college data with a rank, category, and preference-based predictor to produce safe, moderate, and dream college options; users can save choices and explore them further. Other substantial product areas include a mock allotment simulator, commute mapping, trends, chat, and community features. The README documents version-checked user data sync and a live master view for administrators. Some feature paths are evident from the tree and README, but their internal wiring was not sampled, so those connections are omitted.

Main entry points: [`src/app/predictor/page.tsx`](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/predictor/page.tsx) (Smart Predictor), [`src/lib/hooks/useWishlist.ts`](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/hooks/useWishlist.ts) (Wishlist), [`src/app/commute/page.tsx`](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/commute/page.tsx) (Commute Planner), [`src/lib/contexts/CollegeContext.tsx`](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/contexts/CollegeContext.tsx) (College Data Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["College Discovery"]
  node_home["Home Explorer<br/>[page.tsx]"]
  node_predictor_ui["Smart Predictor<br/>[page.tsx]"]
  node_prediction_engine["Prediction Engine<br/>[predictor.ts]"]
  node_cutoffs["Cutoff Explorer<br/>[page.tsx]"]
  node_rank_predictor["Rank Predictor<br/>[page.tsx]"]
  node_compare["College Compare<br/>[page.tsx]"]
  node_commute["Commute Planner<br/>[page.tsx]"]
  node_map["Map View<br/>[Map.tsx]"]
  node_commute_data["Transit Data"]
  node_trends["Trends Explorer<br/>[page.tsx]"]
end

subgraph group_data["Data and Sync"]
  node_college_context["College Data Context<br/>[CollegeContext.tsx]"]
  node_firestore[("Cloud Firestore")]
  node_firebase["Firebase Client<br/>[firebase.ts]"]
end

subgraph group_counseling["Counseling and Community"]
  node_simulator["Mock Simulator<br/>[page.tsx]"]
  node_wishlist["Wishlist<br/>[useWishlist.ts]"]
  node_social_matches["Social Matches"]
  node_messages["Messages<br/>[page.tsx]"]
  node_chat_service["Chat Service<br/>[chat.ts]"]
  node_chat_api["AI Chat API<br/>[route.ts]"]
  node_tracker["Application Tracker<br/>[page.tsx]"]
  node_community["Community<br/>[page.tsx]"]
end

subgraph group_operations["Access and Administration"]
  node_admin["Admin Console<br/>[page.tsx]"]
  node_auth["Authentication Context<br/>[AuthContext.tsx]"]
  node_auth_modal["Sign-in Modal<br/>[AuthModal.tsx]"]
end

node_aspirant(("KCET Aspirant"))

node_aspirant -->|"opens"| node_home
node_aspirant -->|"submits preferences"| node_predictor_ui
node_predictor_ui -->|"calculates predictions"| node_prediction_engine
node_predictor_ui -->|"reads live colleges"| node_college_context
node_predictor_ui -->|"uses saved choices"| node_wishlist
node_predictor_ui -->|"opens sign-in"| node_auth_modal
node_auth_modal -->|"invokes sign-in"| node_auth
node_college_context -->|"uses client"| node_firebase
node_firebase -->|"initializes database"| node_firestore
node_admin -->|"reads and writes master data"| node_firestore
node_admin -->|"uses data context"| node_college_context
node_aspirant -->|"runs mock counseling"| node_simulator
node_simulator -->|"saves simulation state"| node_firestore
node_aspirant -->|"plans travel"| node_commute
node_commute -->|"renders map"| node_map
node_commute -->|"reads transit data"| node_commute_data
node_cutoffs -->|"uses predictions"| node_prediction_engine
node_wishlist -->|"reads user state"| node_auth
node_wishlist -->|"syncs saved choices"| node_firestore
node_social_matches -->|"uses wishlist"| node_wishlist
node_social_matches -->|"queries profiles"| node_firestore
node_messages -->|"uses chat service"| node_chat_service
node_chat_service -->|"uses client database"| node_firestore
node_chat_api -.->|"serves chat requests"| node_aspirant

click node_home "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/page.tsx"
click node_predictor_ui "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/predictor/page.tsx"
click node_prediction_engine "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/predictor.ts"
click node_cutoffs "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/cutoffs/page.tsx"
click node_rank_predictor "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/rank-predictor/page.tsx"
click node_compare "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/compare/page.tsx"
click node_commute "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/commute/page.tsx"
click node_map "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/components/Map.tsx"
click node_commute_data "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/data/metro_connectivity.ts"
click node_college_context "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/contexts/CollegeContext.tsx"
click node_firebase "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/firebase.ts"
click node_admin "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/admin/page.tsx"
click node_auth "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/contexts/AuthContext.tsx"
click node_auth_modal "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/components/AuthModal.tsx"
click node_simulator "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/simulator/page.tsx"
click node_wishlist "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/hooks/useWishlist.ts"
click node_social_matches "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/hooks/useSocialMatches.ts"
click node_messages "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/messages/page.tsx"
click node_chat_service "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/services/chat.ts"
click node_chat_api "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/api/chat/route.ts"
click node_trends "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/trends/page.tsx"
click node_tracker "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/tracker/page.tsx"
click node_community "https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/community/page.tsx"

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_home,node_predictor_ui,node_prediction_engine,node_cutoffs,node_rank_predictor,node_compare,node_commute,node_map,node_commute_data,node_trends toneBlue
class node_college_context,node_firestore,node_firebase toneAmber
class node_simulator,node_wishlist,node_social_matches,node_messages,node_chat_service,node_chat_api,node_tracker,node_community toneMint
class node_admin,node_auth,node_auth_modal toneRose
class node_aspirant toneIndigo
```

## Components

### College Discovery

- [Home Explorer](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/page.tsx): `src/app/page.tsx`
- [Smart Predictor](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/predictor/page.tsx): `src/app/predictor/page.tsx`
- [Prediction Engine](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/predictor.ts): `src/lib/predictor.ts`
- [Cutoff Explorer](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/cutoffs/page.tsx): `src/app/cutoffs/page.tsx`
- [Rank Predictor](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/rank-predictor/page.tsx): `src/app/rank-predictor/page.tsx`
- [College Compare](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/compare/page.tsx): `src/app/compare/page.tsx`
- [Commute Planner](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/commute/page.tsx): `src/app/commute/page.tsx`
- [Map View](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/components/Map.tsx): `src/components/Map.tsx`
- [Transit Data](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/data/metro_connectivity.ts): `src/lib/data/metro_connectivity.ts`
- [Trends Explorer](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/trends/page.tsx): `src/app/trends/page.tsx`

### Data and Sync

- [College Data Context](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/contexts/CollegeContext.tsx): `src/lib/contexts/CollegeContext.tsx`
- **Cloud Firestore**
- [Firebase Client](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/firebase.ts): `src/lib/firebase.ts`

### Counseling and Community

- [Mock Simulator](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/simulator/page.tsx): `src/app/simulator/page.tsx`
- [Wishlist](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/hooks/useWishlist.ts): `src/lib/hooks/useWishlist.ts`
- [Social Matches](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/hooks/useSocialMatches.ts): `src/lib/hooks/useSocialMatches.ts`
- [Messages](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/messages/page.tsx): `src/app/messages/page.tsx`
- [Chat Service](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/services/chat.ts): `src/lib/services/chat.ts`
- [AI Chat API](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Application Tracker](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/tracker/page.tsx): `src/app/tracker/page.tsx`
- [Community](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/community/page.tsx): `src/app/community/page.tsx`

### Access and Administration

- [Admin Console](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/app/admin/page.tsx): `src/app/admin/page.tsx`
- [Authentication Context](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/lib/contexts/AuthContext.tsx): `src/lib/contexts/AuthContext.tsx`
- [Sign-in Modal](https://github.com/yashwinbuilds/kcet-college-predictor/blob/master/src/components/AuthModal.tsx): `src/components/AuthModal.tsx`

### Other components

- **KCET Aspirant**

## Connections

- KCET Aspirant → Home Explorer: opens (evidence: `README.md`)
- KCET Aspirant → Smart Predictor: submits preferences (evidence: `README.md`)
- Smart Predictor → Prediction Engine: calculates predictions (evidence: `src/app/predictor/page.tsx`)
- Smart Predictor → College Data Context: reads live colleges (evidence: `src/app/predictor/page.tsx`)
- Smart Predictor → Wishlist: uses saved choices (evidence: `src/app/predictor/page.tsx`)
- Smart Predictor → Sign-in Modal: opens sign-in (evidence: `src/app/predictor/page.tsx`)
- Sign-in Modal → Authentication Context: invokes sign-in (evidence: `src/components/AuthModal.tsx`)
- College Data Context → Firebase Client: uses client (evidence: `src/lib/contexts/CollegeContext.tsx`)
- Firebase Client → Cloud Firestore: initializes database (evidence: `src/lib/firebase.ts`)
- Admin Console → Cloud Firestore: reads and writes master data (evidence: `src/app/admin/page.tsx`)
- Admin Console → College Data Context: uses data context (evidence: `src/app/admin/page.tsx`)
- KCET Aspirant → Mock Simulator: runs mock counseling (evidence: `README.md`)
- Mock Simulator → Cloud Firestore: saves simulation state (evidence: `src/app/simulator/page.tsx`)
- KCET Aspirant → Commute Planner: plans travel (evidence: `src/app/commute/page.tsx`)
- Commute Planner → Map View: renders map (evidence: `src/app/commute/page.tsx`)
- Commute Planner → Transit Data: reads transit data (evidence: `src/app/commute/page.tsx`)
- Cutoff Explorer → Prediction Engine: uses predictions (evidence: `src/app/cutoffs/page.tsx`)
- Wishlist → Authentication Context: reads user state (evidence: `src/lib/hooks/useWishlist.ts`)
- Wishlist → Cloud Firestore: syncs saved choices (evidence: `src/lib/hooks/useWishlist.ts`)
- Social Matches → Wishlist: uses wishlist (evidence: `src/lib/hooks/useSocialMatches.ts`)
- Social Matches → Cloud Firestore: queries profiles (evidence: `src/lib/hooks/useSocialMatches.ts`)
- Messages → Chat Service: uses chat service (evidence: `src/app/messages/page.tsx`)
- Chat Service → Cloud Firestore: uses client database (evidence: `src/lib/services/chat.ts`)
- AI Chat API → KCET Aspirant: serves chat requests
