A comprehensive, production-ready NFC-based user management system for Model United Nations conferences and large-scale events.
NFC WESMUN is a cutting-edge conference management platform designed specifically for Model United Nations events. It leverages NFC technology to streamline delegate check-ins, bag verification, attendance tracking, and dietary management—all through a secure, role-based system.
- Lightning Fast: Instant delegate identification via NFC tags
- Enterprise Security: Multi-layer security with audit logging
- Mobile Optimized: Perfect for on-the-go security personnel
- Modern UI: Beautiful, responsive interface built with shadcn/ui
- Rich Analytics: Export and analyze data in CSV/PDF formats
- Scalable: Handles hundreds of delegates efficiently
- Unique UUID Assignment: Each delegate receives a unique NFC identifier
- Instant Recognition: Fast delegate lookup and verification
- Custom UUID Format: Base36 encoding for compact, URL-safe identifiers
- User Registration & Approval: Multi-step approval workflow for new users
- Bulk Operations: Create, update, and delete users in bulk
- Data-Only Users: Import delegate lists without login credentials
- Profile Management: Comprehensive delegate profiles with dietary info
- Role Assignment: Granular permission control with 4 distinct roles
- Email Domain Restrictions: Elevated roles limited to @wesmun.com emails
- Account Freeze: Temporarily suspend user accounts without deletion
Four specialized roles with distinct permissions:
| Role | Use Case |
|---|---|
| User | Conference delegates |
| Security | Security checkpoints |
| Overseer | Monitoring & reporting |
| Admin | Conference organizers |
Plus: Emergency Admin role for audit log access and setup
- Bag Check: Mark when security screening is complete
- Attendance: Track delegate check-in/check-out
- Food Distribution: Monitor meal allocation status
- Dietary Preferences: Veg/Non-veg with allergen tracking
- Scan History: View complete interaction timeline
- Live Updates: Real-time synchronization across devices
- Complete Activity Trail: Every action logged with actor and target
- IP & User Agent Tracking: Enhanced security monitoring
- Historical Snapshots: Preserve user data even after changes
- Advanced Filtering: Search by action, user, date, or IP
- Emergency Admin Access: Dedicated role for audit review
- Multiple Formats: Export to CSV or PDF
- Advanced Filtering: Filter by attendance, diet, bags, etc.
- Count Queries: Get statistics without downloading data
- Custom Columns: Include NFC links, scan counts, allergens
- Date Stamping: Auto-generated filenames with timestamps
- Bulk Data: Handle hundreds of records efficiently
- Responsive Layout: Optimized for phones, tablets, and desktops
- Touch-Friendly: Large buttons and intuitive gestures
- Dark Mode: Reduce eye strain during long events
- Fast Loading: Optimized bundle sizes for mobile networks
- Scanner View: Dedicated interface for security/overseer/admin personnel
- Session-Based Auth: Secure HTTP-only cookies
- Rate Limiting: Prevent brute force attacks
- SQL Injection Protection: Parameterized queries throughout
- XSS Prevention: Content Security Policy headers
- Node.js: v18.0.0 or higher
- npm/pnpm/yarn: Latest version
- PostgreSQL: v15.0 or higher (local or hosted)
- Git: For version control
-
Clone the repository
git clone https://github.com/DefinetlyNotAI/WESMUN_NFC cd nfc-wesmun -
Install dependencies
npm install # or pnpm install -
Set up environment variables
Create a
.env.localfile in the root directory:# Database Configuration (Neon PostgreSQL) # Use the pooled connection for serverless deployments (PgBouncer) DATABASE_URL=postgres://user:password@host:POOLER_PORT/database?sslmode=require # Session Configuration (generate with: openssl rand -base64 32) CSRF_SECRET=your-super-secret-csrf-token-here # Emergency Admin Credentials NEXT_PUBLIC_EMERGENCY_ADMIN_NAME=username@domain.com EMERGENCY_ADMIN_PASSWORD=your-password-here NEXT_PUBLIC_EMERGENCY_ADMIN_NAME='username to be used' # Next.js Configuration / Custom APP Settings # Note you still need to update capacitor.config.ts for mobile apps settings NEXT_PUBLIC_BASE_URL=https://your-domain.example.com NEXT_PUBLIC_MUN_NAME=mun-name NEXT_PUBLIC_RESERVED_EMAIL_DOMAIN=your-email-domain.com
-
Set up the database
# Initialize database with all tables, indexes, functions, and views npm run db:setup # or node scripts/syncDB.js --setup # Verify database health npm run db:check
-
Run the development server
npm run dev
-
Open your browser
Navigate to http://localhost:3000
- Login in via emergency admin and setup new admin accounts to share
- Create NFC links for delegates in the admin panel
- Start scanning NFC tags at your event
- Framework: Next.js 16 with App Router
- Language: TypeScript 5
- Styling: Tailwind CSS v4
- Components: shadcn/ui + Radix UI
- Icons: Lucide React
- Theme: next-themes for dark mode
- Analytics: Vercel Analytics
- Runtime: Node.js 18+
- Database: PostgreSQL 15+
- ORM: Raw SQL with node-postgres (pg)
- Authentication: Custom session-based auth
- PDF Generation: pdf-lib
- Hosting: Vercel (recommended) or any Node.js host
- Database Hosting: Neon, Supabase, Aiven or self-hosted PostgreSQL
- Version Control: Git
- CI/CD: Vercel automatic deployments
-
Push to GitHub
git push origin main
-
Import to Vercel
- Go to vercel.com/new
- Import your repository
- Configure environment variables
- Deploy!
-
Set Environment Variables in Vercel Dashboard
Node.js Server
npm run build
npm startKey Architectural Principle: All access control in this system is permission-based, not role-based.
- All authorization checks use
hasPermission() - Roles are organizational containers - They group permissions together
- No assumptions about roles - Check permissions explicitly, never assume a role has certain permissions
- Emergency admin via permissions - Admin role with all permissions enabled by default
- No role-only checks exist - Every access decision is made by checking specific permissions
This diagram illustrates the high-level architecture of the NFC system, which follows a 6-layer serverless web application architecture.
Click to view basic visualisation
┌─────────────────────────────────────────────────────────────────────┐
│ Client / Browser │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Frontend (Next.js UI) │ │
│ │ ┌───────┬──────┬──────┬───────┬───────┬───────┬────────┐ │ │
│ │ │ Auth │ User │ NFC │ Admin │ Audit │ Stats │ System │ │ │
│ │ │ Pages │ Ctrl │ Scan │ Panel │ Logs │ View │ Alerts │ │ │
│ │ └───────┴──────┴──────┴───────┴───────┴───────┴────────┘ │ │
│ │ (React components, hooks, client-side state) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ [cookies] ↕ HTTPS (fetch) │
└───────────────────────────────┬─────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Backend │
│ (Next.js Server Runtime) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Application Programming Interface Layer [API] (/api/*) │ │
│ │ • Auth & Sessions • Day System / Global State │ │
│ │ • Users & Roles • NFC Scan Ingestion │ │
│ │ • Admin Actions • Audit & Alerts │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ↕ internal http calls │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Business Logic Layer [BLL] (lib/) │ │
│ │ • Day-state synchronization • Alert generation │ │
│ │ • Validation & rate limiting • Audit logging │ │
│ │ • Permission checks │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ↕ SQL over TCP/IP │
└───────────────────────────────┬─────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Database Layer │
│ (Serverless PostgreSQL Database) │
│ • users • profiles • roles │
│ • session_tokens • rate_limits • nfc_links │
│ • day_records • global_day_config • audit_logs │
│ • admin_alerts │
└─────────────────────────────────────────────────────────────────────┘
- Authentication: User logs in → Session created → Cookie set
- NFC Scan: QR/NFC scanned → UUID sent to API → User data fetched → Profile updated
- Audit Log: Action performed → Log entry created with actor, target, details
- Permissions: Request received → User authenticated → Role checked → Permission verified
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- shadcn/ui for beautiful component primitives
- Vercel for serverless hosting and deployment platform
- Neon for serverless PostgreSQL database
- Issues: GitHub Issues
- Documentation: Wiki
- Security: See SECURITY.md
This project is licensed under the MIT License - see the LICENSE file for details.