# 14flavius/gradeshelf architecture

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

## Overview

GradeShelf is a self-hosted, private grade tracker and exam planner. Users organize grade lists, subjects, assessment rules and periods, record grades or upcoming exams, and view averages and activity on a dashboard. Notes and attachments, account security, administration, calendar subscriptions and data exports are separate product capabilities. The graph combines documented features with relationships visible in the supplied excerpts and source index; unsampled implementation details are not assumed.

Main entry points: [`lib/db.ts`](https://github.com/14flavius/gradeshelf/blob/main/lib/db.ts) (Application database), [`lib/grades/queries.ts`](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/queries.ts) (Grade queries), [`components/app-shell.tsx`](https://github.com/14flavius/gradeshelf/blob/main/components/app-shell.tsx) (Application shell), [`lib/i18n/server.ts`](https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/server.ts) (Request localization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grades["Grades and planning"]
  node_lists["Grade lists<br/>[page.tsx]"]
  node_gradesapi["Grade API<br/>[route.ts]"]
  node_gradehttp["Grade request handling<br/>[http.ts]"]
  node_entryeditor["Entry editor<br/>[entry-editor.tsx]"]
  node_gradequeries["Grade queries<br/>[queries.ts]"]
  node_entrydetails["Entry details<br/>[entry-details.ts]"]
  node_averages["Averages<br/>[averages.ts]"]
  node_grading["Grading systems<br/>[systems.ts]"]
  node_periods["Periods<br/>[periods.ts]"]
  node_dashboardqueries["Dashboard queries"]
  node_entrypage["Entry details page<br/>[page.tsx]"]
end

subgraph group_experience["Application experience"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_appshell["Application shell<br/>[app-shell.tsx]"]
  node_i18nserver["Request localization<br/>[server.ts]"]
  node_i18nconfig["Locale selection<br/>[config.ts]"]
  node_messages["Translations<br/>[messages.ts]"]
  node_i18nprovider["Language provider<br/>[provider.tsx]"]
end

subgraph group_identity["Accounts and administration"]
  node_auth["Authentication<br/>[server.ts]"]
  node_login["Login<br/>[page.tsx]"]
  node_admin["Administration<br/>[service.ts]"]
end

subgraph group_services["Data and integrations"]
  node_database[("Application database<br/>[db.ts]")]
  node_attachments[("Attachment storage<br/>[storage.ts]")]
  node_export["Data export<br/>[service.ts]"]
  node_exportroute["Export endpoint<br/>[route.ts]"]
  node_calendar["Calendar feed<br/>[service.ts]"]
  node_calendarroute["Calendar endpoint<br/>[route.ts]"]
  node_feed["ICS subscription<br/>[route.ts]"]
  node_logger["Event logging<br/>[logger.mjs]"]
end

node_user(("User"))

node_user -->|"signs in"| node_login
node_user -->|"tracks grades"| node_dashboard
node_dashboard -->|"loads grades"| node_gradequeries
node_dashboard -->|"loads overview"| node_dashboardqueries
node_user -->|"manages lists"| node_lists
node_lists -.->|"edits entries"| node_entryeditor
node_entryeditor -.->|"submits grades"| node_gradesapi
node_gradesapi -->|"dispatches request"| node_gradehttp
node_gradequeries -->|"queries data"| node_database
node_gradequeries -->|"loads details"| node_entrydetails
node_averages -->|"uses scale rules"| node_grading
node_gradequeries -->|"uses periods"| node_periods
node_entrypage -->|"loads entry data"| node_gradequeries
node_entrypage -->|"loads entry detail"| node_entrydetails
node_entrypage -->|"renders within"| node_appshell
node_appshell -->|"checks account"| node_auth
node_appshell -->|"reads settings"| node_database
node_appshell -->|"loads language"| node_i18nserver
node_i18nserver -->|"reads user locale"| node_auth
node_i18nserver -->|"selects locale"| node_i18nconfig
node_i18nserver -->|"loads translations"| node_messages
node_i18nprovider -->|"uses locale rules"| node_i18nconfig
node_i18nprovider -->|"loads translations"| node_messages
node_login -->|"authenticates account"| node_auth
node_login -->|"reads contact settings"| node_database
node_auth -->|"loads auth data"| node_database
node_admin -->|"manages accounts"| node_database
node_admin -->|"uses file storage"| node_attachments
node_user -->|"requests export"| node_exportroute
node_exportroute -.->|"creates archive"| node_export
node_export -->|"reads attachments"| node_attachments
node_export -.->|"reads account data"| node_database
node_user -->|"configures feed"| node_calendarroute
node_calendarroute -->|"handles feed settings"| node_calendar
node_user -->|"subscribes"| node_feed
node_feed -.->|"reads feed data"| node_database
node_gradehttp -->|"logs failures"| node_logger

click node_dashboard "https://github.com/14flavius/gradeshelf/blob/main/app/(protected)/dashboard/page.tsx"
click node_lists "https://github.com/14flavius/gradeshelf/blob/main/app/(protected)/lists/%5BlistId%5D/page.tsx"
click node_gradesapi "https://github.com/14flavius/gradeshelf/blob/main/app/api/grades/route.ts"
click node_gradehttp "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/http.ts"
click node_entryeditor "https://github.com/14flavius/gradeshelf/blob/main/components/grades/entry-editor.tsx"
click node_gradequeries "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/queries.ts"
click node_entrydetails "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/entry-details.ts"
click node_averages "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/averages.ts"
click node_grading "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/systems.ts"
click node_periods "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/periods.ts"
click node_dashboardqueries "https://github.com/14flavius/gradeshelf/blob/main/lib/grades/dashboard-queries.ts"
click node_entrypage "https://github.com/14flavius/gradeshelf/blob/main/app/entries/%5BentryId%5D/page.tsx"
click node_appshell "https://github.com/14flavius/gradeshelf/blob/main/components/app-shell.tsx"
click node_i18nserver "https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/server.ts"
click node_i18nconfig "https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/config.ts"
click node_messages "https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/messages.ts"
click node_i18nprovider "https://github.com/14flavius/gradeshelf/blob/main/components/i18n/provider.tsx"
click node_auth "https://github.com/14flavius/gradeshelf/blob/main/lib/auth/server.ts"
click node_login "https://github.com/14flavius/gradeshelf/blob/main/app/login/page.tsx"
click node_admin "https://github.com/14flavius/gradeshelf/blob/main/lib/admin/service.ts"
click node_database "https://github.com/14flavius/gradeshelf/blob/main/lib/db.ts"
click node_attachments "https://github.com/14flavius/gradeshelf/blob/main/lib/attachments/storage.ts"
click node_export "https://github.com/14flavius/gradeshelf/blob/main/lib/export/service.ts"
click node_exportroute "https://github.com/14flavius/gradeshelf/blob/main/app/api/account/export/route.ts"
click node_calendar "https://github.com/14flavius/gradeshelf/blob/main/lib/calendar/service.ts"
click node_calendarroute "https://github.com/14flavius/gradeshelf/blob/main/app/api/account/calendar/route.ts"
click node_feed "https://github.com/14flavius/gradeshelf/blob/main/app/calendar/%5Btoken%5D/feed.ics/route.ts"
click node_logger "https://github.com/14flavius/gradeshelf/blob/main/lib/logger.mjs"

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_lists,node_gradesapi,node_gradehttp,node_entryeditor,node_gradequeries,node_entrydetails,node_averages,node_grading,node_periods,node_dashboardqueries,node_entrypage,node_user toneBlue
class node_dashboard,node_appshell,node_i18nserver,node_i18nconfig,node_messages,node_i18nprovider toneAmber
class node_auth,node_login,node_admin toneMint
class node_database,node_attachments,node_export,node_exportroute,node_calendar,node_calendarroute,node_feed,node_logger toneRose
```

## Components

### Grades and planning

- [Grade lists](https://github.com/14flavius/gradeshelf/blob/main/app/(protected)/lists/%5BlistId%5D/page.tsx): `app/(protected)/lists/[listId]/page.tsx`
- [Grade API](https://github.com/14flavius/gradeshelf/blob/main/app/api/grades/route.ts): `app/api/grades/route.ts`
- [Grade request handling](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/http.ts): `lib/grades/http.ts`
- [Entry editor](https://github.com/14flavius/gradeshelf/blob/main/components/grades/entry-editor.tsx): `components/grades/entry-editor.tsx`
- [Grade queries](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/queries.ts): `lib/grades/queries.ts`
- [Entry details](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/entry-details.ts): `lib/grades/entry-details.ts`
- [Averages](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/averages.ts): `lib/grades/averages.ts`
- [Grading systems](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/systems.ts): `lib/grades/systems.ts`
- [Periods](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/periods.ts): `lib/grades/periods.ts`
- [Dashboard queries](https://github.com/14flavius/gradeshelf/blob/main/lib/grades/dashboard-queries.ts): `lib/grades/dashboard-queries.ts`
- [Entry details page](https://github.com/14flavius/gradeshelf/blob/main/app/entries/%5BentryId%5D/page.tsx): `app/entries/[entryId]/page.tsx`

### Application experience

- [Dashboard](https://github.com/14flavius/gradeshelf/blob/main/app/(protected)/dashboard/page.tsx): `app/(protected)/dashboard/page.tsx`
- [Application shell](https://github.com/14flavius/gradeshelf/blob/main/components/app-shell.tsx): `components/app-shell.tsx`
- [Request localization](https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/server.ts): `lib/i18n/server.ts`
- [Locale selection](https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/config.ts): `lib/i18n/config.ts`
- [Translations](https://github.com/14flavius/gradeshelf/blob/main/lib/i18n/messages.ts): `lib/i18n/messages.ts`
- [Language provider](https://github.com/14flavius/gradeshelf/blob/main/components/i18n/provider.tsx): `components/i18n/provider.tsx`

### Accounts and administration

- [Authentication](https://github.com/14flavius/gradeshelf/blob/main/lib/auth/server.ts): `lib/auth/server.ts`
- [Login](https://github.com/14flavius/gradeshelf/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Administration](https://github.com/14flavius/gradeshelf/blob/main/lib/admin/service.ts): `lib/admin/service.ts`

### Data and integrations

- [Application database](https://github.com/14flavius/gradeshelf/blob/main/lib/db.ts): `lib/db.ts`
- [Attachment storage](https://github.com/14flavius/gradeshelf/blob/main/lib/attachments/storage.ts): `lib/attachments/storage.ts`
- [Data export](https://github.com/14flavius/gradeshelf/blob/main/lib/export/service.ts): `lib/export/service.ts`
- [Export endpoint](https://github.com/14flavius/gradeshelf/blob/main/app/api/account/export/route.ts): `app/api/account/export/route.ts`
- [Calendar feed](https://github.com/14flavius/gradeshelf/blob/main/lib/calendar/service.ts): `lib/calendar/service.ts`
- [Calendar endpoint](https://github.com/14flavius/gradeshelf/blob/main/app/api/account/calendar/route.ts): `app/api/account/calendar/route.ts`
- [ICS subscription](https://github.com/14flavius/gradeshelf/blob/main/app/calendar/%5Btoken%5D/feed.ics/route.ts): `app/calendar/[token]/feed.ics/route.ts`
- [Event logging](https://github.com/14flavius/gradeshelf/blob/main/lib/logger.mjs): `lib/logger.mjs`

### Other components

- **User**

## Connections

- User → Login: signs in (evidence: `README.md`)
- User → Dashboard: tracks grades (evidence: `README.md`)
- Dashboard → Grade queries: loads grades (evidence: `app/(protected)/dashboard/page.tsx`)
- Dashboard → Dashboard queries: loads overview (evidence: `app/(protected)/dashboard/page.tsx`)
- User → Grade lists: manages lists (evidence: `README.md`)
- Grade lists → Entry editor: edits entries
- Entry editor → Grade API: submits grades
- Grade API → Grade request handling: dispatches request (evidence: `app/api/grades/route.ts`)
- Grade queries → Application database: queries data (evidence: `lib/grades/queries.ts`)
- Grade queries → Entry details: loads details (evidence: `lib/grades/queries.ts`)
- Averages → Grading systems: uses scale rules (evidence: `lib/grades/averages.ts`)
- Grade queries → Periods: uses periods (evidence: `lib/grades/queries.ts`)
- Entry details page → Grade queries: loads entry data (evidence: `app/entries/[entryId]/page.tsx`)
- Entry details page → Entry details: loads entry detail (evidence: `app/entries/[entryId]/page.tsx`)
- Entry details page → Application shell: renders within (evidence: `app/entries/[entryId]/page.tsx`)
- Application shell → Authentication: checks account (evidence: `components/app-shell.tsx`)
- Application shell → Application database: reads settings (evidence: `components/app-shell.tsx`)
- Application shell → Request localization: loads language (evidence: `components/app-shell.tsx`)
- Request localization → Authentication: reads user locale (evidence: `lib/i18n/server.ts`)
- Request localization → Locale selection: selects locale (evidence: `lib/i18n/server.ts`)
- Request localization → Translations: loads translations (evidence: `lib/i18n/server.ts`)
- Language provider → Locale selection: uses locale rules (evidence: `components/i18n/provider.tsx`)
- Language provider → Translations: loads translations (evidence: `components/i18n/provider.tsx`)
- Login → Authentication: authenticates account (evidence: `app/login/page.tsx`)
- Login → Application database: reads contact settings (evidence: `app/login/page.tsx`)
- Authentication → Application database: loads auth data (evidence: `lib/auth/server.ts`)
- Administration → Application database: manages accounts (evidence: `lib/admin/service.ts`)
- Administration → Attachment storage: uses file storage (evidence: `lib/admin/service.ts`)
- User → Export endpoint: requests export (evidence: `README.md`)
- Export endpoint → Data export: creates archive
- Data export → Attachment storage: reads attachments (evidence: `lib/export/service.ts`)
- Data export → Application database: reads account data
- User → Calendar endpoint: configures feed (evidence: `README.md`)
- Calendar endpoint → Calendar feed: handles feed settings (evidence: `app/api/account/calendar/route.ts`)
- User → ICS subscription: subscribes (evidence: `README.md`)
- ICS subscription → Application database: reads feed data (evidence: `app/calendar/[token]/feed.ics/route.ts`)
- Grade request handling → Event logging: logs failures (evidence: `app/api/grades/route.ts`)
