Consentful Civic Lens (CCL)

An event-centric, photo/video forum for your campus and neighborhood. Capture moments with consent, create community stories, and take action together.

🌟 Features

Privacy-First Community Building

• Automatic Face Blurring: Non-consenting faces are automatically blurred using on-device face detection
• Per-Event Consent Tokens: Privacy tokens are event-specific and never stored permanently
• Consent Management: Users can opt-in per event with secure, salted face hashes

Visual Storytelling

• Community Highlights: Auto-generated 60-second recaps from event photos/videos
• Multi-Perspective Cuts: Community, Organizer, and Family-friendly versions
• Source Transparency: See which media contributed to each story

Action-Oriented Engagement

• Smart Recommendations: AI-powered action suggestions based on user profile and event context
• Action Cards: Volunteer shifts, donation requests, forms, and follow-up meetings
• Impact Tracking: Measure real community outcomes

Accessibility & Safety

• Auto Captions: Generated for all video content
• Alt Text: Automatic descriptions for images
• Safety Checks: Flicker, loudness, and content moderation
• Accessibility Scoring: Built-in metrics for inclusive content

🚀 Quick Start

Prerequisites

• Node.js 18+
• Supabase account
• Stripe account (for payments)

1. Clone and Install

git clone <your-repo-url>
cd ConsentfulCivicLens
npm install

2. Environment Setup

Create a .env.local file with your Supabase credentials:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Database
POSTGRES_URL=your_postgres_connection_string

# Authentication
AUTH_SECRET=your_auth_secret_key

# Stripe (optional)
STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

3. Database Setup

Option A: Using Supabase (Recommended)

1. Go to your Supabase dashboard
2. Navigate to SQL Editor
3. Run the migration script from lib/db/migrations/0000_soft_the_anarchist.sql

Option B: Using Drizzle

npm run db:setup
npm run db:migrate
npm run db:seed

4. Supabase Configuration

Enable Authentication

1. Go to Authentication > Settings in your Supabase dashboard
2. Enable email authentication
3. Configure email templates if desired

Set up Row Level Security (RLS)

Run these SQL commands in your Supabase SQL editor:

-- Enable RLS on all tables
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE events ENABLE ROW LEVEL SECURITY;
ALTER TABLE assets ENABLE ROW LEVEL SECURITY;
ALTER TABLE consent_tokens ENABLE ROW LEVEL SECURITY;
ALTER TABLE actions ENABLE ROW LEVEL SECURITY;
ALTER TABLE action_participants ENABLE ROW LEVEL SECURITY;

-- Users can only see their own data
CREATE POLICY "Users can view own profile" ON users
  FOR SELECT USING (auth.uid()::text = id::text);

CREATE POLICY "Users can update own profile" ON users
  FOR UPDATE USING (auth.uid()::text = id::text);

-- Events are public to read, but only organizers can create/update
CREATE POLICY "Events are viewable by everyone" ON events
  FOR SELECT USING (true);

CREATE POLICY "Only organizers can create events" ON events
  FOR INSERT WITH CHECK (
    EXISTS (
      SELECT 1 FROM users 
      WHERE users.id = organizer_id 
      AND users.role = 'organizer'
      AND auth.uid()::text = users.id::text
    )
  );

-- Assets are viewable by everyone, but only the uploader can create
CREATE POLICY "Assets are viewable by everyone" ON assets
  FOR SELECT USING (true);

CREATE POLICY "Users can upload assets" ON assets
  FOR INSERT WITH CHECK (auth.uid()::text = user_id::text);

-- Consent tokens are private to the user
CREATE POLICY "Users can manage own consent tokens" ON consent_tokens
  FOR ALL USING (auth.uid()::text = user_id::text);

-- Actions are viewable by everyone
CREATE POLICY "Actions are viewable by everyone" ON actions
  FOR SELECT USING (true);

-- Action participants can be managed by the user
CREATE POLICY "Users can manage own action participation" ON action_participants
  FOR ALL USING (auth.uid()::text = user_id::text);

Set up Storage

1. Go to Storage in your Supabase dashboard
2. Create a new bucket called media-assets
3. Set up the following policies:

-- Allow authenticated users to upload media
CREATE POLICY "Authenticated users can upload media" ON storage.objects
  FOR INSERT WITH CHECK (bucket_id = 'media-assets' AND auth.role() = 'authenticated');

-- Allow everyone to view media
CREATE POLICY "Media is viewable by everyone" ON storage.objects
  FOR SELECT USING (bucket_id = 'media-assets');

-- Users can update their own uploads
CREATE POLICY "Users can update own uploads" ON storage.objects
  FOR UPDATE USING (bucket_id = 'media-assets' AND auth.uid()::text = (storage.foldername(name))[1]);

5. Run the Application

npm run dev

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

🏗️ Architecture

Frontend (Next.js 15)

• App Router: Modern Next.js routing with server components
• TypeScript: Full type safety throughout
• Tailwind CSS: Utility-first styling
• shadcn/ui: Accessible component library

Backend (Supabase)

• PostgreSQL: Primary database with Drizzle ORM
• Authentication: Supabase Auth with JWT tokens
• Storage: File uploads for media assets
• Real-time: Live updates for collaborative features

Privacy & Security

• On-Device Processing: Face detection runs in browser
• Consent Tokens: Event-scoped, salted face hashes
• RLS Policies: Database-level access control
• HTTPS Only: All communications encrypted

📱 User Flows

For Organizers

1. Sign Up/Login → Choose "Organizer" role
2. Create Event → Add details, actions, and generate QR code
3. Manage Event → View participants, media, and analytics
4. Export Packet → Download civic packet with metrics

For Attendees

1. Scan QR Code → Join event with consent
2. Capture Media → Take photos/videos with privacy protection
3. View Highlights → See auto-generated community stories
4. Take Action → Participate in recommended activities

🔧 Development

Database Migrations

# Generate new migration
npm run db:generate

# Apply migrations
npm run db:migrate

# Open Drizzle Studio
npm run db:studio

Adding New Features

1. Update database schema in lib/db/schema.ts
2. Generate and run migrations
3. Update TypeScript types
4. Implement frontend components
5. Add API routes if needed

Testing

# Run type checking
npm run type-check

# Run linting
npm run lint

# Run build
npm run build

🚀 Deployment

Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Add environment variables in Vercel dashboard
3. Deploy automatically on push to main

Other Platforms

• Railway: Good for full-stack deployment
• Supabase: Hosts your database and auth
• Cloudflare: CDN and edge functions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

• Documentation: Check this README and code comments
• Issues: Create GitHub issues for bugs or feature requests
• Discussions: Use GitHub Discussions for questions

🎯 Roadmap

• Mobile app (React Native)
• Advanced AI features (Claude integration)
• Real-time collaboration
• Advanced analytics dashboard
• Multi-language support
• Integration with calendar apps
• Social media sharing
• Offline support

---

Built with ❤️ for community building and privacy protection.