# linaslabs/gradepilot architecture

> Architecture diagram of the GitHub repository linaslabs/gradepilot, 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/linaslabs/gradepilot
- Repository: https://github.com/linaslabs/gradepilot

## Overview

GradePilot is a student-facing academic progress tracker. Students register or sign in, complete degree onboarding, then view their dashboard and manage academic years, modules, and assignments; the Pilot feature calculates grade progress and predictions. The client routes and server API are visible, and sampled controllers show persistence through Prisma. The README documents the product capabilities, but client-to-API calls and the Pilot calculation’s runtime integration were not shown, so those links are left unverified.

Main entry points: [`grade-pilot-client/src/App.tsx`](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/App.tsx) (Application router), [`grade-pilot-server/src/routes/apiRouter.js`](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/apiRouter.js) (API dispatcher), [`grade-pilot-server/src/lib/prisma.js`](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/lib/prisma.js) (PostgreSQL via Prisma), [`grade-pilot-server/src/app.js`](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/app.js) (Express application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Application router<br/>[App.tsx]"]
  node_authstate["Auth state<br/>[AuthContext.tsx]"]
  node_login["Login and registration<br/>[Login.tsx]"]
  node_onboarding["Degree onboarding<br/>[Onboarding.tsx]"]
  node_dashboard["Dashboard shell"]
  node_settings["User settings<br/>[Settings.tsx]"]
end

subgraph group_academic["Academic tracking"]
  node_overview["Year overview<br/>[Overview.tsx]"]
  node_yeardetails["Year details<br/>[YearDetails.tsx]"]
  node_academicui["Academic editors"]
  node_pilot["Grade Pilot<br/>[calculations.tsx]"]
  node_degreecontroller["Degree management"]
  node_yearcontroller["Academic year management"]
  node_modulecontroller["Module management"]
  node_assignmentcontroller["Assignment management"]
end

subgraph group_server["API and security"]
  node_api["Express application<br/>[app.js]"]
  node_apiroot["API dispatcher<br/>[apiRouter.js]"]
  node_authroutes["Authentication routes<br/>[authRouter.js]"]
  node_authcontroller["Authentication service<br/>[authControllers.js]"]
  node_degreeroutes["Degree routes<br/>[degreeRouter.js]"]
end

subgraph group_data["Persistence and calculations"]
  node_database[("PostgreSQL via Prisma<br/>[prisma.js]")]
end

node_student(("Student"))

node_student -->|"uses"| node_app
node_app -->|"provides auth"| node_authstate
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_onboarding
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_overview
node_app -->|"routes to"| node_yeardetails
node_app -->|"routes to"| node_settings
node_student -->|"authenticates"| node_login
node_student -->|"enters degree"| node_onboarding
node_student -->|"manages records"| node_academicui
node_student -->|"checks predictions"| node_pilot
node_api -->|"mounts API"| node_apiroot
node_apiroot -->|"dispatches auth"| node_authroutes
node_apiroot -->|"dispatches degree"| node_degreeroutes
node_apiroot -.->|"dispatches year"| node_yearcontroller
node_apiroot -.->|"dispatches modules"| node_modulecontroller
node_apiroot -.->|"dispatches assignments"| node_assignmentcontroller
node_authroutes -->|"routes to"| node_authcontroller
node_degreeroutes -->|"routes to"| node_degreecontroller
node_authcontroller -->|"reads and writes"| node_database
node_degreecontroller -->|"reads and writes"| node_database
node_yearcontroller -->|"reads and writes"| node_database
node_modulecontroller -->|"reads and writes"| node_database
node_assignmentcontroller -->|"reads and writes"| node_database
node_onboarding -.->|"submits degree"| node_api
node_login -.->|"sends credentials"| node_api
node_yeardetails -.->|"loads year data"| node_api

click node_app "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/App.tsx"
click node_authstate "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/contexts/AuthContext.tsx"
click node_login "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Login.tsx"
click node_onboarding "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Onboarding.tsx"
click node_dashboard "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/DashboardLayout.tsx"
click node_overview "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Overview.tsx"
click node_yeardetails "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/YearDetails.tsx"
click node_settings "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Settings.tsx"
click node_academicui "https://github.com/linaslabs/gradepilot/tree/main/grade-pilot-client/src/components/ui"
click node_pilot "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/utils/calculations.tsx"
click node_api "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/app.js"
click node_apiroot "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/apiRouter.js"
click node_authroutes "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/authRouter.js"
click node_authcontroller "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/authControllers.js"
click node_degreeroutes "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/degreeRouter.js"
click node_degreecontroller "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/degreeControllers.js"
click node_yearcontroller "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/academicYearControllers.js"
click node_modulecontroller "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/moduleControllers.js"
click node_assignmentcontroller "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/assignmentControllers.js"
click node_database "https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/lib/prisma.js"

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_authstate,node_login,node_onboarding,node_dashboard,node_settings toneBlue
class node_overview,node_yeardetails,node_academicui,node_pilot,node_degreecontroller,node_yearcontroller,node_modulecontroller,node_assignmentcontroller toneAmber
class node_api,node_apiroot,node_authroutes,node_authcontroller,node_degreeroutes toneMint
class node_database toneRose
class node_student toneIndigo
```

## Components

### Client experience

- [Application router](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/App.tsx): `grade-pilot-client/src/App.tsx`
- [Auth state](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/contexts/AuthContext.tsx): `grade-pilot-client/src/contexts/AuthContext.tsx`
- [Login and registration](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Login.tsx): `grade-pilot-client/src/pages/Login.tsx`
- [Degree onboarding](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Onboarding.tsx): `grade-pilot-client/src/pages/Onboarding.tsx`
- [Dashboard shell](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/DashboardLayout.tsx): `grade-pilot-client/src/pages/DashboardLayout.tsx`
- [User settings](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Settings.tsx): `grade-pilot-client/src/pages/Settings.tsx`

### Academic tracking

- [Year overview](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/Overview.tsx): `grade-pilot-client/src/pages/Overview.tsx`
- [Year details](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/pages/YearDetails.tsx): `grade-pilot-client/src/pages/YearDetails.tsx`
- [Academic editors](https://github.com/linaslabs/gradepilot/tree/main/grade-pilot-client/src/components/ui): `grade-pilot-client/src/components/ui`
- [Grade Pilot](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-client/src/utils/calculations.tsx): `grade-pilot-client/src/utils/calculations.tsx`
- [Degree management](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/degreeControllers.js): `grade-pilot-server/src/controllers/degreeControllers.js`
- [Academic year management](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/academicYearControllers.js): `grade-pilot-server/src/controllers/academicYearControllers.js`
- [Module management](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/moduleControllers.js): `grade-pilot-server/src/controllers/moduleControllers.js`
- [Assignment management](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/assignmentControllers.js): `grade-pilot-server/src/controllers/assignmentControllers.js`

### API and security

- [Express application](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/app.js): `grade-pilot-server/src/app.js`
- [API dispatcher](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/apiRouter.js): `grade-pilot-server/src/routes/apiRouter.js`
- [Authentication routes](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/authRouter.js): `grade-pilot-server/src/routes/authRouter.js`
- [Authentication service](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/controllers/authControllers.js): `grade-pilot-server/src/controllers/authControllers.js`
- [Degree routes](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/routes/degreeRouter.js): `grade-pilot-server/src/routes/degreeRouter.js`

### Persistence and calculations

- [PostgreSQL via Prisma](https://github.com/linaslabs/gradepilot/blob/main/grade-pilot-server/src/lib/prisma.js): `grade-pilot-server/src/lib/prisma.js`

### Other components

- **Student**

## Connections

- Student → Application router: uses (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → Auth state: provides auth (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → Login and registration: routes to (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → Degree onboarding: routes to (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → Dashboard shell: routes to (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → Year overview: routes to (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → Year details: routes to (evidence: `grade-pilot-client/src/App.tsx`)
- Application router → User settings: routes to (evidence: `grade-pilot-client/src/App.tsx`)
- Student → Login and registration: authenticates (evidence: `README.md`)
- Student → Degree onboarding: enters degree (evidence: `README.md`)
- Student → Academic editors: manages records (evidence: `README.md`)
- Student → Grade Pilot: checks predictions (evidence: `README.md`)
- Express application → API dispatcher: mounts API (evidence: `grade-pilot-server/src/app.js`)
- API dispatcher → Authentication routes: dispatches auth (evidence: `grade-pilot-server/src/routes/apiRouter.js`)
- API dispatcher → Degree routes: dispatches degree (evidence: `grade-pilot-server/src/routes/apiRouter.js`)
- API dispatcher → Academic year management: dispatches year
- API dispatcher → Module management: dispatches modules
- API dispatcher → Assignment management: dispatches assignments
- Authentication routes → Authentication service: routes to (evidence: `grade-pilot-server/src/routes/authRouter.js`)
- Degree routes → Degree management: routes to (evidence: `grade-pilot-server/src/routes/degreeRouter.js`)
- Authentication service → PostgreSQL via Prisma: reads and writes (evidence: `grade-pilot-server/src/controllers/authControllers.js`)
- Degree management → PostgreSQL via Prisma: reads and writes (evidence: `grade-pilot-server/src/controllers/degreeControllers.js`)
- Academic year management → PostgreSQL via Prisma: reads and writes (evidence: `grade-pilot-server/src/controllers/academicYearControllers.js`)
- Module management → PostgreSQL via Prisma: reads and writes (evidence: `grade-pilot-server/src/controllers/moduleControllers.js`)
- Assignment management → PostgreSQL via Prisma: reads and writes (evidence: `grade-pilot-server/src/controllers/assignmentControllers.js`)
- Degree onboarding → Express application: submits degree
- Login and registration → Express application: sends credentials
- Year details → Express application: loads year data
