Hack-N-Droid 2.0

Hack-N-Droid 2.0 is a role-based Flutter app for running a hackathon end-to-end. It supports participants, judges, and admins with a shared Firebase backend for auth, team data, announcements, judging, and a synchronized event timer.

Overview

This app is built for three user roles:

• Participants: sign in with Google, complete team details, view announcements, see event timer, and show team QR code.
• Judges: sign in with email/password, scan team QR, score teams in Round 1 / Round 2, and view scores overview.
• Admins: sign in with email/password, publish/pin/delete announcements, and control a global timer.

The app currently initializes Firebase for Android and Web. iOS/macOS/Linux/Windows Firebase options are not configured in the generated lib/firebase_options.dart.

Feature Set

Participant

• Google Sign-In onboarding.
• Auto-creation of participant profile in users collection on first login.
• Auto-creation of default team document in teams collection.
• Team details editor (team name, project title, description, 3–4 members).
• Team QR code generation (uid as payload).
• Real-time announcement feed with pinned announcement priority.
• Real-time synchronized hackathon timer (visible/hidden by admin).
• Local sign-out.

Judge

• Email/password login with role gate (role must be judge in Firestore).
• QR scanner (camera) to open team scoring screen.
• Round selector (Round 1 / Round 2).
• Weighted rubric scoring:
  • Problem Clarity: 20%
  • Innovation: 20%
  • Technical: 30%
  • Completeness: 20%
  • Feasibility: 10%
• Optional remarks per round.
• Existing score prefill when revisiting a team.
• Scores overview dashboard across teams and rounds.

Admin

• Email/password login with role gate (role must be admin in Firestore).
• Publish announcement (title, message, optional GIF URL).
• Pin/unpin announcement (single pinned announcement behavior).
• Delete announcement.
• Timer control panel:
  • Set duration (picker + quick presets)
  • Start / pause / resume / reset
  • Show/hide timer for participants

Tech Stack

• Framework: Flutter (Dart)
• State management / routing: GetX
• Backend: Firebase
  • Authentication (firebase_auth, google_sign_in)
  • Firestore (cloud_firestore)
  • Messaging (firebase_messaging)
• Local notifications: flutter_local_notifications
• QR generation: qr_flutter
• QR scanning: mobile_scanner
• HTTP client: http (announcement push trigger endpoint)

Architecture

The app follows a controller-driven pattern using GetX:

• AuthController handles auth, role resolution, and session checks.
• TeamController handles participant team CRUD editing flow.
• JudgeController handles team load, scoring state, weighted total, and save.
• AdminController handles announcement publishing and timer actions.
• TimerController listens to Firestore timer state and syncs countdown client-side.
• NotificationController handles FCM permission/topic subscription and local notifications.

Entry and navigation flow:

1. main.dart initializes Firebase + permanent controllers.
2. Root decides route by auth state + AppUser.role:
   • participant → MainShellScreen
   • judge → JudgeHomeScreen
   • admin → AdminHomeScreen
   • unauthenticated → LoginScreen

MainShellScreen uses a 3-page shell:

• Announcements
• Home (timer + QR)
• Profile

Project Structure

lib/
	controllers/
		admin_controller.dart
		auth_controller.dart
		judge_controller.dart
		notification_controller.dart
		team_controller.dart
		timer_controller.dart
	core/
		themes/
		utils/
		widgets/
	models/
		score.dart
		team.dart
		user.dart
	screens/
		admin/
		app/
		auth/
		judge/
	firebase_options.dart
	main.dart
	main_shell_screen.dart

Firestore Data Model

users/{uid}

{
	"name": "string",
	"email": "string",
	"role": "participant | judge | admin",
	"teamId": "string | null"
}

teams/{uid}

Participant team document (uid as doc id):

{
	"teamName": "string",
	"projectTitle": "string",
	"description": "string",
	"members": [
		{ "name": "string", "regNo": "string" }
	],
	"createdBy": "string",
	"createdAt": "timestamp"
}

announcements/{id}

{
	"title": "string",
	"message": "string",
	"gifUrl": "string",
	"createdAt": "timestamp",
	"isPinned": true
}

scores/{teamId}

