# najm-flutter/github-hehe architecture

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

- Interactive diagram: https://gitdiagram.com/najm-flutter/github-hehe
- Repository: https://github.com/najm-flutter/github-hehe

## Overview

##### Project Type & Purpose
- Type: Cross-platform Flutter client (mobile, web, desktop)
- Purpose: Analyze GitHub profiles with AI-powered humorous feedback

##### File Structure
- Top-Level “hosts” (android, ios, web, linux, macos, windows): platform runners that embed the Flutter engine
- lib/: Dart code, organized by Clean Architecture
– core/: shared constants, services (HTTP client, AI client, URL launcher)
– features/home/: feature module with three layers
- data/: data models, repositories implementation, data sources (remote & static)
- domain/: entities, repository interfaces, use-cases
- presentation/: UI pages, widgets, Bloc/Cubit for state management
- test/: unit/widget tests mirroring lib/features structure
- pubspec.yaml: dependencies (flutter_bloc, google_generative_ai, get_it, dartz, http, etc.)

##### Extract Architecture Insights from README
- “Clean Architecture”: three layers—Presentation · Domain · Data
- State management: flutter_bloc (Cubit pattern)
- Dependency injection: get_it
- AI integration: google_generative_ai for Gemini API
- External data: GitHub REST API + possibly other web endpoints

##### Main Components
a. Platform Layer
– iOS/Android/Web/Desktop runners → Flutter Engine
b. Presentation Layer
– Widgets (HomePage, form widgets, banners)
– Bloc/Cubit (GetHeheCubit & states)
c. Domain Layer
– Entities (UserInfoEnt, ReposUserEnt)
– UseCases (GetHeheGitHub)
– Repository Interfaces (HomeRepo)
d. Data Layer
– Repository Implementations (HomeRepoImp)
– DataSources
- HomeRemoteData (HTTP calls to GitHub API & Gemini AI)
- StaticHomeData (fallback/static content)
– Models (mapping JSON to domain entities)
e. Core Services
– AppServices: HTTP client, AI client, URL launcher (provided via get_it DI)
f. External Services
– GitHub REST API
– Google Generative AI (Gemini)
– Browser or OS (launched via url_launcher)

##### Relationships & Data Flow
– User taps widget → Widget calls Cubit → Cubit invokes UseCase
– UseCase calls Repository interface → Concrete Repository decides which DataSource
– DataSource fetches/parses data → returns Models → mapped to Entities
– Entities bubble up through UseCase → Cubit emits new State → UI rebuilds
– DI container (get_it) provides all dependencies at app startup

##### Architectural Patterns & Principles
- Layered (Presentation → Domain → Data)
- Dependency Inversion: Domain layer defines interfaces, Data layer implements them
- BLoC/Cubit for unidirectional state management
- DI with get_it for testability & modularity
- Functional error handling with dartz (Either types)

