# oapmartins/pokedex_flutter_bloc architecture

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

- Interactive diagram: https://gitdiagram.com/oapmartins/pokedex_flutter_bloc
- Repository: https://github.com/oapmartins/pokedex_flutter_bloc

## Overview

##### Project Type and Purpose
- This is a mobile application built with Flutter (Dart) targeting both Android and iOS.
- It uses the BLoC pattern and Clean Architecture layers (presentation, domain, data) to fetch and display Pokémon data from an external JSON API.

##### File Structure
- Top-level mobile folders:
- android/ – native Android integration
- ios/ – native iOS integration
- Core app code under lib/:
- features/home/… – implements one feature module (“home”) following Clean Architecture:
– data/datasources (remote API client)
– data/models (JSON ↔ Dart models)
– data/repositories (concrete Repo implementation)
– domain/entities, domain/repositories (abstract interfaces), domain/usecases
– presentation/bloc (HomeBloc, events, states), pages & widgets
- main.dart – app entry point
- assets/ – fonts, images, SVGs for UI
- pubspec.yaml – dependencies (flutter_bloc, http, etc.)

##### Inspect the README
- Confirms external API endpoint (pokedex.json)
- References Figma UI spec
- No backend code; this app acts purely as a frontend consumer of a remote API

##### Main Components and Their Interactions
a. Components:
- Mobile Platforms (Android & iOS)
- Flutter Engine & Dart Runtime
- Presentation Layer
– UI Widgets (HomePage, PokemonDetailPage, filter chips, type badges)
– State Manager (HomeBloc)
- Domain Layer
– UseCase (FetchPokemonsUsecase)
– Entity (Pokemon)
- Data Layer
– Repository Impl (PokemonRepositoryImpl)
– Remote DataSource (PokemonRemoteDataSource)
– HTTP Client
- External Service
– PokeAPI JSON endpoint
- Assets & Config
– Fonts, images, constants
b. Interactions (flow of data):
1. User taps UI → UI Widget dispatches HomeEvent to HomeBloc
2. HomeBloc → invokes FetchPokemonsUsecase in the domain layer
3. UseCase → calls PokemonRepository (abstract)
4. RepositoryImpl → fetches data via PokemonRemoteDataSource (HTTP GET)
5. RemoteDataSource → HTTP Client issues request → receives JSON → maps to PokemonModel
6. RepositoryImpl → converts PokemonModel → Pokemon entity → returns to UseCase
7. UseCase → emits entity list → HomeBloc updates HomeState → UI rebuilds
c. Architectural Patterns & Principles:
- Clean Architecture separation: presentation ↔ domain ↔ data
- BLoC for state management and event-driven UI updates
- Dependency inversion: presentation depends on abstract usecases, data on abstract repositories
- Single responsibility: each layer has a narrow focus
d. Key Technologies:
- Flutter & Dart SDK
- flutter_bloc package
- http (or dio) for network requests
- JSON serialization in model classes
- Platform channels are only used for default Flutter engine integration (no custom native code here)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platforms
    Android["Android"]:::platform
    iOS["iOS"]:::platform

    %% Flutter Engine
    Flutter["Flutter Engine & Dart VM"]:::core
    click Flutter "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/main.dart"

    Android -->|"runs on"| Flutter
    iOS -->|"runs on"| Flutter

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        HomePage["HomePage"]:::presentation
        PokemonDetailPage["PokemonDetailPage"]:::presentation
        HomeBloc["HomeBloc"]:::presentation
        HomeEvent["HomeEvent"]:::presentation
        HomeState["HomeState"]:::presentation
        PokemonCard["PokemonCardWidget"]:::presentation
        FilterChip["FilterChipWidget"]:::presentation
        TypeBadge["TypeBadgeWidget"]:::presentation
    end

    click HomeBloc "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/bloc/home_bloc.dart"
    click HomeEvent "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/bloc/home_event.dart"
    click HomeState "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/bloc/home_state.dart"
    click HomePage "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/pages/home_page.dart"
    click PokemonDetailPage "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/pages/pokemon_detail_page.dart"
    click PokemonCard "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/widgets/card_pokemon_widget.dart"
    click FilterChip "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/widgets/filter/custom_filter_chip_widget.dart"
    click TypeBadge "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/presentation/widgets/type_pokemon_widget.dart"

    Flutter -->|"build UI"| HomePage
    HomePage -->|"dispatch"| HomeEvent
    HomeEvent -->|"to"| HomeBloc
    HomeBloc -->|"uses"| HomeState

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        FetchUseCase["FetchPokemonsUseCase"]:::domain
        PokemonEntity["Pokemon Entity"]:::domain
        RepoInterface["PokemonRepository Interface"]:::domain
    end

    click FetchUseCase "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/domain/usecases/fetch_pokemons_usecase.dart"
    click PokemonEntity "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/domain/entities/pokemon.dart"
    click RepoInterface "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/domain/repositories/pokemon_repository.dart"

    HomeBloc -->|"invoke"| FetchUseCase
    FetchUseCase -->|"calls"| RepoInterface

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RemoteDS["PokemonRemoteDataSource"]:::data
        Model["PokemonModel"]:::data
        RepoImpl["PokemonRepositoryImpl"]:::data
        HTTPClient["HTTP Client"]:::data
    end

    click RemoteDS "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/data/datasources/pokemon_remote_datasource.dart"
    click Model "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/data/models/pokemon_model.dart"
    click RepoImpl "https://github.com/oapmartins/pokedex_flutter_bloc/blob/main/lib/features/home/data/repositories/pokemon_repository_impl.dart"

    RepoInterface -->|"implemented by"| RepoImpl
    RepoImpl -->|"fetch via"| RemoteDS
    RemoteDS -->|"HTTP GET"| HTTPClient
    HTTPClient -->|"GET JSON"| ExternalAPI
    ExternalAPI -->|"returns JSON"| HTTPClient
    HTTPClient -->|"map to"| Model
    Model -->|"convert to"| PokemonEntity
    PokemonEntity -->|"return"| FetchUseCase
    FetchUseCase -->|"emit"| HomeBloc
    HomeBloc -->|"update"| HomeState
    HomeState -->|"render"| HomePage

    %% External API
    ExternalAPI["PokeAPI JSON Endpoint"]:::external
    click ExternalAPI "https://github.com/oapmartins/pokedex_flutter_bloc/tree/main/assets not applicable"

    %% Assets
    Assets["Assets (fonts, images, SVGs)"]:::asset
    click Assets "https://github.com/oapmartins/pokedex_flutter_bloc/tree/main/assets/"

    Assets -->|"provides"| HomePage

    %% Classes
    classDef platform fill:#fdd,stroke:#333,stroke-width:1px
    classDef core fill:#dfd,stroke:#333,stroke-width:1px
    classDef presentation fill:#bbf,stroke:#333,stroke-width:1px
    classDef domain fill:#bfb,stroke:#333,stroke-width:1px
    classDef data fill:#fb8,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
    classDef asset fill:#ffd,stroke:#333,stroke-width:1px
```
