Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
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
5 changes: 4 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# ----- PostgreSQL (Docker) -----
POSTGRES_USER=forum
POSTGRES_PASSWORD=YOUR_DB_PASSWORD_HERE
POSTGRES_PASSWORD=forum_password
POSTGRES_DB=the_forum
POSTGRES_PORT=5434

Expand Down Expand Up @@ -40,3 +40,6 @@ NEXT_PUBLIC_CAMPUS_MAP_STYLE=YOUR_CAMPUS_MAP_STYLE_HERE
# Publish active, exact-time, high-confidence events without a location (default: false).
# PUBLISH_LOCATIONLESS_EVENTS=true

# Demo seed scripts refuse remote databases unless explicitly enabled.
# ALLOW_REMOTE_SEED=1

20 changes: 17 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# The Forum — Codex Rules
# The Forum — Agent Rules

## Project Overview

Expand All @@ -9,6 +9,20 @@ Turborepo monorepo with:

---

## Workflow

- Before starting work, read the relevant Linear issue and project guidance when Linear access is available. Use the issue ID and scope to guide the branch name and implementation. If Linear is unavailable, say so and work from the provided context.

- Start branches for changes from the latest `staging`. `main` is the production branch.
- Name branches `<first-name>_<mm-dd>_<ticket-id>[-optional-descriptors]`, using the date the branch is created. Example: `alex_10-27_TIG-123-update-feed`. Linear's generated Git branch name is also acceptable. For work without a Linear issue, use a descriptive name in place of the ticket ID, such as `alex_10-27_agent-workflow`.
- Keep `AGENTS.md` and `CLAUDE.md` identical. They are separate regular files for portability across Windows checkouts; whenever either file changes, repeat the same changes in the other file in the same commit.

### Linear description edits

When proposing a change to a Linear issue description, preserve the full original description in the issue itself. Append a horizontal separator (`---`), then a clearly labeled `Proposed description` section containing the full new description. Keep the original intact so others can review the proposal before accepting the change; do not replace the original with the proposal before acceptance.

---

## Package Manager

**Always use `bun`.** Never use `npm`, `yarn`, or `pnpm`.
Expand Down Expand Up @@ -45,9 +59,9 @@ Never use `process.env.*` directly in Next.js application code.**
- **Client-side** (must start with `NEXT_PUBLIC_`) → goes in the `client:` block
- Add a matching entry in `runtimeEnv:` pointing to `process.env.VAR_NAME`

2. Add it to `apps/web/.env.local.example` and to the root `.env.example`
2. Add it to the root `.env.example`

3. Add it to your local `apps/web/.env.local`
3. Add it to your local root `.env`. Keep local configuration in this single file; workspace scripts explicitly load it.

### Usage in code

Expand Down
20 changes: 17 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# The Forum — Claude Code Rules
# The Forum — Agent Rules

## Project Overview

Expand All @@ -9,6 +9,20 @@ Turborepo monorepo with:

---

## Workflow

- Before starting work, read the relevant Linear issue and project guidance when Linear access is available. Use the issue ID and scope to guide the branch name and implementation. If Linear is unavailable, say so and work from the provided context.

- Start branches for changes from the latest `staging`. `main` is the production branch.
- Name branches `<first-name>_<mm-dd>_<ticket-id>[-optional-descriptors]`, using the date the branch is created. Example: `alex_10-27_TIG-123-update-feed`. Linear's generated Git branch name is also acceptable. For work without a Linear issue, use a descriptive name in place of the ticket ID, such as `alex_10-27_agent-workflow`.
- Keep `AGENTS.md` and `CLAUDE.md` identical. They are separate regular files for portability across Windows checkouts; whenever either file changes, repeat the same changes in the other file in the same commit.

### Linear description edits

When proposing a change to a Linear issue description, preserve the full original description in the issue itself. Append a horizontal separator (`---`), then a clearly labeled `Proposed description` section containing the full new description. Keep the original intact so others can review the proposal before accepting the change; do not replace the original with the proposal before acceptance.

---

## Package Manager

**Always use `bun`.** Never use `npm`, `yarn`, or `pnpm`.
Expand Down Expand Up @@ -45,9 +59,9 @@ Never use `process.env.*` directly in Next.js application code.**
- **Client-side** (must start with `NEXT_PUBLIC_`) → goes in the `client:` block
- Add a matching entry in `runtimeEnv:` pointing to `process.env.VAR_NAME`

2. Add it to `apps/web/.env.local.example` and to the root `.env.example`
2. Add it to the root `.env.example`

