# amarm0t/diu-cgpa-calculator architecture

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

- Interactive diagram: https://gitdiagram.com/amarm0t/diu-cgpa-calculator
- Repository: https://github.com/amarm0t/diu-cgpa-calculator

## Overview

DIU Student Portal is a full-stack transcript lookup and CGPA platform. A student submits portal credentials in the Next.js app; FastAPI manages the streamed lookup, queue and scraper, which retrieves transcript data, calculates results and caches them for display. The admin panel provides Google-authenticated oversight of records, cache and queue activity, with an alternate password sign-in path. The README documents capabilities such as CAPTCHA relay and progressive semester streaming; some implementation details are unsampled, so the graph limits those links to documented or indexed relationships.

Main entry points: [`backend/app.py`](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/app.py) (FastAPI endpoints), [`backend/scraper.py`](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/scraper.py) (Portal scraper), [`frontend/src/app/page.tsx`](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/page.tsx) (Lookup interface), [`backend/db.py`](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/db.py) (Result cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student frontend"]
  node_portal_ui["Lookup interface<br/>[page.tsx]"]
  node_transcript_view["Transcript display<br/>[transcript.ts]"]
  node_session["Session wrapper<br/>[SessionWrapper.tsx]"]
end

subgraph group_service["Lookup service"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_queue["Scrape queue<br/>[queue_manager.py]"]
  node_scraper["Portal scraper<br/>[scraper.py]"]
  node_browser_pool["Browser pool<br/>[browser_pool.py]"]
  node_captcha_relay["CAPTCHA relay<br/>[scraper.py]"]
  node_calculator["CGPA calculator<br/>[cgpa_calculator.py]"]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin panel<br/>[page.tsx]"]
  node_oauth_route["Google OAuth<br/>[route.ts]"]
  node_google_auth["Admin token checks<br/>[auth.py]"]
  node_password_auth["Admin password auth<br/>[admin_auth.py]"]
end

subgraph group_storage["Data storage"]
  node_student_data[("Result cache<br/>[db.py]")]
  node_history[("Task history<br/>[task_history.py]")]
  node_supabase[("Supabase")]
  node_sqlite[("SQLite fallback")]
  node_history_db[("History SQLite")]
end

node_student(("Student"))
node_google["Google identity"]

node_student -->|"submits credentials"| node_portal_ui
node_portal_ui -->|"requests streamed lookup"| node_api
node_api -->|"allocates slots"| node_queue
node_api -->|"starts lookup"| node_scraper
node_scraper -->|"uses browsers"| node_browser_pool
node_scraper -->|"relays clicks"| node_captcha_relay
node_api -->|"dispatches clicks"| node_captcha_relay
node_scraper -->|"calculates GPA"| node_calculator
node_scraper -->|"reads and caches"| node_student_data
node_api -->|"checks settings"| node_student_data
node_api -->|"records task outcomes"| node_history
node_api -->|"checks admin identity"| node_google_auth
node_api -->|"handles password sign-in"| node_password_auth
node_admin_ui -->|"requests admin actions"| node_api
node_oauth_route -->|"authenticates and refreshes"| node_google
node_session -.->|"uses sessions"| node_oauth_route
node_portal_ui -.->|"renders results"| node_transcript_view
node_scraper -->|"streams semester results"| node_portal_ui
node_student_data -->|"uses cloud database"| node_supabase
node_student_data -->|"falls back locally"| node_sqlite
node_history -->|"stores task records"| node_history_db

click node_portal_ui "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/page.tsx"
click node_transcript_view "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/lib/transcript.ts"
click node_admin_ui "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/admin/page.tsx"
click node_session "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/components/SessionWrapper.tsx"
click node_oauth_route "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/api/auth/%5B...nextauth%5D/route.ts"
click node_api "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/app.py"
click node_queue "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/queue_manager.py"
click node_scraper "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/scraper.py"
click node_browser_pool "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/browser_pool.py"
click node_captcha_relay "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/scraper.py"
click node_calculator "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/cgpa_calculator.py"
click node_google_auth "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/auth.py"
click node_password_auth "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/admin_auth.py"
click node_student_data "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/db.py"
click node_history "https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/task_history.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_portal_ui,node_transcript_view,node_session toneBlue
class node_api,node_queue,node_scraper,node_browser_pool,node_captcha_relay,node_calculator toneAmber
class node_admin_ui,node_oauth_route,node_google_auth,node_password_auth toneMint
class node_student_data,node_history,node_supabase,node_sqlite,node_history_db toneRose
class node_student,node_google toneIndigo
```

## Components

### Student frontend

- [Lookup interface](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Transcript display](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/lib/transcript.ts): `frontend/src/lib/transcript.ts`
- [Session wrapper](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/components/SessionWrapper.tsx): `frontend/src/components/SessionWrapper.tsx`

### Lookup service

- [FastAPI endpoints](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/app.py): `backend/app.py`
- [Scrape queue](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/queue_manager.py): `backend/queue_manager.py`
- [Portal scraper](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/scraper.py): `backend/scraper.py`
- [Browser pool](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/browser_pool.py): `backend/browser_pool.py`
- [CAPTCHA relay](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/scraper.py): `backend/scraper.py`
- [CGPA calculator](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/cgpa_calculator.py): `backend/cgpa_calculator.py`

### Administration

- [Admin panel](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/admin/page.tsx): `frontend/src/app/admin/page.tsx`
- [Google OAuth](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/frontend/src/app/api/auth/%5B...nextauth%5D/route.ts): `frontend/src/app/api/auth/[...nextauth]/route.ts`
- [Admin token checks](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/auth.py): `backend/auth.py`
- [Admin password auth](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/admin_auth.py): `backend/admin_auth.py`

### Data storage

- [Result cache](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/db.py): `backend/db.py`
- [Task history](https://github.com/amarm0t/diu-cgpa-calculator/blob/main/backend/task_history.py): `backend/task_history.py`
- **Supabase**
- **SQLite fallback**
- **History SQLite**

### Other components

- **Student**
- **Google identity**

## Connections

- Student → Lookup interface: submits credentials (evidence: `README.md`)
- Lookup interface → FastAPI endpoints: requests streamed lookup (evidence: `README.md`)
- FastAPI endpoints → Scrape queue: allocates slots (evidence: `backend/app.py`)
- FastAPI endpoints → Portal scraper: starts lookup (evidence: `backend/app.py`)
- Portal scraper → Browser pool: uses browsers (evidence: `backend/scraper.py`)
- Portal scraper → CAPTCHA relay: relays clicks (evidence: `backend/scraper.py`)
- FastAPI endpoints → CAPTCHA relay: dispatches clicks (evidence: `backend/app.py`)
- Portal scraper → CGPA calculator: calculates GPA (evidence: `backend/scraper.py`)
- Portal scraper → Result cache: reads and caches (evidence: `backend/scraper.py`)
- FastAPI endpoints → Result cache: checks settings (evidence: `backend/app.py`)
- FastAPI endpoints → Task history: records task outcomes (evidence: `backend/app.py`)
- FastAPI endpoints → Admin token checks: checks admin identity (evidence: `backend/app.py`)
- FastAPI endpoints → Admin password auth: handles password sign-in (evidence: `backend/app.py`)
- Admin panel → FastAPI endpoints: requests admin actions (evidence: `README.md`)
- Google OAuth → Google identity: authenticates and refreshes (evidence: `frontend/src/app/api/auth/[...nextauth]/route.ts`)
- Session wrapper → Google OAuth: uses sessions
- Lookup interface → Transcript display: renders results
- Portal scraper → Lookup interface: streams semester results (evidence: `README.md`)
- Result cache → Supabase: uses cloud database (evidence: `README.md`)
- Result cache → SQLite fallback: falls back locally (evidence: `README.md`)
- Task history → History SQLite: stores task records (evidence: `backend/task_history.py`)