MagPie: Like the clever bird that collects shiny things, MagPie intelligently gathers and organizes your event registrations with style and efficiency.
A professional, production-ready event registration system with dynamic forms, QR code check-ins, and WhatsApp notifications - now with a touch of avian elegance!
Just like the magpie bird known for its intelligence and ability to recognize patterns, MagPie Event Registration Platform:
- Collects registrations with precision
- Remembers user data intelligently (auto-fill feature)
- Organizes events with beautiful simplicity
- Communicates effectively (WhatsApp notifications)
- Adapts to your needs (dynamic forms)
- 🎯 Event Management - Create, edit, clone, and manage events
- 📝 Dynamic Registration Forms - Add custom fields per event
- 🔄 Smart Auto-fill System - MagPie remembers user data across events
- 📱 WhatsApp Notifications - Send bulk messages to registrants with templates and filtering
- 📧 Email Notifications - Beautiful HTML emails with Resend (100 emails/day free tier)
- 🔗 QR Code Check-ins - Generate and scan QR codes for attendance
- 📊 Analytics & Export - View registrations and export to CSV
- 🎨 Modern UI Themes - 22 professional themes with light/dark modes
- ✨ Smooth Animations - Motion One powered animations (lightweight, performant)
- 🔒 Secure Dashboard - Clerk authentication protects admin features
- ⚡ Fast & Reliable - Built with FastAPI and React
- Python 3.11+
- Node.js 18+
- npm or yarn
# Clone the MagPie repository
git clone https://github.com/PandaWhoCodes/magpie.git
cd magpie
# Backend setup
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
## libsql installation error
If you encounter errors installing `libsql-client` or building the backend, make sure you have CMake installed:
```bash
brew install cmakeFor local builds, you do not need Turso. You can set the environment variable:
IS_LOCAL=trueThis will use SQLite locally and skip Turso setup.
To enable email notifications, set up your provider credentials in .env:
EMAIL_PROVIDER=resend # or brevo
RESEND_API_KEY=your_resend_key
BREVO_API_KEY=your_brevo_keyChoose your provider and add the corresponding API key. For more details, see Features Guide and Setup Guide.
cp .env.example .env
cd ../frontend npm install
cd .. ./start.sh
**Access MagPie**:
- 🏠 Frontend: http://localhost:3000
- 📊 Dashboard: http://localhost:3000/dashboard
- 🔧 API: http://localhost:8000
- 📖 API Docs: http://localhost:8000/docs
For detailed installation instructions, see **[Setup Guide](docs/SETUP.md)**.
---
## 🎨 Themes
MagPie comes with **22 professionally designed themes**, each with light and dark modes:
### Popular Themes
- 🌈 **modern-minimal** - Clean, contemporary design
- 💜 **violet-bloom** - Elegant purple accents
- 🌊 **ocean-breeze** - Calming blue tones
- 🌃 **cyberpunk** - Neon-fueled futuristic vibes
- 🎨 **pastel-dreams** - Soft, gentle colors
- 🌲 **forest-mist** - Natural green palette
- ☕ **notebook** - Warm, paper-like aesthetic
- 🎮 **doom-64** - Retro gaming inspired
- 💻 **hacker-green** - Classic terminal look
- ...and 13 more!
**Features:**
- Light and dark modes for each theme
- CSS variable-based (zero-cost switching)
- Custom fonts per theme
- 6-hour caching with auto-invalidation
Switch themes from Dashboard → Branding Settings
---
## 📖 Documentation
| Document | Description |
|----------|-------------|
| **[Setup Guide](docs/SETUP.md)** | Complete installation and configuration |
| **[Features Guide](docs/FEATURES.md)** | Detailed feature documentation |
| **[API Reference](docs/API.md)** | API endpoints and examples |
| **[WhatsApp Setup](docs/WHATSAPP_SETUP.md)** | WhatsApp integration guide |
| **[Deployment Guide](docs/DEPLOYMENT.md)** | Production deployment instructions |
| **[System Architecture](SYSTEM_ARCHITECTURE.md)** | Technical architecture details |
| **[Animation Quick Start](ANIMATION_QUICK_START.md)** | Get started with animations in 5 minutes ⚡ |
| **[Animation Patterns](ANIMATION_PATTERNS.md)** | 35+ ready-to-use animation components |
| **[UI Enhancement Guide](UI_ENHANCEMENT_GUIDE.md)** | Comprehensive animation library guide |
---
## 🛠️ Tech Stack
### Backend Nest 🪺
- **FastAPI** - Modern Python web framework
- **Turso** - Serverless SQLite database
- **Twilio** - WhatsApp messaging API
- **Pydantic** - Data validation
### Frontend Feathers 🪶
- **React 18** - UI library
- **Vite** - Build tool
- **TailwindCSS + shadcn/ui** - Styling & components
- **Motion One** - Lightweight animations (5.8KB)
- **React Query** - State management
- **Clerk** - Authentication
---
## 📱 WhatsApp Integration
Send bulk WhatsApp messages to all event registrants with one click!
**Features**:
- 📤 Bulk messaging
- 📱 Automatic phone formatting (+91 for India)
- 📊 Delivery tracking
- 💰 Cost-effective (FREE sandbox, ~₹0.75/msg production)
**Setup**: See [WhatsApp Setup Guide](docs/WHATSAPP_SETUP.md)
---
## 🎯 Usage
### 1. Create an Event
Visit Dashboard → Create Event → Add custom fields → Save
### 2. Activate Event
Click toggle icon to activate (only one event can be active at a time - like a magpie focusing on one shiny object!)
### 3. Share Registration Link
Share `http://localhost:3000` with participants
### 4. Manage Registrations
View registrations → Export CSV → Send WhatsApp messages
### 5. Check-in with QR Codes
Generate QR code → Print/display → Scan at event
**For detailed usage**, see [Features Guide](docs/FEATURES.md).
---
## 📊 Dashboard Features
**Access**: `/dashboard` (Clerk authentication required)
- 🔐 **Secure Access** - Protected with Clerk authentication
- ✏️ **Create/Edit Events** - Manage event details and fields
- 🔄 **Clone Events** - Duplicate with one click
- 👥 **View Registrations** - Search, filter, check-in status
- 📱 **Send WhatsApp** - Bulk messaging with templates and field-based filtering
- 💬 **Message Templates** - Create reusable WhatsApp message templates with variables
- 📥 **Export CSV** - Download registration data
- 🔗 **Generate QR Codes** - For check-ins with custom messages
- ⚡ **Toggle Active Status** - Activate/deactivate events
- 🎨 **Theme Switcher** - Toggle between Default and Midnight Black
---
## 🚢 Deployment
### Fly.io - Single App (Recommended) 🚀
**One command deployment** - FastAPI serves the React frontend as static files.
```bash
# Quick deploy
./fly-deploy.sh
# Or manually:
fly deploy --build-secret VITE_CLERK_PUBLISHABLE_KEY
Advantages:
- ✅ One app = simpler management
- ✅ Lower cost than separate services
- ✅ No CORS issues (same domain)
- ✅ Built-in SSL and auto-scaling
Setup Guide: docs/FLY_DEPLOYMENT.md
# Push to GitHub
git push origin master
# Deploy on Render
# 1. Connect repository
# 2. Render auto-detects render.yaml
# 3. Add environment variables
# 4. Deploy!Setup Guide: docs/DEPLOYMENT.md
MagPie can nest anywhere:
- Vercel / Netlify (frontend)
- AWS / DigitalOcean (backend)
- Docker containers
- Traditional VPS
- ✅ Clerk authentication for dashboard access
- ✅ JWT-based API authentication
- ✅ Input validation (Pydantic)
- ✅ SQL injection prevention
- ✅ XSS protection
- ✅ CORS configuration
- ✅ Environment variables for secrets
- ✅ Protected admin endpoints with public registration routes
TURSO_DATABASE_URL=your_database_url
TURSO_AUTH_TOKEN=your_auth_token
FRONTEND_URL=http://localhost:3000
CLERK_SECRET_KEY=sk_test_...
# Optional: WhatsApp
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886VITE_API_URL=http://localhost:8000
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...MagPies are social birds, and so are we! Contributions are welcome:
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Open a Pull Request
Thanks to these wonderful people who have contributed to MagPie! 🐦⬛
Made with contrib.rocks
MIT License - Feel free to use and modify for your needs.
Did you know? Magpies are one of the few animals that can recognize themselves in a mirror - just like how MagPie recognizes returning users and auto-fills their data!
Made with ❤️ and a touch of avian intelligence
*~ MagPie: Where Events Take Flight ~*