# mathvdias/pokedex architecture

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

- Interactive diagram: https://gitdiagram.com/mathvdias/pokedex
- Repository: https://github.com/mathvdias/pokedex

## Overview

##### Project type and purpose
- This is a cross-platform Flutter application (“PokeDex”) targeting iOS, Android, Web (PWA), macOS, Windows and Linux.
- It follows Clean Architecture with MVVM and SOLID principles, uses Provider for state management, Dio/http for network calls, and interacts with the external PokeApi to fetch Pokémon data.

##### File structure
- **lib/** layer:
- src/app → app entrypoint, configuration, theming
- src/pages → presentation layer (UI widgets for splash, home, details; mobile + web variants)
- src/viewmodels → MVVM ViewModels
- src/states → UI state representations
- src/services/domain → domain models
- src/services/data/providers → HTTP client interface + Dio implementation
- src/services/data/repository → repository interfaces + implementations
- **platform folders** (android/, ios/, macos/, linux/, windows/, web/): Flutter embedding and native boilerplate.
- **test/**: unit and widget tests for repositories and ViewModels.

##### Key insights from README
- Clean Architecture + MVVM
- Multi-platform Flutter with Material 3
- Testing with Mockito + widget tests
- Core functionality: list/search Pokémon, detail view, data fetched from PokeApi.

##### Main components
a. Presentation Layer
- SplashPage, PokemonsPage (home), DetailsPokemonPage
- UI Components (cards, grids, search bar, charts)
- Bound to ViewModels (PokemonsViewModel, PokemonDetailViewModel)
b. State & ViewModel Layer
- ViewModels expose Stream/ChangeNotifier of UI states (loading, loaded, error)
- States defined in src/states
c. Domain Layer
- Domain models (PokemonListModel, PokemonModel, PokemonDetails, StatsModel)
- Repository interfaces
d. Data Layer
- HTTPClient interface → implemented by DioClientProvider
- Repositories (PokemonRepository, PokemonListRepository, PokemonDetailsRepository)
- Network DTOs → domain models
e. External Services
- PokeApi (REST endpoints)
f. Platform Embedding
- Flutter engine on Android, iOS, Web, Windows, macOS, Linux (can be shown as a single “Flutter host” block per platform or grouped)

##### Relationships & Data Flow
- UI triggers user action → calls method on ViewModel
- ViewModel calls repository interface (domain contract)
- Repository implementation calls HTTPClient → makes a network request to PokeApi
- HTTPClient returns JSON → mapped to domain models → returned up to ViewModel
- ViewModel updates state → UI rebuilds with new data
- Platform embedding hosts the Flutter engine and passes native events if needed (e.g., deep links, lifecycle)

##### Architectural patterns & principles
- Clean Architecture layers (Presentation, Domain, Data) separated by interfaces
- Dependency Inversion: ViewModels depend on abstractions (repository interfaces)
- Single Responsibility: each layer/folder has one concern
- MVVM: UI ↔ ViewModel ↔ Model
- Provider for DI & state management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        SP["SplashPage"]:::presentation
        HP["PokemonsPage"]:::presentation
        DP["DetailsPokemonPage"]:::presentation

        subgraph "Home Variants"
            direction TB
            HPM["Home Mobile"]:::presentation
            HPW["Home Web"]:::presentation
        end

        subgraph "Home Components Mobile"
            direction TB
            Card["CardPokemon"]:::presentation
            Search["SearchBarComponent"]:::presentation
        end

        subgraph "Home Components Web"
            direction TB
            Grid["GridViewWidget"]:::presentation
        end

        subgraph "Details Variants"
            direction TB
            DPM["Details Mobile Loaded"]:::presentation
        end

        subgraph "Details Components"
            direction TB
            About["AboutPokemon"]:::presentation
            Moves["MovesPokemon"]:::presentation
            StatsDisp["StatsPokemon"]:::presentation
            StatsLabel["StatsLabelPokemon"]:::presentation
            Formatter["TextFormatter"]:::presentation
        end
    end

    %% ViewModel Layer
    subgraph "ViewModel Layer"
        direction TB
        PV["PokemonsViewModel"]:::viewmodel
        DV["PokemonDetailViewModel"]:::viewmodel
    end

    %% State Layer
    subgraph "State Layer"
        direction TB
        PS1["pokemons_states"]:::state
        PS2["pokemons_list"]:::state
        PS3["pokemon_state"]:::state
        DS1["details_start"]:::state
        DS2["details_loading"]:::state
        DS3["details_loaded"]:::state
        DS4["details_error"]:::state
        DS5["details_page_pokemon_loaded"]:::state
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DModel1["PokemonListModel"]:::domain
        DModel2["PokemonModel"]:::domain
        DModel3["PokemonDetails"]:::domain
        DModel4["StatsModel"]:::domain
        DModel5["ExceptionResponse"]:::domain
        ListRepoIF["PokemonListRepositoryInterface"]:::domain
        DetailsRepoIF["PokemonDetailsRepositoryInterface"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        HTTPIF["HTTPClientInterface"]:::data
        DioProv["DioClientProvider"]:::data
        RepoImp2["PokemonListRepository"]:::data
        RepoImp3["PokemonDetailsRepository"]:::data
    end

    %% External Service
    External["PokeApi REST"]:::external

    %% Flutter Host Platforms
    subgraph "Flutter Host"
        direction TB
        Android["Android"]:::platform
        iOS["iOS"]:::platform
        WebP["Web"]:::platform
        macOS["macOS"]:::platform
        Windows["Windows"]:::platform
        Linux["Linux"]:::platform
    end

    %% Connections
    SP -->|"binds to"| PV
    HP -->|"binds to"| PV
    DP -->|"binds to"| DV

    PV -->|"fetchPokemonList()"| ListRepoIF
    DV -->|"fetchPokemonDetails()"| DetailsRepoIF

    ListRepoIF -->|"implemented by"| RepoImp2
    DetailsRepoIF -->|"implemented by"| RepoImp3

    RepoImp2 -->|"uses HTTPClient"| HTTPIF
    RepoImp3 -->|"uses HTTPClient"| HTTPIF

    HTTPIF -->|"implemented by"| DioProv
    DioProv -->|"request JSON"| External

    DioProv -->|"map JSON to PokemonListModel"| DModel1
    DioProv -->|"map JSON to PokemonDetails"| DModel3

    DModel1 -->|"return to"| PV
    DModel3 -->|"return to"| DV

    %% Click Events
    click SP "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/splash/splash_page.dart"
    click HP "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/home/pokemons_page.dart"
    click HPM "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/home/mobile/home_mobile.dart"
    click Card "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/home/mobile/components/card_pokemon.dart"
    click Search "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/home/mobile/components/search_bar_component.dart"
    click HPW "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/home/web/home_web.dart"
    click Grid "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/home/web/components/grid_view_widget.dart"
    click DP "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/details_pokemon_page.dart"
    click DPM "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/mobile/loaded_mobile.dart"
    click About "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/components/about_pokemon.dart"
    click Moves "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/components/moves_pokemon.dart"
    click StatsDisp "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/components/stats_pokemon.dart"
    click StatsLabel "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/components/stats_label_pokemon.dart"
    click Formatter "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/components/text_formatter.dart"

    click PV "https://github.com/mathvdias/pokedex/blob/main/lib/src/viewmodels/pokemons_viewmodel.dart"
    click DV "https://github.com/mathvdias/pokedex/blob/main/lib/src/viewmodels/pokemon_detail_viewmodel.dart"

    click PS1 "https://github.com/mathvdias/pokedex/blob/main/lib/src/states/pokemons_states.dart"
    click PS2 "https://github.com/mathvdias/pokedex/blob/main/lib/src/states/pokemons_list.dart"
    click PS3 "https://github.com/mathvdias/pokedex/blob/main/lib/src/states/pokemon_state.dart"
    click DS1 "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/states/details_start.dart"
    click DS2 "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/states/details_loading.dart"
    click DS3 "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/states/details_loaded.dart"
    click DS4 "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/states/details_error.dart"
    click DS5 "https://github.com/mathvdias/pokedex/blob/main/lib/src/pages/details/states/details_page_pokemon_loaded.dart"

    click DModel1 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/domain/models/pokemon_list_model.dart"
    click DModel2 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/domain/models/pokemom_model.dart"
    click DModel3 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/domain/models/pokemon_details.dart"
    click DModel4 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/domain/models/pokemon_details_stats_model.dart"
    click DModel5 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/domain/models/response/exception_response.dart"

    click HTTPIF "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/data/providers/http_client_interface.dart"
    click DioProv "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/data/providers/impl/dio_client_provider.dart"
    click ListRepoIF "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/data/repository/pokemon_list_repository.dart"
    click DetailsRepoIF "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/data/repository/pokemon_details_repository_interface.dart"
    click RepoImp2 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/data/repository/impl/pokemon_list_repository.dart"
    click RepoImp3 "https://github.com/mathvdias/pokedex/blob/main/lib/src/services/data/repository/impl/pokemon_details_repository.dart"

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef viewmodel fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef state fill:#FCF3CF,stroke:#9A7D0A,color:#784212;
    classDef domain fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef data fill:#F9E79F,stroke:#B9770E,color:#7D6608;
    classDef external fill:#D7DBDD,stroke:#566573,color:#2C3E50;
    classDef platform fill:#F2F3F4,stroke:#ABB2B9,color:#566573;
```
