SDU Course Registration Assistant
Plan, validate and (from Sprint 5) submit course registration for Suleyman Demirel University students.
Stack: Next.js 16 (App Router, Turbopack) · React 19 · Tailwind CSS v4 · shadcn-style components · Lucide · Sonner toasts · Prisma 7 + PostgreSQL · Zod · jose (sessions) · Vitest.
Design: minimal, monotone, modern — neutral zinc surfaces, hairline borders, soft shadows, one restrained blue accent, generous whitespace. No gradients. Colour carries meaning only (emerald = passed/open, red = conflict/full, amber = limited). Design tokens live in app/globals.css.
Status: this is the first delivery. It covers the project skeleton, the database schema for all 7 sprints, the SDU integration service (mock and live adapters), and the main planner dashboard. The rule engine for Sprints 2–3 (credit limit, seat status, time conflicts, prerequisites) is already built into the dashboard, because the timetable can't be interactive without it.
Quick start
Requires Node.js ≥ 20.9.
npm install
cp .env.example .env.local # defaults run fully offline against the mock SDU backend
npm run dev # http://localhost:3000 → sign in as a demo student
Tests and checks:
npm test # 31 unit/integration tests (rules, search, SDU client + mock)
npm run typecheck
npm run build
Database (optional for the dashboard in mock mode):
# set DATABASE_URL in .env.local first
npm run db:migrate # applies prisma/migrations (schema + CHECK constraints)
npm run db:seed # syncs departments, catalog, demo students via the SDU adapter
Demo accounts (mock SSO): 230107021, Aigerim Tulegenova, CS year 3 (has a failed course to retake); 240103118, Nursultan Abenov, IS year 2.
Project structure
sdu-course-assistant/
├── app/
│ ├── layout.tsx Root layout: fonts (Onest + JetBrains Mono, Kazakh-ready), toaster
│ ├── globals.css Tailwind v4 theme tokens: navy / gold / emerald / crimson / cyan
│ ├── (auth)/login/page.tsx SSO sign-in (mock mode lists demo students)
│ ├── (app)/ Authenticated shell (header + nav)
│ │ ├── layout.tsx
│ │ ├── error.tsx "SDU unreachable" boundary with retry
│ │ ├── dashboard/ ★ Planner: search sidebar + timetable + plan
│ │ └── transcript/ Completed-course tracker
│ └── api/
│ ├── auth/{login,callback,logout}/route.ts CAS SSO flow → signed session cookie
│ ├── me/route.ts Profile + transcript sync
│ ├── courses/route.ts Multi-filter catalog search
│ └── sections/availability/route.ts Live seat counts (polled)
├── components/
│ ├── ui/ shadcn-style primitives (button, badge, card, input, meter…)
│ ├── layout/ App header, nav
│ ├── dashboard/ Workspace state owner, search sidebar, result cards,
│ │ plan panel, stat strip, live-seat + plan hooks
│ └── timetable/timetable-grid.tsx ★ Interactive Mon–Fri grid with lane layout & previews
├── lib/
│ ├── domain/ App-wide types + time helpers (decoupled from SDU wire format)
│ ├── registration/ ★ Pure rule engine: conflicts, prerequisites, credit policy
│ ├── catalog/search.ts Shared search/filter (API route and client use the same code)
│ ├── auth/ JWT session (token.ts is edge/proxy-safe)
│ ├── sync/sdu-sync.ts SDU → Postgres mirror (seed today, cron later)
│ ├── data/queries.ts Request-scoped RSC loaders
│ ├── api/http.ts Route wrapper: auth + SDU error mapping
│ ├── env.ts Zod-validated environment
│ └── db.ts Prisma client (pg driver adapter)
├── services/
│ ├── sduApi.ts ★ SDU integration service: client, transports, factory
│ └── sdu/
│ ├── endpoints.ts Endpoint map (single routing table for both modes)
│ ├── contracts.ts Zod wire schemas (snake_case, validated at the boundary)
│ ├── mappers.ts Wire → domain translation
│ ├── mock-server.ts In-process fake SDU backend (atomic batch submit, seat drift)
│ └── fixtures.ts Fictional catalog, instructors, students
├── prisma/
│ ├── schema.prisma ★ All tables for Sprints 1–7
│ ├── migrations/ init + integrity CHECK constraints
│ └── seed.ts
├── proxy.ts Next 16 "proxy" (formerly middleware): auth gate
└── prisma.config.ts
Planned additions by sprint
| Sprint | Adds |
|---|
| 4 | lib/recommendation/ (scoring against DegreeRequirement), app/api/recommendations/route.ts, recommendation rail in the sidebar |
| 5 | app/api/plan/route.ts (moves the plan from localStorage to StagedSelection), app/api/registration/submit/route.ts (wraps sdu.batchSubmit and records a RegistrationBatch), app/api/waitlist/route.ts, a submit bar in PlanPanel |
| 6 | components/chat/ floating assistant + app/api/chat/route.ts (grounded in catalog and plan data), app/(advisor)/reviews/… plus app/api/advisor/reviews/… (ScheduleReview) |
| 7 | app/(admin)/capacity/… + app/api/admin/sections/[id]/capacity (CapacityChange, pushed to SDU), app/api/advisor/overrides (PrerequisiteOverride, fed into evaluatePrerequisites(…, waived)) |
Roles: the session type currently has only STUDENT. Sprints 6 and 7 add ADVISOR and REGISTRAR claims from CAS attributes. They map to StaffMember.role and get their own route groups guarded in proxy.ts.
SDU integration
UI / routes ──► SduApiClient ──► SduTransport ─┬─► HttpSduTransport (SDU_API_MODE=live)
(zod parse + │ CAS + REST, OAuth2 client-credentials,
wire→domain map) │ retries w/ backoff, timeouts, Idempotency-Key
└─► MockSduTransport (SDU_API_MODE=mock, default)
in-process fake answering the same endpoint keys
The mock sits at the transport level, so in dev the client's parsing, mapping, pagination and error handling all run exactly as they would in production.
| Key | Method | Path | Notes |
|---|
casLogin | GET | /cas/login?service= | Browser redirect |
casServiceValidate | GET | /cas/p3/serviceValidate?format=JSON | CAS protocol v3 |
casLogout | GET | /cas/logout?service= | Single sign-out |
studentProfile | GET | /api/v1/students/:studentId/profile | GPA, program, completed_credits, advisor |
studentTranscript | GET | /api/v1/students/:studentId/transcript | transcript_data[] |
departments | GET | /api/v1/departments | |
termSections | GET | /api/v1/terms/:termCode/sections?cursor= | Paginated; available_seats, total_capacity, instructor_name, time_slots, classroom |
sectionAvailability | GET | /api/v1/terms/:termCode/sections/availability?ids= | Live seats |
batchSubmit | POST | /api/v1/registration/batch-submit | Atomic, all-or-nothing; Idempotency-Key header |
waitlistJoin | POST | /api/v1/sections/:sectionId/waitlist | |
⚠️ Confirm with SDU IT before going live. The CAS paths follow the public CAS protocol. The REST paths and payload shapes are a proposed contract, not a published SDU spec. When SDU provides its real OpenAPI document, the expected changes are limited to services/sdu/endpoints.ts, contracts.ts and mappers.ts.
Auth flow
/api/auth/login → CAS (/cas/login?service=…/api/auth/callback) → /api/auth/callback?ticket= → server-to-server serviceValidate → profile check (suspended or graduated accounts are refused) → HS256 session cookie (8 h, httpOnly). proxy.ts redirects signed-out page views, and API routes return 401.
Registration rules (lib/registration/)
| Rule | Behaviour | Sprint |
|---|
| Already passed | Block | 1 |
| Section full | Block (waitlist in Sprint 5) | 2 |
| Credit limit | Block over limit; standard 30 ECTS, 35 at GPA ≥ 3.33, 20 on probation | 2 |
| Prerequisites | Block. Rules are AND-of-OR groups, e.g. CSS 225 and (MAT 201 or MAT 250), and support advisor waivers | 3 |
| Time conflict | Warn (sweep-line per day, exclusive end times); highlighted per meeting on the grid | 3 |
| Same course, other section | Treated as a swap, not extra credits | — |
CREDIT_POLICY values are placeholders. Confirm them with the Registrar; they all live in lib/registration/credits.ts. The mock SDU enforces the same rules server-side on batch submit, as the real registration engine should.
Database
The ownership model is documented at the top of prisma/schema.prisma. SDU is the system of record: students, transcripts, the catalog and enrolments are mirrored locally, keyed by SDU ids. This app owns the planning state: staged selections, batches, waitlist, reviews, overrides and capacity changes.
| Group | Tables |
|---|
| Structure | terms, departments, programs, degree_requirements |
| People | students, staff_members (advisor / registrar / admin), instructors |
| Catalog | courses, prerequisites (CNF: groupNo), sections, meetings |
| Record | transcript_entries |
| Registration | staged_selections, registration_batches (idempotency key), enrollments, waitlist_entries |
| Advising / admin | schedule_reviews, prerequisite_overrides, capacity_changes |
Available seats are derived (totalCapacity − enrolledCount), never stored. The second migration adds CHECK constraints for time windows, seat counters, self-prerequisites and GPA range.
Design notes
- Minimal & monotone: neutral zinc surfaces on a near-white app background, 1 px hairline borders, soft shadows, one restrained blue accent for interactive/selected state. No gradients, no heavy chrome.
- Colour carries meaning only, sparingly: emerald = open or passed, red = full or conflict, amber = limited seats, blue = in plan or preview. Timetable block tints are low-saturation and avoid strong emerald/red so status stays unambiguous.
- Typography: Onest (Cyrillic-ready) for UI, JetBrains Mono with tabular figures for codes, credits and times.
- Hovering a section previews it on the grid as a dashed ghost block. Overlapping blocks sit side by side in lanes. Removing a section shows an Undo toast. Seats poll every 10 s (paused in background tabs) and toast when a staged section fills or reopens.
- Blocked "Add" buttons stay focusable, using
aria-disabled, so keyboard and screen-reader users hear why a section is locked.
- Mobile: panels stack and the timetable scrolls horizontally inside its own card.
