Skip to content

README.md

Latest commit

 

History

History
294 lines (230 loc) · 7.91 KB

README.md

File metadata and controls

294 lines (230 loc) · 7.91 KB
Raw

🚀 HackFlow

Python Flask Supabase Cloud Run License Tests Coverage

Stars Forks Issues

Smart Hackathon Management System — A production-ready platform for managing hackathons and large-scale tech events. Streamline participant queues, volunteer coordination, and event operations through a unified, role-based interface.

✨ Features

🔹 User Panel

  • Join and track position in real-time queues
  • View estimated wait times and counter availability
  • Receive live updates and announcements
  • Submit help requests

🔹 Volunteer Panel

  • Manage food and resource counters
  • Handle participant help requests
  • Monitor crowd zones and capacity
  • Coordinate with other volunteers

🔹 Admin Panel

  • Complete user and role management
  • Approve and manage volunteer registrations
  • Control counter status and capacity
  • Send event-wide announcements
  • View analytics and insights

🔐 Security & Scalability

  • Role-based access control (RBAC) — Three distinct user roles with granular permissions
  • Secure authentication — Google OAuth + Email/Password login with bcrypt hashing
  • Backend validation — All requests validated server-side
  • Production security — CSRF protection, secure cookies (HttpOnly, SameSite)
  • Cloud-native — Scales automatically on Google Cloud Run

🛠 Tech Stack

Category Technology
Backend Flask (Python)
Database Supabase (PostgreSQL)
Authentication Google OAuth + Email/Password
Frontend HTML, CSS, JavaScript
Deployment Google Cloud Run
Testing Pytest + Coverage
Containerization Docker

📁 Project Structure

HackFlow/
├── app/
│   ├── __init__.py
│   ├── auth/
│   │   ├── __init__.py
│   │   └── routes.py
│   ├── main/
│   │   ├── __init__.py
│   │   └── routes.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── user.py
│   ├── templates/
│   │   ├── auth/
│   │   ├── main/
│   │   └── base.html
│   ├── static/
│   │   ├── css/
│   │   ├── js/
│   │   └── images/
│   └── utils/
│       ├── __init__.py
│       └── decorators.py
├── tests/
│   ├── test_auth.py
│   └── test_protected.py
├── .env
├── .gitignore
├── requirements.txt
├── run.py
└── Dockerfile

🚦 Quick Start

# Clone the repository
git clone https://github.com/TheMukeshDev/HackFlow.git
cd HackFlow

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py

Access the app at http://localhost:5000

⚙️ Installation & Setup

Prerequisites

  • Python 3.8+
  • Supabase account
  • Google Cloud project (for OAuth)

1. Clone the Repository

git clone https://github.com/TheMukeshDev/HackFlow.git
cd HackFlow

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the project root:

# Supabase
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_anon_key

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Flask
SECRET_KEY=your_flask_secret_key
FLASK_ENV=development

4. Run the Application

python run.py

🔧 Environment Variables

Variable Required Description
SUPABASE_URL ✅ Your Supabase project URL
SUPABASE_KEY ✅ Supabase anon/public key
SUPABASE_SERVICE_KEY ❌ Supabase service role key
GOOGLE_CLIENT_ID ❌ Google OAuth Client ID
GOOGLE_CLIENT_SECRET ❌ Google OAuth Client Secret
GOOGLE_REDIRECT_URI ❌ OAuth callback URL
SECRET_KEY ✅ Flask secret key
FLASK_ENV ❌ development or production
PORT ❌ Server port (default: 8080)
BCRYPT_LOG_ROUNDS ❌ Hashing rounds (default: 12)
RATELIMIT_ENABLED ❌ Enable rate limiting
SESSION_COOKIE_SECURE ❌ Require HTTPS for cookies
WTF_CSRF_ENABLED ❌ Enable CSRF protection

🧪 Testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=hackflow --cov-report=html

Test Coverage

  • Login/logout flows
  • Registration validation
  • Role-based access control
  • Session management
  • API security

☁️ Deployment (Google Cloud Run)

1. Build the Docker Image

gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/hackflow

2. Deploy to Cloud Run

gcloud run deploy hackflow \
  --image gcr.io/YOUR_PROJECT_ID/hackflow \
  --platform managed \
  --region asia-south2 \
  --allow-unauthenticated

3. Set Environment Variables

gcloud run services update hackflow \
  --update-env-vars "\
SUPABASE_URL=your-supabase-url,\
SUPABASE_KEY=your-supabase-key,\
FLASK_ENV=production,\
SECRET_KEY=your-secure-secret,\
GOOGLE_CLIENT_ID=your-client-id,\
GOOGLE_CLIENT_SECRET=your-secret,\
GOOGLE_REDIRECT_URI=https://your-app.run.app/auth/google/callback" \
  --region asia-south2

4. Configure Google OAuth

In Google Cloud Console > APIs & Services > Credentials:

  • Authorized redirect URIs: 
    https://your-app.run.app/auth/google/callback
  • Authorized JavaScript origins: 
    https://your-app.run.app

🔮 Future Enhancements

  • 🌐 Real-time updates via WebSockets
  • 📊 Advanced analytics dashboard
  • 🤖 AI-based crowd prediction
  • 📱 Mobile application
  • 🎪 Multi-event support

🤝 Contributing

Contributions are welcome! Follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature-name)
  3. Commit your changes
  4. Push to the branch
  5. Open a Pull Request

📄 License

MIT License — See LICENSE for details.

👤 Author

Mukesh Kumar
B.Tech Student | Tech Hub BBS

LinkedIn GitHub

Made with ❤️ by Mukesh Kumar