# mansurisodev/chess_game_bloc architecture

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

- Interactive diagram: https://gitdiagram.com/mansurisodev/chess_game_bloc
- Repository: https://github.com/mansurisodev/chess_game_bloc

## Overview

##### Project Type and Purpose
- This project is a multi-platform Flutter application written in Dart. Its main purpose is to provide a chess game with a clear separation between the game logic (models) and the presentation (UI), utilizing the flutter_bloc state management library.
- The README emphasizes separation of concerns, with models handling the game logic and UI components rendering the chess board and game pieces, while the bloc layer ties them together.

##### Major Components
- UI Layer:
- Located mainly in the lib/ui and lib/screens directories.
- Contains components such as board_widget, cell_widget, figure_widget, and lost_figures_widget.
- Business Logic (BLoC) Layer:
- Found in the lib/bloc directory.
- Includes overall app_blocs, cubits like game_cubit and settings_cubit, and their associated states.
- Models:
- In the lib/models directory.
- Represents the chess board, individual cells, figures (pawn, knight, bishop, etc.), player details, and logic for calculating valid moves.
- Services:
- In lib/services.
- Services provide additional functionality like the AI manager (in lib/services/ai) for future single-player features and logging services for move history.
- Configuration and Assets:
- The assets folder holds images (including chess figures) which the UI layer uses.
- Platform Wrappers:
- The project contains directories for Android, iOS, Linux, macOS, Web, and Windows showing that the core Flutter code is embedded within native shells for multi-platform support.

##### Relationships and Interactions
- User interactions are captured through the UI layer, which dispatches events to the Bloc.
- The Bloc (using flutter_bloc) manages state by interacting with the Models. These models contain the core game logic, such as determining valid moves and game state transitions.
- When state changes occur (e.g., a move is made, or game status updates), the Bloc pushes updates back to the UI.
- Supplementary Services (like AI or logging) are hooked into the Bloc layer to provide side functionalities. For example, the AI Manager would be invoked by the Bloc when a player-to-AI move is required.
- Configuration elements (such as theme and asset paths) are used by both the UI and Models to ensure consistency.

