# mostafahamed-w/book_hunter architecture

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

- Interactive diagram: https://gitdiagram.com/mostafahamed-w/book_hunter
- Repository: https://github.com/mostafahamed-w/book_hunter

## Overview

##### Project Context & Purpose
- This is a Flutter-based, cross-platform mobile application (also targeting web, desktop, etc.) that delivers an immersive reading experience. The project offers extensive book collections, intuitive searches, and a smooth, offline-capable reading interface.
- The README explicitly mentions that the application is built using the MVVM design pattern alongside BLoC architecture for state management, which is key to understanding its internal layers and component interactions.

##### Key Architectural Layers and Main Components
a. Presentation Layer (Frontend/UI)
- Located primarily in the “lib/Features” directory. This includes feature-specific folders (e.g., Splash, Home, Preview, Search) where you have separate directories for “presentation”, “views”, and “widgets”.
- Each screen (like splash_view, home_view, book_details_view, etc.) will be a UI component that interacts with state managers (Cubits) from the business logic layer.

b. Business Logic Layer (BLoC / Cubits)
- Found under “lib/Features/(feature)/presentation/manager” directories (such as featured_books_cubit, newest_books_cubit, similar_books_cubit, search_book_cubit).
- These components manage state and business logic, coordinating data retrieval and UI updates.

c. Data Layer (Repositories & Models)
- Organized in “lib/Features/(feature)/data” folders. This includes data models (like book_model files) and repository implementations (e.g., home_repo_impl.dart, search_repo_impl.dart) that handle API calls and/or local storage interactions.
- The “lib/core/utils/api_service.dart” and other related core utilities help with network calls and other shared functionality.

d. Core Utilities & Cross-Cutting Concerns
- Found in “lib/core”. This includes error handling modules, general-purpose functions, the service locator, routing (app_router.dart), and common widgets.
- This shared code underpins the entire application, providing consistency in error management, styling, and asset management.

e. Platform-specific Setups
- Directories such as android, ios, macos, linux, windows, and web indicate the project supports multiple platforms.
- These directories contain platform-specific configuration files, build scripts, and assets that integrate the Flutter framework with each target operating system.

##### Relationships and Interactions between Components
- The UI (presentation layer) invokes Cubit functions to request data or perform actions.
- The BLoC components (Cubits) coordinate with the repositories in the data layer to obtain necessary data, applying business logic and state management.
- Data flows from repository to BLoC and then is pushed to UI components, with error handling and utility functions (from the core layer) supporting throughout.
- Platform-specific wrappers (e.g., native gradle or Xcode configurations) ensure the Flutter module is correctly embedded across devices.

##### Architectural Patterns & Design Principles
- MVVM: Clearly divide UI (Views) and logic (ViewModels/BLoC components). Indicate that business logic and state transitions occur in separate Cubit or BLoC components, isolating the UI.
- BLoC: Emphasize how the business logic components (Cubits) are decoupled from presentation and data layers.
- Modularization: The project is split into several “Features” (Splash, Home, Preview, Search), making it easier to manage and scale individual functionalities.

