CommFlock

Version: 0.3.0 | Status: Production Ready ✅

CommFlock is a Lightning-powered community platform where users discover and create communities, coordinate events, and connect with others. Built with Next.js 15, Prisma, PostgreSQL, and shadcn/ui.

What's New in v0.3

• 🚀 Week 1-2 Complete: Code quality and performance optimizations (87% done)
• ⚡ Performance Optimized: Database indexes, image optimization, mobile responsiveness verified
• 🎨 UX Improvements: Skeleton loaders, better error messages, success toasts
• 📊 Performance Audited: Lighthouse testing on all key pages
• ✨ New Landing Page with animated hero section and community discovery
• 🔒 Phase 1-5 Complete: Testing, password reset, rate limiting, CI/CD, and error monitoring
• 🌍 Full i18n Support: English and Spanish throughout entire site
• 📊 Load More Pagination: Discover communities with infinite scroll
• 🔐 Security Hardened: Rate limiting, password reset, Sentry monitoring
• 🤖 CI/CD Pipeline: Automated testing and deployment

Features

• Multi-tenant Communities: Each community has its own space with custom settings and policies
• Lightning Payments: Built-in Lightning Network support for community creation and event payments (simulated in v1)
• Lightning Address Integration: Users can optionally provide Lightning addresses for seamless payments
• Nostr Integration: Users can optionally provide Nostr public keys for decentralized identity
• Events & Polls: Coordinate activities with events, polls, and community announcements
• Flexible Join Policies: Auto-join, approval-required, or closed communities
• Member Management: Points, badges, and leaderboards
• Internationalization: English and Spanish support
• Modern UI: Built with shadcn/ui and Tailwind CSS

Tech Stack

• Frontend: Next.js 15 (App Router) + TypeScript
• Database: PostgreSQL + Prisma ORM
• Authentication: Auth.js with credentials provider
• UI: Tailwind CSS + shadcn/ui
• Internationalization: next-intl
• Validation: Zod
• Forms: react-hook-form

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL 14+ (for local development)
• npm or pnpm

Installation

1. Clone the repository:

git clone <repository-url>
cd CommFlock

2. Install dependencies:

npm install

3. Set up environment variables:

cp env.example .env

Edit .env with your database credentials:

For open source contributors (SQLite):

DATABASE_URL="file:./dev.db"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="dev-secret-change-later"

For shared development (Neon PostgreSQL):

DATABASE_URL="postgresql://USER:PASSWORD@HOST-POOLER.neon.tech/DB?sslmode=require&pgbouncer=true"
DIRECT_URL="postgresql://USER:PASSWORD@HOST.neon.tech/DB?sslmode=require"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="dev-secret-change-later"

4. Set up the database:

# Run migrations
npm run db:migrate

# Generate Prisma client
npm run db:generate

# Seed the database (optional)
npm run seed

5. Start the development server:

npm run dev

6. Open http://localhost:3000 in your browser.

Deploying to Netlify + Neon

Prerequisites for Deployment

• Neon account (free tier available)
• Netlify account (free tier available)

1. Set up Neon Database

1. Create a new project in Neon Console
2. Copy your connection strings:
   • Pooled URL (for runtime): postgresql://USER:PASSWORD@HOST-POOLER.neon.tech/DB?sslmode=require&pgbouncer=true
   • Direct URL (for migrations): postgresql://USER:PASSWORD@HOST.neon.tech/DB?sslmode=require

2. Deploy to Netlify

1. Connect your GitHub repository to Netlify
2. Set environment variables in Netlify dashboard:

   DATABASE_URL=postgresql://USER:PASSWORD@HOST-POOLER.neon.tech/DB?sslmode=require&pgbouncer=true
   DIRECT_URL=postgresql://USER:PASSWORD@HOST.neon.tech/DB?sslmode=require
   NEXTAUTH_URL=https://your-site.netlify.app
   NEXTAUTH_SECRET=your-secret-key-here
   

3. Deploy! Netlify will automatically:
   • Run prisma migrate deploy
   • Generate Prisma client
   • Build the Next.js app
   • Deploy using OpenNext

3. Post-Deployment

1. Health Check: Visit https://your-site.netlify.app/api/health
2. Database Test: Create a test community
3. Authentication: Test sign-in functionality
4. i18n: Verify language switching works

Smoke Test Checklist

• Health endpoint returns 200
• Database connection successful
• Home page loads correctly
• Language switching works (/en ↔ /es)
• Community creation works
• Authentication flow works
• Images load properly
• API routes respond correctly

Project Structure

src/
├── app/                    # Next.js App Router
│   ├── [locale]/          # Internationalized routes
│   │   ├── (auth)/        # Authentication pages
│   │   ├── (public)/      # Public pages
│   │   └── [slug]/        # Community pages
│   ├── api/               # API routes
│   └── globals.css        # Global styles
├── components/            # React components
│   └── ui/               # shadcn/ui components
├── lib/                  # Utility libraries
│   ├── auth.ts          # Auth.js configuration
│   ├── db.ts            # Prisma client
│   ├── i18n.ts          # Internationalization
│   ├── validators.ts    # Zod schemas
│   └── slug.ts          # URL slug utilities
├── messages/            # i18n message files
│   ├── en.json
│   └── es.json
└── middleware.ts        # Next.js middleware

Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint
• npm run prisma:studio - Open Prisma Studio
• npm run db:migrate - Run database migrations
• npm run db:generate - Generate Prisma client
• npm run seed - Seed the database

Database

The project uses Prisma as the ORM with PostgreSQL. Database schema is defined in prisma/schema.prisma.

Key models:

• User: Users with username and optional email
• Community: Multi-tenant communities with various settings
• CommunityMember: User memberships with roles and status
• Event: Community events with capacity and pricing
• Poll: Community polls with voting
• Payment: Simulated Lightning payments

Authentication

Secure authentication with Auth.js:

• Username + password (required)
• Email (optional, for password reset)
• Lightning Address (optional, for payments)
• Nostr Pubkey (optional, for decentralized identity)
• Password reset flow with email tokens
• Rate limiting on auth endpoints

Internationalization

The app supports English and Spanish with next-intl:

• Default locale: English (en)
• URL structure: /en/... or /es/...
• Message files in src/messages/
• Language switcher in header
• Full translation coverage (100%)

Roadmap

✅ Phase 1-5: Complete

• Testing framework (Vitest + Playwright)
• Password reset with email
• Rate limiting (Upstash Redis)
• CI/CD pipeline (GitHub Actions)
• Error monitoring (Sentry)

🚧 Phase 2: Security Hardening (Next)

• CSRF protection
• Authorization audit
• Input sanitization
• Session security improvements

📋 Phase 3: Performance

• Database indexes
• Caching strategy
• Image optimization
• Performance monitoring

🎯 Phase 4: Features

• Notifications system
• Image uploads
• Advanced search
• Analytics dashboard

⚡ Phase 5: Lightning Integration

• Real Lightning payments via NWC
• Payment webhooks
• Automatic refunds

See PROJECT_ROADMAP.md for full details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - see LICENSE file for details