# amishapai/beeflow architecture

> Architecture diagram of the GitHub repository amishapai/beeflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amishapai/beeflow
- Repository: https://github.com/amishapai/beeflow

## Overview

##### Project Type & Purpose
- BeeFlow is a cross-platform mobile/desktop application built with Flutter that focuses on task management, gamification, focus mode, and AI-powered task breakdowns for users with ADHD.
- The README clearly outlines its purpose as a productivity tool with features such as smart task management, gamification, progress tracking, voice input, and focus mode.

##### Analyzing the File Structure
- Platform Specific Directories: Notice the android, ios, linux, macos, web, and windows folders. These indicate a Flutter project that targets multiple platforms.
- Core Flutter Code: The main application logic is in the lib directory, which contains:
- config: For configuration files (e.g., Gemini API key and XP settings).
- models: Data models like user, task, settings, progress, and subtasks.
- providers: State management classes using the Provider package.
- screens: Different UI screens (login, task list, focus mode, progress, settings, etc.).
- services: Business logic handling interactions with Firebase authentication and task-related services.
- utils and widgets: Reusable components and helper functions.
- Assets Directory: Contains images, audio, and videos used for UI elements and splash screens.
- Additional project files: pubspec.yaml for Flutter dependencies, test directory for widget tests, and configuration files for build settings.

a. Main Components:
- UI (View Layer): Comprised of multiple screens (login/registration, home/task list, focus screen, progress screen, settings, etc.) found in the lib/screens folder.
- State Management: Providers (lib/providers) that manage application state between UI and business logic.
- Business Logic & Services: Components in lib/services that handle Firebase authentication and task management (task breakdown using the Gemini API).
- Data Models: Defined in lib/models representing tasks, subtasks, user, and progress.
- Configuration: Config files (lib/config) to set up API keys, especially for AI functionality.
- External Integrations: Firebase (for authentication and data storage) and Gemini API (for AI-powered task analysis).
- Assets: Images, audio, and video files used by the UI, managed under the assets directory.
- Multi-platform Layers: Native integration folders for Android, iOS, etc., which handle platform-specific behaviors.

b. Relationships & Interactions:
- Providers interface with Services that perform network calls or local data handling (e.g., Firebase authentication and data transactions).
- Data Models act as intermediaries between the backend (services) and the presentation layer (providers and UI).
- Configuration settings (from lib/config) are used by Services for tasks like AI-powered task breakdown.
- Assets are loaded into the UI as needed, enhancing user experience.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: The project cleanly separates UI (screens/widgets), state (providers), business logic (services), and data (models).
- MVVM/MVC-like Approach: Providers mediate between the view and model.
- Modular Design: Distinct directories and modules allow for ease of testing and feature updates.
- Cross-Platform Consistency: A unified Flutter codebase targets mobile (Android/iOS) and desktop/web platforms, with platform-specific folders handling finer adjustments.

d. Technologies, Frameworks, & Libraries:
- Flutter & Dart – Primary development language and UI framework.
- Provider – For state management.
- Firebase – For authentication and possibly data storage.
- Gemini API – For AI task breakdown and challenge analysis.
- Shared Preferences – For local persistence.
- Additional libraries such as Confetti for celebration effects.

