# kshrr/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/kshrr/nexus
- Repository: https://github.com/kshrr/nexus

## Overview

Nexus helps Malaysian students explore education pathways: users create a profile, assess interests and academic strengths, then explore careers, courses and scholarships, with recommendations and an optional AI advisory chat. Administrators manage catalog data and review scholarship discoveries produced by a separate scraper. The graph covers those product branches and the shared Supabase layer. Some feature implementations and Edge Functions were not excerpted, so their internal calls are omitted; documented and indexed relationships are retained where supported.

Main entry points: [`src/routes.jsx`](https://github.com/kshrr/nexus/blob/main/src/routes.jsx) (Route tree), [`src/lib/api.js`](https://github.com/kshrr/nexus/blob/main/src/lib/api.js) (Function client), [`src/lib/supabase.js`](https://github.com/kshrr/nexus/blob/main/src/lib/supabase.js) (Supabase client), [`scraper/main.py`](https://github.com/kshrr/nexus/blob/main/scraper/main.py) (Scraper runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student experience"]
  node_routes["Route tree<br/>[routes.jsx]"]
  node_profile["Profile setup<br/>[ProfileSetup.jsx]"]
  node_assessment["RIASEC assessment"]
  node_academic["Academic analysis"]
  node_recommendations["Recommendations"]
  node_careers["Career explorer<br/>[CareerDetail.jsx]"]
  node_catalog["Course explorer<br/>[CourseList.jsx]"]
  node_scholarships["Scholarship explorer"]
  node_chatui["Chat interface<br/>[useChat.js]"]
end

subgraph group_services["Application services"]
  node_api["Function client<br/>[api.js]"]
  node_riasecfn["RIASEC scoring<br/>[index.ts]"]
  node_recommendfn["Recommendation engine<br/>[index.ts]"]
  node_matchfn["Scholarship matching<br/>[index.ts]"]
  node_chatendpoint["Chat endpoint<br/>[chat.ts]"]
  node_gemini["Gemini service<br/>[gemini.ts]"]
  node_crawlertrigger["Crawl trigger<br/>[index.ts]"]
end

subgraph group_admin["Administration"]
  node_adminui["Admin operations<br/>[AdminHome.jsx]"]
  node_discoveryreview["Discovery review"]
end

subgraph group_scraper["Scholarship discovery"]
  node_scraperentry["Scraper runner<br/>[main.py]"]
  node_webdiscovery["Web discovery<br/>[discovery.py]"]
  node_search["Lead search<br/>[search.py]"]
  node_parsers["Provider parsers<br/>[base.py]"]
  node_monitor["Selected monitoring<br/>[monitor.py]"]
end

subgraph group_data["Identity and data"]
  node_auth["Auth provider<br/>[AuthContext.jsx]"]
  node_supabase["Supabase client<br/>[supabase.js]"]
  node_database[("Supabase database<br/>[db.py]")]
end

node_student(("Student"))

node_student -->|"opens"| node_routes
node_routes -->|"routes to"| node_profile
node_routes -->|"routes to"| node_assessment
node_routes -->|"routes to"| node_academic
node_routes -->|"routes to"| node_recommendations
node_routes -->|"routes to"| node_careers
node_routes -->|"routes to"| node_catalog
node_routes -->|"routes to"| node_scholarships
node_auth -->|"reads session"| node_supabase
node_auth -->|"loads profile"| node_supabase
node_chatui -->|"invokes"| node_api
node_api -->|"invokes functions"| node_supabase
node_assessment -.->|"requests scoring"| node_api
node_api -.->|"dispatches"| node_riasecfn
node_recommendations -.->|"requests results"| node_api
node_api -.->|"dispatches"| node_recommendfn
node_recommendations -.->|"requests matches"| node_api
node_api -.->|"dispatches"| node_matchfn
node_chatendpoint -.->|"calls"| node_gemini
node_adminui -->|"triggers crawl"| node_crawlertrigger
node_adminui -->|"loads operations"| node_supabase
node_discoveryreview -.->|"reviews records"| node_supabase
node_scraperentry -->|"runs discovery"| node_webdiscovery
node_scraperentry -->|"runs monitoring"| node_monitor
node_scraperentry -->|"uses database"| node_database
node_webdiscovery -->|"searches leads"| node_search
node_webdiscovery -->|"stages candidates"| node_database
node_monitor -->|"reads selected"| node_database
node_crawlertrigger -.->|"dispatches crawl"| node_scraperentry
node_chatui -->|"requests chat"| node_chatendpoint

click node_routes "https://github.com/kshrr/nexus/blob/main/src/routes.jsx"
click node_profile "https://github.com/kshrr/nexus/blob/main/src/pages/student/ProfileSetup.jsx"
click node_assessment "https://github.com/kshrr/nexus/blob/main/src/pages/student/RiasecAssessment.jsx"
click node_academic "https://github.com/kshrr/nexus/blob/main/src/pages/student/AcademicAnalysis.jsx"
click node_recommendations "https://github.com/kshrr/nexus/blob/main/src/pages/student/Recommendations.jsx"
click node_careers "https://github.com/kshrr/nexus/blob/main/src/pages/student/CareerDetail.jsx"
click node_catalog "https://github.com/kshrr/nexus/blob/main/src/pages/public/CourseList.jsx"
click node_scholarships "https://github.com/kshrr/nexus/blob/main/src/pages/public/ScholarshipList.jsx"
click node_chatui "https://github.com/kshrr/nexus/blob/main/src/hooks/useChat.js"
click node_auth "https://github.com/kshrr/nexus/blob/main/src/context/AuthContext.jsx"
click node_supabase "https://github.com/kshrr/nexus/blob/main/src/lib/supabase.js"
click node_api "https://github.com/kshrr/nexus/blob/main/src/lib/api.js"
click node_riasecfn "https://github.com/kshrr/nexus/blob/main/supabase/functions/score-riasec/index.ts"
click node_recommendfn "https://github.com/kshrr/nexus/blob/main/supabase/functions/recommend/index.ts"
click node_matchfn "https://github.com/kshrr/nexus/blob/main/supabase/functions/match-scholarship/index.ts"
click node_chatendpoint "https://github.com/kshrr/nexus/blob/main/api/chat.ts"
click node_gemini "https://github.com/kshrr/nexus/blob/main/supabase/functions/_shared/gemini.ts"
click node_adminui "https://github.com/kshrr/nexus/blob/main/src/pages/admin/AdminHome.jsx"
click node_discoveryreview "https://github.com/kshrr/nexus/blob/main/src/pages/admin/AdminScholarshipDiscovery.jsx"
click node_crawlertrigger "https://github.com/kshrr/nexus/blob/main/supabase/functions/trigger-crawl/index.ts"
click node_scraperentry "https://github.com/kshrr/nexus/blob/main/scraper/main.py"
click node_webdiscovery "https://github.com/kshrr/nexus/blob/main/scraper/discovery.py"
click node_search "https://github.com/kshrr/nexus/blob/main/scraper/search.py"
click node_parsers "https://github.com/kshrr/nexus/blob/main/scraper/parsers/base.py"
click node_monitor "https://github.com/kshrr/nexus/blob/main/scraper/monitor.py"
click node_database "https://github.com/kshrr/nexus/blob/main/scraper/db.py"

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_routes,node_profile,node_assessment,node_academic,node_recommendations,node_careers,node_catalog,node_scholarships,node_chatui toneBlue
class node_api,node_riasecfn,node_recommendfn,node_matchfn,node_chatendpoint,node_gemini,node_crawlertrigger toneAmber
class node_adminui,node_discoveryreview toneMint
class node_scraperentry,node_webdiscovery,node_search,node_parsers,node_monitor toneRose
class node_auth,node_supabase,node_database,node_student toneIndigo
```

## Components

### Student experience

- [Route tree](https://github.com/kshrr/nexus/blob/main/src/routes.jsx): `src/routes.jsx`
- [Profile setup](https://github.com/kshrr/nexus/blob/main/src/pages/student/ProfileSetup.jsx): `src/pages/student/ProfileSetup.jsx`
- [RIASEC assessment](https://github.com/kshrr/nexus/blob/main/src/pages/student/RiasecAssessment.jsx): `src/pages/student/RiasecAssessment.jsx`
- [Academic analysis](https://github.com/kshrr/nexus/blob/main/src/pages/student/AcademicAnalysis.jsx): `src/pages/student/AcademicAnalysis.jsx`
- [Recommendations](https://github.com/kshrr/nexus/blob/main/src/pages/student/Recommendations.jsx): `src/pages/student/Recommendations.jsx`
- [Career explorer](https://github.com/kshrr/nexus/blob/main/src/pages/student/CareerDetail.jsx): `src/pages/student/CareerDetail.jsx`
- [Course explorer](https://github.com/kshrr/nexus/blob/main/src/pages/public/CourseList.jsx): `src/pages/public/CourseList.jsx`
- [Scholarship explorer](https://github.com/kshrr/nexus/blob/main/src/pages/public/ScholarshipList.jsx): `src/pages/public/ScholarshipList.jsx`
- [Chat interface](https://github.com/kshrr/nexus/blob/main/src/hooks/useChat.js): `src/hooks/useChat.js`

### Application services

- [Function client](https://github.com/kshrr/nexus/blob/main/src/lib/api.js): `src/lib/api.js`
- [RIASEC scoring](https://github.com/kshrr/nexus/blob/main/supabase/functions/score-riasec/index.ts): `supabase/functions/score-riasec/index.ts`
- [Recommendation engine](https://github.com/kshrr/nexus/blob/main/supabase/functions/recommend/index.ts): `supabase/functions/recommend/index.ts`
- [Scholarship matching](https://github.com/kshrr/nexus/blob/main/supabase/functions/match-scholarship/index.ts): `supabase/functions/match-scholarship/index.ts`
- [Chat endpoint](https://github.com/kshrr/nexus/blob/main/api/chat.ts): `api/chat.ts`
- [Gemini service](https://github.com/kshrr/nexus/blob/main/supabase/functions/_shared/gemini.ts): `supabase/functions/_shared/gemini.ts`
- [Crawl trigger](https://github.com/kshrr/nexus/blob/main/supabase/functions/trigger-crawl/index.ts): `supabase/functions/trigger-crawl/index.ts`

### Administration

- [Admin operations](https://github.com/kshrr/nexus/blob/main/src/pages/admin/AdminHome.jsx): `src/pages/admin/AdminHome.jsx`
- [Discovery review](https://github.com/kshrr/nexus/blob/main/src/pages/admin/AdminScholarshipDiscovery.jsx): `src/pages/admin/AdminScholarshipDiscovery.jsx`

### Scholarship discovery

- [Scraper runner](https://github.com/kshrr/nexus/blob/main/scraper/main.py): `scraper/main.py`
- [Web discovery](https://github.com/kshrr/nexus/blob/main/scraper/discovery.py): `scraper/discovery.py`
- [Lead search](https://github.com/kshrr/nexus/blob/main/scraper/search.py): `scraper/search.py`
- [Provider parsers](https://github.com/kshrr/nexus/blob/main/scraper/parsers/base.py): `scraper/parsers/base.py`
- [Selected monitoring](https://github.com/kshrr/nexus/blob/main/scraper/monitor.py): `scraper/monitor.py`

### Identity and data

- [Auth provider](https://github.com/kshrr/nexus/blob/main/src/context/AuthContext.jsx): `src/context/AuthContext.jsx`
- [Supabase client](https://github.com/kshrr/nexus/blob/main/src/lib/supabase.js): `src/lib/supabase.js`
- [Supabase database](https://github.com/kshrr/nexus/blob/main/scraper/db.py): `scraper/db.py`

### Other components

- **Student**

## Connections

- Student → Route tree: opens (evidence: `src/routes.jsx`)
- Route tree → Profile setup: routes to (evidence: `src/routes.jsx`)
- Route tree → RIASEC assessment: routes to (evidence: `src/routes.jsx`)
- Route tree → Academic analysis: routes to (evidence: `src/routes.jsx`)
- Route tree → Recommendations: routes to (evidence: `src/routes.jsx`)
- Route tree → Career explorer: routes to (evidence: `src/routes.jsx`)
- Route tree → Course explorer: routes to (evidence: `src/routes.jsx`)
- Route tree → Scholarship explorer: routes to (evidence: `src/routes.jsx`)
- Auth provider → Supabase client: reads session (evidence: `src/context/AuthContext.jsx`)
- Auth provider → Supabase client: loads profile (evidence: `src/context/AuthContext.jsx`)
- Chat interface → Function client: invokes (evidence: `src/hooks/useChat.js`)
- Function client → Supabase client: invokes functions (evidence: `src/lib/api.js`)
- RIASEC assessment → Function client: requests scoring
- Function client → RIASEC scoring: dispatches
- Recommendations → Function client: requests results
- Function client → Recommendation engine: dispatches
- Recommendations → Function client: requests matches
- Function client → Scholarship matching: dispatches
- Chat endpoint → Gemini service: calls (evidence: `api/chat.ts`)
- Admin operations → Crawl trigger: triggers crawl
- Admin operations → Supabase client: loads operations
- Discovery review → Supabase client: reviews records
- Scraper runner → Web discovery: runs discovery (evidence: `scraper/main.py`)
- Scraper runner → Selected monitoring: runs monitoring (evidence: `scraper/main.py`)
- Scraper runner → Supabase database: uses database (evidence: `scraper/main.py`)
- Web discovery → Lead search: searches leads (evidence: `scraper/discovery.py`)
- Web discovery → Supabase database: stages candidates (evidence: `scraper/discovery.py`)
- Selected monitoring → Supabase database: reads selected (evidence: `scraper/monitor.py`)
- Crawl trigger → Scraper runner: dispatches crawl
- Chat interface → Chat endpoint: requests chat (evidence: `README.md`)
