Event-Hall-Booking-App

# 🏛️ Halla: Secure Event Hall Booking System ### Final Year Project Technical & Security Architecture Report ![Flutter](https://img.shields.io/badge/Framework-Flutter-02569B?style=for-the-badge&logo=flutter&logoColor=white) ![Dart](https://img.shields.io/badge/Language-Dart-0175C2?style=for-the-badge&logo=dart&logoColor=white) ![Firebase](https://img.shields.io/badge/Backend-Firebase-FFCA28?style=for-the-badge&logo=firebase&logoColor=black) ![Security](https://img.shields.io/badge/Security-AES--256-4CAF50?style=for-the-badge&logo=letsencrypt&logoColor=white) *A comprehensive breakdown of the languages, integrations, packages, and security mitigations designed to solve critical problem statements in peer-to-peer booking platforms.*

Last Deep Scan: 2026-05-16 — application encryption migrated from AES-256-CBC to AES-256-GCM (authenticated encryption / AEAD); MobSF static-analysis triage in SECURITY.md now references concrete deobfuscated class names; PII redacted from debug logs. flutter analyze clean, flutter test 9/9 passing.

📋 Requirements

Before setting up the project, ensure your environment meets the following requirements:

Requirement	Version
Flutter SDK	3.x (stable channel)
Dart SDK	3.x (bundled with Flutter)
Firebase CLI	Latest (v13.x+)
Node.js	18.x / 20.x LTS
Android Studio	Hedgehog (2023.1.1+) or later
Xcode	15.x+ (macOS only, for iOS builds)
Platform Targets	Android 8.0+ (API 26), iOS 16.0+

✨ Features

🔐 Security & Privacy

AES-256-GCM authenticated encryption for sensitive fields (with backward-compatible decrypt for legacy CBC records)
Android Keystore / Apple Keychain integration via flutter_secure_storage
Firebase App Check (Play Integrity API + DeviceCheck) to block emulators & tampered APKs
Root / Jailbreak detection — app terminates on compromised OS environments
Input validation middleware — strips HTML tags and NoSQL injection operators
Server-side Role-Based Access Control (RBAC) via Firebase Cloud Functions

📍 Booking & Discovery

Interactive map-based hall discovery (flutter_map + OpenStreetMap)
Real-time availability calendar (table_calendar)
Atomic Firestore transactions to prevent double-booking
Geolocation-based search and reverse geocoding
Detailed hall pages with high-resolution imagery

🧠 Host Verification

Business license, national ID PDF, and selfie evidence upload
Server-side promotion through Cloud Functions
Firebase custom claims prevent client-side role tampering

👤 User Management

OAuth 2.0 (Google Sign-In), email/password, and phone (SMS) authentication
Role-based routing (User, Host, Admin)
Multi-factor authentication support
Profile management with privacy controls
Real-time notifications & messaging

📄 Payment & Receipt Handling

Secure receipt uploads to Firebase Storage
Verification gateway for payment confirmation
Encrypted payment data handling

📸 Screenshots

Screenshots will be added here. Place image files in the screenshots/ directory.

Home	Map	Calendar	Host Dashboard	Security

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/your-username/halla-event-booking.git
cd halla-event-booking

2. Install Flutter Dependencies

flutter pub get

3. Configure Firebase

# Login to Firebase
npx -y firebase-tools@latest login

# List your Firebase projects
npx -y firebase-tools@latest projects:list

# Fetch the Firebase configuration for this project
# Replace <project-id> with your Firebase project ID
flutterfire configure --project=<project-id>

If lib/firebase_options.dart already exists in your clone, keep it synchronized with your Firebase project settings by re-running flutterfire configure. This project keeps lib/firebase_options.dart in version control for consistent team and CI builds.

4. Set Up Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env with your actual values

5. Install Cloud Functions Dependencies (optional)

cd functions
npm install
cd ..

If you deploy Cloud Functions, use Node.js 22 (as defined in functions/package.json).

6. Run the Application

# For development
flutter run

# For a specific platform
flutter run -d android   # Android device/emulator
flutter run -d ios       # iOS simulator (macOS only)
flutter run -d chrome    # Web (limited support)

7. Build for Production

# Android APK
flutter build apk --split-per-abi

# Android App Bundle (Play Store)
flutter build appbundle

# iOS (requires Xcode and Apple Developer account)
flutter build ipa

🔥 Firebase Setup

Enable the following Firebase services in the Firebase Console:

Required Services

Service	Purpose	Configuration Steps
Authentication	User sign-in & session management	Enable Email/Password, Google (OAuth), and Phone sign-in providers
Cloud Firestore	Primary NoSQL database	Deploy security rules via `firestore.rules`; create indexes as needed
Cloud Storage	Receipt & image storage	Deploy security rules via `storage.rules`
Cloud Functions	Server-side RBAC logic	Deploy with `npx -y firebase-tools@latest deploy --only functions`
App Check	Play Integrity & DeviceCheck	Register Android (SHA-256) and iOS app in App Check section

