Hostel Mess App - Codebase Explorer

An interactive overview of the Flutter application's architecture and features.

Project Overview

This application provides a high-level overview of the 'Hostel Mess App' Flutter codebase. Its purpose is to manage a hostel's mess system, allowing students to book meals and admins to manage the system. This explorer helps developers understand the project's structure, technology stack, and key components.

Technology Stack

  • Framework: Flutter (for cross-platform mobile and web)
  • Language: Dart
  • State Management: `provider` package
  • API Communication: REST API via `http` package
  • Backend: Deployed at OnRender
  • Local Storage: `shared_preferences` (for auth token)
  • Notifications: Firebase Cloud Messaging (FCM) for mobile
  • Animation: `flutter_staggered_animations` (lists), `Lottie` (JSON animations)

File Breakdown

Application Architecture

The app follows a clear, layered architecture centered around the `provider` state management pattern. This separates UI, business logic, and data services.

Core Concept: Provider

`Provider` allows us to separate logic from widgets. Instead of a screen fetching its own data, it "listens" to a provider. This makes the UI dumb (presentation only) and the providers smart (logic and state).

  • UI Layer (Screens): Displays data from a provider. Calls methods on the provider (e.g., `context.read().fetchNotices()`).
  • Provider Layer: Holds state (e.g., `_isLoading`, `_notices`). Contains logic to fetch/update data (e.g., `fetchNotices()`). Calls `ApiService` for network requests.
  • Service Layer: Helper classes like `ApiService`. Abstract away complex tasks (like making an HTTP request).

High-Level Architecture Diagram

This diagram shows the overall separation of concerns and data flow in the application.

1. UI Layer (Screens)

Flutter Widgets

(e.g., BookingScreen, NoticeScreen)

User interacts. Calls provider methods.

↑

Listens for state changes.

2. Provider Layer (State)

Provider Classes

(e.g., AuthProvider, BookingProvider)

Holds state & logic. Calls `notifyListeners()`.

↓

Calls services.

3. Service & Data Layer

Service Classes

(e.g., ApiService, NotificationService)

Abstracts external tasks.

↓
External Data

(Backend API, Firebase, Local Storage)

Visual Workflow: Data Fetch (e.g., Fetching Notices)

This diagram shows how all layers interact when a user action (like a pull-to-refresh) triggers a data fetch.

UI Layer

NoticeScreen

User triggers `_refreshNotices()`

↓

Calls `context.read().fetchNotices()`

➔

Provider Layer

NoticeProvider

`_isLoading = true;`
`notifyListeners();`

↓

Calls `_apiService.get('/notices/')`

↓
NoticeProvider

Receives response, populates `_notices` list, sets `_isLoading = false;`, calls `notifyListeners()`

➔

Service/API Layer

ApiService.get()

Attaches Auth token, sends HTTP GET request

↓↑
Backend API

Returns JSON data

User Features

The application provides a robust set of features for the primary user (students). This section details each user-facing screen, its purpose, and the key state providers it interacts with. Click on a feature to see its details.

Feature List

Select a feature

Admin Features

A separate set of password-protected screens are available for administrators (roles: `convenor`, `mess_committee`), accessible via the Profile screen. These features focus on management and oversight.

Feature List

Select a feature

Data & State Management

State management is handled by the `provider` package. Each `...Provider` class encapsulates a specific piece of state, fetches its own data, and notifies listeners of changes. This is the "brain" behind each feature.

Key State Providers

AuthProvider

Manages authentication state, user object (`_currentUser`), and token (`_token`). Handles login, logout, register, and profile updates.

AdminProvider

Manages all admin-related data, including the list of users (`_users`) and the daily meal list (`_mealList`).

BookingProvider

Handles the logic for the `BookingScreen`. Submits, updates, and cancels bookings for a *specific selected date*.

MyBookingsProvider

Fetches and holds the *entire list* of the user's past and future bookings for the `MyBookingsScreen`.

MenuProvider

Fetches and caches the menu (lunch/dinner options) for any given date.

NoticeProvider

Fetches and holds the list of all notices for the `NoticeScreen`.

ThemeProvider

Manages the app's theme (Light/Dark mode) and persists the choice using `shared_preferences`.

Core Services

The app uses several service classes to abstract common tasks, promote reusability, and keep logic out of the providers. These are the main services:

ApiService

The central hub for all network communication. It's responsible for:

  • Holding the base URL for the backend.
  • Automatically attaching the `Authorization` token to requests.
  • Providing clean `get`, `post`, `patch`, `delete` methods.
  • Handling different content types (JSON vs. form-encoded).

NotificationService

Handles all logic for Firebase Cloud Messaging (FCM) on mobile platforms (iOS/Android). It is disabled on the web.

  • Requesting user permissions for notifications.
  • Initializing foreground and background message handlers.
  • Retrieving the FCM token and sending it to the backend via `AuthProvider`.

PdfExportService

A static class dedicated to generating a PDF report for the admin's "Daily Meal List" screen. It uses the `pdf` and `printing` packages to:

  • Take the `MealList` data object and chart images as input.
  • Construct a multi-page PDF document with headers, footers, charts, and tables.
  • Provide a `Uint8List` of the PDF to be saved or shared (using `printing` for web and `open_filex` for mobile).

Contribution Guide

Welcome to the team! Here's how you can get started and contribute to the project.

Setup & Installation

  1. Fork & Clone: Fork the repository to your own account, then clone it to your local machine.
  2. Get Dependencies: Run `flutter pub get` in the project root to install all required packages.
  3. Run the App: Connect a device or simulator and run `flutter run`. The app should build and connect to the production backend.

Code Style & Quality

We follow the standard Dart & Flutter style guides. Before committing, please run:

  • flutter format . to auto-format all code.
  • flutter analyze to check for any static analysis errors.
  • Fix all warnings reported by the analyzer.

Contribution Workflow

  1. Create a Branch: Create a new branch from `main` for your feature or bugfix (e.g., `git checkout -b feature/add-meal-rating`).
  2. Implement Changes: Write your code, following the architecture rules below.
  3. Test Locally: Thoroughly test your changes on both iOS and Android simulators (and web, if applicable).
  4. Commit: Write clear, descriptive commit messages (e.g., `feat(booking): Add meal rating feature`).
  5. Push & Open PR: Push your branch to your fork and open a Pull Request against the main repository's `main` branch.
  6. Code Review: Wait for feedback, address any comments, and get approval.

Golden Architectural Rules

  • UI is Dumb: Screens in `lib/screens/` should contain *no* business logic. They only display state from providers and call functions on them.
  • Logic is in Providers: All state, business logic, and API calls should be initiated from a class in `lib/provider/`.
  • Use ApiService: *Never* use the `http` package directly in a provider. Always call `ApiService` methods.
  • Separate Concerns: Don't add unrelated logic to an existing provider. If it's a new, distinct feature, create a new provider.