STUDYNEXUS
A platform no HsH student had.
Built by one who needed it.
Chapter I: The Origin
Real frustration becomes a real product.
Managing your studies is a mess
Every HS Hannover student knows it: QIS for grades, Moodle for materials, Excel for ECTS tracking, a notebook for exam dates — and you still lose track. No tool speaks the language of a student. None knows the exam regulations. None calculates GPA automatically.
This isn't a comfort problem — it's a system failure. System failures deserve systemic solutions.
- No central hub for study progress
- Manual ECTS tracking in Excel
- Exam dates spread across multiple systems
- Calculating GPA manually with a calculator
- Schedule conflicts only discovered in the lecture hall
# Aktuelle Realität an der HsH
# Die StudyNexus Lösung
[✓] backend started on :8000
[✓] postgres ready — migrations applied
[READY] StudyNexus is running.
Platform Scope
An Operating System for your Studies.
StudyNexus is not another to-do app. It's a complete study operating system — built specifically for HS Hannover. The platform knows the real exam regulations, calculates weighted GPA by ECTS, and automatically detects schedule conflicts.
Access is intentionally exclusive: only @stud.hs-hannover.de email addresses are accepted. No noise, no bot accounts — a real student community.
Although the project is still in active development, a complete full-stack MVP is already running: authentication with email verification, study plan with automatic GPA calculation, Kanban board with drag & drop, schedule board with collision detection, and visual study plan.
200+
Source Files
(Frontend + Backend)
17
Alembic
Migrations
22+
Architecture Decision
Records (ADRs)
122
Backend Tests
all green
37
BIN Modules
fully seeded
5
Docker Services
(Compose Stack)
Chapter II: System Architecture
Five containers. One coherent platform.
Frontend & Backend. One Repository.
StudyNexus is built as a monorepo — frontend (Next.js) and backend (FastAPI) live in the same repository, share commit history, and are deployed together. This eliminates context switches and keeps API contracts consistent.
Every change to the API contract is immediately visible in the frontend. No desync between two repos.
The path of a request
Every mutation in the frontend goes through a secure pipeline: Next.js API Routes proxy all requests to the FastAPI backend. This eliminates browser CORS issues and keeps the backend URL completely hidden. The backend validates with Pydantic, checks the JWT, and writes to PostgreSQL.
Docker Compose: Five Services
The entire infrastructure starts with a single command. In production, the same containers are deployed — no 'works on my machine'.
PostgreSQL and Redis have health checks. The backend only starts when the database is ready.
✓ redis healthy (redis:7-alpine)
✓ backend started → :8000
✓ frontend started → :3000
✓ adminer started → :8080
Chapter III: Engineering Decisions
14 Architecture Decision Records. Here are the most impactful ones.
Architecture decisions should be documented — not just what was decided, but why and which alternatives were rejected. StudyNexus has 14 ADRs. Here are the ones that shaped the system most.
FastAPI instead of Django
Django is the 'safe' Python framework. FastAPI is the right one for this use case: native async support, Pydantic v2 directly in the schema, automatic OpenAPI docs at /api/docs — and an architecture ready for AI extensions.
httpOnly Cookies over localStorage
Storing JWT tokens in localStorage is a classic XSS vulnerability: any injected script can read localStorage. httpOnly cookies are fundamentally invisible to JavaScript. The browser sends them automatically — no script can steal them.
bcrypt directly — no passlib
passlib is de facto unmaintained. Last version 2022, known compatibility issues with Python 3.13+. Using bcrypt 4.1.3 directly is safer, leaner and more future-proof — no abstraction layer that breaks tomorrow.
CSRF via Custom Header
Classic CSRF token management requires server state. Instead, every mutating request carries the header x-studynexus-client: true. Browsers don't allow cross-origin requests to set custom headers without a CORS preflight — that's the protection. Stateless, simple, effective.
HsH-Only Strategy
Restricting access to @stud.hs-hannover.de is not a limitation — it's a design decision. Instead of a generic platform for all universities: a deeply integrated system for one. The exam regulations are built in. The module structure is real.
Redis for Admin Session Tokens
JWT cannot be invalidated server-side. For admin actions (Delete, Archive, Reset) we need a token we can revoke instantly. Redis with 15-minute TTL — the sudo concept for the web.
is_admin in JWT Payload
Next.js Middleware runs in the Edge Runtime — no database access possible. is_admin: true directly in the JWT enables admin route guards without DB query and without latency.
Chapter IV: Feature Deep-Dive
What the platform can do today.
The Core: Mission Control Dashboard
The first view after login. The dashboard aggregates everything relevant in real-time: GPA status, ECTS progress, upcoming exams and today's events — calculated directly from the database, no caching.
Every widget is functional. The Exam Countdown pulses red when an exam is less than 14 days away. The Daily Focus view automatically switches to 'tomorrow' after 8 PM.
- GPA tracker with ECTS-weighted real-time calculation
- Exam countdown with pulse animation (< 14 days = red)
- Daily Focus: today's events, automatic switch after 8 PM
- Smart Timeline: task-intelligent sorting by due date
Kanban Board with Real Drag & Drop
Not localStorage, not useState tricks — @dnd-kit v6 as the foundation. Four columns: To Do, In Progress, Exam Ready, Done. Tasks have priorities, can be linked to modules and carry a submission flag.
Position-based sorting: every drag-drop action writes immediately to the database. Page reload changes nothing — the board is fully persistent.
15-Minute CSS Grid Engine
The schedule is not a table — it's a real CSS Grid with 15-minute resolution from 8 AM to 8 PM. Events are placed pixel-perfectly. A red line shows the current time in real-time. Collisions are detected and reported with HTTP 409.
10 event types: LECTURE, EXERCISE, TUTORIAL, SEMINAR, PRACTICUM, CUSTOM_STUDY, FOCUS, EXAM, WORK, LIFE. Semester binding prevents data loss on semester change. Ghosting mode temporarily hides events without deleting them.
Visual Study Plan
Modules in semester-based columns. Drag & drop between semesters, automatic ECTS calculation per column, color coding by module type. Data comes from the real HsH exam regulations — no placeholder data.
- Mandatory modules loaded automatically
- Elective & supplementary modules addable manually
- Drag & Drop between semesters via @dnd-kit
- ECTS sum per column calculated live
MilestoneWidget — §6 exam regulation monitored live
The dashboard has a new sidebar widget that evaluates the BIN exam regulation §6 in real time: Which semesters are complete? Is the preliminary exam passed?
- Sem 1 complete: alle 6 Module BIN-100..116
- Preliminary exam: all 17 modules from Sem 1–3 passed
- BA admission: preliminary exam + ≥ 134 ECTS
- Live progress bar per milestone
Enterprise Admin — 14 pages, 35+ endpoints
A complete admin control center: user management, exam regulation management, analytics dashboard, audit log and JSON import — delivered in full in 2 days.
Study Regulations at a Glance
A dedicated dashboard page displaying all relevant exam regulation rules: admission rules §6, grading scale §10, repeat rules §11 — with live status badges directly from the database.
- Programm-aware: erkennt BIN via API-Response
- Exam types PX / EA / R / BAA+Ko color-coded
- BA admission: live ECTS progress bar
- No hardcode — Sprint 7 adds more exam regulations
Chapter V: BIN Exam Regulations
3 PDFs. 37 Modules. All §6 rules mapped automatically.
Built from real documents
No placeholder data. All 37 BIN modules were extracted directly from three official HsH documents and transferred into the database.
- §5 — Modulstruktur Abschnitt 1 + 2
- §6 — Admission & prerequisite rules
- Annex B1/B2 — complete module lists
- §7 — Prüfungsarten (PX, EA, R, BAA+Ko)
- §10 — 11 official HsH grades
- §11 — Repeat rules (max. 3 attempts)
- SWS per module (semester weekly hours)
- Exam type per module
- 37 complete module descriptions
Four types. Directly from ATPO-FIV §7.
Each of the 37 BIN modules carries the official exam type from the module handbook — persisted in the database, color-coded in the UI.
A Pydantic validation ensures that only the 11 official HsH grades can be entered. HTTP 422 for invalid grades.
§6 ADMISSION RULES — FULLY IMPLEMENTED
Study progress per §6 — live
GET /me/stats delivers 8 new fields. The dashboard widget evaluates them in real time. No polling — status is calculated on page load.
Chapter VI: Security by Design
Security is not an afterthought. Security is architecture.
Stateless CSRF via Custom Header
Every mutating request (POST, PUT, DELETE, PATCH) carries the custom header x-studynexus-client: true. Cross-origin requests cannot set custom headers without a CORS preflight. Combined with Origin header validation, this creates complete CSRF protection — without any token storage.
JWT in httpOnly Cookies
The JWT token lives exclusively in an httpOnly cookie with Secure and SameSite=Lax flags. JavaScript cannot read this cookie. The browser sends it automatically — no manual token management in the frontend needed.
HttpOnly; Secure; SameSite=Lax
Path=/; Max-Age=604800 (7d)
6-Digit Email Verification
After registration, the student receives an email with a 6-digit code via Resend API. The code expires after 15 minutes. The account is only active after verification — and only @stud.hs-hannover.de addresses are accepted.
Row-Level User Isolation
Every database query filters by user_id. No student can see another student's data, even if they know the UUID. No separate permissions system — the ORM model enforces isolation structurally.
.filter(Task.user_id == current_user.id)
.all()
Sudo Concept: Read vs. Destroy
A stolen admin JWT alone cannot cause damage. Destructive operations require a second factor — a short-lived Redis token issued through password re-verification.
JWT-based admin check
is_admin: true in the JWT payload (ADR-021). Edge-Runtime compatible — no DB lookup, zero latency. Sufficient for all read-only admin operations.
Redis Session Token (Sudo)
Admin re-enters password → Redis token with 15-min TTL. Only this token unlocks destructive ops. Immediately revocable — no waiting for JWT expiry.
Chapter VII: Admin Panel
Enterprise Control Center. Planned for one week. Delivered in two days.
What the admin panel can do
Dashboard & KPI
13-field KPI response, growth chart (Recharts LineChart, 7d/30d/90d/1y), user segmentation, DB size via pg_database_size().
Full user access
Paginated list (25/page), 5 filter tabs, search by email+name, PATCH all fields, password reset, hard delete with mandatory reason.
University → Module → Prerequisite
6 router files, ~30 endpoints. Soft delete on exam regulations/modules (protection of existing data), hard delete on universities/faculties.
Complete since phase 2
Every admin mutation logged since day one. Timeline layout, ActionBadge with 8 color variants, DiffBlock (old→new diff, strikethrough for removed values).
JSON bulk import up to 500 modules
Validate → Preview (first 10) → POST → Result. Idempotent via abbreviation lookup within the same exam regulation. PDF placeholder for Sprint 7 (ML/NLP).
Real-time system status
Overall badge (ok/degraded/down), ServiceBadge per service (DB ping + Redis.ping), DB version + size, auto-refresh every 60 seconds.
AdminDataTable — one component for all lists
Instead of 6 separate table implementations: one generic TypeScript component. Column sort, debounced search (350ms), server-side pagination, hideOnMobile per column — all configurable via props.
22 new TypeScript interfaces, 11 new TanStack Query hooks, adminFetch.ts as a thin wrapper: no direct fetch(), centralized header logic, 204-handling.
Chapter VIII: Database Architecture
12+ tables. 17 Alembic migrations. Complete university hierarchy.
From University to Single Module
The data model reflects the real university hierarchy. A student selects an exam regulation — the system automatically loads all mandatory modules into their personal study plan.
9 SQLAlchemy models with complete foreign key constraints and UUID primary keys. PostgreSQL-native ENUMs for status, priority and event_type.
Weighted Grade — like at real universities
GPA is not simply averaged. Each module has an ECTS-based weighting. Only passed, graded modules are included. The result: a GPA that actually reflects the curriculum.
17 Alembic Migrations — Every step versioned
No manual SQL changes — every schema change is versioned, reversible, and reproducible. Sprint 4 (0012–0014) added BIN exam regulation data. Sprint 5 (0015–0017) delivered admin infrastructure.
Sprints 1–3 laid the foundation (0001–0011). Sprint 4 added the BIN exam regulation data (0012–0014). Sprint 5 delivered the admin infrastructure (0015–0017).
Chapter IX: Sprint Roadmap
Where the project stands. Where it's going.
Foundation: Auth, DB & Docker
JWT Authentication, PostgreSQL-Schema mit Alembic, Docker Compose Stack mit 5 Services, Email-Verifikation via Resend API, vollständige Studienplan-CRUD mit GPA-Berechnung.
Mission Control & Mobile
Kanban Board (@dnd-kit), Schedule Board (15-Min CSS Grid), Dashboard Widgets, Mobile FAB, Agenda View für kleine Screens, TanStack Query Migration, vollständige i18n (DE/EN).
BIN Prüfungsordnung Integration
37 BIN-Module aus 3 PDFs, Prüfungsart-System (PX/EA/R/BAA+Ko), §6-Voraussetzungen als DB-Constraints, MilestoneWidget, PO-Übersicht-Seite, GPA-Fix BIN-209.
Admin Panel — Enterprise Control Center
14 Admin-Seiten, 35+ Endpunkte, Two-Layer Auth (JWT + Redis Sudo), Audit-Log, Analytics (Recharts), JSON-Bulk-Import, 122/122 Tests grün.
Security Audit & Email-Templates
Admin-API-Rate-Limiting, Toast-Notifications bei API-Errors, E-Mail-Templates für Passwort-Reset, UI-Polishing und Dropdown-Auswahl für UUID-Felder.
Production Launch für die HsH
Öffentlicher Launch für alle HS Hannover Studierenden. Onboarding-Flow mit vorausgefüllten Prüfungsordnungen. Gamification: XP, Badges, Streaks.
A Project
in Motion.
StudyNexus is not finished — and that's exactly the point. Real software lives. It grows with its requirements. Every week a sprint. Every sprint a new feature.