##### Final Points
- Clear labels for each component (e.g., Splash Feature, Home Feature, Preview Feature, Search Feature)
- Optional: Add any libraries or frameworks (Flutter, BLoC, MVVM) next to their respective components to emphasize the design choices.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Presentation Layer
    subgraph "Presentation Layer"
        splashViews["Splash Views"]
        homeViews["Home Views"]
        previewViews["Preview Views"]
        searchViews["Search Views"]
    end

    %% Business Logic Layer (BLoC / Cubits)
    subgraph "Business Logic Layer"
        featuredCubit["Featured Books Cubit"]
        newestCubit["Newest Books Cubit"]
        similarCubit["Similar Books Cubit"]
        searchCubit["Search Book Cubit"]
    end

    %% Data Layer (Repositories & Models)
    subgraph "Data Layer"
        homeModels["Home Models"]
        homeRepo["Home Repository"]
        searchModels["Search Models"]
        searchRepo["Search Repository"]
    end

    %% Core Utilities & Cross-Cutting Concerns
    subgraph "Core Utilities"
        apiService["API Service"]
        appRouter["App Router"]
        customButton["Custom Button"]
        failures["Failures"]
    end

    %% Platform-specific Setups
    subgraph "Platform Specific"
        android["Android"]
        ios["iOS"]
        web["Web"]
        macos["macOS"]
        linux["Linux"]
        windows["Windows"]
    end

    %% Connections between Layers
    %% Presentation to Business Logic
    homeViews -->|"calls"| featuredCubit
    homeViews -->|"calls"| newestCubit
    homeViews -->|"calls"| similarCubit
    searchViews -->|"calls"| searchCubit
    splashViews -->|"transitions"| homeViews

    %% Business Logic to Data Layer
    featuredCubit -->|"fetches"| homeRepo
    newestCubit -->|"fetches"| homeRepo
    similarCubit -->|"fetches"| homeRepo
    searchCubit -->|"fetches"| searchRepo

    %% Data Layer internal connections
    homeRepo -->|"uses"| homeModels
    searchRepo -->|"uses"| searchModels
    homeRepo -->|"calls"| apiService
    searchRepo -->|"calls"| apiService

    %% Core Utilities interconnections
    appRouter -->|"routes"| homeViews
    failures -->|"handles"| featuredCubit
    failures -->|"handles"| newestCubit
    failures -->|"handles"| similarCubit
    failures -->|"handles"| searchCubit

    %% Presentation Layer to Platform Specific
    homeViews -->|"runs_on"| android
    homeViews -->|"runs_on"| ios
    homeViews -->|"runs_on"| web
    homeViews -->|"runs_on"| macos
    homeViews -->|"runs_on"| linux
    homeViews -->|"runs_on"| windows
    splashViews -->|"runs_on"| android
    splashViews -->|"runs_on"| ios
    splashViews -->|"runs_on"| web
    splashViews -->|"runs_on"| macos
    splashViews -->|"runs_on"| linux
    splashViews -->|"runs_on"| windows
    previewViews -->|"runs_on"| android
    previewViews -->|"runs_on"| ios
    previewViews -->|"runs_on"| web
    previewViews -->|"runs_on"| macos
    previewViews -->|"runs_on"| linux
    previewViews -->|"runs_on"| windows
    searchViews -->|"runs_on"| android
    searchViews -->|"runs_on"| ios
    searchViews -->|"runs_on"| web
    searchViews -->|"runs_on"| macos
    searchViews -->|"runs_on"| linux
    searchViews -->|"runs_on"| windows

    %% Styling Classes
    class splashViews,homeViews,previewViews,searchViews presentation
    class featuredCubit,newestCubit,similarCubit,searchCubit bloc
    class homeModels,homeRepo,searchModels,searchRepo data
    class apiService,appRouter,customButton,failures core
    class android,ios,web,macos,linux,windows platform

    %% Click Events - Presentation Layer
    click splashViews "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/Splash/presentation/views"
    click homeViews "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/home/presentation/views"
    click previewViews "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/preview/presentation/views"
    click searchViews "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/search/presentation/views"

    %% Click Events - Business Logic Layer
    click featuredCubit "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/home/presentation/manager/featured_books_cubit"
    click newestCubit "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/home/presentation/manager/newest_books_cubit"
    click similarCubit "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/home/presentation/manager/similar_books_cubit"
    click searchCubit "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/search/presentation/manager/cubit"

    %% Click Events - Data Layer
    click homeModels "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/home/data/book_model"
    click homeRepo "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/home/data/repos"
    click searchModels "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/search/data/book_model"
    click searchRepo "https://github.com/mostafahamed-w/book_hunter/tree/main/lib/Features/search/data/repos"

    %% Click Events - Core Utilities
    click apiService "https://github.com/mostafahamed-w/book_hunter/blob/main/lib/core/utils/api_service.dart"
    click appRouter "https://github.com/mostafahamed-w/book_hunter/blob/main/lib/core/utils/app_router.dart"
    click customButton "https://github.com/mostafahamed-w/book_hunter/blob/main/lib/core/widgets/custom_Button.dart"
    click failures "https://github.com/mostafahamed-w/book_hunter/blob/main/lib/core/errors/failures.dart"

    %% Click Events - Platform Specific
    click android "https://github.com/mostafahamed-w/book_hunter/tree/main/android/"
    click ios "https://github.com/mostafahamed-w/book_hunter/tree/main/ios/"
    click web "https://github.com/mostafahamed-w/book_hunter/tree/main/web/"
    click macos "https://github.com/mostafahamed-w/book_hunter/tree/main/macos/"
    click linux "https://github.com/mostafahamed-w/book_hunter/tree/main/linux/"
    click windows "https://github.com/mostafahamed-w/book_hunter/tree/main/windows/"

    %% Class Definitions for Color Coding
    classDef presentation fill:#f9f,stroke:#333,stroke-width:2px;
    classDef bloc fill:#9f9,stroke:#333,stroke-width:2px;
    classDef data fill:#9ff,stroke:#333,stroke-width:2px;
    classDef core fill:#ff9,stroke:#333,stroke-width:2px;
    classDef platform fill:#fc9,stroke:#333,stroke-width:2px;
```
