# vindyang/planr architecture

> Architecture diagram of the GitHub repository vindyang/planr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vindyang/planr
- Repository: https://github.com/vindyang/planr

## Overview

#### 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`

Main entry points: [`prisma/schema.prisma`](https://github.com/vindyang/planr/blob/main/prisma/schema.prisma) (Prisma database), [`app/(student)/layout.tsx`](https://github.com/vindyang/planr/blob/main/app/(student)/layout.tsx) (Student shell), [`app/api/admin/universities/route.ts`](https://github.com/vindyang/planr/blob/main/app/api/admin/universities/route.ts) (Admin management API), [`app/layout.tsx`](https://github.com/vindyang/planr/blob/main/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_root["App shell<br/>Next.js entry<br/>[layout.tsx]"]
  node_auth_ui["Authentication UI<br/>route layout<br/>[layout.tsx]"]
  node_student_shell["Student shell<br/>route layout<br/>[layout.tsx]"]
  node_course_ui["Course discovery<br/>student page<br/>[page.tsx]"]
  node_planner_ui["Planner workspace<br/>client workflow<br/>[PlannerClient.tsx]"]
  node_dashboard_ui["Student dashboard<br/>student page<br/>[page.tsx]"]
  node_reviews_ui["Reviews<br/>student page<br/>[page.tsx]"]
  node_admin_shell["Admin tenant shell<br/>route layout<br/>[layout.tsx]"]
end

subgraph group_api["Server APIs"]
  node_auth_api["Auth API<br/>auth endpoint<br/>[route.ts]"]
  node_course_api["Courses &amp; eligibility API<br/>HTTP endpoints<br/>[route.ts]"]
  node_planner_api["Planner API<br/>HTTP endpoints<br/>[route.ts]"]
  node_recommendation_api["Recommendations API<br/>HTTP endpoints<br/>[route.ts]"]
  node_admin_api["Admin management API<br/>HTTP endpoints<br/>[route.ts]"]
end

subgraph group_domain["Domain Services"]
  node_eligibility{{"Eligibility engine<br/>domain service<br/>[service.ts]"}}
  node_planner_validation{{"Plan validation<br/>validator pipeline<br/>[index.ts]"}}
  node_ai_recommendations{{"AI recommendation boundary<br/>AI service<br/>[recommendation.ts]"}}
  node_dashboard_data["Dashboard aggregation<br/>data service<br/>[dashboard.ts]"]
end

subgraph group_platform["Platform Controls"]
  node_access_control{{"Access control<br/>authorization service<br/>[access-control.ts]"}}
  node_audit["Audit logger<br/>audit service<br/>[audit-logger.ts]"]
  node_database[("Prisma database<br/>persistence boundary<br/>[schema.prisma]")]
end

node_root --> node_auth_ui
node_root --> node_student_shell
node_root --> node_admin_shell
node_auth_ui -->|"sign-in"| node_auth_api
node_student_shell --> node_course_ui
node_student_shell --> node_planner_ui
node_student_shell --> node_dashboard_ui
node_student_shell --> node_reviews_ui
node_course_ui -->|"courses and eligibility"| node_course_api
node_course_api -->|"evaluate"| node_eligibility
node_eligibility -->|"rules and records"| node_database
node_planner_ui -->|"plan changes"| node_planner_api
node_planner_api -->|"validate plan"| node_planner_validation
node_planner_validation -->|"plan and course data"| node_database
node_planner_api -->|"persist plan"| node_database
node_planner_ui -->|"request or apply roadmap"| node_recommendation_api
node_recommendation_api -->|"generate and validate"| node_ai_recommendations
node_ai_recommendations -->|"check proposal"| node_planner_validation
node_dashboard_ui -->|"summary"| node_dashboard_data
node_dashboard_data -->|"aggregate"| node_database
node_reviews_ui -.->|"reviews and professors"| node_database
node_admin_shell -->|"authorize tenant role"| node_access_control
node_admin_shell -->|"manage tenant"| node_admin_api
node_admin_api -->|"enforce permissions"| node_access_control
node_admin_api -->|"manage records"| node_database
node_admin_api -->|"sensitive actions"| node_audit
node_auth_api -->|"identity records"| node_database

click node_root "https://github.com/vindyang/planr/blob/main/app/layout.tsx"
click node_auth_ui "https://github.com/vindyang/planr/blob/main/app/(auth)/layout.tsx"
click node_student_shell "https://github.com/vindyang/planr/blob/main/app/(student)/layout.tsx"
click node_course_ui "https://github.com/vindyang/planr/blob/main/app/(student)/courses/page.tsx"
click node_planner_ui "https://github.com/vindyang/planr/blob/main/app/(student)/planner/PlannerClient.tsx"
click node_dashboard_ui "https://github.com/vindyang/planr/blob/main/app/(student)/dashboard/page.tsx"
click node_reviews_ui "https://github.com/vindyang/planr/blob/main/app/(student)/reviews/page.tsx"
click node_admin_shell "https://github.com/vindyang/planr/blob/main/app/admin/%5Buniversity%5D/layout.tsx"
click node_auth_api "https://github.com/vindyang/planr/blob/main/app/api/auth/%5B...all%5D/route.ts"
click node_course_api "https://github.com/vindyang/planr/blob/main/app/api/courses/%5Bid%5D/eligibility/route.ts"
click node_planner_api "https://github.com/vindyang/planr/blob/main/app/api/planner/route.ts"
click node_recommendation_api "https://github.com/vindyang/planr/blob/main/app/api/recommendations/route.ts"
click node_admin_api "https://github.com/vindyang/planr/blob/main/app/api/admin/universities/route.ts"
click node_eligibility "https://github.com/vindyang/planr/blob/main/lib/eligibility/service.ts"
click node_planner_validation "https://github.com/vindyang/planr/blob/main/lib/planner/validation/index.ts"
click node_ai_recommendations "https://github.com/vindyang/planr/blob/main/lib/ai/recommendation.ts"
click node_dashboard_data "https://github.com/vindyang/planr/blob/main/lib/data/dashboard.ts"
click node_access_control "https://github.com/vindyang/planr/blob/main/lib/access-control.ts"
click node_audit "https://github.com/vindyang/planr/blob/main/lib/audit-logger.ts"
click node_database "https://github.com/vindyang/planr/blob/main/prisma/schema.prisma"

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_root,node_auth_ui,node_student_shell,node_course_ui,node_planner_ui,node_dashboard_ui,node_reviews_ui,node_admin_shell toneBlue
class node_auth_api,node_course_api,node_planner_api,node_recommendation_api,node_admin_api toneAmber
class node_eligibility,node_planner_validation,node_ai_recommendations,node_dashboard_data toneMint
class node_access_control,node_audit,node_database toneRose
```

## Components

### Next.js UI

Role-scoped App Router experiences.

- [App shell](https://github.com/vindyang/planr/blob/main/app/layout.tsx): Next.js entry · `app/layout.tsx`
- [Authentication UI](https://github.com/vindyang/planr/blob/main/app/(auth)/layout.tsx): route layout · `app/(auth)/layout.tsx`
- [Student shell](https://github.com/vindyang/planr/blob/main/app/(student)/layout.tsx): route layout · Student navigation and role-specific UI boundary. · `app/(student)/layout.tsx`
- [Course discovery](https://github.com/vindyang/planr/blob/main/app/(student)/courses/page.tsx): student page · `app/(student)/courses/page.tsx`
- [Planner workspace](https://github.com/vindyang/planr/blob/main/app/(student)/planner/PlannerClient.tsx): client workflow · Interactive semester planning and validation display. · `app/(student)/planner/PlannerClient.tsx`
- [Student dashboard](https://github.com/vindyang/planr/blob/main/app/(student)/dashboard/page.tsx): student page · `app/(student)/dashboard/page.tsx`
- [Reviews](https://github.com/vindyang/planr/blob/main/app/(student)/reviews/page.tsx): student page · `app/(student)/reviews/page.tsx`
- [Admin tenant shell](https://github.com/vindyang/planr/blob/main/app/admin/%5Buniversity%5D/layout.tsx): route layout · University-scoped administrative boundary. · `app/admin/[university]/layout.tsx`

### Server APIs

HTTP mutation and query boundaries.

- [Auth API](https://github.com/vindyang/planr/blob/main/app/api/auth/%5B...all%5D/route.ts): auth endpoint · `app/api/auth/[...all]/route.ts`
- [Courses & eligibility API](https://github.com/vindyang/planr/blob/main/app/api/courses/%5Bid%5D/eligibility/route.ts): HTTP endpoints · Returns course data and student-specific eligibility. · `app/api/courses/[id]/eligibility/route.ts`
- [Planner API](https://github.com/vindyang/planr/blob/main/app/api/planner/route.ts): HTTP endpoints · Reads and persists semesters and scheduled courses. · `app/api/planner/route.ts`
- [Recommendations API](https://github.com/vindyang/planr/blob/main/app/api/recommendations/route.ts): HTTP endpoints · Generates and separately applies accepted roadmaps. · `app/api/recommendations/route.ts`
- [Admin management API](https://github.com/vindyang/planr/blob/main/app/api/admin/universities/route.ts): HTTP endpoints · Manages tenant courses, users, and universities. · `app/api/admin/universities/route.ts`

### Domain Services

Planning, eligibility, AI, and data composition.

- [Eligibility engine](https://github.com/vindyang/planr/blob/main/lib/eligibility/service.ts): domain service · Evaluates prerequisites and academic rules per student. · `lib/eligibility/service.ts`
- [Plan validation](https://github.com/vindyang/planr/blob/main/lib/planner/validation/index.ts): validator pipeline · Combines prerequisite, corequisite, duplicate, term, and load checks. · `lib/planner/validation/index.ts`
- [AI recommendation boundary](https://github.com/vindyang/planr/blob/main/lib/ai/recommendation.ts): AI service · Validates generated roadmaps and provides fallback output. · `lib/ai/recommendation.ts`
- [Dashboard aggregation](https://github.com/vindyang/planr/blob/main/lib/data/dashboard.ts): data service · Composes plan, eligibility, deadline, and statistics summaries. · `lib/data/dashboard.ts`

### Platform Controls

Authentication, authorization, auditing, and persistence.

- [Access control](https://github.com/vindyang/planr/blob/main/lib/access-control.ts): authorization service · `lib/access-control.ts`
- [Audit logger](https://github.com/vindyang/planr/blob/main/lib/audit-logger.ts): audit service · Records sensitive administrative operations. · `lib/audit-logger.ts`
- [Prisma database](https://github.com/vindyang/planr/blob/main/prisma/schema.prisma): persistence boundary · Relational multi-tenant academic and review data. · `prisma/schema.prisma`

## Connections

- App shell → Authentication UI
- App shell → Student shell
- App shell → Admin tenant shell
- Authentication UI → Auth API: sign-in
- Student shell → Course discovery
- Student shell → Planner workspace
- Student shell → Student dashboard
- Student shell → Reviews
- Course discovery → Courses & eligibility API: courses and eligibility
- Courses & eligibility API → Eligibility engine: evaluate
- Eligibility engine → Prisma database: rules and records
- Planner workspace → Planner API: plan changes
- Planner API → Plan validation: validate plan
- Plan validation → Prisma database: plan and course data
- Planner API → Prisma database: persist plan
- Planner workspace → Recommendations API: request or apply roadmap
- Recommendations API → AI recommendation boundary: generate and validate
- AI recommendation boundary → Plan validation: check proposal
- Student dashboard → Dashboard aggregation: summary
- Dashboard aggregation → Prisma database: aggregate
- Reviews → Prisma database: reviews and professors
- Admin tenant shell → Access control: authorize tenant role
- Admin tenant shell → Admin management API: manage tenant
- Admin management API → Access control: enforce permissions
- Admin management API → Prisma database: manage records
- Admin management API → Audit logger: sensitive actions
- Auth API → Prisma database: identity records