Enquesta Android Buzzer System

A complete quiz buzzer system consisting of an Android app and a serverless Flask API backend. Perfect for quiz competitions, game shows, or any scenario where you need to track the order of participants pressing a buzzer.

🏗️ System Architecture

┌─────────────────┐    HTTP GET     ┌─────────────────┐
│                 │    Request      │                 │
│  Android App    │ ───────────────▶│  Flask API      │
│  (Buzzer)       │                 │  (Vercel)       │
│                 │                 │                 │
└─────────────────┘                 └─────────────────┘
                                              │
                                              ▼
                                    ┌─────────────────┐
                                    │  Web Dashboard  │
                                    │  (Real-time)    │
                                    └─────────────────┘

📱 Android App Features

• Full-screen immersive mode - Hides status and navigation bars
• Large buzzer button - Easy to press during competitions
• Network connectivity - Sends buzz requests to remote server
• Notification suppression - Minimizes distractions during use
• Instant response - Low-latency network requests

🌐 API Backend Features

• Multi-buzzer support - Handles up to 6 different buzzers (b1-b6)
• Order tracking - Records the exact sequence of buzzer presses
• Thread-safe - Handles concurrent requests safely
• Real-time dashboard - Live view of buzz order
• JSON API - Programmatic access to results
• Reset functionality - Clear results between rounds

🚀 Quick Start

Running the Android App

1. Prerequisites

   • Android Studio 4.0 or later
   • Android device/emulator with API level 21+

2. Setup

   cd android-app
   # Open in Android Studio or build with Gradle
   ./gradlew assembleDebug

3. Install and Run

   • Install the APK on your Android device
   • Launch the app for full-screen buzzer interface

Running the API Backend

1. Local Development

   cd api-vercel
   pip install -r requirements.txt
   python api/index.py

   Access at http://localhost:5000

2. Deploy to Vercel

   npm i -g vercel
   cd api-vercel
   vercel deploy

📡 API Endpoints

Endpoint	Method	Description	Response
/b1 to /b6	GET	Register buzzer press	"1" (accepted) or "0" (rejected)
/reset	GET	Clear all buzzer data	"2"
/winners	GET	Get buzz order as JSON	["b2", "b1", "b4"]
/	GET	Real-time dashboard	HTML page

🎮 Usage Scenarios

Quiz Competition Setup

1. Deploy the API to Vercel or your preferred hosting platform
2. Install the Android app on participants' devices
3. Update the API URL in the Android app if using custom deployment
4. Open the dashboard at your API URL for real-time monitoring
5. Start the game - participants can buzz in order

Game Show Format

• Host monitors the web dashboard
• Participants use Android devices as buzzers
• First to buzz gets priority (recorded in order)
• Reset between questions using /reset endpoint

🔧 Configuration

Android App

The app is currently configured to send requests to:

https://flask-buzzer.vercel.app

To change the endpoint, modify the URL in MainActivity.kt:

val url = URL("https://your-api-endpoint.com/b1")

API Backend

The backend supports configuration through:

• MAX_BUZZES: Maximum number of buzzer presses to accept
• BUZZER_NAMES: Array of buzzer identifiers ("b1" through "b6")

🏃‍♂️ Development

Project Structure

├── android-app/          # Android buzzer application
│   ├── app/
│   │   └── src/main/
│   │       ├── java/com/example/buzzer/
│   │       │   └── MainActivity.kt
│   │       └── res/layout/
│   │           └── activity_main.xml
│   └── build.gradle
├── api-vercel/           # Flask API backend
│   ├── api/
│   │   └── index.py      # Main Flask application
│   ├── requirements.txt  # Python dependencies
│   └── vercel.json       # Vercel deployment config
└── README.md

Key Technologies

• Android: Kotlin, Android SDK
• Backend: Python, Flask, Flask-CORS
• Deployment: Vercel (serverless)
• Threading: Python threading for concurrent requests

📋 Requirements

Android App

• Android 5.0 (API level 21) or higher
• Network connectivity (WiFi or cellular)
• Permissions: Internet access

API Backend

• Python 3.7+
• Flask 2.0+
• Flask-CORS for cross-origin requests

🚨 Limitations

• Android notifications: Cannot fully block all system notifications (Android security restriction)
• Concurrent limit: Backend handles concurrent requests but has practical limits
• Network dependency: Requires stable internet connection for real-time functionality

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

This project is open source and available under the MIT License.

🆘 Support

• Android Issues: Check Android Studio build logs
• API Issues: Monitor Vercel deployment logs
• Network Issues: Verify API endpoint accessibility
• General Questions: Open an issue on GitHub

---

Built with ❤️ for quiz enthusiasts and competition organizers.