Sagip Ahas — Snake Sightings 🐍

A geospatial safety platform for reporting and tracking snake encounters in the Philippines. Citizens can report sightings safely (heatmap only, no exact coordinates exposed), responders handle incidents with exact GPS access, and admins manage verification and analytics.

🌟 Features

Feature	Citizens	Responders	Admins
View heatmap (no exact pins)	✅	✅	✅
Report sightings (click-to-place map)	✅	❌	❌
Respond to incidents (exact GPS pins + 100m search zones)	❌	✅	✅
Manage users & roles	❌	❌	✅
Verify responder applications	❌	❌	✅
System audit logs	❌	❌	✅
Analytics dashboard	❌	❌	✅

🏗️ Tech Stack

Frontend

• Next.js 16.2.6 (App Router, Turbopack)
• React 19.2.4
• TailwindCSS v4 (@import "tailwindcss" + @theme directives)
• Framer Motion 12.38 (animations, page transitions)
• Leaflet / OpenStreetMap (all map views, zero API keys)
• @tanstack/react-query (data caching)

Backend

• Supabase (Auth, PostgreSQL, RLS, Realtime, Storage)
• Row Level Security (20+ policies, privacy-first)
• Auth: Email/password + OAuth (Google, GitHub)

📁 Project Structure

src/
├── proxy.ts                           # Next.js proxy middleware (auth + role guard)
├── app/
│   ├── layout.tsx                     # Root layout (providers, fonts)
│   ├── page.tsx                       # Citizen landing: hero, heatmap, safety cards
│   ├── globals.css                    # Tailwind v4 design system (@theme, @utility)
│   ├── providers.tsx                  # Framer Motion LazyMotion
│   ├── login/page.tsx                 # Login + signup (Google/GitHub OAuth, email/password)
│   ├── report/page.tsx                # Click-to-place map report form
│   ├── auth/
│   │   ├── callback/route.ts          # OAuth callback handler
│   │   └── logout/route.ts            # Server-side logout (cookie clearing)
│   ├── responder/
│   │   ├── page.tsx                   # Responder dashboard (cases, map, profile)
│   │   └── apply/page.tsx             # Responder application form
│   └── admin/
│       ├── layout.tsx
│       └── page.tsx                   # Admin panel (5 tabs: Overview, Users, Verification, Sightings, Logs)
├── components/
│   ├── UserProvider.tsx               # User context (user + role)
│   ├── map/
│   │   ├── HeatmapMap.tsx             # Citizen view — translucent circles, no pins
│   │   ├── ResponderMap.tsx           # Responder view — exact pins + 100m zones
│   │   └── AdminMap.tsx               # Admin view — full overlay
│   ├── report/
│   │   └── ReportMap.tsx              # Click-to-place pin map
│   └── ui/
│       ├── Navbar.tsx                 # Role-aware navigation
│       ├── GlassCard.tsx, GlassPanel.tsx
│       ├── Button.tsx, Badge.tsx
│       ├── Input.tsx, Modal.tsx
│       ├── LoadingSpinner.tsx, Skeleton.tsx
│       └── Toast.tsx, Sidebar.tsx
├── lib/
│   ├── supabase.ts                    # Singleton createBrowserClient + all types
│   ├── supabase-provider.tsx          # Supabase context provider
│   ├── query-provider.tsx             # React Query client
│   └── utils.ts                       # cn() helper
└── hooks/
    ├── useSightings.ts                # Fetch + realtime subscription
    └── useRealtime.ts                 # Generic realtime hook

🚀 Getting Started

Prerequisites

• Node.js 18+ (for Next.js 16)
• npm or yarn
• Supabase project (free tier works)

Installation

1. Clone the repo

   git clone https://github.com/qppd/snake-sightings.git
   cd snake-sightings

2. Install dependencies

   npm install --legacy-peer-deps

3. Environment setup Copy .env.example to .env.local and fill in your Supabase credentials:

   cp .env.example .env.local

   Required variables:

   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
   

4. Run database migration Open your Supabase SQL Editor and run:

   • supabase/migrations/001_initial_schema.sql (complete schema + RLS)
   • supabase/rls.sql (RLS policies — already included in migration)

5. Start the dev server

   npm run dev

   Open http://localhost:3000

🔧 Build

npm run build
npm run start

Vercel Deployment (One-Click)

1. Push to GitHub
2. Import repo on Vercel
3. Add environment variables (same as .env.local)
4. Deploy — no build config needed

🔐 Auth Architecture

Supabase Client Architecture

Uses single createBrowserClient from @supabase/ssr (cookie-based session storage):

Source	Library	Creates Instance?
src/lib/supabase.ts	@supabase/ssr createBrowserClient()	Yes — singleton
src/lib/supabase-provider.tsx	@supabase/ssr	No — reuses singleton
src/proxy.ts	@supabase/ssr createServerClient()	Per-request
auth/callback/route.ts	@supabase/ssr createServerClient()	Per-request
auth/logout/route.ts	@supabase/ssr createServerClient()	Per-request

Logout Flow

Server-side POST route clears ALL cookies via maxAge: 0. Navbar uses <form action="/auth/logout" method="POST"> for reliable logout.

Proxy Middleware

src/proxy.ts runs on every request:

1. Checks session via createServerClient
2. Redirects unauthenticated users to /login
3. Fetches user role from profiles table
4. Enforces role-based route access
5. Public routes pass through

🗺️ Map System

Three role-separated map components (Leaflet/OpenStreetMap with SSR-safe dynamic() imports):

1. HeatmapMap — Citizen view: translucent risk-colored circles over metro areas. No pins, no exact coords.
2. ResponderMap — Exact GPS pins + 100m search zone circles for assigned incidents.
3. AdminMap — Full data overlay with all sightings.

Privacy model: Citizens see heatmap only. Responders see exact pins + zones for assigned incidents. Admins see everything.

👥 Roles

Role	Default Route	Access
citizen	/	Heatmap, report sightings
responder	/responder	Dashboard, assigned cases
admin	/admin	Full system governance
sub_admin	/admin	Limited moderation

🗄️ Database Schema

Tables

• profiles — User profiles (extends auth.users, auto-created on signup)
• sightings — Core data: risk level, GPS coords, description, visibility mode
• incidents — Links responders to sightings they handle
• responder_applications — Verification applications
• system_logs — Audit trail for admin actions

RLS Policies

• 20+ policies enforcing privacy-first access
• Citizens: INSERT own sightings, SELECT own + heatmap_only
• Responders: SELECT only assigned incident sightings
• Admins: Full read/write
• get_user_role() function with SECURITY DEFINER to avoid recursion

📊 Testing

npm test          # Run all tests
npm run test:watch  # Watch mode
npm run test:coverage # Coverage report

🔒 Security

• No frontend trust — RLS enforces all access control server-side
• Heatmap privacy — exact coords never exposed to citizens
• Cookie-based sessions — HttpOnly cookies managed server-side
• Audit logging — All admin actions logged to system_logs
• Input sanitization — RLS prevents unauthorized inserts/updates

📝 License

MIT — see LICENSE

🤝 Contributing

1. Fork the repo
2. Create a feature branch
3. Make changes
4. Run npm run build — ensure it compiles
5. Submit a PR

---

Built with ❤️ for community safety