> Where College Events Actually Happen

Events shouldn't be scattered across WhatsApp statuses and Google Forms that nobody ever finds.

CampusEventHub brings them together. Students discover what's happening. Admins track registrations. Everyone stays in the loop.

🔥 The Problem We Solved

Your college hosts multiple events every year. Here's what actually happens:

graph LR
    A["📱 Event Posted"] 
    B["WhatsApp Groups"] 
    C["Instagram Stories"] 
    D["Random Emails"]
    E["Google Forms"]
    F["Lost Students"]
    G["Empty Events"]
    
    A --> B
    A --> C
    A --> D
    B --> F
    C --> F
    D --> E
    E --> F
    F --> G
    
    style A fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:3px
    style F fill:#F06595,stroke:#c2255c,color:#fff,stroke-width:3px
    style G fill:#C92A2A,stroke:#7D0F1F,color:#fff,stroke-width:3px
    style B fill:#FFA94D,stroke:#d9480f,color:#fff
    style C fill:#FFD43B,stroke:#f59f00,color:#000
    style D fill:#B5F7A0,stroke:#5c940d,color:#000
    style E fill:#74C0FC,stroke:#1971c2,color:#fff

Problem	What Happens
Discovery	Students miss 40% of events because they didn't see the announcement
Registration	Manual Google Forms with duplicate entries. No way to verify who's actually coming
Attendance	Admins manually count heads. No proof of participation. Data lost.
Learning	No insights into what worked. What events flopped. Why. Next time? Same mess.

✅ How We Fixed It

Students find events in one place. Register instantly. Get reminded. Admins see who's coming. Track attendance. Learn what works.

sequenceDiagram
    participant S as Student
    participant App as 📱 Hub
    participant API as Backend
    participant DB as Database
    
    S->>App: Browse events
    App->>API: GET /events
    API->>DB: Query
    DB-->>API: Events list
    API-->>App: Display
    App-->>S: "Tap one"
    
    S->>App: Register
    App->>API: POST /register
    alt Spots Available
        API->>DB: Create registration
        DB-->>API: ✅ Confirmed
        API-->>App: Calendar added<br/>Reminder set
    else Slots Full
        API->>DB: Add to waitlist
        DB-->>API: Position #3
        API-->>App: Waitlisted<br/>We'll notify
    end
    
    Note over S,DB: Event day → Check in with QR<br/>After → Leave feedback

🎯 What Each Role Gets

👤 Students

graph TD
    A["🔍 Discover"] --> B["Browse all college events<br/>in one place"]
    C["⚡ Register Fast"] --> D["Click once. In.<br/>Waitlist auto-manages"]
    E["🔔 Get Notified"] --> F["24hr reminder +<br/>updates if time changes"]
    G["⭐ Leave Feedback"] --> H["Rate events.<br/>Help admins improve"]
    
    style A fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:2px
    style C fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:2px
    style E fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:2px
    style G fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:2px
    style B fill:#95E1D3,stroke:#2d8659,color:#000
    style D fill:#95E1D3,stroke:#2d8659,color:#000
    style F fill:#95E1D3,stroke:#2d8659,color:#000
    style H fill:#95E1D3,stroke:#2d8659,color:#000

🏫 Event Admins

graph TD
    A["📝 Create Fast"] --> B["Title + date + capacity<br/>Live in 2 minutes"]
    C["✅ Track Real-Time"] --> D["See who registered.<br/>Who confirmed.<br/>Live dashboard"]
    E["🎯 Manage Capacity"] --> F["Set spots. Waitlist<br/>auto-manages. Close/open"]
    G["🔐 Mark Attendance"] --> H["QR check-in or manual.<br/>Proof for reports"]
    
    style A fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:2px
    style C fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:2px
    style E fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:2px
    style G fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:2px
    style B fill:#FFB3BA,stroke:#a61e4d,color:#000
    style D fill:#FFB3BA,stroke:#a61e4d,color:#000
    style F fill:#FFB3BA,stroke:#a61e4d,color:#000
    style H fill:#FFB3BA,stroke:#a61e4d,color:#000

⚙️ SuperAdmins