##### Technologies & Libraries
– Flutter Framework & Dart SDK
– flutter_bloc & bloc
– google_generative_ai
– http
– get_it
– equatable, dartz
– url_launcher

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Layer
    subgraph "Platform Layer"
        direction TB
        AndroidRunner["Android Runner"]:::external
        IOSRunner["iOS Runner"]:::external
        WebRunner["Web Runner"]:::external
        LinuxRunner["Linux Runner"]:::external
        MacOSRunner["macOS Runner"]:::external
        WindowsRunner["Windows Runner"]:::external
    end

    FlutterEngine["Flutter Engine"]:::core
    Application["Application Entry Point\n(main.dart)"]:::core

    %% Core Services
    subgraph "Core Services & DI"
        direction TB
        AppServices["AppServices\n(HTTP, AI, URL Launcher)"]:::core
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        subgraph "Bloc / Cubit"
            GetHeheCubit["GetHeheCubit"]:::presentation
            GetHeheState["GetHeheState"]:::presentation
        end
        subgraph "Pages"
            HomePage["HomePage"]:::presentation
        end
        subgraph "Widgets"
            ButtonHehe["ButtonHehe"]:::presentation
            ChooseLang["ChooseLangWidget"]:::presentation
            ShowMessage["ShowMessageWidget"]:::presentation
            StarBanner["StarAiToolsBanner"]:::presentation
            TextForm["TextFormWidget"]:::presentation
            TitleWidget["TitleWidget"]:::presentation
        end
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        UserInfoEnt["UserInfoEnt"]:::domain
        ReposUserEnt["ReposUserEnt"]:::domain
        HomeRepoInterface["HomeRepo (Interface)"]:::domain
        GetHeheUseCase["GetHeheGitHub UseCase"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        HomeRepoImp["HomeRepoImp"]:::data
        subgraph "DataSources"
            HomeRemote["HomeRemoteData"]:::data
            StaticHome["StaticHomeData"]:::data
        end
        subgraph "Models"
            UserInfoModel["UserInfoModel"]:::data
            ReposUserModel["ReposUserModel"]:::data
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub REST API"]:::external
        GeminiAPI["Google Gemini AI"]:::external
        BrowserOS["Browser/OS (url_launcher)"]:::external
    end

    %% Connections
    AndroidRunner -->|launch| FlutterEngine
    IOSRunner -->|launch| FlutterEngine
    WebRunner -->|launch| FlutterEngine
    LinuxRunner -->|launch| FlutterEngine
    MacOSRunner -->|launch| FlutterEngine
    WindowsRunner -->|launch| FlutterEngine

    FlutterEngine -->|run| Application
    Application -->|registers| AppServices

    Application -->|injects| HomePage
    AppServices -->|provided to| GetHeheCubit

    HomePage -->|interacts| ButtonHehe
    HomePage -->|interacts| ChooseLang
    HomePage -->|interacts| ShowMessage
    HomePage -->|interacts| StarBanner
    HomePage -->|interacts| TextForm
    HomePage -->|interacts| TitleWidget

    ButtonHehe -->|calls| GetHeheCubit
    GetHeheCubit -->|emits| GetHeheState
    GetHeheCubit -->|calls| GetHeheUseCase

    GetHeheUseCase -->|depends on| HomeRepoInterface
    HomeRepoImp -->|implements| HomeRepoInterface

    HomeRepoImp -->|uses| HomeRemote
    HomeRepoImp -->|uses| StaticHome

    HomeRemote -->|fetches JSON| GitHubAPI
    HomeRemote -->|calls AI| GeminiAPI

    HomeRemote -->|maps| UserInfoModel
    HomeRemote -->|maps| ReposUserModel

    UserInfoModel -->|to entity| UserInfoEnt
    ReposUserModel -->|to entity| ReposUserEnt

    UserInfoEnt -->|returns| GetHeheUseCase
    ReposUserEnt -->|returns| GetHeheUseCase

    GeminiAPI -->|response| HomeRemote
    GitHubAPI -->|response| HomeRemote

    ShowMessage -->|opens link| BrowserOS

    %% Click Events - Platform
    click AndroidRunner "https://github.com/najm-flutter/github-hehe/blob/main/android/app/src/main/kotlin/com/example/github_hehe/MainActivity.kt"
    click IOSRunner "https://github.com/najm-flutter/github-hehe/blob/main/ios/Runner/AppDelegate.swift"
    click WebRunner "https://github.com/najm-flutter/github-hehe/blob/main/web/index.html"
    click LinuxRunner "https://github.com/najm-flutter/github-hehe/blob/main/linux/main.cc"
    click MacOSRunner "https://github.com/najm-flutter/github-hehe/blob/main/macos/Runner/MainFlutterWindow.swift"
    click WindowsRunner "https://github.com/najm-flutter/github-hehe/blob/main/windows/runner/main.cpp"

    %% Click Events - Presentation
    click GetHeheCubit "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/bloc/get_hehe_cubit/get_hehe_cubit.dart"
    click GetHeheState "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/bloc/get_hehe_cubit/get_hehe_state.dart"
    click HomePage "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/pages/home_page.dart"
    click ButtonHehe "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/widgets/button_hehe.dart"
    click ChooseLang "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/widgets/choose_lang_widget.dart"
    click ShowMessage "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/widgets/show_message_widget.dart"
    click StarBanner "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/widgets/star_ai_tools_banner.dart"
    click TextForm "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/widgets/text_form_widget.dart"
    click TitleWidget "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/presentation/widgets/title_widget.dart"

    %% Click Events - Domain
    click UserInfoEnt "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/domain/entities/user_info_ent.dart"
    click ReposUserEnt "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/domain/entities/repos_user_ent.dart"
    click HomeRepoInterface "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/domain/repositories/home_repo.dart"
    click GetHeheUseCase "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/domain/usecases/get_hehe_git_hub.dart"

    %% Click Events - Data
    click HomeRepoImp "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/data/repositories/home_repo_imp.dart"
    click HomeRemote "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/data/datasources/home_remote_data.dart"
    click StaticHome "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/data/datasources/static_home_data.dart"
    click UserInfoModel "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/data/models/user_info_model.dart"
    click ReposUserModel "https://github.com/najm-flutter/github-hehe/blob/main/lib/features/home/data/models/repos_user_model.dart"

    %% Click Events - Core & Entry
    click AppServices "https://github.com/najm-flutter/github-hehe/blob/main/lib/core/services/app_services.dart"
    click Application "https://github.com/najm-flutter/github-hehe/blob/main/lib/main.dart"

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1B4F72,stroke-width:2px
    classDef domain fill:#ABEBC6,stroke:#1D8348,stroke-width:2px
    classDef data fill:#F9E79F,stroke:#B7950B,stroke-width:2px
    classDef core fill:#D5D8DC,stroke:#566573,stroke-width:2px
    classDef external fill:#E8DAEF,stroke:#6C3483,stroke-width:2px
```