##### Essential Components
- The UI components (screens/widgets).
- State management (Providers).
- Business logic Service layer.
- Models holding data.
- Configuration settings.
- External integrations (Firebase and Gemini API).
- Asset management container.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        Login["Login/Registration Screen"]:::ui
        TaskList["Task List Screen"]:::ui
        Focus["Focus Mode Screen"]:::ui
        Progress["Progress Screen"]:::ui
        Settings["Settings Screen"]:::ui
    end

    %% State Management
    subgraph "State Management"
        Providers["Providers (State Management)"]:::state
    end

    %% Business Logic & Services Layer
    subgraph "Business Logic & Services"
        FirebaseAuthService["FirebaseAuthService"]:::service
        TaskService["TaskService (AI Task Breakdown)"]:::service
        Config["Configuration Settings"]:::config
        FirebaseUtils["Firebase Utilities"]:::utils
    end

    %% Data Models
    subgraph "Data Models"
        User["User Model"]:::model
        Task["Task Model"]:::model
        Subtask["Subtask Model"]:::model
        ProgressModel["Progress Model"]:::model
    end

    %% External Integrations
    subgraph "External Integrations"
        Firebase["Firebase"]:::external
        Gemini["Gemini API"]:::external
    end

    %% Assets
    Assets["Asset Management"]:::assets

    %% Platform Specific Modules
    subgraph "Platform Specific Modules"
        Android["Android"]:::platform
        iOS["iOS"]:::platform
        Linux["Linux"]:::platform
        macOS["macOS"]:::platform
        Web["Web"]:::platform
        Windows["Windows"]:::platform
    end

    %% Relationships between UI and State Management
    Login -->|"updates"| Providers
    TaskList -->|"updates"| Providers
    Focus -->|"updates"| Providers
    Progress -->|"updates"| Providers
    Settings -->|"configures"| Providers

    %% Providers interactions with Services and Models
    Providers -->|"calls"| FirebaseAuthService
    Providers -->|"calls"| TaskService
    Providers -->|"binds"| User
    Providers -->|"binds"| Task
    Providers -->|"binds"| Subtask
    Providers -->|"binds"| ProgressModel

    %% Service interactions    
    FirebaseAuthService -->|"uses"| FirebaseUtils
    FirebaseAuthService -->|"authenticates"| Firebase
    TaskService -->|"analyzesTask"| Gemini
    Config -->|"configures"| TaskService

    %% UI uses Assets
    Login -->|"renders"| Assets
    TaskList -->|"renders"| Assets
    Focus -->|"renders"| Assets
    Progress -->|"renders"| Assets
    Settings -->|"renders"| Assets

    %% Click Events
    click Login "https://github.com/amishapai/beeflow/tree/main/lib/screens"
    click TaskList "https://github.com/amishapai/beeflow/tree/main/lib/screens"
    click Focus "https://github.com/amishapai/beeflow/tree/main/lib/screens"
    click Progress "https://github.com/amishapai/beeflow/tree/main/lib/screens"
    click Settings "https://github.com/amishapai/beeflow/tree/main/lib/screens"
    click Providers "https://github.com/amishapai/beeflow/tree/main/lib/providers"
    click FirebaseAuthService "https://github.com/amishapai/beeflow/tree/main/lib/services"
    click TaskService "https://github.com/amishapai/beeflow/tree/main/lib/services"
    click Config "https://github.com/amishapai/beeflow/tree/main/lib/config"
    click FirebaseUtils "https://github.com/amishapai/beeflow/blob/main/lib/utils/firebase_utils.dart"
    click User "https://github.com/amishapai/beeflow/tree/main/lib/models"
    click Task "https://github.com/amishapai/beeflow/tree/main/lib/models"
    click Subtask "https://github.com/amishapai/beeflow/tree/main/lib/models"
    click ProgressModel "https://github.com/amishapai/beeflow/tree/main/lib/models"
    click Assets "https://github.com/amishapai/beeflow/tree/main/assets"
    click Android "https://github.com/amishapai/beeflow/tree/main/android"
    click iOS "https://github.com/amishapai/beeflow/tree/main/ios"
    click Linux "https://github.com/amishapai/beeflow/tree/main/linux"
    click macOS "https://github.com/amishapai/beeflow/tree/main/macos"
    click Web "https://github.com/amishapai/beeflow/tree/main/web"
    click Windows "https://github.com/amishapai/beeflow/tree/main/windows"

    %% Styling Classes
    classDef ui fill:#ffefba,stroke:#e6a700,stroke-width:2px;
    classDef state fill:#d0f0c0,stroke:#5cb85c,stroke-width:2px;
    classDef service fill:#cce5ff,stroke:#31708f,stroke-width:2px;
    classDef config fill:#fceabb,stroke:#f0ad4e,stroke-width:2px;
    classDef model fill:#d9edf7,stroke:#31708f,stroke-width:2px;
    classDef external fill:#f2dede,stroke:#a94442,stroke-width:2px;
    classDef assets fill:#fcf8e3,stroke:#8a6d3b,stroke-width:2px;
    classDef platform fill:#dff0d8,stroke:#3c763d,stroke-width:2px;
    classDef utils fill:#eee,stroke:#999,stroke-width:2px;
```