graph TD
    A["🏫 Manage Colleges"] --> B["Approve new institutions.<br/>Multi-tenant setup"]
    C["👁️ See Everything"] --> D["All events. All registrations.<br/>Complete audit logs"]
    E["📈 System Analytics"] --> F["Which colleges perform.<br/>Which event types work"]
    G["🔒 Security & Compliance"] --> H["Role-based access.<br/>Email verification.<br/>Two-factor auth"]
    
    style A fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:2px
    style C fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:2px
    style E fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:2px
    style G fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:2px
    style B fill:#FFF3BF,stroke:#e67700,color:#000
    style D fill:#FFF3BF,stroke:#e67700,color:#000
    style F fill:#FFF3BF,stroke:#e67700,color:#000
    style H fill:#FFF3BF,stroke:#e67700,color:#000

🔄 Event Lifecycle (How Events Move Through States)

stateDiagram-v2
    [*] --> Draft
    
    Draft --> Draft: Keep editing
    Draft --> Pending: Submit for review
    
    Pending --> Published: Admin approves
    Pending --> Draft: Needs changes
    
    Published --> Published: Registrations open
    Published --> Paused: Stop accepting students
    Published --> Cancelled: Something came up
    
    Paused --> Published: Resume accepting
    
    Cancelled --> [*]
    Published --> Ended: Event date passed
    Ended --> [*]

Stage	Who Sees It	What Students Do
Draft 🔵	Only creator	Nothing. They're editing.
Pending 🟡	Admin only	Nothing. Waiting for approval.
Published 🟢	Everyone	Browse, register, get reminded.
Paused ⏸️	Everyone	Can't register. Existing registrations stay.
Cancelled 🔴	Nobody	Deleted from listings. Students notified.
Ended ⚪	Everyone	Archived. Feedback visible. Analytics kept.

💻 How It's Built

graph TB
    subgraph FE["Frontend Layer"]
        A["React 18"]
        B["Vite Bundler"]
        C["Tailwind CSS"]
        D["Axios HTTP"]
    end
    
    subgraph API["API & Auth"]
        E["Express Server"]
        F["JWT Tokens"]
        G["Rate Limit"]
        H["Error Handler"]
    end
    
    subgraph DB["Data Layer"]
        I["MongoDB"]
        J["Mongoose ODM"]
        K["Audit Logs"]
    end
    
    subgraph EXT["External"]
        L["Cloudinary<br/>Images"]
        M["Nodemailer<br/>Emails"]
    end
    
    FE -->|REST API| API
    API -->|Query| DB
    API -->|Upload| L
    API -->|Send| M
    
    style FE fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:3px
    style API fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:3px
    style DB fill:#95E1D3,stroke:#2d8659,color:#000,stroke-width:3px
    style EXT fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:3px

Layer	Stack	Why
Frontend	React 18 + Vite + Tailwind	Fast dev server, instant hot reload, simple styling
Backend	Node.js + Express	JavaScript everywhere, real-time ready, easy to scale
Database	MongoDB	Flexible for events/registrations/feedback, no schema headaches
Auth	JWT + HttpOnly Cookies	Secure, works mobile & web, no server state needed
Files	Cloudinary	Event posters stored in cloud, not your server
Email	Nodemailer	Confirmations, reminders, notifications

🗂️ Data Model (What Gets Stored)

