How 14flavius/gradeshelf works
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: db.ts Application database · queries.ts Grade queries · app-shell.tsx Application shell · server.ts Request localization
Components 29
Grades and planning
- Grade lists
app/(protected)/lists/[listId]/page.tsx - Grade API
app/api/grades/route.ts - Grade request handling
lib/grades/http.ts - Entry editor
components/grades/entry-editor.tsx - Grade queries
lib/grades/queries.ts - Entry details
lib/grades/entry-details.ts - Averages
lib/grades/averages.ts - Grading systems
lib/grades/systems.ts - Periods
lib/grades/periods.ts - Dashboard queries
lib/grades/dashboard-queries.ts - Entry details page
app/entries/[entryId]/page.tsx
Application experience
- Dashboard
app/(protected)/dashboard/page.tsx - Application shell
components/app-shell.tsx - Request localization
lib/i18n/server.ts - Locale selection
lib/i18n/config.ts - Translations
lib/i18n/messages.ts - Language provider
components/i18n/provider.tsx
Accounts and administration
- Authentication
lib/auth/server.ts - Login
app/login/page.tsx - Administration
lib/admin/service.ts
Data and integrations
- Application database
lib/db.ts - Attachment storage
lib/attachments/storage.ts - Data export
lib/export/service.ts - Export endpoint
app/api/account/export/route.ts - Calendar feed
lib/calendar/service.ts - Calendar endpoint
app/api/account/calendar/route.ts - ICS subscription
app/calendar/[token]/feed.ics/route.ts - Event logging
lib/logger.mjs
Other components
- User
Connections 37
- User → Login: signs in
README.md - User → Dashboard: tracks grades
README.md - Dashboard → Grade queries: loads grades
app/(protected)/dashboard/page.tsx - Dashboard → Dashboard queries: loads overview
app/(protected)/dashboard/page.tsx - User → Grade lists: manages lists
README.md - Grade lists → Entry editor: edits entries
- Entry editor → Grade API: submits grades
- Grade API → Grade request handling: dispatches request
app/api/grades/route.ts - Grade queries → Application database: queries data
lib/grades/queries.ts - Grade queries → Entry details: loads details
lib/grades/queries.ts - Averages → Grading systems: uses scale rules
lib/grades/averages.ts - Grade queries → Periods: uses periods
lib/grades/queries.ts - Entry details page → Grade queries: loads entry data
app/entries/[entryId]/page.tsx - Entry details page → Entry details: loads entry detail
app/entries/[entryId]/page.tsx - Entry details page → Application shell: renders within
app/entries/[entryId]/page.tsx - Application shell → Authentication: checks account
components/app-shell.tsx - Application shell → Application database: reads settings
components/app-shell.tsx - Application shell → Request localization: loads language
components/app-shell.tsx - Request localization → Authentication: reads user locale
lib/i18n/server.ts - Request localization → Locale selection: selects locale
lib/i18n/server.ts - Request localization → Translations: loads translations
lib/i18n/server.ts - Language provider → Locale selection: uses locale rules
components/i18n/provider.tsx - Language provider → Translations: loads translations
components/i18n/provider.tsx - Login → Authentication: authenticates account
app/login/page.tsx - Login → Application database: reads contact settings
app/login/page.tsx - Authentication → Application database: loads auth data
lib/auth/server.ts - Administration → Application database: manages accounts
lib/admin/service.ts - Administration → Attachment storage: uses file storage
lib/admin/service.ts - User → Export endpoint: requests export
README.md - Export endpoint → Data export: creates archive
- Data export → Attachment storage: reads attachments
lib/export/service.ts - Data export → Application database: reads account data
- User → Calendar endpoint: configures feed
README.md - Calendar endpoint → Calendar feed: handles feed settings
app/api/account/calendar/route.ts - User → ICS subscription: subscribes
README.md - ICS subscription → Application database: reads feed data
app/calendar/[token]/feed.ics/route.ts - Grade request handling → Event logging: logs failures
app/api/grades/route.ts