# hoagieclub/plan architecture

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

- Interactive diagram: https://gitdiagram.com/hoagieclub/plan
- Repository: https://github.com/hoagieclub/plan

## Overview

HoagiePlan is a Princeton academic planner: students search courses, organize them in a dashboard and semester bins, track program progress, and build calendars. The frontend sends backend requests through a Next.js proxy; the sampled search endpoint queries course records and serializes results. The tree documents additional calendar, profile, and program-guidance areas. Backend endpoint wiring beyond the sampled search code is not verified here; README describes CAS, while the sampled frontend proxy obtains an Auth0 access token.

Main entry points: [`frontend/app/api/hoagie/[...path]/route.ts`](https://github.com/hoagieclub/plan/blob/main/frontend/app/api/hoagie/%5B...path%5D/route.ts) (API proxy), [`backend/hoagieplan/models.py`](https://github.com/hoagieclub/plan/blob/main/backend/hoagieplan/models.py) (Course records), [`frontend/components/ReviewMenu.tsx`](https://github.com/hoagieclub/plan/blob/main/frontend/components/ReviewMenu.tsx) (Course reviews), [`frontend/app/dashboard/page.tsx`](https://github.com/hoagieclub/plan/blob/main/frontend/app/dashboard/page.tsx) (Planning dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student experience"]
  node_dashboard["Planning dashboard<br/>[page.tsx]"]
  node_dashboard_canvas["Dashboard canvas<br/>[Canvas.tsx]"]
  node_calendar_ui["Calendar planner<br/>[Calendar.tsx]"]
  node_course_search["Course search<br/>[CalendarSearch.tsx]"]
  node_program_modal["Near completion"]
  node_review_menu["Course reviews<br/>[ReviewMenu.tsx]"]
end

subgraph group_transport["Request and identity"]
  node_proxy["API proxy<br/>[route.ts]"]
  node_auth["Auth0 client<br/>[auth0.ts]"]
  node_django["Django API<br/>[urls.py]"]
end

subgraph group_academic["Academic planning"]
  node_search_api["Course search API<br/>[search.py]"]
  node_calendar_api["Calendar API"]
  node_program_api["Program guidance API"]
  node_profile_api["Profile API"]
  node_calendar_service["Calendar operations<br/>[calendarService.ts]"]
  node_almost_service["Progress lookup"]
  node_program_service["Program details"]
end

subgraph group_data["Course data"]
  node_course_models["Course records<br/>[models.py]"]
  node_course_store[("Academic database")]
  node_course_data["Course data preparation"]
end

node_student(("Student"))
node_external_reviews["Reviews service"]

node_student -->|"plans courses"| node_dashboard
node_student -->|"plans schedule"| node_calendar_ui
node_dashboard -->|"renders bins"| node_dashboard_canvas
node_course_search -->|"requests courses"| node_proxy
node_calendar_service -->|"requests calendar"| node_proxy
node_almost_service -->|"requests progress"| node_proxy
node_program_service -->|"requests details"| node_proxy
node_review_menu -->|"requests reviews"| node_proxy
node_proxy -->|"gets token"| node_auth
node_proxy -->|"forwards requests"| node_django
node_django -->|"dispatches search"| node_search_api
node_search_api -->|"queries courses"| node_course_models
node_course_models -->|"reads records"| node_course_store
node_calendar_api -.->|"uses course data"| node_course_models
node_course_data -.->|"prepares records"| node_course_store
node_review_menu -.->|"fetches reviews"| node_external_reviews

click node_dashboard "https://github.com/hoagieclub/plan/blob/main/frontend/app/dashboard/page.tsx"
click node_dashboard_canvas "https://github.com/hoagieclub/plan/blob/main/frontend/app/dashboard/Canvas.tsx"
click node_calendar_ui "https://github.com/hoagieclub/plan/blob/main/frontend/app/calendar/Calendar.tsx"
click node_course_search "https://github.com/hoagieclub/plan/blob/main/frontend/app/calendar/CalendarSearch.tsx"
click node_program_modal "https://github.com/hoagieclub/plan/blob/main/frontend/components/AlmostCompletedMinorsModal/AlmostCompletedMinorsModal.tsx"
click node_review_menu "https://github.com/hoagieclub/plan/blob/main/frontend/components/ReviewMenu.tsx"
click node_proxy "https://github.com/hoagieclub/plan/blob/main/frontend/app/api/hoagie/%5B...path%5D/route.ts"
click node_auth "https://github.com/hoagieclub/plan/blob/main/frontend/lib/auth0.ts"
click node_django "https://github.com/hoagieclub/plan/blob/main/backend/config/urls.py"
click node_search_api "https://github.com/hoagieclub/plan/blob/main/backend/hoagieplan/api/dashboard/search.py"
click node_calendar_api "https://github.com/hoagieclub/plan/tree/main/backend/hoagieplan/api/calendar"
click node_program_api "https://github.com/hoagieclub/plan/tree/main/backend/hoagieplan/api/dashboard"
click node_profile_api "https://github.com/hoagieclub/plan/tree/main/backend/hoagieplan/api/profile"
click node_calendar_service "https://github.com/hoagieclub/plan/blob/main/frontend/services/calendarService.ts"
click node_almost_service "https://github.com/hoagieclub/plan/blob/main/frontend/services/almostCompletedService.ts"
click node_program_service "https://github.com/hoagieclub/plan/blob/main/frontend/services/programDetailsService.ts"
click node_course_models "https://github.com/hoagieclub/plan/blob/main/backend/hoagieplan/models.py"
click node_course_data "https://github.com/hoagieclub/plan/tree/main/backend/data"

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_dashboard,node_dashboard_canvas,node_calendar_ui,node_course_search,node_program_modal,node_review_menu,node_external_reviews toneBlue
class node_proxy,node_auth,node_django toneAmber
class node_search_api,node_calendar_api,node_program_api,node_profile_api,node_calendar_service,node_almost_service,node_program_service toneMint
class node_course_models,node_course_store,node_course_data toneRose
class node_student toneIndigo
```

## Components

### Student experience

- [Planning dashboard](https://github.com/hoagieclub/plan/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Dashboard canvas](https://github.com/hoagieclub/plan/blob/main/frontend/app/dashboard/Canvas.tsx): `frontend/app/dashboard/Canvas.tsx`
- [Calendar planner](https://github.com/hoagieclub/plan/blob/main/frontend/app/calendar/Calendar.tsx): `frontend/app/calendar/Calendar.tsx`
- [Course search](https://github.com/hoagieclub/plan/blob/main/frontend/app/calendar/CalendarSearch.tsx): `frontend/app/calendar/CalendarSearch.tsx`
- [Near completion](https://github.com/hoagieclub/plan/blob/main/frontend/components/AlmostCompletedMinorsModal/AlmostCompletedMinorsModal.tsx): `frontend/components/AlmostCompletedMinorsModal/AlmostCompletedMinorsModal.tsx`
- [Course reviews](https://github.com/hoagieclub/plan/blob/main/frontend/components/ReviewMenu.tsx): `frontend/components/ReviewMenu.tsx`

### Request and identity

- [API proxy](https://github.com/hoagieclub/plan/blob/main/frontend/app/api/hoagie/%5B...path%5D/route.ts): `frontend/app/api/hoagie/[...path]/route.ts`
- [Auth0 client](https://github.com/hoagieclub/plan/blob/main/frontend/lib/auth0.ts): `frontend/lib/auth0.ts`
- [Django API](https://github.com/hoagieclub/plan/blob/main/backend/config/urls.py): `backend/config/urls.py`

### Academic planning

- [Course search API](https://github.com/hoagieclub/plan/blob/main/backend/hoagieplan/api/dashboard/search.py): `backend/hoagieplan/api/dashboard/search.py`
- [Calendar API](https://github.com/hoagieclub/plan/tree/main/backend/hoagieplan/api/calendar): `backend/hoagieplan/api/calendar`
- [Program guidance API](https://github.com/hoagieclub/plan/tree/main/backend/hoagieplan/api/dashboard): `backend/hoagieplan/api/dashboard`
- [Profile API](https://github.com/hoagieclub/plan/tree/main/backend/hoagieplan/api/profile): `backend/hoagieplan/api/profile`
- [Calendar operations](https://github.com/hoagieclub/plan/blob/main/frontend/services/calendarService.ts): `frontend/services/calendarService.ts`
- [Progress lookup](https://github.com/hoagieclub/plan/blob/main/frontend/services/almostCompletedService.ts): `frontend/services/almostCompletedService.ts`
- [Program details](https://github.com/hoagieclub/plan/blob/main/frontend/services/programDetailsService.ts): `frontend/services/programDetailsService.ts`

### Course data

- [Course records](https://github.com/hoagieclub/plan/blob/main/backend/hoagieplan/models.py): `backend/hoagieplan/models.py`
- **Academic database**
- [Course data preparation](https://github.com/hoagieclub/plan/tree/main/backend/data): `backend/data`

### Other components

- **Student**
- **Reviews service**

## Connections

- Student → Planning dashboard: plans courses
- Student → Calendar planner: plans schedule
- Planning dashboard → Dashboard canvas: renders bins
- Course search → API proxy: requests courses
- Calendar operations → API proxy: requests calendar
- Progress lookup → API proxy: requests progress
- Program details → API proxy: requests details
- Course reviews → API proxy: requests reviews
- API proxy → Auth0 client: gets token
- API proxy → Django API: forwards requests
- Django API → Course search API: dispatches search
- Course search API → Course records: queries courses
- Course records → Academic database: reads records
- Calendar API → Course records: uses course data
- Course data preparation → Academic database: prepares records
- Course reviews → Reviews service: fetches reviews