3. Add it to your local `apps/web/.env.local`
3. Add it to your local root `.env`. Keep local configuration in this single file; workspace scripts explicitly load it.

### Usage in code

Expand Down
102 changes: 79 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,18 +47,26 @@ bun install # installs every workspace package + sets up Husky pre-commit hook

### 2. Environment variables

Copy the example files:
Copy the single root example file:

```bash
cp .env.example .env # root — used by docker-compose
cp apps/web/.env.local.example apps/web/.env.local # Next.js app
cp apps/database/.env.example apps/database/.env # drizzle-kit CLI
cp .env.example .env
```

Then fill in `apps/web/.env.local`. Env vars are validated at startup by
Then fill in the root `.env`. Docker, the web app, and database commands share this
file. Env vars are validated at startup by
[`apps/web/src/env.ts`](apps/web/src/env.ts) — the app won't boot if a required
one is missing, and that file is the source of truth for what's required.

Workspace package scripts explicitly load the root `.env`, so commands work from
the repo root or their app directory. Deployment can continue supplying variables
through the process environment without a local file. Existing checkouts can keep
using `apps/web/.env.local` and `apps/database/.env` as legacy fallbacks. Exported
environment variables take priority over the root `.env`, which takes priority
over duplicate legacy values. To migrate to one file, move your app-specific
values into the root `.env`, then remove the legacy files.
Restart the dev server after editing the root `.env`.

> **Can't obtain a value yourself? Ask Ibraheem.** He is the contact for all
> credentials that aren't self-serve (Mapbox tokens, AWS, etc.).

Expand All @@ -77,19 +85,34 @@ Clicking "Log in" goes to `/api/auth/cas/login`, which redirects to
`fed.princeton.edu/cas`; CAS sends you back to `/api/auth/cas/callback`, where the
ticket is validated server-side and your user row is created from your NetID.

### 3. Start the database
### 3. Start the database and app

Make sure **Docker Desktop is running**, then from the repo root:

```bash
bun run db:up # starts Postgres 17 in Docker (container: the-forum-db, host port 5434)
bun run db:push # push the Drizzle schema into the fresh database
bun run dev
```

This starts Postgres 17 in Docker (container: `<compose-project>-db`, host port **5434**),
waits until it is healthy, pushes the Drizzle schema, and runs the `apps/web` dev
script from the repo root. Open <http://localhost:3000>.

On a fresh database volume, Docker enables the `vector` extension before reporting
Postgres ready. You can also run `bun run db:up` followed by `bun run db:push`
separately. Before comparing schemas, `db:push` also ensures the `vector` extension
exists in its target database, including existing volumes. This requires a database
role allowed to enable extensions. Drizzle compares the live schema on each run
and applies only differences; it does not recreate unchanged tables.
In Turbo's terminal UI, select the database task and press `i` to
interact with Drizzle's confirmation menu, then use the arrow keys and Enter.

Use the same command on every startup. It runs `db:push` to keep the local schema
up to date; Docker preserves existing data between restarts.

Sanity checks:

```bash
docker compose ps # the-forum-db should show "Up (healthy)"
docker compose ps # the postgres service should show "Up (healthy)"
bun run db:logs # tail the Postgres logs if something looks wrong
```

Expand All @@ -102,21 +125,19 @@ Optionally fill the database with realistic demo data:
bun run db:seed
```

### 4. Run the app
To start only the web app, use `bun run --cwd apps/web dev` from the repo root.

```bash
cd apps/web && bun run dev
```

Open <http://localhost:3000>. You're set up.

To run the dev server through Turborepo from the repo root: `bun run dev`.
Local development uses Turbopack. Its persistent development cache is disabled to
avoid a recurring hot-reload panic (`Next.js package not found`) observed with
Bun workspace dependencies on Windows. Compilation is still reused in memory
during a running session; restarting the dev server starts with a cold cache.

---

## Everyday commands

```bash
bun run dev # start Postgres, wait for health, push schema, and start apps/web
bun run check # Biome lint + format with auto-fix (run before pushing)
bun run format # format only
bun run build # build all packages
Expand All @@ -136,7 +157,7 @@ if your commit fails, read the Biome output, fix, and re-commit.
### Conventions