Callable Cloud Functions enforce Firebase App Check. For local debug builds, register the Firebase App Check debug token shown in the app logs.

Deploy Security Rules & Functions

# Deploy Firestore security rules
npx -y firebase-tools@latest deploy --only firestore:rules

# Deploy Storage security rules
npx -y firebase-tools@latest deploy --only storage:rules

# Deploy Cloud Functions
npx -y firebase-tools@latest deploy --only functions

💻 1. Core Languages & Technology Stack

The application utilizes a modern, cross-platform, serverless architecture to ensure high performance and robust security.

Technology Layer	Primary Languages & Platforms	Purpose
Frontend UI/UX		Used exclusively for building the reactive Flutter UI, client-side encryption, and business logic.
Native Compilation		Flutter compiles the Dart code Down-to-Machine-Code (AOT) using Kotlin (Android) and Swift (iOS), making the app highly resistant to reverse-engineering.
Backend / DB		Cloud Firestore (NoSQL) serves as the primary database, utilizing strictly typed Firebase Security Rules.
Serverless Logic		Firebase Cloud Functions execute secure, admin-level logic (like Host Promotion) entirely server-side, preventing client manipulation.

🔌 2. System Integrations & External Packages

To fulfill the complex requirements of the Architecture Diagrams and Problem Statement, the system integrates several advanced external packages.

🔐 Security & Cryptography

encrypt (^5.0.3): The core AES-256-GCM authenticated-encryption engine (with legacy CBC decrypt path). Secures sensitive payloads locally before transit; tampered ciphertext is rejected at decrypt time.
flutter_secure_storage (^9.0.0): Interfaces directly with the OS's native Android Keystore and Apple Keychain to lock cryptographic keys away from app memory.
crypto (^3.0.3): Provides SHA-256 hashing for one-way data masking.
firebase_app_check: Integrates Google Play Integrity API and Apple DeviceCheck to block requests from emulators, bots, or tampered APKs.

🧠 Host Verification & Automated Governance

The host application flow collects identity evidence and sends role promotion through Cloud Functions.

file_picker and image_picker: Collect business license PDFs, national ID PDFs, selfies, receipt images, and hall photos.
cloud_functions: Performs server-side host promotion and booking slot reservation without trusting client privilege writes.

☁️ Backend & Database Ecosystem

firebase_core & cloud_firestore: The foundational NoSQL database for syncing Users, Inventory, and Bookings in real-time.
firebase_storage: Secure bucket storage for payment receipts and high-res hall imagery.
cloud_functions: Triggers automated server-side code without exposing admin privileges to the mobile client.

📍 Geolocation & Interactive Mapping

geolocator & geocoding: Interfaces with native GPS hardware to fetch physical coordinates and reverse-geocode physical addresses.
flutter_map (^7.0.2) & latlong2: Provides a robust, open-source mapping interface to display hall locations natively.

📱 User Identity & Interfaces

firebase_auth & google_sign_in: Manages user sessions, OAuth 2.0 Google logins, and SMS-based Multi-Factor Authentication (MFA).
table_calendar (^3.0.9): Manages complex booking dates, seamlessly tying into Firestore Atomic Transactions.
image_picker & file_picker: Securely interfaces with the device camera and gallery for document uploads.
Custom Skeleton UI Engine: A zero-dependency, highly performant AnimationController based shimmer effect used across the app to improve perceived loading speeds without bloating the application bundle size.

🛡️ 3. FYP Security Architecture Mapping

The following table synthesizes the Misuse Case Diagram and proves exactly how the chosen technology stack mitigates the identified OWASP Mobile Top 10 problem statements.

