BLACK_

THE ULTIMATE OPEN SOURCE ACADEMIC SPACE

Introduction

Welcome to the comprehensive technical documentation for BLACK. This document provides an exhaustive, in-depth analysis of the application's architecture, codebase, backend structure, and core components. It is intended for developers who wish to contribute to the project or understand its inner workings at a professional level.

BLACK is a cross-platform mobile application built with Flutter and Dart, designed to be a central hub for students. It combines note sharing, task management, and social features into a single, cohesive experience. The backend is powered by a combination of Firebase for notifications and Supabase for authentication, database, and storage, leveraging the strengths of each platform.

Architectural Overview

The project strictly follows the principles of Clean Architecture. This approach decouples the code into distinct layers, promoting maintainability, scalability, and testability. The data flows between these layers in a structured, predictable way.

The Three Layers

  • Presentation (UI Layer): Composed of Flutter widgets located in the screens/ and widgets/ directories. Its sole responsibility is to display data provided by the Application layer and to capture user input. It is "dumb" and contains no business logic.
  • Application (Business Logic Layer): This is the brain of the application. It contains the application-specific business rules and orchestrates the flow of data. This logic is implemented within the providers/ and the service classes themselves. For example, when a user taps "Upload Note", the UI layer calls a method in a provider, which in turn uses a service to handle the upload logic.
  • Data (Data Access Layer): This layer is responsible for all communication with the outside world, primarily the Supabase and Firebase backends. It abstracts the data sources from the rest of the application. The services/ directory contains this layer's implementation. The Application layer knows it needs to fetch a user profile, but it doesn't know or care if that profile comes from Supabase, Firebase, or a local cache—that's the Data layer's job.

Data Flow Example: User Login

  1. User enters email/password on LoginScreen (UI Layer) and taps "Login".
  2. The `onPressed` callback calls a method, e.g., AuthService.signInWithPassword().
  3. The AuthService (Data Layer) makes an API call to Supabase Auth.
  4. Supabase responds with success or failure.
  5. The AuthService returns the result to the LoginScreen.
  6. The LoginScreen (UI Layer) updates its state to show a success message and navigate to the home screen, or display an error.

Key Dependencies Analysis

The project's functionality is heavily supported by a set of carefully chosen packages from pubspec.yaml. Understanding these is key to understanding the app.

  • supabase_flutter: The cornerstone of the backend connection. It provides a singleton client for all Supabase interactions. Example: final client = Supabase.instance.client; is used in every service to perform database queries, authentication, and file storage operations.
  • provider: The chosen state management solution. It uses the InheritedWidget system to provide state down the widget tree efficiently. For example, ThemeProvider is provided at the top of the app in main.dart, and any widget can listen to theme changes using context.watch().
  • firebase_core & firebase_messaging: Used exclusively for Push Notifications. NotificationService contains the logic to initialize Firebase, request user permission for notifications, and handle incoming messages when the app is in the foreground, background, or terminated.
  • flutter_pdfview & photo_view: These are critical for the core note-viewing feature. The ViewNotesScreen dynamically chooses which widget to render based on the file extension of the note's URL, providing a seamless experience for both PDFs and images.
  • shared_preferences: A simple key-value store for non-sensitive data. Its only major use case in this app is persisting the user's theme choice (true/false for dark mode) so it's remembered when the app is closed and reopened.

Project Structure Analysis

The lib directory is meticulously organized to reflect the Clean Architecture principles. Below is a file-by-file breakdown.