erDiagram
    COLLEGE ||--o{ USER : has
    COLLEGE ||--o{ EVENT : hosts
    USER ||--o{ REGISTRATION : makes
    EVENT ||--o{ REGISTRATION : receives
    EVENT ||--o{ FEEDBACK : gets
    USER ||--o{ FEEDBACK : submits
    
    COLLEGE {
        ObjectId college_id
        string name
        string email
        string status
        timestamp created_at
    }
    
    USER {
        ObjectId user_id
        string email
        string name
        string role
        ObjectId college_id
    }
    
    EVENT {
        ObjectId event_id
        string title
        string description
        datetime event_date
        int capacity
        string status
        ObjectId created_by
    }
    
    REGISTRATION {
        ObjectId reg_id
        ObjectId user_id
        ObjectId event_id
        string status
        datetime registered_at
    }
    
    FEEDBACK {
        ObjectId feedback_id
        ObjectId user_id
        ObjectId event_id
        int rating
        string comment
        datetime created_at
    }

The Connections:

College hosts multiple events
User belongs to one college, registers for events, leaves feedback
Event receives registrations and feedback
Registration links student to event
Feedback links student's opinion to event

🚀 Get Running in 5 Minutes

What You Need

Node.js v18+
MongoDB (free tier on MongoDB Atlas)
npm or yarn

Step 1: Clone

git clone https://github.com/udaycodespace/CampusEventHub.git
cd CampusEventHub

Step 2: Backend Setup

cd backend
npm install

# Create .env file
cat > .env << 'EOF'
MONGO_URI=mongodb+srv://your_user:password@cluster.mongodb.net/campushub
JWT_SECRET=your_random_secret_key_here
EMAIL_HOST=smtp.gmail.com
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
CLOUDINARY_NAME=your_name
CLOUDINARY_KEY=your_key
CLOUDINARY_SECRET=your_secret
NODE_ENV=development
PORT=5000
EOF

npm run dev
# ✅ Running on http://localhost:5000

Step 3: Frontend (New Terminal)

cd frontend
npm install

echo "VITE_API_URL=http://localhost:5000/api" > .env

npm run dev
# ✅ Open http://localhost:5173

Test it:

Student: student@test.com / password123
Admin: admin@test.com / password123

📡 API Endpoints (What You Can Do)

graph TB
    subgraph AUTH["Authentication"]
        A1["POST /auth/register"]
        A2["POST /auth/login"]
        A3["GET /auth/profile"]
        A4["POST /auth/logout"]
    end
    
    subgraph EVENTS["Events"]
        E1["GET /events"]
        E2["POST /events"]
        E3["PATCH /events/:id"]
        E4["DELETE /events/:id"]
    end
    
    subgraph REG["Registrations"]
        R1["POST /registrations/:eventId"]
        R2["GET /registrations/my"]
        R3["PATCH /registrations/:id/attend"]
        R4["DELETE /registrations/:id"]
    end
    
    subgraph FEED["Feedback"]
        F1["POST /feedback"]
        F2["GET /feedback/event/:eventId"]
    end
    
    style AUTH fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:2px
    style EVENTS fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:2px
    style REG fill:#95E1D3,stroke:#2d8659,color:#000,stroke-width:2px
    style FEED fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:2px

Full API reference → API.md

🔒 Security (We Take It Seriously)

✅ JWT + HttpOnly Cookies (blocks XSS attacks)
✅ Bcrypt password hashing (10 rounds, slow & safe)
✅ Rate limiting (100 requests per 15 min)
✅ CORS locked to your domain
✅ Input validation on every route
✅ Email verification on signup
✅ Audit logs for every action
✅ Role-based access control (RBAC)
✅ MongoDB injection prevention
✅ No secrets in code

Details → SECURITY.md

👥 Permissions Matrix (Who Can Do What)

graph TB
    subgraph S["👤 Student"]
        S1["✅ Browse events"]
        S2["✅ Register for events"]
        S3["✅ Cancel registration"]
        S4["✅ Submit feedback"]
        S5["❌ Create events"]
        S6["❌ See admin dashboard"]
    end
    
    subgraph A["🏫 Admin"]
        A1["✅ Create events"]
        A2["✅ Edit own events"]
        A3["✅ Track attendance"]
        A4["✅ See event analytics"]
        A5["✅ Manage registrations"]
        A6["❌ Approve colleges"]
        A7["❌ Delete other colleges' events"]
    end
    
    subgraph SU["⚙️ SuperAdmin"]
        SU1["✅ Approve colleges"]
        SU2["✅ Review all events"]
        SU3["✅ System-wide analytics"]
        SU4["✅ Access audit logs"]
        SU5["✅ Manage all roles"]
        SU6["✅ Everything"]
    end
    
    style S fill:#4ECDC1,stroke:#0a7e75,color:#fff,stroke-width:2px
    style A fill:#FF6B6B,stroke:#c92a2a,color:#fff,stroke-width:2px
    style SU fill:#FFE66D,stroke:#f59f00,color:#000,stroke-width:2px

📁 Where Everything Lives

CampusEventHub/
├── frontend/                    # React app
│   └── src/
│       ├── api/                 # API calls
│       ├── components/          # Reusable UI
│       ├── pages/               # Full screens
│       ├── context/             # Global state
│       └── styles/              # Tailwind setup
│
├── backend/                     # Express API
│   └── src/
│       ├── controllers/         # Route handlers
│       ├── models/              # Database schemas
│       ├── routes/              # URL endpoints
│       ├── middleware/          # Auth & validation
│       └── utils/               # Helpers
│
└── docs/                        # Guides
    ├── API.md
    ├── SECURITY.md
    └── DEPLOYMENT.md

🛠️ Commands (Build, Test, Deploy)

# Frontend
npm run dev          # Start (http://localhost:5173)
npm run build        # Production build
npm run preview      # Test production build locally
npm run lint         # Check code quality

# Backend
npm run dev          # Start with auto-reload
npm run start        # Production
npm run test         # Run tests
npm audit            # Check for vulnerabilities

# From root
npm run dev:all      # Start both servers
npm run build:all    # Build both

🐛 Troubleshooting

Having issues? Check TROUBLESHOOTING.md for detailed solutions to common problems.

Quick fixes:

MongoDB error? Check MONGO_URI in .env
Port already in use? Run lsof -i :5000 and kill it
API unreachable? Make sure backend is running on port 5000
Emails not sending? Use Gmail app password

Still stuck? → Open an Issue

🤝 Contributing (We Mean This)

Not all PRs merge. We're picky because we care.

We Accept ✅	We Don't Accept ❌
Bugs with clear reproduction steps	Random UI tweaks or style changes
Features students/admins actually requested	Refactors without a clear problem
Performance improvements with benchmarks	Features solving hypothetical problems
Documentation fixes & clarity	Churn changes (reformatting code)
Accessibility improvements	Anything that doesn't improve the app

How to Contribute

1. Find an issue (or create one)

https://github.com/springboardmentor212/CampusEventHub/issues

2. Fork & branch

git checkout -b fix/issue-name
# Make changes

3. Test

npm run lint    # No errors
npm run test    # All pass

4. Commit clearly

git commit -m "fix: describe what you fixed"
git push origin fix/issue-name

5. Open PR

Link the issue: Fixes #123
Explain what changed
Include screenshots if UI changed

6. Code review We review in 3-5 days. May ask for cleaner commits, more tests, or documentation updates.

Contribution Checklist

🧑‍💼 Project Admin

SOMAPURAM UDAY

Project Owner & Maintainer

Built and maintained CampusEventHub, from product decisions and code to design and everything in between.

💻 Full-stack development & architecture 🎨 UI/UX & Figma design ⚙️ Backend APIs & database 🧪 Testing & debugging
📦 Deployment & DevOps 📝 Documentation & code reviews

👥 Contributors

Different people. Different backgrounds. Different skills. One shared project. That's what open source is.

Gayatri

💾 Database implementation
🗂️ Milestone 1: Data models & schemas
🔌 Milestone 2: API endpoints

Charan

🎓 Architecture guidance
📋 Code review & best practices
🚀 Helped shape the project

Want to Contribute?

Submit a real PR that solves a problem. Get merged. Your name goes here + GitHub credit + resume permission.

How Contributions Shape the Project

pie title Contribution Types
    "Bug Fixes" : 40
    "Features" : 35
    "Docs" : 15
    "Performance" : 10

Timeline of Key Milestones

timeline
    title CampusEventHub Development
    2024-Q2 : Project kickoff : Initial architecture design
    2024-Q3 : Backend foundation : Database & API built
    2024-Q4 : Frontend launch : React UI deployed
    2025-Q1 : Student feedback : Waitlist system added
    2025-Q2 : Admin tools : Analytics dashboard
    2025-Q3 : Open source : Community contributions begin

📄 License

→ Read LICENSE

📚 Resources

Resource	Link	Purpose
API Docs	API.md	Every endpoint explained
Security Guide	SECURITY.md	How we keep data safe
Deployment	DEPLOYMENT.md	Deploy to production
Discussions	GitHub Discussions	Ask questions
Issues	Report bugs	Found a bug? Tell us

🌟 Give It a Star

If this helped your college manage events better:

⭐ Star this repo
🔗 Share with your college
💬 Feedback in Discussions
🐛 Report bugs
🤝 Contribute a fix

Questions? Let's Talk

📧 Email — Direct message
💬 Discussions — Ask anything
🔗 LinkedIn — Connect
💻 GitHub — More projects

Built With

Runs locally. Zero cost. Maximum value.

Students built this for students. 🎓⚡

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
.gitignore		.gitignore
CampusEventHub.pptx		CampusEventHub.pptx
CampusEventHub_Documentation.pdf		CampusEventHub_Documentation.pdf
FIGMA.md		FIGMA.md
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation