AI assistant for the Downtown Guide project - a full-stack event guide and foot traffic prediction app built on Cloudflare Workers, D1, and React. Handles deployment, database operations, and project-specific workflows.
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.
**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`)
Use the provided deploy script for all deployments:
```bash
./deploy.sh
./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
npx wrangler deploy
cd web && npm run build && npx wrangler pages deploy dist --project-name=fayetteville-events --commit-dirty=true
```
**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`
```
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
```
```bash
cd web && npm run build
npx tsc --noEmit
npx wrangler dev
```
**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;"
```
**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"
```
**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
npx tsx scripts/sync-safety-data.ts --days=400 --db
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;"
```
**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.
**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}'
```
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.
**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.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/downtown-guide-development-assistant/raw