# lissjackb/swat-hackrack architecture

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

- Interactive diagram: https://gitdiagram.com/lissjackb/swat-hackrack
- Repository: https://github.com/lissjackb/swat-hackrack

## Overview

Hackro is a dining-hall plate recommender and meal tracker for Tri-Co students. A student supplies profile goals and restrictions, gets macro targets, and can request a meal-specific plate built from the day's menu; they can log what they ate and review daily or weekly progress. Menu scraping and USDA enrichment supply nutrition data, while Claude explains recommendations and WHOOP can optionally adjust targets using recovery and strain. Routes own the visible orchestration; some connections for unsampled handlers are based on the README or SOURCE INDEX, not inspected implementation.

Main entry points: [`src/lib/db.ts`](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/db.ts) (Database client), [`src/app/(ui)/page.tsx`](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/(ui)/page.tsx) (App screen), [`src/app/api/recommend/route.ts`](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/recommend/route.ts) (Recommendation API), [`src/app/api/progress/route.ts`](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/progress/route.ts) (Progress API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student experience"]
  node_screen["App screen<br/>[page.tsx]"]
  node_targets_api["Targets API<br/>[route.ts]"]
  node_menu_api["Menu API<br/>[route.ts]"]
  node_recommend_api["Recommendation API<br/>[route.ts]"]
end

subgraph group_nutrition["Nutrition planning"]
  node_targets_logic["Macro targets<br/>[targets.ts]"]
  node_plate_solver["Plate optimizer<br/>[recommend.ts]"]
  node_plate_explainer["Plate explanation<br/>[claude.ts]"]
  node_shared_types["Shared data types<br/>[types.ts]"]
end

subgraph group_menu["Menu and nutrition data"]
  node_menu_scraper["Menu scraper<br/>[scrape.ts]"]
  node_nutrition_api["Nutrition enrichment API<br/>[route.ts]"]
  node_database_client["Database client<br/>[db.ts]"]
  node_database[("SQLite data<br/>[schema.prisma]")]
  node_menu_snapshot["Menu snapshot<br/>[menu-snapshot.json]"]
end

subgraph group_tracking["Meal tracking"]
  node_log_api["Meal log API<br/>[route.ts]"]
  node_progress_api["Progress API<br/>[route.ts]"]
  node_progress_logic["Progress calculations<br/>[progress.ts]"]
end

subgraph group_integrations["External integrations"]
  node_usda_lookup["USDA lookup<br/>[usda.ts]"]
  node_whoop_api["WHOOP API<br/>[route.ts]"]
  node_whoop_oauth["WHOOP OAuth and fetch<br/>[whoop.ts]"]
  node_whoop_connect["WHOOP connect and callback<br/>[route.ts]"]
  node_whoop_callback["WHOOP callback<br/>[route.ts]"]
  node_swat_feed["Swarthmore menu feed"]
  node_usda["USDA FoodData Central"]
  node_anthropic["Anthropic Claude"]
  node_whoop_service["WHOOP service"]
end

node_student(("Student"))

node_student -->|"uses"| node_screen
node_screen -.->|"requests targets"| node_targets_api
node_screen -.->|"requests menu"| node_menu_api
node_screen -.->|"requests plate"| node_recommend_api
node_screen -.->|"logs meal"| node_log_api
node_screen -.->|"views progress"| node_progress_api
node_targets_api -->|"computes targets"| node_targets_logic
node_recommend_api -->|"optimizes plate"| node_plate_solver
node_recommend_api -->|"requests explanation"| node_plate_explainer
node_plate_explainer -.->|"generates note"| node_anthropic
node_recommend_api -->|"loads menu"| node_database_client
node_menu_api -->|"reads menu"| node_database_client
node_menu_scraper -->|"fetches menu"| node_swat_feed
node_menu_scraper -->|"falls back"| node_menu_snapshot
node_menu_scraper -->|"stores menu"| node_database_client
node_nutrition_api -->|"reads and updates"| node_database_client
node_nutrition_api -->|"looks up nutrition"| node_usda_lookup
node_usda_lookup -.->|"queries"| node_usda
node_whoop_api -->|"fetches live data"| node_whoop_oauth
node_whoop_api -->|"reads and caches"| node_database_client
node_whoop_oauth -->|"requests data"| node_whoop_service
node_whoop_connect -->|"starts consent"| node_whoop_oauth
node_whoop_callback -->|"exchanges code"| node_whoop_oauth
node_progress_api -->|"loads history"| node_database_client
node_progress_api -->|"computes targets"| node_targets_logic
node_progress_api -->|"calculates progress"| node_progress_logic
node_log_api -->|"stores and reads logs"| node_database_client
node_targets_logic -->|"uses types"| node_shared_types
node_plate_solver -->|"uses types"| node_shared_types
node_database_client -.->|"accesses"| node_database
node_targets_api -.->|"uses recovery"| node_whoop_api

click node_screen "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/(ui)/page.tsx"
click node_targets_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/targets/route.ts"
click node_menu_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/menu/route.ts"
click node_recommend_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/recommend/route.ts"
click node_log_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/log/route.ts"
click node_progress_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/progress/route.ts"
click node_targets_logic "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/targets.ts"
click node_plate_solver "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/recommend.ts"
click node_plate_explainer "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/claude.ts"
click node_shared_types "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/types.ts"
click node_menu_scraper "https://github.com/lissjackb/swat-hackrack/blob/main/scripts/scrape.ts"
click node_nutrition_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/nutrition/route.ts"
click node_usda_lookup "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/usda.ts"
click node_whoop_api "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/whoop/route.ts"
click node_whoop_oauth "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/whoop.ts"
click node_whoop_connect "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/whoop/connect/route.ts"
click node_whoop_callback "https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/whoop/callback/route.ts"
click node_progress_logic "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/progress.ts"
click node_database_client "https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/db.ts"
click node_database "https://github.com/lissjackb/swat-hackrack/blob/main/prisma/schema.prisma"
click node_menu_snapshot "https://github.com/lissjackb/swat-hackrack/blob/main/data/menu-snapshot.json"

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_screen,node_targets_api,node_menu_api,node_recommend_api toneBlue
class node_targets_logic,node_plate_solver,node_plate_explainer,node_shared_types toneAmber
class node_menu_scraper,node_nutrition_api,node_database_client,node_database,node_menu_snapshot toneMint
class node_log_api,node_progress_api,node_progress_logic toneRose
class node_usda_lookup,node_whoop_api,node_whoop_oauth,node_whoop_connect,node_whoop_callback,node_swat_feed,node_usda,node_anthropic,node_whoop_service,node_student toneIndigo
```

## Components

### Student experience

- [App screen](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/(ui)/page.tsx): `src/app/(ui)/page.tsx`
- [Targets API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/targets/route.ts): `src/app/api/targets/route.ts`
- [Menu API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/menu/route.ts): `src/app/api/menu/route.ts`
- [Recommendation API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/recommend/route.ts): `src/app/api/recommend/route.ts`

### Nutrition planning

- [Macro targets](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/targets.ts): `src/lib/targets.ts`
- [Plate optimizer](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/recommend.ts): `src/lib/recommend.ts`
- [Plate explanation](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/claude.ts): `src/lib/claude.ts`
- [Shared data types](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/types.ts): `src/lib/types.ts`

### Menu and nutrition data

- [Menu scraper](https://github.com/lissjackb/swat-hackrack/blob/main/scripts/scrape.ts): `scripts/scrape.ts`
- [Nutrition enrichment API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/nutrition/route.ts): `src/app/api/nutrition/route.ts`
- [Database client](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [SQLite data](https://github.com/lissjackb/swat-hackrack/blob/main/prisma/schema.prisma): `prisma/schema.prisma`
- [Menu snapshot](https://github.com/lissjackb/swat-hackrack/blob/main/data/menu-snapshot.json): `data/menu-snapshot.json`

### Meal tracking

- [Meal log API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/log/route.ts): `src/app/api/log/route.ts`
- [Progress API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/progress/route.ts): `src/app/api/progress/route.ts`
- [Progress calculations](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/progress.ts): `src/lib/progress.ts`

### External integrations

- [USDA lookup](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/usda.ts): `src/lib/usda.ts`
- [WHOOP API](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/whoop/route.ts): `src/app/api/whoop/route.ts`
- [WHOOP OAuth and fetch](https://github.com/lissjackb/swat-hackrack/blob/main/src/lib/whoop.ts): `src/lib/whoop.ts`
- [WHOOP connect and callback](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/whoop/connect/route.ts): `src/app/api/whoop/connect/route.ts`
- [WHOOP callback](https://github.com/lissjackb/swat-hackrack/blob/main/src/app/api/whoop/callback/route.ts): `src/app/api/whoop/callback/route.ts`
- **Swarthmore menu feed**
- **USDA FoodData Central**
- **Anthropic Claude**
- **WHOOP service**

### Other components

- **Student**

## Connections

- Student → App screen: uses (evidence: `README.md`)
- App screen → Targets API: requests targets
- App screen → Menu API: requests menu
- App screen → Recommendation API: requests plate
- App screen → Meal log API: logs meal
- App screen → Progress API: views progress
- Targets API → Macro targets: computes targets (evidence: `README.md`)
- Recommendation API → Plate optimizer: optimizes plate (evidence: `src/app/api/recommend/route.ts`)
- Recommendation API → Plate explanation: requests explanation (evidence: `src/app/api/recommend/route.ts`)
- Plate explanation → Anthropic Claude: generates note
- Recommendation API → Database client: loads menu (evidence: `src/app/api/recommend/route.ts`)
- Menu API → Database client: reads menu (evidence: `src/app/api/menu/route.ts`)
- Menu scraper → Swarthmore menu feed: fetches menu (evidence: `README.md`)
- Menu scraper → Menu snapshot: falls back (evidence: `README.md`)
- Menu scraper → Database client: stores menu (evidence: `scripts/scrape.ts`)
- Nutrition enrichment API → Database client: reads and updates (evidence: `src/app/api/nutrition/route.ts`)
- Nutrition enrichment API → USDA lookup: looks up nutrition (evidence: `src/app/api/nutrition/route.ts`)
- USDA lookup → USDA FoodData Central: queries
- WHOOP API → WHOOP OAuth and fetch: fetches live data (evidence: `src/app/api/whoop/route.ts`)
- WHOOP API → Database client: reads and caches (evidence: `src/app/api/whoop/route.ts`)
- WHOOP OAuth and fetch → WHOOP service: requests data (evidence: `src/lib/whoop.ts`)
- WHOOP connect and callback → WHOOP OAuth and fetch: starts consent (evidence: `src/app/api/whoop/connect/route.ts`)
- WHOOP callback → WHOOP OAuth and fetch: exchanges code (evidence: `src/app/api/whoop/callback/route.ts`)
- Progress API → Database client: loads history (evidence: `src/app/api/progress/route.ts`)
- Progress API → Macro targets: computes targets (evidence: `src/app/api/progress/route.ts`)
- Progress API → Progress calculations: calculates progress (evidence: `src/app/api/progress/route.ts`)
- Meal log API → Database client: stores and reads logs (evidence: `src/app/api/log/route.ts`)
- Macro targets → Shared data types: uses types (evidence: `src/lib/targets.ts`)
- Plate optimizer → Shared data types: uses types (evidence: `src/lib/recommend.ts`)
- Database client → SQLite data: accesses
- Targets API → WHOOP API: uses recovery