lib/
├── assets/
│   └── default_profile.png
├── main.dart
├── providers/
│   ├── note_engagement_provider.dart
│   └── theme_provider.dart
├── screens/
│   ├── calendar_screen.dart
│   ├── create_post_screen.dart
│   ├── followers_list_screen.dart
│   ├── forum_post_screen.dart
│   ├── forum_screen.dart
│   ├── home_screen.dart
│   ├── login_screen.dart
│   ├── manage_notes_screen.dart
│   ├── profile_screen.dart
│   ├── search_notes_screen.dart
│   ├── search_users_screen.dart
│   ├── settings_screen.dart
│   ├── signup_screen.dart
│   ├── splash_screen.dart
│   ├── splash_screen_animation.dart
│   ├── todo_screen.dart
│   ├── trending_notes_screen.dart
│   ├── upload_notes_screen.dart
│   ├── user_selection_screen.dart
│   ├── verify_otp_reset_screen.dart
│   └── view_notes_screen.dart
├── services/
│   ├── auth_service.dart
│   ├── followers_service.dart
│   ├── forum_service.dart
│   ├── note_engagement_service.dart
│   ├── note_service.dart
│   ├── notification_service.dart
│   ├── search_service.dart
│   ├── supabase_service.dart
│   └── user_service.dart
├── utils/
│   ├── document_preview_widget.dart
│   ├── file_loading_dialog.dart
│   ├── in_app_file_viewer.dart
│   ├── profile_picture_handler.dart
│   ├── secure_file_handler.dart
│   └── secure_file_viewer.dart
└── widgets/
    ├── background_widget.dart
    ├── native_ad_widget.dart
    └── profile_notes_grid.dart

Backend Schema (Supabase)

Understanding the database structure is crucial. The app relies on several tables in Supabase PostgreSQL.

`profiles` table

Stores public user data. Linked via a one-to-one relationship to the `auth.users` table.

  • `id` (uuid, Primary Key): Foreign key to `auth.users.id`.
  • `username` (text)
  • `full_name` (text)
  • `avatar_url` (text): URL to the user's profile picture in Supabase Storage.
  • `updated_at` (timestamp)

`notes` table

Stores metadata for every uploaded note.

  • `id` (uuid, Primary Key)
  • `user_id` (uuid): Foreign key to `profiles.id`.
  • `title` (text)
  • `subject` (text)
  • `file_url` (text): URL to the note file in Supabase Storage.
  • `created_at` (timestamp)

`followers` table

A many-to-many relationship table for the social graph.

  • `follower_id` (uuid): The user who is doing the following.
  • `followed_id` (uuid): The user who is being followed.
  • (Composite Primary Key on both columns)

`posts` and `replies` tables

Powers the community forum.

  • `posts` table contains `id`, `user_id`, `title`, `content`.
  • `replies` table contains `id`, `post_id`, `user_id`, `content`.

Core Logic & Entry Point

main.dart

This is the application's entry point. It performs critical initialization tasks in a specific order:

  1. WidgetsFlutterBinding.ensureInitialized(): Ensures the Flutter engine is ready.
  2. Supabase.initialize(): Sets up the global Supabase client with the URL and anon key. This is mandatory before any service is called.
  3. Provider Setup: The entire app is wrapped in a MultiProvider. This is where providers like ThemeProvider are created and made available to the entire widget tree.
  4. runApp(MyApp()): Starts the Flutter application by mounting the root widget.

firebase_options.dart

This file is auto-generated by the FlutterFire CLI. It contains the platform-specific configuration details (API keys, project IDs) required to connect the app to your Firebase project. It's crucial for enabling Firebase services, especially Firebase Cloud Messaging for notifications.

Services Deep Dive

The services directory is the data layer. Each service is a stateless class that communicates with the backend.

AuthService.dart

Handles all user authentication. It is a wrapper around Supabase.instance.client.auth.

  • signUpUser(...): Calls supabase.auth.signUp(). On success, it immediately inserts a new row into the `profiles` table using the returned user's ID.
  • signInWithPassword(...): Calls supabase.auth.signInWithPassword().

NoteService.dart

