Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/react-doctor.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,16 @@ on:
pull_request:
paths:
- "apps/web/**"
- "packages/dorm/**"
- "packages/ui/**"
types: [opened, synchronize, reopened, ready_for_review]
# Scans `main` on every push to track the health-score trend and catch regressions that slipped past PR review.
push:
branches: ["main"]
paths:
- "apps/web/**"
- "packages/dorm/**"
- "packages/ui/**"

permissions:
contents: read
Expand Down
33 changes: 20 additions & 13 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# IlliniGuide agent guide

These rules apply repository-wide. `apps/web/AGENTS.md` takes precedence within
`apps/web/**`.
`apps/web/**`, and `packages/dorm/AGENTS.md` within `packages/dorm/**`.

## Project

A UIUC knowledge platform with a React 19 frontend and Cloudflare Worker gateway.
Supabase provides auth and Postgres; DeepSeek handles inference and Tavily
supplies web search.

| Path | Role |
| :-------------- | :----------------------------------------------------------------------- |
| `apps/web/` | Frontend and Worker: SPA, static assets, agent loop, tools, skills, MCP. |
| `dorm_scripts/` | Standalone Puppeteer/Bun review scrapers. |
| Path | Role |
| :--------------- | :-------------------------------------------------------------------------- |
| `apps/web/` | Frontend and Worker: SPA, static assets, agent loop, tools, skills, MCP. |
| `packages/dorm/` | Dorm feature (`@iguide/dorm`): UI, state, dorm SQL, data scripts, scrapers. |
| `packages/ui/` | Business-agnostic UI primitives shared by the app and feature packages. |

<!--VITE PLUS START-->

Expand Down Expand Up @@ -84,9 +85,14 @@ Run checks before delivery; `package.json` defines no validation scripts, so

## Architecture

- `apps/web/src` is the React 19 SPA: react-router 7, Tailwind CSS 4,
assistant-ui for chat, Mapbox GL for the dorm map, and supabase-js for auth
and user data.
- `apps/web/src` is the React 19 SPA shell: react-router 7, Tailwind CSS 4,
assistant-ui for chat, and supabase-js for auth and user data.
- `packages/dorm` (`@iguide/dorm`) is the dorm feature: list, Mapbox GL map,
detail, compare, and reviews, plus the dorm SQL, data scripts, and review
scrapers. The SPA mounts it lazily at `/dorms/*` through
`apps/web/src/pages/dorms/DormRoute.tsx`, so no other page loads dorm code or
queries dorm tables. `packages/ui` (`@iguide/ui`) holds UI primitives both
use.
- `apps/web/worker` is the Cloudflare Worker named `uiuc`. It routes `/api/*` and
serves the SPA's static assets for every other path, so the app and the whole
API share one origin. It also hosts the streaming tool-use agent
Expand Down Expand Up @@ -181,10 +187,11 @@ Paths below are relative to `apps/web/`:

- Enable RLS and grants in each new table's migration: `anon` and `authenticated`
receive `select`; writes use the service key.
- Apply the dorm chain in `apps/web/scripts/migrations/`, starting with
- Apply the dorm chain in `packages/dorm/scripts/migrations/`, starting with
`create_dorms_table.sql`, then `add_categorized_tags.sql`, then follow-ups.
`apps/web/AGENTS.md` owns the dorm schema order, the tables the tracked SQL
never creates, the seed scripts, and their known conflicts.
`packages/dorm/AGENTS.md` owns the dorm schema order, the seed scripts, and
their known conflicts. `apps/web/AGENTS.md` owns the tables the tracked SQL
never creates and the chat-owned `add_soul_and_memory.sql`.

## Deploy

Expand Down Expand Up @@ -218,8 +225,8 @@ the current Git branch.

Roll out in this order:

1. Create the tables the tracked SQL omits and run the dorm chain, then seed the
dorms table. Both steps are spelled out in `apps/web/AGENTS.md`.
1. Create the tables the tracked SQL omits (`apps/web/AGENTS.md`), run the dorm
chain, then seed the dorms table (`packages/dorm/AGENTS.md`).
2. Set the Worker secrets: `SUPABASE_URL` and `SUPABASE_ANON_KEY` are what
`Env` requires (Cloudflare binds `ASSETS`), but chat needs `DEEPSEEK_API_KEY`
and search needs `TAVILY_API_KEY`.
Expand Down
23 changes: 12 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,17 +49,18 @@ curl http://localhost:5173/api/health

## Documentation

