# jiteshck/campusassist architecture

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

- Interactive diagram: https://gitdiagram.com/jiteshck/campusassist
- Repository: https://github.com/jiteshck/campusassist

## Overview

CampusAssist is a student-service portal whose main workflow takes university PDFs through extraction and chunking into a searchable knowledge base, then retrieves cited context for student questions and generates grounded answers. The portal also provides authentication, document administration, and attendance tools. The graph combines README-documented capabilities with relationships visible in the supplied excerpts and source index; unsampled implementation details are not treated as inspected.

Main entry points: [`backend/main.py`](https://github.com/jiteshck/campusassist/blob/main/backend/main.py) (FastAPI endpoints), [`frontend/src/App.jsx`](https://github.com/jiteshck/campusassist/blob/main/frontend/src/App.jsx) (Student portal), [`backend/vector_store.py`](https://github.com/jiteshck/campusassist/blob/main/backend/vector_store.py) (Vector retrieval), [`backend/index_chunks.py`](https://github.com/jiteshck/campusassist/blob/main/backend/index_chunks.py) (Chunk indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Document ingestion"]
  node_pdfs["University PDFs"]
  node_extract["PDF extraction and OCR<br/>[pipeline.py]"]
  node_chunk["Page-aware chunking<br/>[chunking.py]"]
  node_chunkdata["Chunk dataset<br/>[core_chunks.jsonl]"]
  node_adminupload["Admin upload processing<br/>[main.py]"]
end

subgraph group_rag["Knowledge and answers"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_embed["Text embeddings<br/>[embeddings.py]"]
  node_indexer["Chunk indexing<br/>[index_chunks.py]"]
  node_vector["Vector retrieval<br/>[vector_store.py]"]
  node_vectordb[("Supabase pgvector")]
  node_answer["Grounded answer generation<br/>[generator.py]"]
  node_gemini["Google Gemini"]
end

subgraph group_identity["Authentication"]
  node_authui["Sign-in and signup<br/>[AuthPage.jsx]"]
  node_authapi["Auth endpoints<br/>[main.py]"]
  node_users[("User accounts<br/>[user_table.sql]")]
  node_brevo["Brevo email"]
  node_googleoauth["Google OAuth"]
end

subgraph group_attendance["Attendance services"]
  node_attendanceui["Attendance calculator"]
  node_attendanceapi["Timetable and attendance API<br/>[main.py]"]
  node_attendance_db[("Attendance tables")]
  node_reminders["Attendance reminders<br/>[main.py]"]
end

subgraph group_portal["Student and admin portal"]
  node_app["Student portal<br/>[App.jsx]"]
  node_adminui["Knowledge base admin<br/>[AdminBoard.jsx]"]
end

node_student(("Student"))
node_staff(("Staff admin"))
node_browser(("Browser user"))

node_pdfs -->|"provides PDFs"| node_extract
node_extract -->|"feeds records"| node_chunk
node_chunk -->|"writes chunks"| node_chunkdata
node_chunkdata -->|"indexes dataset"| node_indexer
node_indexer -->|"embeds text"| node_embed
node_indexer -->|"upserts chunks"| node_vector
node_vector -->|"writes and searches"| node_vectordb
node_browser -->|"opens portal"| node_app
node_app -->|"renders sign-in"| node_authui
node_authui -->|"submits signup and OTP"| node_authapi
node_authapi -->|"persists accounts"| node_users
node_authapi -->|"sends verification"| node_brevo
node_authui -->|"supports OAuth"| node_googleoauth
node_app -->|"sends chat requests"| node_api
node_api -->|"embeds query"| node_embed
node_api -->|"retrieves chunks"| node_vector
node_api -->|"generates response"| node_answer
node_answer -->|"requests generation"| node_gemini
node_adminui -->|"uploads documents"| node_api
node_api -->|"extracts uploaded PDF"| node_extract
node_api -->|"chunks extracted record"| node_chunk
node_api -.->|"embeds uploaded chunks"| node_embed
node_api -.->|"indexes uploaded chunks"| node_vector
node_app -->|"renders calculator"| node_attendanceui
node_attendanceui -->|"manages attendance"| node_attendanceapi
node_attendanceapi -->|"reads and writes"| node_attendance_db
node_attendanceapi -.->|"schedules reminders"| node_reminders
node_reminders -.->|"sends reminders"| node_brevo

click node_pdfs "https://github.com/jiteshck/campusassist/tree/main/data/raw"
click node_extract "https://github.com/jiteshck/campusassist/blob/main/campusassist_ingestion/pipeline.py"
click node_chunk "https://github.com/jiteshck/campusassist/blob/main/campusassist_ingestion/chunking.py"
click node_chunkdata "https://github.com/jiteshck/campusassist/blob/main/data/chunks/core_chunks.jsonl"
click node_adminupload "https://github.com/jiteshck/campusassist/blob/main/backend/main.py"
click node_api "https://github.com/jiteshck/campusassist/blob/main/backend/main.py"
click node_embed "https://github.com/jiteshck/campusassist/blob/main/backend/embeddings.py"
click node_indexer "https://github.com/jiteshck/campusassist/blob/main/backend/index_chunks.py"
click node_vector "https://github.com/jiteshck/campusassist/blob/main/backend/vector_store.py"
click node_vectordb "https://github.com/jiteshck/campusassist/blob/main/database/migrations/001_document_chunks.sql"
click node_answer "https://github.com/jiteshck/campusassist/blob/main/backend/generator.py"
click node_authui "https://github.com/jiteshck/campusassist/blob/main/frontend/src/components/layout/AuthPage.jsx"
click node_authapi "https://github.com/jiteshck/campusassist/blob/main/backend/main.py"
click node_users "https://github.com/jiteshck/campusassist/blob/main/database/migrations/user_table.sql"
click node_attendanceui "https://github.com/jiteshck/campusassist/blob/main/frontend/src/pages/AttendanceCalculator.tsx"
click node_attendanceapi "https://github.com/jiteshck/campusassist/blob/main/backend/main.py"
click node_attendance_db "https://github.com/jiteshck/campusassist/blob/main/database/migrations/002_timetable_attendance.sql"
click node_reminders "https://github.com/jiteshck/campusassist/blob/main/backend/main.py"
click node_app "https://github.com/jiteshck/campusassist/blob/main/frontend/src/App.jsx"
click node_adminui "https://github.com/jiteshck/campusassist/blob/main/frontend/src/pages/AdminBoard.jsx"

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_pdfs,node_extract,node_chunk,node_chunkdata,node_adminupload,node_browser toneBlue
class node_api,node_embed,node_indexer,node_vector,node_vectordb,node_answer,node_gemini toneAmber
class node_authui,node_authapi,node_users,node_brevo,node_googleoauth toneMint
class node_attendanceui,node_attendanceapi,node_attendance_db,node_reminders toneRose
class node_app,node_adminui,node_student,node_staff toneIndigo
```

## Components

### Document ingestion

- [University PDFs](https://github.com/jiteshck/campusassist/tree/main/data/raw): `data/raw`
- [PDF extraction and OCR](https://github.com/jiteshck/campusassist/blob/main/campusassist_ingestion/pipeline.py): `campusassist_ingestion/pipeline.py`
- [Page-aware chunking](https://github.com/jiteshck/campusassist/blob/main/campusassist_ingestion/chunking.py): `campusassist_ingestion/chunking.py`
- [Chunk dataset](https://github.com/jiteshck/campusassist/blob/main/data/chunks/core_chunks.jsonl): `data/chunks/core_chunks.jsonl`
- [Admin upload processing](https://github.com/jiteshck/campusassist/blob/main/backend/main.py): `backend/main.py`

### Knowledge and answers

- [FastAPI endpoints](https://github.com/jiteshck/campusassist/blob/main/backend/main.py): `backend/main.py`
- [Text embeddings](https://github.com/jiteshck/campusassist/blob/main/backend/embeddings.py): `backend/embeddings.py`
- [Chunk indexing](https://github.com/jiteshck/campusassist/blob/main/backend/index_chunks.py): `backend/index_chunks.py`
- [Vector retrieval](https://github.com/jiteshck/campusassist/blob/main/backend/vector_store.py): `backend/vector_store.py`
- [Supabase pgvector](https://github.com/jiteshck/campusassist/blob/main/database/migrations/001_document_chunks.sql): `database/migrations/001_document_chunks.sql`
- [Grounded answer generation](https://github.com/jiteshck/campusassist/blob/main/backend/generator.py): `backend/generator.py`
- **Google Gemini**

### Authentication

- [Sign-in and signup](https://github.com/jiteshck/campusassist/blob/main/frontend/src/components/layout/AuthPage.jsx): `frontend/src/components/layout/AuthPage.jsx`
- [Auth endpoints](https://github.com/jiteshck/campusassist/blob/main/backend/main.py): `backend/main.py`
- [User accounts](https://github.com/jiteshck/campusassist/blob/main/database/migrations/user_table.sql): `database/migrations/user_table.sql`
- **Brevo email**
- **Google OAuth**

### Attendance services

- [Attendance calculator](https://github.com/jiteshck/campusassist/blob/main/frontend/src/pages/AttendanceCalculator.tsx): `frontend/src/pages/AttendanceCalculator.tsx`
- [Timetable and attendance API](https://github.com/jiteshck/campusassist/blob/main/backend/main.py): `backend/main.py`
- [Attendance tables](https://github.com/jiteshck/campusassist/blob/main/database/migrations/002_timetable_attendance.sql): `database/migrations/002_timetable_attendance.sql`
- [Attendance reminders](https://github.com/jiteshck/campusassist/blob/main/backend/main.py): `backend/main.py`

### Student and admin portal

- [Student portal](https://github.com/jiteshck/campusassist/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Knowledge base admin](https://github.com/jiteshck/campusassist/blob/main/frontend/src/pages/AdminBoard.jsx): `frontend/src/pages/AdminBoard.jsx`

### Other components

- **Student**
- **Staff admin**
- **Browser user**

## Connections

- University PDFs → PDF extraction and OCR: provides PDFs (evidence: `README.md`)
- PDF extraction and OCR → Page-aware chunking: feeds records (evidence: `README.md`)
- Page-aware chunking → Chunk dataset: writes chunks (evidence: `README.md`)
- Chunk dataset → Chunk indexing: indexes dataset (evidence: `README.md`)
- Chunk indexing → Text embeddings: embeds text (evidence: `backend/index_chunks.py`)
- Chunk indexing → Vector retrieval: upserts chunks (evidence: `backend/index_chunks.py`)
- Vector retrieval → Supabase pgvector: writes and searches (evidence: `backend/vector_store.py`)
- Browser user → Student portal: opens portal (evidence: `README.md`)
- Student portal → Sign-in and signup: renders sign-in (evidence: `frontend/src/App.jsx`)
- Sign-in and signup → Auth endpoints: submits signup and OTP (evidence: `frontend/src/components/layout/AuthPage.jsx`)
- Auth endpoints → User accounts: persists accounts (evidence: `README.md`)
- Auth endpoints → Brevo email: sends verification (evidence: `README.md`)
- Sign-in and signup → Google OAuth: supports OAuth (evidence: `README.md`)
- Student portal → FastAPI endpoints: sends chat requests (evidence: `README.md`)
- FastAPI endpoints → Text embeddings: embeds query (evidence: `backend/main.py`)
- FastAPI endpoints → Vector retrieval: retrieves chunks (evidence: `README.md`)
- FastAPI endpoints → Grounded answer generation: generates response (evidence: `README.md`)
- Grounded answer generation → Google Gemini: requests generation (evidence: `backend/generator.py`)
- Knowledge base admin → FastAPI endpoints: uploads documents (evidence: `frontend/src/pages/AdminBoard.jsx`)
- FastAPI endpoints → PDF extraction and OCR: extracts uploaded PDF (evidence: `backend/main.py`)
- FastAPI endpoints → Page-aware chunking: chunks extracted record (evidence: `backend/main.py`)
- FastAPI endpoints → Text embeddings: embeds uploaded chunks (evidence: `backend/main.py`)
- FastAPI endpoints → Vector retrieval: indexes uploaded chunks (evidence: `backend/main.py`)
- Student portal → Attendance calculator: renders calculator (evidence: `frontend/src/App.jsx`)
- Attendance calculator → Timetable and attendance API: manages attendance (evidence: `README.md`)
- Timetable and attendance API → Attendance tables: reads and writes (evidence: `README.md`)
- Timetable and attendance API → Attendance reminders: schedules reminders (evidence: `backend/main.py`)
- Attendance reminders → Brevo email: sends reminders