A mobile-first interactive mapping application for organizing neighborhood Halloween trick-or-treating events. Built with the T3 Stack.

Halloween Maps helps neighborhoods coordinate trick-or-treating by displaying:

• Participating houses and distribution points
• Real-time candy availability
• Walking directions optimized for foot traffic
• Age-appropriate routes
• Special activities and starting points

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4
• Database: Supabase (PostgreSQL)
• Authentication: Supabase Auth
• Maps: Leaflet.js + Leaflet.markercluster + Leaflet.heat + OpenStreetMap
• Icons: Custom SVG (map markers) + Lucide React (UI elements)
• State: TanStack Query + tRPC
• Analytics: PostHog (optional, for visitor insights + real-time heatmap)

All project documentation is in the docs/ folder:

• Progress - Current status, completed features and deployment steps
• PRD - Complete product requirements and specifications
• PRD Summary - Quick reference and design decisions
• Admin Setup - Creating admin users with Supabase Auth
• Analytics Guide - PostHog analytics setup (optional)
• AI Image Prompts - AI-generated image prompts and social media requirements

• Node.js 18+
• npm or pnpm
• Supabase account (for database)

1. Clone the repository

git clone https://github.com/TrueBurn/halloween-maps-2025.git
cd halloween-maps-2025

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env
# Edit .env with your Supabase credentials and configuration
# Optional: Add PostHog credentials for analytics (see docs/ANALYTICS.md)

4. Run development server

npm run dev

Open http://localhost:3000 to see the app.

Database migrations are in supabase/migrations/. To set up:

1. Create a Supabase project
2. Run migrations using MCP server or Supabase CLI
3. Generate TypeScript types: npx supabase gen types typescript --project-id YOUR_PROJECT_ID > src/types/database.types.ts

See docs/PROGRESS.md for detailed setup and migration status.

Core Features:

• ✅ T3 App initialized with TypeScript, Tailwind, tRPC
• ✅ Multi-neighborhood architecture with separate Supabase databases
• ✅ Database migrations (enums, tables, RLS policies)
• ✅ Interactive map view with Leaflet
• ✅ Custom SVG location markers (25 markers: 4 location types × 4 states + 3 static + shadow)
  • States: Normal (orange), Starting Point (green), Activity (pink), No Candy (purple)
  • Static types: Parking, Refreshments, AnimalCharity
  • Priority rendering: No candy > Starting point > Activity > Normal
• ✅ Walking directions with OSRM
• ✅ GPS user location tracking
• ✅ Location list with filtering and sorting
• ✅ Admin panel with full CRUD operations
• ✅ Admin authentication with Supabase Auth
• ✅ Password reset & user invites (email-based auth flow)
• ✅ Coordinate picker (interactive map)
• ✅ Export to CSV and JSON
• ✅ Bulk actions (reset candy status)
• ✅ Real-time updates across all views
• ✅ Mobile-first responsive design
• ✅ Dark Halloween theme 🎃
• ✅ Performance optimizations (localStorage caching, smart map updates)
• ✅ Mobile browser compatibility (safe area insets, dvh viewport height)
• ✅ Marker clustering (Halloween-themed with 🦇🕷️👻 emojis)
• ✅ Social media sharing (WhatsApp-optimized preview images, Open Graph tags)
• ✅ PostHog analytics (optional) - Separate analytics dashboard at /admin/analytics with 12 cards (live users, sessions, GPS permission, popular locations, user journey, engagement, filters, events, recent activity)
• ✅ Real-time user location heatmap - Admin-only heatmap showing active users with GPS enabled (configurable time range, blurred heat density visualization, manual refresh)
• ✅ Movement timeline playback - Admin-only animated heatmap showing user movement patterns during Halloween event (5-minute intervals, play/pause controls, multiple playback speeds, map lock feature)
• ✅ First-visit info modal - Auto-opens event info with localStorage tracking
• ✅ Map location counter - Shows only candy-giving locations (filters out parking/refreshments)

Next Steps:

• 🎯 Deploy to Vercel (once per neighborhood)
• 🎯 Configure production environment variables
• 🎯 (Optional) Set up PostHog analytics - see Analytics Guide
• 🎯 Test WhatsApp sharing with Facebook Sharing Debugger
• 🎯 Create admin user accounts in each Supabase project

# Development
npm run dev          # Start dev server
npm run build        # Build for production
npm run start        # Start production server

# Code quality
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint
npm run format       # Prettier (if configured)

Access development tools at http://localhost:3000/dev (dev mode only):

• Seed Locations - Add example locations (starting points dynamically generated from NEXT_PUBLIC_ROUTES)
• Clear Example Locations - Remove all example locations (prefix: "Example - ")
• Database Stats - View location counts with auto-refresh

All dev endpoints are protected and only work in development mode.

This application is designed for multiple independent neighborhood deployments.

✅ Complete Data Isolation

• Each neighborhood has its own Supabase project
• Zero shared data between instances
• Independent admin access and authentication

✅ Separate Deployments

• Each neighborhood gets its own Vercel project
• Custom domain per deployment
• Independent environment variable configuration

✅ Scalable Design

• Same codebase deployed multiple times
• Configure via environment variables:
  • Map coordinates and neighborhood name
  • Dynamic routes/age groups (NEXT_PUBLIC_ROUTES - comma-separated, e.g., "All Ages" or "Over 8,Under 8,Toddlers")
  • Supabase credentials
  • Optional PostHog analytics
• No code changes needed for new neighborhoods

For each neighborhood:

1. Create a new Supabase project
2. Run all database migrations
3. Create a Vercel project
4. Set environment variables (Supabase credentials + neighborhood config + optional PostHog)
5. (Optional) Configure PostHog analytics - see Analytics Guide
6. Deploy with custom domain
7. Create admin user in Supabase Auth

See docs/PROGRESS.md for detailed deployment checklist.

This is a private project for specific neighborhoods, but contributions are welcome for bug fixes and improvements.

See LICENSE file for details.

• Built with Create T3 App
• Maps powered by Leaflet and OpenStreetMap
• Marker clustering by Leaflet.markercluster
• Heatmap visualization by Leaflet.heat
• Routing via Leaflet Routing Machine and OSRM
• UI icons from Lucide
• Database and authentication by Supabase
• Analytics (optional) by PostHog