vindyang/planr

Purpose and Runtime

This is a Next.js App Router application for university students to discover courses, assess eligibility, build and validate semester plans, receive AI-assisted recommendations, and submit course/professor reviews. It also provides multi-tenant administrative management for universities and departments. The primary runtime is Next.js/TypeScript, with Prisma-backed persistence and Better Auth-style authentication integration.

Key entry points:

• app/layout.tsx

• app/page.tsx

• proxy.ts

Route and Access Boundaries

The UI is divided into public/authentication, student, and admin route spaces. Layouts provide role-specific shells and form the primary authorization/navigation boundaries; server APIs enforce data operations separately.

• Authentication: app/(auth)/layout.tsx, app/(auth)/login/page.tsx, app/api/auth/[...all]/route.ts

• Student application: app/(student)/layout.tsx, app/(student)/dashboard/page.tsx, app/(student)/planner/page.tsx

• Administration: app/admin/layout.tsx, app/admin/[university]/layout.tsx, lib/access-control.ts

Student Course Discovery and Eligibility

Students browse courses, view individual course details and reviews, and request eligibility decisions. Course data access is separated into shared data services and HTTP endpoints; eligibility is a domain subsystem rather than UI-only logic.

• Course UI/API: app/(student)/courses/page.tsx, app/api/courses/route.ts, app/api/courses/[id]/eligibility/route.ts

• Eligibility engine: lib/eligibility/checker.ts, lib/eligibility/prerequisite-graph.ts, lib/eligibility/service.ts

• Course data boundary: lib/data/courses.ts

Primary flow: course page/client requests course records and eligibility; the eligibility service evaluates prerequisite/rule data and returns a student-specific decision for display or plan actions.

Academic Planner and Validation Pipeline

The planner is the core stateful student workflow. It manages semesters and scheduled courses through planner APIs, renders a board/sidebar/tracker UI, and validates the resulting plan against independent rule validators.

• Planner experience: app/(student)/planner/PlannerClient.tsx, app/(student)/planner/components/PlannerBoard.tsx, app/(student)/planner/components/ValidationPanel.tsx

• Mutation/read API: app/api/planner/route.ts, app/api/planner/semesters/[id]/route.ts, app/api/planner/courses/[id]/route.ts

• Validation domain: lib/planner/validation/index.ts, lib/planner/validation/prerequisite-validator.ts, lib/planner/validation/overload-validator.ts

Primary flow: a student creates semesters and assigns courses; planner endpoints persist changes; validation combines prerequisite, corequisite, duplicate, term, and unit-load checks; UI presents failures before or alongside plan changes.

Recommendations and AI Boundary

AI planning features are isolated behind recommendation modules and API routes, with explicit fallback and validation layers. This prevents AI output from directly becoming authoritative planner state.

• Recommendation API: app/api/recommendations/route.ts, app/api/recommendations/apply/route.ts

• AI domain: lib/ai/recommendation.ts, lib/ai/fallback.ts, lib/ai/validation.ts

• Student presentation: components/planner/ai-recommendation-modal.tsx, components/planner/ai-roadmap-view.tsx

The recommendation flow generates a proposed roadmap, validates it, presents it to the student, then applies accepted changes through a distinct endpoint.

Reviews, Professors, and Dashboard Aggregation

Reviews and professor data are separate student-facing domains. The dashboard aggregates plan summary, eligible courses, deadlines, and statistics rather than owning those source records.

• Reviews: app/(student)/reviews/page.tsx, app/api/reviews/courses/route.ts, app/api/reviews/professors/route.ts

• Professors: app/(student)/professors/page.tsx, app/api/professors/route.ts

• Dashboard: app/(student)/dashboard/page.tsx, lib/data/dashboard.ts, app/(student)/dashboard/components/PlanSummary.tsx

Persistence, Tenancy, and Administration

Prisma is the persistence boundary, with migrations showing evolving relational data, reviews, onboarding, department requirements, and multi-tenant/super-admin support. Admin APIs manage courses, users, universities, departments, and statistics; audit logging is available for sensitive operations.

• Database: prisma/schema.prisma, lib/prisma.ts, prisma/migrations/20260313153000_migrate_to_relational/migration.sql

• Admin APIs: app/api/admin/courses/route.ts, app/api/admin/universities/route.ts, app/api/admin/users/route.ts

• Cross-cutting controls: lib/auth.ts, lib/auth-utils.ts, lib/audit-logger.ts