⚡ EventSync

One platform for running modern hackathons and technology events.
From registration and QR check-in to team formation, judge allocation, scoring, live rankings, and organizer operations.

🌐 Live App · ⚙️ API · 💻 Repository

---

🎯 Why EventSync?

Large technology events usually split operations across spreadsheets, chat groups, QR tools, submission forms, judge sheets, and separate leaderboard systems. That fragmentation creates delays, duplicate work, and poor visibility for organizers.

EventSync turns those disconnected workflows into a single live command center.

The core problem

How do we run a large-scale technical event from one operational system without forcing organizers, judges, and participants across disconnected tools?

The solution

Workflow	EventSync approach
Registration	Unified account + event membership
Check-in	Personal QR pass + organizer verification
Team formation	Browse teams + deterministic Smart Match
Team operations	Requests, approvals, roster management, invitations
Project submission	Structured team submission workflow
Judge allocation	Organizer-controlled assignment + workload visibility
Judging	Weighted rubric + qualitative feedback
Leaderboard	Live score aggregation + variance warning
Broadcasting	Priority announcements + pinned alerts
Operations	Organizer Command Center + Action Center

---

✨ Feature Overview

🎓 Participant

• Personal dashboard for the active event
• Event-specific QR check-in pass
• Smart Match teammate discovery
• Browse open teams
• Create and manage a team
• Send and manage team join requests
• Team roster and leader controls
• Submit and edit project details
• Announcements feed
• Live leaderboard

⚖️ Judge

• Dedicated judge experience
• Assigned-submission queue
• Project repository/demo links
• Weighted rubric evaluation
• Numeric scoring + feedback
• Evaluation status tracking
• Leaderboard visibility
• Judge assignments enforced server-side

🧑‍💼 Organizer

• Live Operations Command Center
• Participant/judge/organizer membership management
• Judge assignment and workload tracking
• Event configuration
• Track management
• QR check-in terminal
• Announcement broadcasting
• Leaderboard monitoring
• Operational alerts / Action Center

🛡️ Technical Administration

• Django Admin at /admin/
• User and event management
• EventMembership management
• Teams, submissions, judging, check-ins, and announcements
• Separate from event-level Organizer permissions

---

👥 Role Model

EventSync uses one user identity with event-scoped roles.

flowchart TD
    U[User Account] --> M[EventMembership]
    M --> P[Participant]
    M --> J[Judge]
    M --> O[Organizer]

    P --> PD[Participant Experience]
    J --> JD[Judge Experience]
    O --> OD[Organizer Command Center]

Loading

A person's email domain does not grant permissions. Gmail, Outlook, university emails, and custom domains are treated the same. The server checks the user's active EventMembership for the specific event.

This allows the same user to have different roles in different events.

---

🔁 How the Platform Works

Participant lifecycle

flowchart LR
    R[Register] --> E[Event Membership]
    E --> D[Dashboard]
    D --> C[QR Check-in]
    D --> T[Team / Smart Match]
    T --> S[Submit Project]
    S --> L[Live Leaderboard]

Loading

Team lifecycle

flowchart TD
    A[Participant] --> B[Browse / Smart Match]
    B --> C[Join Request]
    C --> D[Team Leader Review]
    D -->|Accept| E[Team Member]
    D -->|Reject| F[Request Rejected]
    E --> G[Team Roster]
    G --> H[Leader manages members]

Loading

Judging lifecycle

flowchart LR
    O[Organizer] --> A[Assign Judge]
    A --> J[Judge]
    J --> S[Assigned Submission]
    S --> R[Weighted Rubric]
    R --> E[Evaluation]
    E --> L[Leaderboard]

Loading

---

🏗️ Architecture at a Glance

flowchart TB
    B[Browser]
    F[React + Vite + TypeScript]
    Q[TanStack Query + Axios]
    API[FastAPI REST API]
    D[Django ORM + Django Admin]
    DB[(PostgreSQL)]

    B --> F
    F --> Q
    Q --> API
    API --> D
    D --> DB

    F -. /admin .-> D

Loading

Stack

Layer	Technology	Purpose
Frontend	React 18 + Vite + TypeScript	UI and client routing
Styling	Tailwind CSS + shadcn/ui	Product UI
Interaction	Motion + Lucide React	Animation and icons
Data	TanStack Query + Axios	API state and caching
Charts	Recharts	Organizer analytics
API	FastAPI + Pydantic	REST endpoints and validation
Domain/data	Django + Django ORM	Models, migrations, admin
Database	PostgreSQL	Production source of truth
Auth	JWT	Stateless API authentication
Deployment	Vercel + Render + PostgreSQL/Neon	Production hosting

See docs/ARCHITECTURE.md for the full system, role, data, and request-flow diagrams.

---

🚀 Run Locally

Backend

cd backend

# Activate virtual environment
.\.venv\Scripts\activate          # Windows
# source .venv/bin/activate          # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Apply migrations
python manage.py migrate

# Seed demo data
python manage.py seed_demo_data

# Start API
uvicorn api.main:create_app --factory --reload --port 8000

Frontend

cd frontend

npm install
npm run dev

Production build:

npm run build

Test suite

cd backend
pytest

The final hardening pass reported 54/54 backend tests passing and a clean frontend production build.

---

🌐 Production

Service	URL
Frontend	https://event-sync-ten.vercel.app/
Backend	https://event-sync-api.onrender.com/
API docs	https://event-sync-api.onrender.com/docs
Repository	https://github.com/ankush-poonia007/event-sync

Deployment model

flowchart LR
    G[GitHub main] --> V[Vercel]
    G --> R[Render]
    V --> F[React Frontend]
    R --> B[FastAPI + Django]
    B --> P[(PostgreSQL / Neon)]

Loading

See docs/DEPLOYMENT.md for environment variables, build commands, CORS, routing, and deployment notes.

---

🔐 Authentication & Access

Public registration creates a normal account. Privileged event access is assigned through EventMembership.

Public registration
      ↓
User account
      ↓
EventMembership
      ↓
participant / judge / organizer

A normal participant cannot promote themselves to Judge or Organizer from the registration form.

For technical administration, Django Admin remains separate from event-level Organizer permissions.

See docs/USER_GUIDE.md for the exact onboarding flow for participants, judges, and organizers.

---

🧪 Validation Snapshot

The final implementation report recorded:

• 54/54 backend tests passed
• 0 Django system-check issues
• No pending model migrations
• Frontend npm run build passed with 0 compilation errors
• Git working tree clean
• Final hardening commit: ea7eda8

---

📚 Documentation

Document	Purpose
README.md	Project overview, features, setup, deployment
docs/ARCHITECTURE.md	System, data, role, API, and deployment architecture
docs/USER_GUIDE.md	Participant, Judge, Organizer, and Admin workflows
docs/DEPLOYMENT.md	Vercel, Render, PostgreSQL, env vars, production startup
docs/SECURITY.md	Authentication, authorization, secrets, event isolation
docs/DEMO_GUIDE.md	Competition demo script and seeded demo accounts

---

🏆 Competition Context

EventSync was built as a competition-oriented event operations platform for PromptWars 2026 xAbhiyantriX.

The product is designed to demonstrate that event management can be treated as a real-time systems problem: identity, attendance, collaboration, submissions, evaluation, communication, and ranking all converge on the same event context.

---

📌 Status

MVP + enhancement batches + final hardening completed.

The project is intentionally kept as a modular Django + FastAPI + React system rather than being split into unnecessary microservices. The implementation prioritizes event isolation, role-based access, operational visibility, and a clean competition demo experience.

---

📄 License

Add the project's intended license here before public reuse.