| Goal | Start here |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Learn the repo rules, commands, and data model | [AGENTS.md](AGENTS.md) |
| Understand the runtime, endpoints, and access | [AGENTS.md](AGENTS.md#architecture) · [AGENTS.md](AGENTS.md#endpoint-access) |
| Work on the React app or the Worker | [apps/web/AGENTS.md](apps/web/AGENTS.md) |
| Change the agent's prompt or loop | [apps/web/worker/routes/agent-prompts](apps/web/worker/routes/agent-prompts) · [apps/web/worker/agent](apps/web/worker/agent) |
| Add an agent tool or skill | [apps/web/worker/tools](apps/web/worker/tools) · [apps/web/worker/skills](apps/web/worker/skills) |
| Configure secrets and the Worker | [apps/web/.dev.vars.example](apps/web/.dev.vars.example) · [apps/web/.env.local.example](apps/web/.env.local.example) · [apps/web/cloudflare.config.ts](apps/web/cloudflare.config.ts) |
| Set up dorm tables and seed data | [apps/web/AGENTS.md](apps/web/AGENTS.md#dorm-database) · [apps/web/scripts/migrations](apps/web/scripts/migrations) · [apps/web/scripts/seed-dorms-table.ts](apps/web/scripts/seed-dorms-table.ts) |
| Deploy and roll back | [AGENTS.md](AGENTS.md#deploy) |
| See what runs on pull requests | [.github/workflows/react-doctor.yml](.github/workflows/react-doctor.yml) |
| Goal | Start here |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Learn the repo rules, commands, and data model | [AGENTS.md](AGENTS.md) |
| Understand the runtime, endpoints, and access | [AGENTS.md](AGENTS.md#architecture) · [AGENTS.md](AGENTS.md#endpoint-access) |
| Work on the React app or the Worker | [apps/web/AGENTS.md](apps/web/AGENTS.md) |
| Change the agent's prompt or loop | [apps/web/worker/routes/agent-prompts](apps/web/worker/routes/agent-prompts) · [apps/web/worker/agent](apps/web/worker/agent) |
| Add an agent tool or skill | [apps/web/worker/tools](apps/web/worker/tools) · [apps/web/worker/skills](apps/web/worker/skills) |
| Configure secrets and the Worker | [apps/web/.dev.vars.example](apps/web/.dev.vars.example) · [apps/web/.env.local.example](apps/web/.env.local.example) · [apps/web/cloudflare.config.ts](apps/web/cloudflare.config.ts) |
| Work on the dorm feature | [packages/dorm/AGENTS.md](packages/dorm/AGENTS.md) · [packages/dorm/README.md](packages/dorm/README.md) |
| Set up dorm tables and seed data | [packages/dorm/AGENTS.md](packages/dorm/AGENTS.md#dorm-database) · [packages/dorm/scripts/migrations](packages/dorm/scripts/migrations) · [packages/dorm/scripts/seed-dorms-table.ts](packages/dorm/scripts/seed-dorms-table.ts) |
| Deploy and roll back | [AGENTS.md](AGENTS.md#deploy) |
| See what runs on pull requests | [.github/workflows/react-doctor.yml](.github/workflows/react-doctor.yml) |

## Development

Expand Down
23 changes: 12 additions & 11 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,17 +49,18 @@ curl http://localhost:5173/api/health

## 文档

| 目标 | 从这里开始 |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 了解仓库规则、命令和数据模型 | [AGENTS.md](AGENTS.md) |
| 了解运行时、接口和访问模型 | [AGENTS.md](AGENTS.md#architecture) · [AGENTS.md](AGENTS.md#endpoint-access) |
| 在 React 应用或 Worker 上开发 | [apps/web/AGENTS.md](apps/web/AGENTS.md) |
| 修改 agent 的提示词或循环 | [apps/web/worker/routes/agent-prompts](apps/web/worker/routes/agent-prompts) · [apps/web/worker/agent](apps/web/worker/agent) |
| 添加 agent 工具或技能 | [apps/web/worker/tools](apps/web/worker/tools) · [apps/web/worker/skills](apps/web/worker/skills) |
| 配置 secrets 和 Worker | [apps/web/.dev.vars.example](apps/web/.dev.vars.example) · [apps/web/.env.local.example](apps/web/.env.local.example) · [apps/web/cloudflare.config.ts](apps/web/cloudflare.config.ts) |
| 创建宿舍表并导入种子数据 | [apps/web/AGENTS.md](apps/web/AGENTS.md#dorm-database) · [apps/web/scripts/migrations](apps/web/scripts/migrations) · [apps/web/scripts/seed-dorms-table.ts](apps/web/scripts/seed-dorms-table.ts) |
| 部署与回滚 | [AGENTS.md](AGENTS.md#deploy) |
| 查看 pull request 上会运行什么 | [.github/workflows/react-doctor.yml](.github/workflows/react-doctor.yml) |
| 目标 | 从这里开始 |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 了解仓库规则、命令和数据模型 | [AGENTS.md](AGENTS.md) |
| 了解运行时、接口和访问模型 | [AGENTS.md](AGENTS.md#architecture) · [AGENTS.md](AGENTS.md#endpoint-access) |
| 在 React 应用或 Worker 上开发 | [apps/web/AGENTS.md](apps/web/AGENTS.md) |
| 修改 agent 的提示词或循环 | [apps/web/worker/routes/agent-prompts](apps/web/worker/routes/agent-prompts) · [apps/web/worker/agent](apps/web/worker/agent) |
| 添加 agent 工具或技能 | [apps/web/worker/tools](apps/web/worker/tools) · [apps/web/worker/skills](apps/web/worker/skills) |
| 配置 secrets 和 Worker | [apps/web/.dev.vars.example](apps/web/.dev.vars.example) · [apps/web/.env.local.example](apps/web/.env.local.example) · [apps/web/cloudflare.config.ts](apps/web/cloudflare.config.ts) |
| 开发宿舍功能 | [packages/dorm/AGENTS.md](packages/dorm/AGENTS.md) · [packages/dorm/README_CN.md](packages/dorm/README_CN.md) |
| 创建宿舍表并导入种子数据 | [packages/dorm/AGENTS.md](packages/dorm/AGENTS.md#dorm-database) · [packages/dorm/scripts/migrations](packages/dorm/scripts/migrations) · [packages/dorm/scripts/seed-dorms-table.ts](packages/dorm/scripts/seed-dorms-table.ts) |
| 部署与回滚 | [AGENTS.md](AGENTS.md#deploy) |
| 查看 pull request 上会运行什么 | [.github/workflows/react-doctor.yml](.github/workflows/react-doctor.yml) |

## 开发

Expand Down
Loading
Loading