🌮 CartoTaco
An interactive map-based application for exploring taco establishments in Tucson, AZ. Discover local taco shops, food trucks, and stands with detailed information on menu items, salsas, spice levels, and specialty offerings.
🚀 Features
- Interactive Map with Clustering: Visualize all taco establishments with automatic marker clustering
- Search & Filter: Find spots by name, protein type, establishment type, spice level, open status, and favorites
- Mobile-First Responsive Design: Bottom sheet cards, swipe gestures, and optimized layouts for all screen sizes
- Detailed Information Cards: Rich data visualizations including radar charts, spice gauges, and specialty carousels
- User Authentication: Email/password auth via Supabase with protected routes
- Favorites System: Save spots with a heart icon, filter by favorites, dedicated favorites page
- Taco Trail Route Builder: Plan multi-stop taco crawls with walking/cycling/driving directions via Mapbox Directions API
- Spot Comparison Mode: Compare up to 3 establishments side-by-side with shareable URLs at
/compare
- Taste Profile & Personalization: k-NN based recommendations from your favorites, 13 taste archetypes
- Taco Summit: Shareable ranked-choice group vote — share a link, everyone ranks their picks, Borda count reveals the winner with a live rank-distribution chart at
/vote/[id]
- Surprise Me: One-tap random spot selection that respects active filters
- Onboarding Tour: 11-step guided tour for first-time users
- Dark Mode: Light/dark/auto themes with time-based automatic switching
- Directions Deep-Link: Smart links to Apple Maps (iOS), Google Maps (Android), or Google Maps web
- New Spots Badge: Notification badge for recently added establishments
- Map Lenses: Switch the map between spots, heat, salsa count, and density views
- Tucson Taco Census: City-wide stats dashboard at
/census
- Vibe Votes: Four one-tap votes per spot (Heat Legit, Authentic, Value, Vibe) instead of star ratings
- Public Profiles: Username, bio, and avatar at
/u/[username]
- Pending & Closed Spots: Unvetted, web-scraped spots and permanently closed ones are shown but clearly marked
- Community Location Submissions: Geocoded submission form with moderation queue
- Contact Information: Direct links to phone, website, Instagram, and Facebook
- Specialty Highlights: Discover unique specialty items at each location
- Salsa & Spice Analysis: Compare salsa varieties and heat levels with context
- Performance Optimized: 60-70% faster load times with single-query database view
🔧 Tech Stack
- Frontend: SvelteKit v2 with Vite
- Styling: Tailwind CSS with CSS-variable design tokens and Phosphor icons
- Backend: Supabase for database, authentication, and SSR (
@supabase/ssr)
- Mapping: Mapbox GL with geocoding and directions
- Data Visualization: ECharts
- Testing: Vitest
- Deployment: Vercel with adapter-vercel; GitHub Actions for CI and database migrations
📋 Prerequisites
Before you begin, ensure you have:
- Node.js 24 (see
.nvmrc)
- pnpm package manager
- A Supabase account for backend services
- A Mapbox account for map rendering
🔑 Environment Variables
Copy .env.example to .env and fill in:
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_MAPBOX_KEY=your_mapbox_api_key
🏗️ Installation
-
Clone the repository
git clone <repository-url>
cd cartoTaco
-
Install dependencies
pnpm install
-
Start the development server
pnpm dev
-
Open your browser and navigate to http://localhost:5175
🧪 Development Commands
pnpm dev - Start development serverpnpm build - Build for productionpnpm preview - Preview production buildpnpm check - Run Svelte type checkingpnpm check:watch - Run type checking in watch modepnpm test - Run unit tests (vitest)pnpm test:watch - Run tests in watch mode
📚 Documentation
📁 Project Structure
src/
├── components/ # Svelte components (Card, FilterBar, charts, trays, ...)
├── lib/ # Stores, Mapbox rendering, Supabase clients, utilities, unit tests
├── routes/ # SvelteKit routes
│ ├── +page.svelte # Main map page
│ ├── census/ # City-wide stats dashboard
│ ├── compare/ # Spot comparison (shareable via ?ids=)
│ ├── vote/ # Taco Summit creation and voting
│ ├── u/[username]/ # Public profiles
│ ├── (auth)/ # Login, signup, email confirmation
│ └── (protected)/ # Favorites, profile, submit (requires auth)
├── app.css # Global styles and design tokens
docs/ # Feature documentation
supabase/migrations/ # Database migrations, applied by CI
schema/ # Canonical sites_complete view definition
CLAUDE.md has the file-by-file breakdown.
🗃️ Database Setup
The application uses Supabase with the following main tables:
sites - Basic information about taco establishmentsdescriptions - Short and long descriptions for each locationmenu - Menu item data and ratingshours - Operating hours informationsalsa - Salsa varieties and heat levelsprotein - Protein options and ratingsitem_spec, protein_spec, salsa_spec - Specialty item informationsites_complete - Optimized view joining all site-related tablesprofiles, user_favorites, vibe_votes, location_submissions - User data, protected by row-level securitygroup_sessions, group_votes - Taco Summit sessions and ballots
Running Migrations
Migrations are applied by CI: merge to staging to apply them there, then staging → main to ship. Never run SQL in the Supabase editor by hand — CI then believes the migration never ran.
For a brand-new database, point supabase db push --db-url at it once to run them all in order.
🌟 Roadmap
See docs/IMPROVEMENTS.md for what has shipped and what's planned. Next up: geo-fenced check-ins and aficionado tiers.
🤝 Contributing
Branch off staging, open a PR into staging, and verify on the staging deploy; staging → main ships it. CI runs pnpm check, pnpm test, and pnpm build on every PR. See docs/DEPLOYMENT.md.
