# sandboxnu/searchneu architecture

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

- Interactive diagram: https://gitdiagram.com/sandboxnu/searchneu
- Repository: https://github.com/sandboxnu/searchneu

## Overview

SearchNEU is Northeastern University’s course-information platform. Its central workflow is to browse or search course offerings, inspect sections and meeting details, and use those offerings in a schedule; the app also supports degree planning, saved schedules, and seat notifications. The data lifecycle begins with scraping Banner, validating and caching catalog data, then uploading it to PostgreSQL for application use. The graph preserves those documented capabilities, but several web-to-database and UI-to-API links are only shown as unverified because sampled route excerpts do not expose their wiring.

Main entry points: [`packages/db/src/neon.ts`](https://github.com/sandboxnu/searchneu/blob/main/packages/db/src/neon.ts) (PostgreSQL), [`packages/scraper/src/generate/main.ts`](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/main.ts) (Banner scraping), [`apps/searchneu/app/api/scheduler/generate-schedules/route.ts`](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/scheduler/generate-schedules/route.ts) (Schedule APIs), [`packages/scraper/src/upload/main.ts`](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/upload/main.ts) (Catalog upload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Catalog and scheduling"]
  node_catalog_ui["Course catalog<br/>[page.tsx]"]
  node_catalog_api["Catalog APIs<br/>[route.ts]"]
  node_scheduler_ui["Schedule generator<br/>[page.tsx]"]
  node_scheduler_api["Schedule APIs<br/>[route.ts]"]
  node_scheduler_logic["Schedule generation"]
end

subgraph group_planning["Plans and identity"]
  node_audit_ui["Degree plans<br/>[PlanClient.tsx]"]
  node_audit_api["Audit APIs<br/>[route.ts]"]
  node_audit_logic["Audit utilities<br/>[auditUtils.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

subgraph group_ingest["Catalog ingestion"]
  node_scraper_generate["Banner scraping<br/>[main.ts]"]
  node_scraper_fetch["Fetch engine<br/>[fetch.ts]"]
  node_scraper_steps["Scrape steps<br/>[sections.ts]"]
  node_cache_schema["Cache validation<br/>[banner-cache.ts]"]
  node_cli_generate["Generate command<br/>[generate.ts]"]
  node_cli_upload["Upload command<br/>[upload.ts]"]
  node_upload_main["Catalog upload<br/>[main.ts]"]
  node_upload_sections["Section persistence<br/>[sections.ts]"]
end

subgraph group_data["Persistent data"]
  node_db_schema["Database schema<br/>[catalog.ts]"]
  node_postgres[("PostgreSQL<br/>[neon.ts]")]
end

subgraph group_updates["Seat updates"]
  node_tracker_api["Seat trackers<br/>[route.ts]"]
  node_notifications["SMS notifications<br/>[twilio.ts]"]
  node_cron_update["Scheduled updates<br/>[route.ts]"]
  node_update_logic["Term comparison<br/>[main.ts]"]
end

node_student(("Student"))
node_banner{{"Banner"}}

node_student -->|"browses"| node_catalog_ui
node_student -->|"builds schedules"| node_scheduler_ui
node_catalog_ui -.->|"loads catalog"| node_catalog_api
node_scheduler_ui -.->|"requests schedules"| node_scheduler_api
node_scheduler_api -.->|"generates schedules"| node_scheduler_logic
node_student -->|"plans degree"| node_audit_ui
node_audit_ui -.->|"manages plans"| node_audit_api
node_student -.->|"signs in"| node_auth
node_student -.->|"tracks sections"| node_tracker_api
node_cron_update -->|"updates term"| node_update_logic
node_update_logic -->|"scrapes sections"| node_scraper_steps
node_cron_update -->|"sends alerts"| node_notifications
node_cli_generate -->|"runs scrape"| node_scraper_generate
node_scraper_generate -->|"scrapes sections"| node_scraper_steps
node_scraper_steps -->|"fetches Banner"| node_scraper_fetch
node_scraper_generate -->|"requests catalog"| node_banner
node_scraper_generate -->|"produces cache"| node_cache_schema
node_cli_upload -->|"runs upload"| node_upload_main
node_upload_main -->|"upserts sections"| node_upload_sections
node_upload_main -->|"writes catalog"| node_postgres
node_upload_sections -->|"reads cache"| node_cache_schema
node_db_schema -.->|"defines tables"| node_postgres
node_catalog_api -.->|"reads catalog"| node_postgres
node_scheduler_api -.->|"stores schedules"| node_postgres
node_audit_api -.->|"stores plans"| node_postgres

click node_catalog_ui "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/catalog/%5Bterm%5D/%5Bcourse%5D/page.tsx"
click node_catalog_api "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/catalog/courses/route.ts"
click node_scheduler_ui "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/scheduler/generator/page.tsx"
click node_scheduler_api "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/scheduler/generate-schedules/route.ts"
click node_scheduler_logic "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/scheduler/generateSchedules.ts"
click node_audit_ui "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/components/graduate/PlanClient.tsx"
click node_audit_api "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/audit/plan/route.ts"
click node_audit_logic "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/graduate/auditUtils.ts"
click node_auth "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/auth/auth.ts"
click node_tracker_api "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/trackers/route.ts"
click node_notifications "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/trackers/twilio.ts"
click node_cron_update "https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/update/route.ts"
click node_scraper_generate "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/main.ts"
click node_scraper_fetch "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/fetch.ts"
click node_scraper_steps "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/steps/sections.ts"
click node_cache_schema "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/schemas/scraper/banner-cache.ts"
click node_cli_generate "https://github.com/sandboxnu/searchneu/blob/main/apps/cli/src/commands/generate.ts"
click node_cli_upload "https://github.com/sandboxnu/searchneu/blob/main/apps/cli/src/commands/upload.ts"
click node_upload_main "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/upload/main.ts"
click node_upload_sections "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/upload/steps/sections.ts"
click node_db_schema "https://github.com/sandboxnu/searchneu/blob/main/packages/db/src/schema/catalog.ts"
click node_postgres "https://github.com/sandboxnu/searchneu/blob/main/packages/db/src/neon.ts"
click node_update_logic "https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/update/main.ts"

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_catalog_ui,node_catalog_api,node_scheduler_ui,node_scheduler_api,node_scheduler_logic toneBlue
class node_audit_ui,node_audit_api,node_audit_logic,node_auth toneAmber
class node_scraper_generate,node_scraper_fetch,node_scraper_steps,node_cache_schema,node_cli_generate,node_cli_upload,node_upload_main,node_upload_sections toneMint
class node_db_schema,node_postgres toneRose
class node_tracker_api,node_notifications,node_cron_update,node_update_logic,node_student,node_banner toneIndigo
```

## Components

### Catalog and scheduling

- [Course catalog](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/catalog/%5Bterm%5D/%5Bcourse%5D/page.tsx): `apps/searchneu/app/catalog/[term]/[course]/page.tsx`
- [Catalog APIs](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/catalog/courses/route.ts): `apps/searchneu/app/api/catalog/courses/route.ts`
- [Schedule generator](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/scheduler/generator/page.tsx): `apps/searchneu/app/scheduler/generator/page.tsx`
- [Schedule APIs](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/scheduler/generate-schedules/route.ts): `apps/searchneu/app/api/scheduler/generate-schedules/route.ts`
- [Schedule generation](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/scheduler/generateSchedules.ts): `apps/searchneu/lib/scheduler/generateSchedules.ts`

### Plans and identity

- [Degree plans](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/components/graduate/PlanClient.tsx): `apps/searchneu/components/graduate/PlanClient.tsx`
- [Audit APIs](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/audit/plan/route.ts): `apps/searchneu/app/api/audit/plan/route.ts`
- [Audit utilities](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/graduate/auditUtils.ts): `apps/searchneu/lib/graduate/auditUtils.ts`
- [Authentication](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/auth/auth.ts): `apps/searchneu/lib/auth/auth.ts`

### Catalog ingestion

- [Banner scraping](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/main.ts): `packages/scraper/src/generate/main.ts`
- [Fetch engine](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/fetch.ts): `packages/scraper/src/generate/fetch.ts`
- [Scrape steps](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/generate/steps/sections.ts): `packages/scraper/src/generate/steps/sections.ts`
- [Cache validation](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/schemas/scraper/banner-cache.ts): `packages/scraper/src/schemas/scraper/banner-cache.ts`
- [Generate command](https://github.com/sandboxnu/searchneu/blob/main/apps/cli/src/commands/generate.ts): `apps/cli/src/commands/generate.ts`
- [Upload command](https://github.com/sandboxnu/searchneu/blob/main/apps/cli/src/commands/upload.ts): `apps/cli/src/commands/upload.ts`
- [Catalog upload](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/upload/main.ts): `packages/scraper/src/upload/main.ts`
- [Section persistence](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/upload/steps/sections.ts): `packages/scraper/src/upload/steps/sections.ts`

### Persistent data

- [Database schema](https://github.com/sandboxnu/searchneu/blob/main/packages/db/src/schema/catalog.ts): `packages/db/src/schema/catalog.ts`
- [PostgreSQL](https://github.com/sandboxnu/searchneu/blob/main/packages/db/src/neon.ts): `packages/db/src/neon.ts`

### Seat updates

- [Seat trackers](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/trackers/route.ts): `apps/searchneu/app/api/trackers/route.ts`
- [SMS notifications](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/lib/trackers/twilio.ts): `apps/searchneu/lib/trackers/twilio.ts`
- [Scheduled updates](https://github.com/sandboxnu/searchneu/blob/main/apps/searchneu/app/api/update/route.ts): `apps/searchneu/app/api/update/route.ts`
- [Term comparison](https://github.com/sandboxnu/searchneu/blob/main/packages/scraper/src/update/main.ts): `packages/scraper/src/update/main.ts`

### Other components

- **Student**
- **Banner**

## Connections

- Student → Course catalog: browses (evidence: `README.md`)
- Student → Schedule generator: builds schedules (evidence: `README.md`)
- Course catalog → Catalog APIs: loads catalog
- Schedule generator → Schedule APIs: requests schedules
- Schedule APIs → Schedule generation: generates schedules
- Student → Degree plans: plans degree (evidence: `README.md`)
- Degree plans → Audit APIs: manages plans
- Student → Authentication: signs in
- Student → Seat trackers: tracks sections
- Scheduled updates → Term comparison: updates term (evidence: `apps/searchneu/app/api/update/route.ts`)
- Term comparison → Scrape steps: scrapes sections (evidence: `packages/scraper/src/update/main.ts`)
- Scheduled updates → SMS notifications: sends alerts (evidence: `apps/searchneu/app/api/update/route.ts`)
- Generate command → Banner scraping: runs scrape (evidence: `README.md`)
- Banner scraping → Scrape steps: scrapes sections (evidence: `packages/scraper/src/generate/main.ts`)
- Scrape steps → Fetch engine: fetches Banner (evidence: `packages/scraper/src/generate/steps/sections.ts`)
- Banner scraping → Banner: requests catalog
- Banner scraping → Cache validation: produces cache (evidence: `packages/scraper/src/generate/main.ts`)
- Upload command → Catalog upload: runs upload (evidence: `apps/cli/src/commands/upload.ts`)
- Catalog upload → Section persistence: upserts sections (evidence: `packages/scraper/src/upload/main.ts`)
- Catalog upload → PostgreSQL: writes catalog (evidence: `packages/scraper/src/upload/main.ts`)
- Section persistence → Cache validation: reads cache (evidence: `packages/scraper/src/upload/steps/sections.ts`)
- Database schema → PostgreSQL: defines tables
- Catalog APIs → PostgreSQL: reads catalog
- Schedule APIs → PostgreSQL: stores schedules
- Audit APIs → PostgreSQL: stores plans
