Skip to content

README.md

Latest commit

 

History

History
356 lines (253 loc) · 10 KB

README.md

File metadata and controls

356 lines (253 loc) · 10 KB
Raw

🐦‍⬛ MagPie Event Registration Platform

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!

Demo Version License

🪶 Why MagPie?

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)

✨ Key Features

  • 🎯 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

🚀 Quick Start

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • npm or yarn

Installation

# 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 cmake

Local development (no Turso needed)

For local builds, you do not need Turso. You can set the environment variable:

IS_LOCAL=true

This will use SQLite locally and skip Turso setup.

Email setup instructions

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_key

Choose your provider and add the corresponding API key. For more details, see Features Guide and Setup Guide.

Configure .env (see Setup Guide)

cp .env.example .env

Edit .env with your credentials

Frontend setup

cd ../frontend npm install

Start both servers (Option 1 - Recommended)

cd .. ./start.sh

OR Start manually (Option 2)

Terminal 1: cd backend && source venv/bin/activate && uvicorn app.main:app --reload

Terminal 2: cd frontend && npm run dev


**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

Render - Separate Services (Legacy)

# 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

Other Platforms

MagPie can nest anywhere:

  • Vercel / Netlify (frontend)
  • AWS / DigitalOcean (backend)
  • Docker containers
  • Traditional VPS

🔐 Security

  • ✅ 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

📝 Environment Variables

Backend (.env)

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:+14155238886

Frontend (.env)

VITE_API_URL=http://localhost:8000
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

🤝 Contributing

MagPies are social birds, and so are we! Contributions are welcome:

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Open a Pull Request

👥 Contributors

Thanks to these wonderful people who have contributed to MagPie! 🐦‍⬛

Made with contrib.rocks

📜 License

MIT License - Feel free to use and modify for your needs.

🆘 Support

🐦‍⬛ Fun Fact

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 ~*