##### Recommended Architectural Patterns
- Separation of Concerns: Clearly divide responsibilities across the UI, Bloc, and Model layers.
- BLoC Pattern: Emphasize the unidirectional data flow: UI → Bloc → Models → (state update back to) UI.
- Multi-Platform Structure: Recognize that while the shared Flutter code resides within the lib folder, platform-specific configurations exist separately (android, ios, etc.), indicating a clean separation of cross-platform and native code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Wrappers
    subgraph "Platform Wrappers"
        android("Android"):::platform
        ios("iOS"):::platform
        linux("Linux"):::platform
        macos("macOS"):::platform
        web("Web"):::platform
        windows("Windows"):::platform
    end

    %% Shared Flutter Core node
    flutterCore("Flutter Core")

    %% Connections from Platform Wrappers to Flutter Core
    android --> flutterCore
    ios --> flutterCore
    linux --> flutterCore
    macos --> flutterCore
    web --> flutterCore
    windows --> flutterCore

    %% Shared Flutter Code Layer
    subgraph "Shared Flutter Code"
        %% UI Layer
        subgraph "UI Layer"
            boardWidget("Board Widget"):::ui
            cellWidget("Cell Widget"):::ui
            figureWidget("Figure Widget"):::ui
            lostFiguresWidget("Lost Figures Widget"):::ui
            gameScreen("Game Screen"):::ui
        end

        %% Business Logic (BLoC) Layer
        subgraph "Business Logic (BLoC) Layer"
            appBlocs("App Blocs"):::bloc
            gameCubit("Game Cubit"):::bloc
            settingsCubit("Settings Cubit"):::bloc
            gameState("Game State"):::bloc
            gameStateFreezed("Game State Freezed"):::bloc
            settingsState("Settings State"):::bloc
            settingsStateFreezed("Settings State Freezed"):::bloc
        end

        %% Models
        subgraph "Models"
            board("Board"):::models
            cell("Cell"):::models
            cellCalc("Cell Calculator"):::models
            cellPos("Cell Position"):::models
            figure("Figure"):::models
            figureTypes("Figure Types"):::models
            gameColors("Game Colors"):::models
            lostFigures("Lost Figures"):::models
            player("Player"):::models
            bishop("Bishop"):::models
            king("King"):::models
            knight("Knight"):::models
            pawn("Pawn"):::models
            queen("Queen"):::models
            rook("Rook"):::models
        end

        %% Services
        subgraph "Services"
            aiManager("AI Manager"):::services
            iLogger("ILogger"):::services
            moveLogger("Move Logger"):::services
        end

        %% Config & Assets
        subgraph "Config & Assets"
            assetsConfig("Assets Config"):::config
            colorsConfig("Colors Config"):::config
            assetsImages("Assets Images"):::config
            figuresBlack("Figures Black"):::config
            figuresWhite("Figures White"):::config
        end
    end

    %% External dependency note
    flutterBlocLib("flutter_bloc Library"):::note

    %% Interactions between layers
    %% UI Layer to BLoC Layer
    gameScreen -->|"event"| appBlocs

    %% BLoC Layer to Models and back
    appBlocs -->|"process_move"| board
    board -->|"state_update"| appBlocs

    %% BLoC Layer to UI Layer (state update)
    appBlocs -->|"update_UI"| gameScreen

    %% BLoC Layer interactions with Services
    appBlocs -->|"invoke_AI"| aiManager
    appBlocs -->|"log_move"| moveLogger

    %% BLoC internal interactions
    gameCubit -->|"yield_state"| gameState
    settingsCubit -->|"yield_state"| settingsState

    %% Config & Assets influence
    assetsConfig -->|"theme"| boardWidget
    colorsConfig -->|"theme"| boardWidget
    assetsConfig -->|"configure"| board
    assetsImages -->|"provides"| boardWidget

    %% External dependency connection
    appBlocs -.->|"uses"| flutterBlocLib

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef bloc fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef models fill:#ABEBC6,stroke:#145A32,stroke-width:2px;
    classDef services fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef config fill:#D5DBDB,stroke:#616A6B,stroke-width:2px;
    classDef platform fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef note fill:#CCD1D1,stroke:#5D6D7E,stroke-width:2px;

    %% Click Events for UI Layer
    click boardWidget "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/ui/board_widget.dart"
    click cellWidget "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/ui/cell_widget.dart"
    click figureWidget "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/ui/figure_widget.dart"
    click lostFiguresWidget "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/ui/lost_figures_widget.dart"
    click gameScreen "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/screens/game_screen.dart"

    %% Click Events for BLoC Layer
    click appBlocs "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/app_blocs.dart"
    click gameCubit "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/cubits/game_cubit.dart"
    click settingsCubit "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/cubits/settings_cubit.dart"
    click gameState "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/states/game_state.dart"
    click gameStateFreezed "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/states/game_state.freezed.dart"
    click settingsState "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/states/settings_state.dart"
    click settingsStateFreezed "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/bloc/states/settings_state.freezed.dart"

    %% Click Events for Models
    click board "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/board.dart"
    click cell "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/cell.dart"
    click cellCalc "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/cell_calculator.dart"
    click cellPos "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/cell_position.dart"
    click figure "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figure.dart"
    click figureTypes "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figure_types.dart"
    click gameColors "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/game_colors.dart"
    click lostFigures "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/lost_figures.dart"
    click player "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/player.dart"
    click bishop "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figures/bishop.dart"
    click king "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figures/king.dart"
    click knight "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figures/knight.dart"
    click pawn "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figures/pawn.dart"
    click queen "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figures/queen.dart"
    click rook "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/models/figures/rook.dart"

    %% Click Events for Services
    click aiManager "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/services/ai/ai_manager.dart"
    click iLogger "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/services/loggers/i_logger.dart"
    click moveLogger "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/services/loggers/move_logger.dart"

    %% Click Events for Config & Assets
    click assetsConfig "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/config/assets.dart"
    click colorsConfig "https://github.com/mansurisodev/chess_game_bloc/blob/master/lib/config/colors.dart"
    click assetsImages "https://github.com/mansurisodev/chess_game_bloc/tree/master/assets/images"
    click figuresBlack "https://github.com/mansurisodev/chess_game_bloc/tree/master/assets/images/figures/black"
    click figuresWhite "https://github.com/mansurisodev/chess_game_bloc/tree/master/assets/images/figures/white"

    %% Click Events for Platform Wrappers
    click android "https://github.com/mansurisodev/chess_game_bloc/tree/master/android/"
    click ios "https://github.com/mansurisodev/chess_game_bloc/tree/master/ios/"
    click linux "https://github.com/mansurisodev/chess_game_bloc/tree/master/linux/"
    click macos "https://github.com/mansurisodev/chess_game_bloc/tree/master/macos/"
    click web "https://github.com/mansurisodev/chess_game_bloc/tree/master/web/"
    click windows "https://github.com/mansurisodev/chess_game_bloc/tree/master/windows/"
```
