# i0bz/grade_tracker_site architecture

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

- Interactive diagram: https://gitdiagram.com/i0bz/grade_tracker_site
- Repository: https://github.com/i0bz/grade_tracker_site

## Overview

This is a grade-tracking web application: users register or log in, select catalog subjects, assign grading weights, record activities and scores, then view calculated subject grades. FastAPI serves the pages and API; TypeScript pages call the API, and backend handlers query MySQL through a shared session dependency. The grade calculation is a distinct domain stage in the user-subject API. Frontend dashboard and authentication-page behavior is represented from the tree, but their API wiring is not verified in the excerpts.

Main entry points: [`api/router.py`](https://github.com/i0bz/grade_tracker_site/blob/master/api/router.py) (API router), [`database.py`](https://github.com/i0bz/grade_tracker_site/blob/master/database.py) (DB sessions), [`api/auth.py`](https://github.com/i0bz/grade_tracker_site/blob/master/api/auth.py) (Authentication), [`frontend/src/utils.ts`](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/utils.ts) (Session helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app["Page server<br/>[main.py]"]
  node_landing["Entry redirect<br/>[index.ts]"]
  node_authpages["Account pages<br/>[login.ts]"]
  node_dashboard["Grade dashboard<br/>[dashboard.ts]"]
  node_subjectui["Subject management<br/>[subjects.ts]"]
  node_editui["Subject editor<br/>[edit.ts]"]
  node_sessionutils["Session helpers<br/>[utils.ts]"]
end

subgraph group_api["API routing"]
  node_router["API router<br/>[router.py]"]
end

subgraph group_domain["Grade domain"]
  node_auth["Authentication<br/>[auth.py]"]
  node_users["User operations<br/>[users.py]"]
  node_catalog["Subject catalog<br/>[subjects.py]"]
  node_usercourses["User subjects<br/>[user_subjects.py]"]
  node_grades["Grade calculation<br/>[user_subjects.py]"]
  node_activities["Activities<br/>[activities.py]"]
end

subgraph group_data["Persistence"]
  node_dbsession["DB sessions<br/>[database.py]"]
  node_mysql[("MySQL store")]
end

node_visitor(("User"))

node_visitor -->|"opens pages"| node_app
node_app -->|"mounts API"| node_router
node_visitor -.->|"starts at"| node_landing
node_landing -->|"reads session"| node_sessionutils
node_authpages -.->|"uses session"| node_sessionutils
node_dashboard -.->|"uses session"| node_sessionutils
node_subjectui -->|"builds requests"| node_sessionutils
node_editui -->|"builds requests"| node_sessionutils
node_landing -.->|"redirects pages"| node_app
node_authpages -.->|"calls account API"| node_router
node_dashboard -.->|"requests grades"| node_router
node_subjectui -->|"requests subjects"| node_router
node_editui -->|"requests edits"| node_router
node_router -->|"registers routes"| node_auth
node_router -->|"registers routes"| node_users
node_router -->|"registers routes"| node_catalog
node_router -->|"registers routes"| node_usercourses
node_router -->|"registers routes"| node_activities
node_auth -->|"gets session"| node_dbsession
node_users -->|"checks token"| node_auth
node_users -->|"gets session"| node_dbsession
node_catalog -->|"gets session"| node_dbsession
node_usercourses -->|"checks token"| node_auth
node_usercourses -->|"gets session"| node_dbsession
node_activities -->|"checks token"| node_auth
node_activities -->|"gets session"| node_dbsession
node_grades -->|"reads scores"| node_mysql
node_dbsession -->|"opens connection"| node_mysql

click node_app "https://github.com/i0bz/grade_tracker_site/blob/master/main.py"
click node_landing "https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/index.ts"
click node_authpages "https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/login.ts"
click node_dashboard "https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/dashboard.ts"
click node_subjectui "https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/subjects.ts"
click node_editui "https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/edit.ts"
click node_sessionutils "https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/utils.ts"
click node_router "https://github.com/i0bz/grade_tracker_site/blob/master/api/router.py"
click node_auth "https://github.com/i0bz/grade_tracker_site/blob/master/api/auth.py"
click node_users "https://github.com/i0bz/grade_tracker_site/blob/master/api/users.py"
click node_catalog "https://github.com/i0bz/grade_tracker_site/blob/master/api/subjects.py"
click node_usercourses "https://github.com/i0bz/grade_tracker_site/blob/master/api/user_subjects.py"
click node_grades "https://github.com/i0bz/grade_tracker_site/blob/master/api/user_subjects.py"
click node_activities "https://github.com/i0bz/grade_tracker_site/blob/master/api/activities.py"
click node_dbsession "https://github.com/i0bz/grade_tracker_site/blob/master/database.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_app,node_landing,node_authpages,node_dashboard,node_subjectui,node_editui,node_sessionutils,node_visitor toneBlue
class node_router toneAmber
class node_auth,node_users,node_catalog,node_usercourses,node_grades,node_activities toneMint
class node_dbsession,node_mysql toneRose
```

## Components

### Web app

- [Page server](https://github.com/i0bz/grade_tracker_site/blob/master/main.py): `main.py`
- [Entry redirect](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/index.ts): `frontend/src/index.ts`
- [Account pages](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/login.ts): `frontend/src/login.ts`
- [Grade dashboard](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/dashboard.ts): `frontend/src/dashboard.ts`
- [Subject management](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/subjects.ts): `frontend/src/subjects.ts`
- [Subject editor](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/edit.ts): `frontend/src/edit.ts`
- [Session helpers](https://github.com/i0bz/grade_tracker_site/blob/master/frontend/src/utils.ts): `frontend/src/utils.ts`

### API routing

- [API router](https://github.com/i0bz/grade_tracker_site/blob/master/api/router.py): `api/router.py`

### Grade domain

- [Authentication](https://github.com/i0bz/grade_tracker_site/blob/master/api/auth.py): `api/auth.py`
- [User operations](https://github.com/i0bz/grade_tracker_site/blob/master/api/users.py): `api/users.py`
- [Subject catalog](https://github.com/i0bz/grade_tracker_site/blob/master/api/subjects.py): `api/subjects.py`
- [User subjects](https://github.com/i0bz/grade_tracker_site/blob/master/api/user_subjects.py): `api/user_subjects.py`
- [Grade calculation](https://github.com/i0bz/grade_tracker_site/blob/master/api/user_subjects.py): `api/user_subjects.py`
- [Activities](https://github.com/i0bz/grade_tracker_site/blob/master/api/activities.py): `api/activities.py`

### Persistence

- [DB sessions](https://github.com/i0bz/grade_tracker_site/blob/master/database.py): `database.py`
- **MySQL store**

### Other components

- **User**

## Connections

- User → Page server: opens pages (evidence: `main.py`)
- Page server → API router: mounts API (evidence: `main.py`)
- User → Entry redirect: starts at
- Entry redirect → Session helpers: reads session (evidence: `frontend/src/index.ts`)
- Account pages → Session helpers: uses session (evidence: `frontend/src/login.ts`)
- Grade dashboard → Session helpers: uses session (evidence: `frontend/src/dashboard.ts`)
- Subject management → Session helpers: builds requests (evidence: `frontend/src/subjects.ts`)
- Subject editor → Session helpers: builds requests (evidence: `frontend/src/edit.ts`)
- Entry redirect → Page server: redirects pages
- Account pages → API router: calls account API
- Grade dashboard → API router: requests grades
- Subject management → API router: requests subjects (evidence: `frontend/src/subjects.ts`)
- Subject editor → API router: requests edits (evidence: `frontend/src/edit.ts`)
- API router → Authentication: registers routes (evidence: `api/router.py`)
- API router → User operations: registers routes (evidence: `api/router.py`)
- API router → Subject catalog: registers routes (evidence: `api/router.py`)
- API router → User subjects: registers routes (evidence: `api/router.py`)
- API router → Activities: registers routes (evidence: `api/router.py`)
- Authentication → DB sessions: gets session (evidence: `api/auth.py`)
- User operations → Authentication: checks token (evidence: `api/users.py`)
- User operations → DB sessions: gets session (evidence: `api/users.py`)
- Subject catalog → DB sessions: gets session (evidence: `api/subjects.py`)
- User subjects → Authentication: checks token (evidence: `api/user_subjects.py`)
- User subjects → DB sessions: gets session (evidence: `api/user_subjects.py`)
- Activities → Authentication: checks token (evidence: `api/activities.py`)
- Activities → DB sessions: gets session (evidence: `api/activities.py`)
- Grade calculation → MySQL store: reads scores (evidence: `api/user_subjects.py`)
- DB sessions → MySQL store: opens connection (evidence: `database.py`)