{
	"teamName": "string",
	"round1": {
		"problemClarity": 0,
		"innovation": 0,
		"technical": 0,
		"completeness": 0,
		"feasibility": 0,
		"remarks": "optional string",
		"total": 0.0,
		"updatedAt": "timestamp"
	},
	"round2": {
		"problemClarity": 0,
		"innovation": 0,
		"technical": 0,
		"completeness": 0,
		"feasibility": 0,
		"remarks": "optional string",
		"total": 0.0,
		"updatedAt": "timestamp"
	},
	"total": 0.0,
	"updatedAt": "timestamp"
}

config/timer

{
	"duration": 86400,
	"isRunning": false,
	"isPaused": false,
	"isVisible": true,
	"remainingSeconds": 86400,
	"startTime": "timestamp"
}

Authentication & Roles

• Participants: Google Sign-In only.
• Admins/Judges: Email/password login.
• Email users without a valid Firestore role are signed out.
• Participant profile/team is auto-created on first Google login.

Seed admin/judge users in Firebase Auth and ensure matching Firestore users/{uid} docs with role: admin or role: judge.

Push Notifications

• Participants subscribe to FCM topic: announcements after login.
• Foreground messages are shown using flutter_local_notifications.
• Admin announcement publish also triggers an external HTTP endpoint:
  • https://hackndroid-backend.onrender.com/send-announcement

⚠️ The endpoint secret is currently hardcoded in app code. Move this to a secure backend-only secret management flow for production.

Prerequisites

• Flutter SDK (stable)
• Dart SDK (as bundled with Flutter)
• Android Studio / Xcode (for target platforms)
• Firebase project with:
  • Authentication (Google + Email/Password)
  • Cloud Firestore
  • Cloud Messaging
• Java 17 (Android build is configured for Java/Kotlin 17)

Local Setup

1) Clone and install

git clone <your-repo-url>
cd Hack-N-Droid
flutter pub get

2) Firebase setup

This repo already contains:

• android/app/google-services.json
• lib/firebase_options.dart

If you are using a different Firebase project, reconfigure with FlutterFire CLI:

dart pub global activate flutterfire_cli
flutterfire configure

Ensure at least Android and Web are configured.

3) Enable providers in Firebase console

• Google Sign-In
• Email/Password sign-in

4) Create Firestore role docs for admin/judge users

For each staff account, create users/{uid} with role:

{
	"name": "Judge One",
	"email": "judge@example.com",
	"role": "judge"
}

{
	"name": "Admin One",
	"email": "admin@example.com",
	"role": "admin"
}

Run the App

Android

flutter run

Web

flutter run -d chrome

Release build (example)

flutter build apk --release
flutter build web --release

UX Notes

• On non-mobile widths, screens are shown inside an IPhoneFrame container for a mobile-like preview.
• Home screen may auto-navigate users to team edit when required team info is incomplete.
• Team QR payload is the participant user/team document id.

Known Limitations

• Firebase options for iOS/macOS/Linux/Windows are not configured in current firebase_options.dart.
• Announcement push trigger URL + secret are hardcoded and should be production-hardened.
• No repository-level test suite is currently documented.

Troubleshooting

Login says “Access Denied” for staff

• Verify the Firebase Auth account exists.
• Verify matching Firestore users/{uid} doc exists.
• Ensure role is exactly admin or judge.

Camera scan not working

• Confirm camera permission is granted on device.
• Verify app has CAMERA permission in Android manifest (already present).

Notifications not appearing

• Confirm notification permission is granted.
• Confirm device is subscribed to topic after participant login.
• Confirm backend announcement endpoint is up and FCM server-side send is configured.

Timer not updating

• Verify config/timer exists in Firestore.
• If missing, it is auto-initialized at runtime by TimerController.

Linting & Analysis

flutter analyze

Lint rules come from flutter_lints via analysis_options.yaml.

Security Recommendations

Before production usage:

• Move any shared secrets out of client code.
• Add strict Firestore Security Rules for role-based read/write permissions.
• Restrict score writes to authenticated judges only.
• Restrict timer and announcement writes to admins only.

License

No explicit license file is currently present in this repository.