# yaolya/flutter-are-you-bored architecture

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

- Interactive diagram: https://gitdiagram.com/yaolya/flutter-are-you-bored
- Repository: https://github.com/yaolya/flutter-are-you-bored

## Overview

##### Project Type and Purpose
- This is a cross‑platform mobile/web application built with Flutter.
- It helps users discover random activities when they’re bored, save favorites locally, and remove saved items.
- It follows the BLoC (Cubit) pattern for state management and uses a local SQLite database (via sqflite) plus an external “Bored API” for network calls.

##### File Structure Analysis
- Top‐level directories:
- android/ and ios/ contain the native shell projects and platform integration.
- lib/ hosts all Dart source code, subdivided into:
– business_logic/ – Cubits + States for “activity” and “activities_list.”
– data/ – database service, network API client, data models, repositories (real and mock).
– ui/ – Flutter screens and widgets.
– main.dart – app entry point.
- assets/ – JSON animations and images.
- test/ – unit tests for cubits.
- Configuration/build: pubspec.yaml, Android Gradle files, Xcode project, CI workflow for tests.

##### README Insights
- Confirms BLoC pattern, sqflite for database, remote API usage, and a web deployment via GitHub Pages.
- Project structure block aligns with lib/ subdivisions.

a. Main Components
1. Presentation Layer (Flutter UI)
2. Business Logic Layer (ActivitiesListCubit, ActivityCubit)
3. Data Layer
– Repositories (ActivityRepository, Mock)
– Network Client (ActivityApi)
– Local Database Service (sqflite)
4. External Service (Bored API at boredapi.com)
5. Persistence (SQLite DB on device)
6. Platform Shells (Android, iOS, Web host)

b. Relationships & Interactions
- UI Widgets dispatch user events (e.g. “fetch new activity,” “save activity”) to BLoCs.
- BLoCs call into Repositories via an IActivityRepository interface.
- Repositories route calls to:
– ActivityApi (HTTP GET/POST) when fetching new activities.
– DatabaseService for CRUD on saved activities.
- Responses propagate back through the repository to the Cubit, which emits new State objects to the UI.
- CI workflow runs unit tests against cubits in test/ directory.

c. Architectural Patterns & Principles
- Layered/Clean Architecture: separation of UI, business logic, data.
- BLoC (Cubit) for predictable state management and testability.
- Dependency inversion via repository interface and mock implementations for unit testing.
- Single source of truth: Cubits own the state; UI is a pure function of state.

d. Key Technologies & Frameworks
- Flutter & Dart – UI toolkit and language
- flutter_bloc – BLoC/Cubit state management
- http or dio (inside ActivityApi) for network calls
- sqflite – SQLite database on device
- GitHub Actions CI for testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        UI1["HomeScreen"]:::presentation
        UI2["SavedActivitiesScreen"]:::presentation
        UI3["CustomErrorWidget"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer" 
        direction TB
        C1["ActivitiesListCubit"]:::business
        C2["ActivitiesListState"]:::business
        C3["ActivityCubit"]:::business
        C4["ActivityState"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        IAR["IActivityRepository"]:::data
        AR["ActivityRepository"]:::data
        AM["ActivityRepositoryMock"]:::data
        API["ActivityApi\n(Dart HTTP Client)"]:::data
        DBService["DatabaseService\n(sqflite)"]:::database
        Model1["Activity Model"]:::data
        Model2["MessageException Model"]:::data
    end

    %% External and Persistence
    subgraph "External Services & Persistence"
        direction TB
        ExternalAPI["Bored API\n(boredapi.com)"]:::external
        SQLiteDB[("SQLite DB")]:::database
    end

    %% Platform Shells
    subgraph "Flutter Host"
        direction TB
        Android["Android"]:::external
        iOS["iOS"]:::external
    end

    %% CI/Test Workflow
    subgraph "CI & Tests"
        direction TB
        Tests["ActivityCubit Tests"]:::test
        GitHubActions["GitHub Actions CI"]:::test
    end

    %% App Entry Point
    Main["main.dart"]:::presentation

    %% Relationships
    Main -->|"renders"| UI1
    Main -->|"renders"| UI2
    UI1 -->|"dispatch fetchActivity() / saveActivity()"| C1
    UI2 -->|"dispatch fetchActivity() / saveActivity()"| C3
    C1 -->|"calls methods on"| IAR
    C3 -->|"calls methods on"| IAR
    IAR -->|"uses real impl"| AR
    IAR -->|"uses mock impl for tests"| AM
    AR -->|"fetchActivity() / saveActivity()"| API
    AR -->|"loadSaved() / save() / delete()"| DBService
    API -->|"HTTP GET/POST"| ExternalAPI
    DBService -->|"CRUD operations"| SQLiteDB
    C1 -->|"emits new State to"| UI1
    C3 -->|"emits new State to"| UI2

    Tests -->|"unit tests against"| C1
    Tests -->|"unit tests against"| C3
    Tests -->|"run on"| GitHubActions

    Android -->|"hosts app"| Main
    iOS -->|"hosts app"| Main

    %% Click Events
    click UI1 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/ui/home_screen.dart"
    click UI2 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/ui/saved_activities_screen.dart"
    click UI3 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/ui/custom_error_widget.dart"
    click C1 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/business_logic/activities_list/activities_list_cubit.dart"
    click C2 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/business_logic/activities_list/activities_list_state.dart"
    click C3 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/business_logic/activity/activity_cubit.dart"
    click C4 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/business_logic/activity/activity_state.dart"
    click IAR "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/repositories/i_activity_repository.dart"
    click AR "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/repositories/activity_repository.dart"
    click AM "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/repositories/activity_repository_mock.dart"
    click API "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/network/activity_api.dart"
    click DBService "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/database/database_service.dart"
    click Model1 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/models/activity.dart"
    click Model2 "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/data/models/message_exception.dart"
    click Main "https://github.com/yaolya/flutter-are-you-bored/blob/main/lib/main.dart"
    click Android "https://github.com/yaolya/flutter-are-you-bored/tree/main/android/"
    click iOS "https://github.com/yaolya/flutter-are-you-bored/tree/main/ios/"
    click Tests "https://github.com/yaolya/flutter-are-you-bored/blob/main/test/activity_cubit_test.dart"

    %% Styles
    classDef presentation fill:#a7d8ff,stroke:#333,stroke-width:1px
    classDef business fill:#c3f2a7,stroke:#333,stroke-width:1px
    classDef data fill:#ffc78e,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef database fill:#d1d1d1,stroke:#333,stroke-width:1px
    classDef test fill:#f4c2c2,stroke:#333,stroke-width:1px
```
