Downtown Guide Development Assistant

You are an AI assistant for the Downtown Guide project - a full-stack web application providing event listings, venue information, foot traffic predictions, and safety analytics for downtown Fayetteville, NC.

Project Architecture

**Backend:** Cloudflare Workers (TypeScript)

**Frontend:** React + Vite + Tailwind CSS

**Database:** Cloudflare D1 (SQLite)

**Hosting:** Cloudflare Pages

**Deployment Targets:**

**Database:** D1 database named `downtown-events` (ID: `fd953a64-4f1a-452c-aac4-84ad28c68370`)

Deployment Commands

Use the provided deploy script for all deployments:

```bash

Deploy both API and Web (default)

./deploy.sh

Deploy specific components

./deploy.sh --api # API Worker only

./deploy.sh --web # Web Frontend only

./deploy.sh --all # Both (explicit)

./deploy.sh --help # Show help

```

**Manual deployment (only if deploy script fails):**

```bash

API Worker

npx wrangler deploy

Web Frontend (from project root)

cd web && npm run build && npx wrangler pages deploy dist --project-name=fayetteville-events --commit-dirty=true

```

Database Operations

**Run migrations:**

```bash

npx wrangler d1 execute downtown-events --remote --file=migrations/XXXX_migration_name.sql

```

**Query database:**

```bash

npx wrangler d1 execute downtown-events --remote --command="SELECT * FROM table_name LIMIT 10;"

```

**Key tables:** `events`, `venues`, `sources`, `seasonal_specials`, `parking_lots`, `traffic_predictions`, `recurring_events`, `weather_cache`, `safety_incidents`, `analytics_events`

Project Structure

```

Downtown-Guide/

├── src/ # Backend (Cloudflare Worker)

│ ├── index.ts # Main entry point

│ ├── routes/ # API routes

│ └── services/ # Business logic

├── web/ # Frontend (React + Vite)

│ ├── src/

│ │ ├── pages/ # Page components

│ │ ├── components/ # Reusable components

│ │ └── lib/ # Utilities

│ └── dist/ # Build output

├── migrations/ # D1 database migrations

├── scripts/ # Sync and utility scripts

└── docs/ # Documentation and plans

```

Testing & Development

```bash

Build frontend

cd web && npm run build

Type check

npx tsc --noEmit

Test API locally

npx wrangler dev

```

Critical Lessons Learned

1. Analytics Field Naming (Jan 21, 2026)

**Problem:** Frontend sent camelCase (`deviceId`, `sessionId`, `eventType`) but backend validated for snake_case (`device_id`, `session_id`, `event_type`). Silent failures in analytics tracking.

**Solution:** Backend now accepts both naming conventions. Always verify actual payload format when building API endpoints.

**Verification:**

```bash

npx wrangler d1 execute downtown-events --remote \

--command="SELECT event_type, session_id, timestamp FROM analytics_events ORDER BY timestamp DESC LIMIT 5;"

```

2. Weather API Rate Limiting (Jan 22, 2026)

**Problem:** Open-Meteo API hit rate limits, causing fallback to identical seasonal averages for all days.

**Solution:** Switched to National Weather Service (NWS) API as primary (no rate limits), Open-Meteo as fallback, seasonal averages as last resort.

**Weather API Priority:**

1. NWS API (`api.weather.gov`) - Primary

2. Open-Meteo API - Fallback

3. Seasonal averages - Last resort

**Debug endpoint:**

```bash

curl -s "https://downtown-guide.wemea-5ahhf.workers.dev/api/predictions/debug-weather"

```

3. Safety Data Insufficient History (Jan 22, 2026)

**Problem:** Safety Snapshot showed identical data for 30/90/365 day periods due to limited historical data.

**Solution:** Run full backfill once after table creation:

```bash

Initial backfill (run once)

npx tsx scripts/sync-safety-data.ts --days=400 --db

For year-over-year comparisons

npx tsx scripts/sync-safety-data.ts --days=2200 --db

```

**Verification:**

```bash

npx wrangler d1 execute downtown-events --remote \

--command="SELECT MIN(incident_date) as oldest, MAX(incident_date) as newest, COUNT(*) as total FROM safety_incidents;"

```

4. Safety Snapshot Design Philosophy (Jan 22, 2026)

**Principle:** Present downtown in the best truthful, data-backed light. Lead with positive context, not raw crime numbers.

**Page structure:**

1. Hero (brief intro)

2. "Putting the Numbers in Context" (positive facts first)

3. Safety Trends Over Time (line chart)

4. Incident Types & Categories (pie + bar charts)

5. When Do Incidents Happen? (heatmap)

6. Downtown Incident Data (period selector + KPI cards)

7. Understanding This Data (explanatory context)

**Only show positive year-over-year trends.** If violent crimes increase, show category names instead of percentage change.

5. Date Planner Safety Logic (Jan 23, 2026)

**Problem:** Pit Stop feature recommended Cross Creek Park for evening/night strolls (safety concerns: homeless population, poor lighting).

**Solution:** Added time-based logic to `buildTimeSlots` in `src/services/date-generator.ts`:

**Use `forced: true` to bypass venue selection and recommend specific locations with safety notes.**

**Test evening pit stop:**

```bash

curl -s 'https://downtown-guide.wemea-5ahhf.workers.dev/api/date-planner/generate' \

-H 'Content-Type: application/json' \

-d '{"event_type":"pit_stop","budget_range":"$$","vibes":["relaxed"],"duration_hours":1,"date":"2026-01-23","time_of_day":"evening"}' \

| jq '.plan.stops[] | {activity, notes}'

```

Instructions

When helping with the Downtown Guide project:

1. **Deployment:** Always use `./deploy.sh` unless it fails. Specify `--api`, `--web`, or `--all` as needed.

2. **Database changes:** After modifying schema, create migration file and run it against the remote D1 database.

3. **API endpoints:** Always accept both camelCase and snake_case for field names to avoid silent failures.

4. **Weather features:** Use NWS API as primary source. Verify forecasts vary by day (identical data = fallback mode).

5. **Safety features:** Lead with positive context. Only show favorable year-over-year trends. For evening/night recommendations, prefer well-lit, active areas over parks.

6. **Data backfills:** When adding new time-series tables, run initial backfill with sufficient history for all time period selectors.

7. **Testing:** Always verify API responses with `curl` and database state with `wrangler d1 execute`. Check actual data, not just HTTP 200 responses.

8. **Documentation:** Update `docs/` directory for algorithm changes. Add new lessons learned to the CLAUDE.md "Lessons Learned" section.

Key Documentation Files

Common Tasks

**Add new venue:**

```sql

INSERT INTO venues (name, address, category, ...) VALUES (...);

```

**Update predictions with fresh weather:**

```bash

curl -X POST "https://downtown-guide.wemea-5ahhf.workers.dev/api/predictions/refresh"

```

**Sync safety data:**

```bash

npx tsx scripts/sync-safety-data.ts --days=365 --db

```

**Check API logs:**

```bash

npx wrangler tail

```

Always prioritize user safety, data accuracy, and positive (but truthful) framing of downtown Fayetteville.