🔴 FYP Problem Statement (Identified Threat)	🔵 Architectural Mitigation Strategy	🛠️ Packages & Technologies Used	🟢 Protection Status
OWASP M9: Insecure Data Storage / Data Theft _{Threat: Unauthorized extraction of sensitive PII from databases or local device storage.}	Client-Side Encryption Engine & OS Keystore	`encrypt` `flutter_secure_storage`	✅ Fully Protected Data is encrypted locally using AES-256 before transit. Keys are locked in the hardware Keystore/Keychain, making data unreadable even if Firestore is breached.
OWASP M7: Reverse Engineering / Tampering _{Threat: Attackers decompiling the app or using rooted devices to bypass security logic.}	AOT Compilation, App Check & Root Detection	`firebase_app_check` Custom Root Service	✅ Fully Protected Play Integrity API drops requests from tampered apps. The custom `root_detection_service.dart` strictly kills the app (`exit(0)`) if `su` binaries or jailbreaks are detected.
OWASP M3: Broken Access Control / Hijacking _{Threat: Users exploiting the client code to manually elevate their role to 'Host'.}	Server-Side RBAC & Automated Governance	`cloud_functions` Firestore custom claims	✅ Protected The client app cannot change user roles directly. A secure Cloud Function verifies the host application and executes role promotion.
OWASP M4: Double-Booking Fraud / Race Conditions _{Threat: Multiple users attempting to book the exact same hall simultaneously.}	Atomic Database Transactions & Smart Logic	`cloud_firestore` `table_calendar`	✅ Fully Protected Approvals trigger Firestore Atomic Transactions. If two users write to the same date block at the exact same millisecond, the transaction aborts automatically.
OWASP M8: Code Injection / XSS _{Threat: Malicious actors injecting scripts into booking notes or hall descriptions.}	Strict Input Validation Middleware	Custom Dart Logic (`input_validation_service.dart`)	✅ Fully Protected A middleware gateway sanitizes all inputs via strict Regex. It strips HTML tags (stopping XSS) and removes NoSQL operators (e.g., `$gt`, `$where`) to stop injection attacks.

💡 Final Year Project Note: By isolating privileges using Cloud Functions, implementing AES-256 encryption for sensitive values, and applying atomic Firestore transactions, this application moves beyond a standard CRUD app and establishes a strong zero-trust security posture for an FYP system.

🔒 Security Features Summary

Category	Feature	Implementation
Data Encryption	AES-256-GCM (AEAD)	Authenticated encryption via `encrypt` package; legacy CBC records decrypted backward-compatibly
Key Storage	Hardware-backed Keystore	`flutter_secure_storage` wrapping Android Keystore / Apple Keychain
Device Integrity	App Check	Play Integrity API (Android) + DeviceCheck (iOS)
Root Detection	Runtime OS integrity check	Custom `root_detection_service.dart` — exits app on compromise
Input Validation	XSS & NoSQL injection prevention	`input_validation_service.dart` — regex sanitization middleware
Access Control	Server-side RBAC	Cloud Functions handle role elevation; clients cannot self-elevate
Anti-Fraud	Host evidence review	Business license, national ID PDF, selfie upload, and server-side role promotion
Concurrency	Atomic Firestore transactions	Prevents double-booking race conditions

📁 Project Structure

eventbookingapp/
├── android/                 # Android platform files (Kotlin)
├── ios/                     # iOS platform files (Swift)
├── lib/
│   ├── host/                # Host-specific features (dashboard, halls, bookings)
│   ├── models/              # Data models (booking, user, hall, etc.)
│   ├── pages/               # Screens / UI pages
│   │   └── profile/         # Profile sub-screens
│   ├── services/            # Business logic & integrations
│   ├── theme/               # App theming (colors, fonts, theme)
│   └── widgets/             # Reusable UI components
├── functions/               # Firebase Cloud Functions (Node.js)
├── scripts/                 # Utility & backfill scripts
├── docs/                    # Additional documentation
├── font/                    # Custom fonts (Inter)
├── icon/                    # App icon assets (Android & iOS)
├── images/                  # App image assets
├── plans/                   # Planning documents & reports
├── public/                  # Public web assets (privacy, terms)
├── test/                    # Unit & widget tests
├── web/                     # Web platform files
├── .firebaserc              # Firebase project alias mapping
├── firebase.json            # Firebase project configuration
├── firestore.rules          # Firestore security rules
├── storage.rules            # Cloud Storage security rules
└── pubspec.yaml             # Flutter project dependencies

🧰 Tech Stack

Category	Technology
Framework	Flutter 3.x (Dart 3.x)
Backend	Firebase (Cloud Firestore, Cloud Functions, Cloud Storage)
Authentication	Firebase Auth (Google OAuth, Email/Password, Phone)
State Management	setState / InheritedWidget
Maps	flutter_map + OpenStreetMap (latlong2)
Verification	Firebase Auth, App Check, Cloud Functions, Storage evidence uploads
Encryption	AES-256-GCM (encrypt) + SHA-256 (crypto)
Secure Storage	flutter_secure_storage (Keystore / Keychain)
Calendar	table_calendar
Geolocation	geolocator, geocoding
CI/CD	GitHub Actions

🤝 Contributing

This is a final year project. Contributions, issues, and feature requests are welcome. See SECURITY.md for security-related guidelines.

📄 License

This project is intended for academic and educational purposes.

📬 Contact

For general questions, open a GitHub Issue. For security vulnerabilities, follow the private responsible disclosure process in SECURITY.md.

Built With

c
c++
cmake
dart
html
javascript
kotlin
objective-c
powershell
ruby
shell
swift