Manages all CRUD operations for notes. This involves both the database and storage.

  • uploadNote(...): A critical multi-step process. First, it uploads the file bytes to Supabase Storage at a unique path (e.g., `user_id/note_id.pdf`). Second, it gets the public URL of the uploaded file. Third, it inserts a new record into the `notes` table with the metadata and the file URL.
  • deleteNote(...): The reverse of upload. It first deletes the file from Supabase Storage, then deletes the record from the `notes` table.

Screens Deep Dive

Each file in screens/ represents a full page in the app. They are stateful widgets that fetch data from services and display it.

profile_screen.dart

  • Purpose: Displays a user's profile, including their name, avatar, follower counts, and a grid of their uploaded notes.
  • State Management: It's a `StatefulWidget`. In `initState`, it calls `UserService.fetchUserProfile()` and `FollowersService.fetchFollowers()` to get the necessary data. It uses `setState` to update the UI when the data arrives.
  • Key Widgets: Uses a `FutureBuilder` to handle the loading state of the profile data. The body contains a `ProfileNotesGrid` widget, passing the user ID to it.

view_notes_screen.dart

  • Purpose: Renders a specific note file (PDF or image).
  • Logic: It receives a `note` object. It downloads the file from the note's `file_url` into the device's cache using the `flutter_cache_manager` package. It then checks the file extension. If it's a PDF, it renders the `FlutterPdfView` widget. If it's an image, it renders the `PhotoView` widget.
  • Engagement: This screen is also responsible for tracking views. When the screen is initialized, it calls `NoteEngagementService.incrementViewCount()` and notifies the `NoteEngagementProvider`.

State Management: Providers

Providers are used to manage and share application state, avoiding the need to pass data down through many layers of widgets.

ThemeProvider.dart

Manages the app's theme. It's a `ChangeNotifier`.

  • It holds a private boolean, _isDarkMode.
  • It exposes a public getter isDarkMode.
  • The toggleTheme() method changes the boolean, saves the new value to `SharedPreferences`, and then calls `notifyListeners()` to trigger a rebuild in all listening widgets.

Utilities Deep Dive

The utils directory contains helper classes and functions that are reused across the application.

  • profile_picture_handler.dart: Encapsulates the entire flow of updating a profile picture: uses `image_picker` to let the user select a file, uploads the file to Supabase Storage, gets the URL, and finally calls `UserService` to update the `avatar_url` in the user's profile.
  • file_loading_dialog.dart: A simple utility function that shows a standardized, non-dismissible `AlertDialog` with a `CircularProgressIndicator`. Used across the app to give the user feedback during long operations like file uploads or downloads.

Custom Widgets Analysis

This directory contains reusable UI components to maintain a consistent look and feel and reduce code duplication.

  • profile_notes_grid.dart: A highly reusable widget. It takes a `userId` as a parameter. It is a `StatefulWidget` that calls `NoteService.fetchUserNotes(userId)` and displays the results in a `GridView.builder`. This isolates the logic for fetching and displaying notes, so it can be used on the main profile screen, a different user's profile screen, etc.
  • native_ad_widget.dart: Encapsulates all the boilerplate for loading and displaying a native ad from `google_mobile_ads`. It handles creating the ad, loading it, and building the widget layout, making it easy to drop an ad into any list view with a single line.

Conclusion

The BLACK codebase is a well-structured and robust Flutter application that effectively leverages modern tools and architectural patterns. The strict adherence to Clean Architecture, with a clear separation of concerns into services (Data), providers (Application), and screens (Presentation), makes the project highly maintainable, testable, and scalable. The pragmatic choice of Supabase for the primary backend and Firebase for notifications demonstrates a solid understanding of using the best tool for each job.

This deep analysis reveals a solid foundation. Future contributors can confidently build upon this structure. Potential areas for improvement include expanding test coverage with more unit and widget tests, implementing more sophisticated caching strategies to reduce network calls, and further refining the UI/UX for an even more polished feel. Overall, the project is an excellent example of a modern Flutter application and a fantastic starting point for new contributors.