Careable is a centralized event management and community support platform designed specifically for caregiver organizations supporting children with disabilities. It streamlines event creation, volunteer coordination, participant registration, and attendance tracking through AI-powered automation and secure QR code systems.

Version: 0.3.0 (Unified Portal - January 2026)
Status: Production Ready

• 🟢 Volunteer: Green (#86B1A4) - "Make a Difference"
• 🌸 Caregiver: Pink (#EC4899) - "Caring for Participants"
• 🟠 Participant: Orange (#E89D71) - "Your Wellness Journey"

• ✅ Unified Route Architecture: Merged volunteer, participant, and caregiver portals into single /portal/ routes
• 🎨 Role-Based Dynamic Theming: Automatic color themes (Green/Pink/Orange) based on user role
• ⚡ ~40% Smaller Bundle: Eliminated duplicate code across 3 route groups
• 🏗️ Single Source of Truth: One codebase for all user-facing features
• 📦 Better Performance: Improved caching and faster builds (24 routes instead of 36)

/portal/dashboard       # Role-aware dashboard (adapts to volunteer/caregiver/participant)
/portal/events          # Event discovery (filtered by role)
/portal/events/[id]     # Event details (dynamic theming)
/portal/registrations   # My registered events (with QR codes)
/portal/profile         # User profile (with stats)
/portal/participants    # Caregiver-only participant management

• 🧡 Caregiver Portal: Link participants, register them for events, track special needs
• 📊 Admin Analytics Dashboard: Platform metrics, staff leaderboard, engagement tracking
• 👥 Enhanced Attendance Tracking: Records which staff performed check-ins with optional notes

Run the new migration to enable all features:

psql -h your-db.supabase.co -U postgres -f sql/08_enhanced_schema_caregiver_attendance.sql

• AI-Powered Event Extraction: Upload calendar images (PNG, JPEG, PDF) and let Gemini Vision automatically extract event details, venues, and timings with reasoning-based accuracy.
• Comprehensive Event Management: Create, edit, and cancel events. View all activities in responsive card or table layouts.
• Data Normalization: Intelligent mapping of Singapore-based venues and automatic conversion of 12h time formats to ISO-standard 24h.
• QR Attendance Tracking: (In progress) Automatic generation of ticket codes for secure event check-ins.

• Opportunity Discovery: Browse a real-time feed of "Latest Needs" and sign up for volunteer roles.
• Self-Service Scheduling: View upcoming volunteer commitments and manage registration status.
• Integrated QR Codes: Quick access to attendance QR codes for on-site verification.

• Event Discovery: Explore upcoming community events through a beautiful, searchable landing page and dashboard.
• Smart Registration: A seamless "one-click" registration flow. First-time users are guided to provide their full names for accurate record-keeping.
• Wellness Tracking: Keep track of joined activities and upcoming schedules in one place.

• Framework: Next.js 15 (App Router)
• Authentication: Clerk (Role-based access control)
• Database: Supabase (PostgreSQL with Row Level Security)
• AI Engine: Google Gemini 2.0 Flash
• Styling: Tailwind CSS + Shadcn UI
• Icons: Lucide React
• Date Handling: date-fns

Ensure you have Node.js 18+ and a Supabase/Clerk account.

Create a .env.local file in the root directory:

# Clerk Auth
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Gemini AI
GEMINI_API_KEY=AIza...
GEMINI_MODEL=gemini-2.0-flash-exp

Execute the SQL scripts located in the /sql directory in your Supabase SQL Editor in the following order:

1. 01_supabase_schema.sql (Tables & Enums)
2. 02_auth_integration.sql (Clerk Sync)
3. 03_fix_schema_and_roles.sql (Role Helpers)
4. 04_add_event_unique_constraint.sql (Deduplication)
5. 05_add_event_status.sql (Event Lifecycle)
6. 06_add_is_first_time_to_profiles.sql (Onboarding Flow)
7. 07_fix_rls_for_registration.sql (Permissions)

npm install
npm run dev

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

For full setup instructions, see the Project Summary.

• AI-Powered Event Extraction: Upload calendar images and let Gemini Vision extract events automatically
• Event Management: Create, edit, cancel events with capacity and accessibility tracking
• QR Check-in System: Scan participant QR codes using rear camera on mobile
• Attendance Tracking: Record who performed check-ins with optional notes
• Singapore Venue Normalization: Automatic mapping of common Singapore locations

• Participant Management: Link and manage multiple participants (children under care)
• On-Behalf Registration: Register participants for events
• Special Needs Tracking: Record accessibility requirements and emergency contacts
• Consolidated Dashboard: View all events and registrations in one place

• Event Discovery: Browse upcoming community events on mobile-friendly interface
• One-Click Registration: Seamless registration flow with QR code generation
• Personal Dashboard: Track upcoming events and attendance history

• Opportunity Discovery: Browse volunteer opportunities by date and location
• Self-Service Scheduling: Manage your volunteer commitments
• QR Code Access: Quick access to attendance verification

• Platform Analytics: Real-time metrics on users, events, and attendance
• Staff Leaderboard: Track events created and check-ins performed
• Engagement Metrics: Monitor top participants and volunteers
• Geographic Insights: Identify popular venues and event hotspots
• Caregiver Program Stats: Track caregiver adoption and managed participants

• Frontend: Next.js 16.1.4 (App Router), React 19, TypeScript 5, Tailwind CSS 4
• Backend: Next.js API Routes, Server Actions
• Database: Supabase (PostgreSQL with Row Level Security)
• Auth: Clerk (role-based access control)
• AI: Google Gemini 2.0 Flash (vision + reasoning)
• QR: qrcode (generation) + html5-qrcode (scanning with rear camera)
• Security: SHA-256 hashed tokens, RLS policies, staff attribution

• Project Summary - Complete technical documentation
• Cursor Prompt - Development guidelines for AI assistants
• Improvement Plan - Roadmap and completed enhancements

Execute migrations in order:

# 01-07: Base schema (already applied)
# 08: New caregiver and analytics features
psql -h your-db.supabase.co -U postgres -f sql/08_enhanced_schema_caregiver_attendance.sql

What Migration 08 adds:

• caregiver_participants table for managing relationships
• Enhanced profiles with language preference, special needs, emergency contact
• Enhanced events with age restrictions, guardian requirements, target audience
• Enhanced registrations with staff attribution and attendance notes
• Analytics views for reporting and dashboards

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Supabase Database
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Google Gemini AI
GEMINI_API_KEY=AIza...
GEMINI_MODEL=gemini-2.0-flash-exp

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.