- **Env vars in `apps/web`:** always `import { env } from "~/env"` — never `process.env.*` directly.
New vars get added to `apps/web/src/env.ts` *and* the `.env.example` files.
New vars get added to `apps/web/src/env.ts` *and* the root `.env.example`.
- **UI components:** use [shadcn/ui](https://ui.shadcn.com). Add new ones from `apps/web`:
`bunx shadcn@latest add <component>`.
- **Linting:** Biome only (no ESLint/Prettier).
Expand All @@ -158,7 +179,7 @@ It ingests MyPrincetonU's official events feed and residential/FreeFood listserv
resolves the hosting organization, extracts time and place, and exposes a revisioned change feed.

```bash
# apps/database/.env
# Root .env
INBOX_ENGINE_URL=https://inbox-engine.tigerapps.org
INBOX_ENGINE_TOKEN=… # ask a TigerApps admin

Expand Down Expand Up @@ -274,24 +295,59 @@ To change runtime configuration, update the SSM parameter and redeploy (or re-ru
`main` is protected — you cannot push to it directly, and pull requests into `main`
are only accepted from `staging`.

1. Branch off `main`: `git checkout -b feat/my-feature origin/main`
1. Branch off the latest `staging`: `git fetch origin`, then
`git checkout -b alex_11-07_TIG-123-update-feed origin/staging`.
2. Open a PR **into `staging`** and merge it there
3. When `staging` is ready to ship, open a PR from `staging` into `main`

Name branches `<first-name>_<mm-dd>_<ticket-id>[-optional-descriptors]`, using
the branch creation date. Linear's generated Git branch name is also acceptable.
Without a Linear issue, replace the ticket ID with a description, for example
`alex_11-07_local-startup`. Read the relevant Linear issue and project guidance
before starting when access is available.

Agent instructions live in `AGENTS.md` and `CLAUDE.md`; keep these files identical
when updating either one.

---

## Troubleshooting

**The app crashes on startup with "Invalid environment variables"**
A required var in `apps/web/.env.local` is missing or malformed — compare against
`apps/web/.env.local.example` and the table above.
A required var in the root `.env` is missing or malformed — compare against
the root `.env.example` and the table above.

**`ECONNREFUSED` / `DATABASE_URL` errors**
The database container isn't running (`bun run db:up`), or your `DATABASE_URL`
uses the wrong port — the Docker database listens on **5434**, not 5432.

**Port 5434 already in use**
Change `POSTGRES_PORT` in the root `.env` and update `DATABASE_URL` everywhere to match.
Change `POSTGRES_PORT` in the root `.env` and update `DATABASE_URL` in that file to match.

**Multiple Git worktrees**

Compose uses the worktree directory name as its default project name. Each project
gets its own database container (`forum-1-db`, `forum-2-db`, etc.) and data volume.
Use a different `POSTGRES_PORT` in each worktree's root `.env` when running them
simultaneously, and match that port in its `DATABASE_URL` (for example, port 5435
in `forum-2`). The database name inside each container can remain `the_forum`.
You can override the project name with `COMPOSE_PROJECT_NAME` or Compose's `-p`
flag. Keep the project name stable to continue using the same data volume;
renaming a container does not move it or its data into another project.

**`type "vector" does not exist` on an existing database**

First-time Docker initialization scripts only run for an empty data volume.
`bun run db:push` now enables the extension for existing databases too. If the
configured database role lacks permission, have an administrator enable it:

```bash
docker compose exec postgres psql -U forum -d the_forum -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

Replace the user and database if you customized `POSTGRES_USER` or `POSTGRES_DB`,
then retry `bun run db:push`. For a hosted database, enable the extension in the
database referenced by `DATABASE_URL` instead.

**Husky hooks not running**
Re-run `bun install` from the repo root (the `prepare` script reinstalls hooks).
Expand Down
6 changes: 0 additions & 6 deletions apps/database/.env.example

This file was deleted.

6 changes: 6 additions & 0 deletions apps/database/drizzle/0009_large_electro.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
CREATE INDEX "organizations_name_id_idx" ON "organizations" USING btree ("name","id");--> statement-breakpoint
CREATE INDEX "organizations_members_id_idx" ON "organizations" USING btree (coalesce("member_count", '-2147483649'::bigint) desc nulls last,"id" DESC NULLS LAST);--> statement-breakpoint
CREATE INDEX "organizations_created_at_id_idx" ON "organizations" USING btree ("created_at" DESC NULLS LAST,"id" DESC NULLS LAST);--> statement-breakpoint
CREATE INDEX "organizations_category_name_id_idx" ON "organizations" USING btree ("category","name","id");--> statement-breakpoint
CREATE INDEX "organizations_category_members_id_idx" ON "organizations" USING btree ("category",coalesce("member_count", '-2147483649'::bigint) desc nulls last,"id" DESC NULLS LAST);--> statement-breakpoint
CREATE INDEX "organizations_category_created_at_id_idx" ON "organizations" USING btree ("category","created_at" DESC NULLS LAST,"id" DESC NULLS LAST);
Loading
Loading