# sezanhaque/kahf_flutter architecture

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

- Interactive diagram: https://gitdiagram.com/sezanhaque/kahf_flutter
- Repository: https://github.com/sezanhaque/kahf_flutter

## Overview

1. **Overall shape**  
This is a Flutter cross-platform app, with the actual application architecture living under `lib/`. The `android/`, `ios/`, `web/`, `linux/`, `macos/`, and `windows/` directories are standard Flutter host shells rather than separate app logic.

2. **Entry point and app bootstrap**  
`lib/main.dart` is the startup entry. The app appears to boot into a shared splash flow (`lib/src/screens/splash_screen.dart`) before moving into the main feature screens. The bootstrap likely wires dependency injection and global state before rendering feature UI.

3. **Core foundation layer**  
`lib/src/core/` holds cross-cutting infrastructure:  
- result/error primitives in `base/` (`Failure`, `ResponseResult`, `Status`, exceptions)  
- app-wide constants in `constants/`  
- network definitions in `network/` (`api_endpoints.dart`, `utf8_interceptor.dart`)  
- logging in `logger/`  
- shared utilities and formatting extensions  
- a global `error_notifier` provider for surfacing failures.  
This layer is the main boundary for non-feature-specific behavior.

4. **Dependency injection boundary**  
`lib/src/core/di/` contains a code-generated DI setup split into `externals`, `services`, and `repositories`. This is where concrete implementations are assembled and exposed to the rest of the app, keeping feature code from constructing dependencies directly.

5. **Shared UI components**  
`lib/src/common/widgets/` contains reusable UI primitives such as loading and error widgets and a custom bottom navigation bar. These are intentionally outside feature folders so multiple screens can share the same presentation patterns.

6. **Feature modularization**  
The app uses a clean-architecture-style feature split under `lib/src/features/`. Each feature is divided into `data`, `domain`, and `presentation`, which makes the architecture diagram fairly clean: infrastructure at the bottom, feature logic in the middle, and screens/widgets/providers at the top.

7. **Home feature: main content pipeline**  
`features/home` is the main data-driven feature. It includes:  
- `data/services/video_services.dart` for remote calls  
- `data/repositories/video_repository_impl.dart` for data access orchestration  
- `domain/entities/video_entity.dart` and repository contracts  
- `presentation/provider/video_notifier.dart` and `video_state.dart` for UI state  
- screens and widgets for the home feed.  
This is the primary path for fetching, paging, and rendering the video list.

8. **Home feature data flow**  
The typical flow is: Home UI → `video_notifier`/state → repository interface → repository implementation → video service → API endpoint → JSON model → domain entity → back to UI.  
The data layer uses model classes for API serialization and the domain layer uses a separate `VideoEntity`, so the UI is insulated from raw API shapes.

9. **Home UI composition and mini-player behavior**  
The home presentation layer is composed of reusable video widgets such as thumbnails, duration badges, info blocks, card widgets, and a `video_pip_bar_widget`. This indicates the home screen supports a draggable mini-player / picture-in-picture-style experience while the feed remains visible.

10. **Video player feature**  
`features/video_player` is a second feature area focused on playback state rather than content retrieval. It has its own notifier/state pair and a `video_player_dialog.dart`, suggesting playback can be launched or controlled in a dialog-like overlay as well as a dedicated screen. This is the main boundary for player controls, options, and full-screen behavior.

11. **Presentation state management pattern**  
The presence of `*.notifier.dart`, `*.state.dart`, and generated `*.g.dart` files strongly suggests Riverpod-style state management with code generation. The architecture therefore separates view state from widgets, with providers acting as the bridge between UI and repositories/player logic.

12. **Data contracts and serialization**  
`freezed` and generated JSON files (`*.freezed.dart`, `*.g.dart`) appear throughout the models and states. That means immutable value objects and serialized API models are part of the app’s core design, reducing manual boilerplate and enforcing explicit data contracts.

13. **Platform and asset boundaries**  
Assets are organized separately under `assets/images` and `assets/logo`, while platform-specific launch icons, manifests, and app entry stubs live in the host folders. These are support concerns only; they do not change the application’s feature/data architecture.

14. **Build and tooling constraints**  
The repo is pinned with FVM (`.fvmrc`) and targets Flutter 3.32.5 / Dart 3.8.1, with code generation driven by `build_runner`. That matters for the architecture diagram because several core pieces depend on generated code and the app expects the Flutter toolchain to match the pinned version.

Main entry points: [`lib/main.dart`](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/main.dart) (main.dart), [`lib/src/core/di`](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/di) (DI setup), [`lib/src/features/home/presentation/screen/home_screen.dart`](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/screen/home_screen.dart) (Home screen), [`lib/src/features/home/presentation/provider/video_notifier.dart`](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/provider/video_notifier.dart) (Video notifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_lib_main(("main.dart<br/>entrypoint<br/>[main.dart]"))
  node_splash_screen["Splash<br/>screen<br/>[splash_screen.dart]"]
end

subgraph group_core["Core"]
  node_base_primitives["Base types<br/>core primitives"]
  node_core_di["DI setup<br/>dependency injection"]
  node_api_layer["Network API<br/>networking"]
  node_error_notifier(("Error notifier<br/>provider"))
  node_shared_widgets["Shared widgets<br/>ui components"]
end

subgraph group_home["Home feature"]
  node_home_screen["Home screen<br/>[home_screen.dart]"]
  node_video_notifier(("Video notifier<br/>state provider"))
  node_video_state["Video state<br/>ui state<br/>[video_state.dart]"]
  node_video_repo["Video repo"]
  node_video_service["Video service<br/>remote service"]
  node_video_models["Video models<br/>dto models"]
  node_video_entity["Video entity<br/>domain entity<br/>[video_entity.dart]"]
  node_video_widgets["Video widgets<br/>ui widgets"]
end

subgraph group_player["Player feature"]
  node_player_notifier(("Player notifier<br/>state provider"))
  node_player_state["Player state<br/>ui state"]
  node_player_dialog["Player dialog<br/>overlay screen"]
end

subgraph group_platform["Platforms"]
  node_android_shell["Android<br/>platform shell"]
  node_ios_shell["iOS<br/>platform shell"]
  node_desktop_shells["Desktop<br/>platform shells"]
end

node_lib_main -->|"starts"| node_splash_screen
node_lib_main -->|"initializes"| node_core_di
node_splash_screen -->|"navigates to"| node_home_screen
node_core_di -.->|"assembles"| node_base_primitives
node_core_di -->|"provides"| node_api_layer
node_core_di -->|"binds"| node_video_repo
node_home_screen -->|"reads state"| node_video_notifier
node_video_notifier -->|"emits"| node_video_state
node_video_notifier -->|"uses"| node_video_repo
node_video_repo -->|"fetches via"| node_video_service
node_video_service -->|"calls"| node_api_layer
node_video_service -->|"parses"| node_video_models
node_video_models -->|"maps to"| node_video_entity
node_video_entity -->|"supplies"| node_video_notifier
node_home_screen -->|"composes"| node_video_widgets
node_video_widgets -.->|"reuses"| node_shared_widgets
node_home_screen -->|"opens player"| node_player_notifier
node_player_notifier -->|"emits"| node_player_state
node_player_dialog -->|"reads state"| node_player_notifier
node_android_shell -.->|"hosts"| node_lib_main
node_ios_shell -.->|"hosts"| node_lib_main
node_desktop_shells -.->|"hosts"| node_lib_main

click node_lib_main "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/main.dart"
click node_splash_screen "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/screens/splash_screen.dart"
click node_base_primitives "https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/base"
click node_core_di "https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/di"
click node_api_layer "https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/network"
click node_error_notifier "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/core/providers/error_notifier.dart"
click node_shared_widgets "https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/common/widgets"
click node_home_screen "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/screen/home_screen.dart"
click node_video_notifier "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/provider/video_notifier.dart"
click node_video_state "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/provider/video_state.dart"
click node_video_repo "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/domain/repositories/video_repository.dart"
click node_video_service "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/data/services/video_services.dart"
click node_video_models "https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/features/home/data/models/video"
click node_video_entity "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/domain/entities/video_entity.dart"
click node_video_widgets "https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/features/home/presentation/widgets/video"
click node_player_notifier "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/video_player/presentation/provider/video_player_notifier.dart"
click node_player_state "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/video_player/presentation/provider/video_player_state.dart"
click node_player_dialog "https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/video_player/presentation/screen/video_player_dialog.dart"
click node_android_shell "https://github.com/sezanhaque/kahf_flutter/tree/master/android"
click node_ios_shell "https://github.com/sezanhaque/kahf_flutter/tree/master/ios"
click node_desktop_shells "https://github.com/sezanhaque/kahf_flutter/tree/master/linux"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lib_main,node_splash_screen toneBlue
class node_base_primitives,node_core_di,node_api_layer,node_error_notifier,node_shared_widgets toneAmber
class node_home_screen,node_video_notifier,node_video_state,node_video_repo,node_video_service,node_video_models,node_video_entity,node_video_widgets toneMint
class node_player_notifier,node_player_state,node_player_dialog toneRose
class node_android_shell,node_ios_shell,node_desktop_shells toneIndigo
```

## Components

### App shell

Flutter entrypoint and shared startup flow

- [main.dart](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/main.dart): entrypoint · App startup and bootstrap entrypoint · `lib/main.dart`
- [Splash](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/screens/splash_screen.dart): screen · Shared startup splash flow · `lib/src/screens/splash_screen.dart`

### Core

Cross-cutting infrastructure and app-wide primitives

- [Base types](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/base): core primitives · Failure, result, status, and exception primitives · `lib/src/core/base`
- [DI setup](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/di): dependency injection · Generated assembly of externals, services, and repositories · `lib/src/core/di`
- [Network API](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/core/network): networking · Endpoints and response interception · `lib/src/core/network`
- [Error notifier](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/core/providers/error_notifier.dart): provider · Global failure surfacing provider · `lib/src/core/providers/error_notifier.dart`
- [Shared widgets](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/common/widgets): ui components · Reusable loading, error, and navigation widgets · `lib/src/common/widgets`

### Home feature

Content feed, paging, and home presentation

- [Home screen](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/screen/home_screen.dart): screen · Primary feed screen · `lib/src/features/home/presentation/screen/home_screen.dart`
- [Video notifier](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/provider/video_notifier.dart): state provider · Home feed state and pagination controller · `lib/src/features/home/presentation/provider/video_notifier.dart`
- [Video state](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/presentation/provider/video_state.dart): ui state · Immutable home feature view state · `lib/src/features/home/presentation/provider/video_state.dart`
- [Video repo](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/domain/repositories/video_repository.dart): repository · Home feature repository contract and implementation boundary · `lib/src/features/home/domain/repositories/video_repository.dart`
- [Video service](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/data/services/video_services.dart): remote service · API-backed video fetch service · `lib/src/features/home/data/services/video_services.dart`
- [Video models](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/features/home/data/models/video): dto models · Paginated response and video/comment serialization models · `lib/src/features/home/data/models/video`
- [Video entity](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/home/domain/entities/video_entity.dart): domain entity · Domain video model used by the app layer · `lib/src/features/home/domain/entities/video_entity.dart`
- [Video widgets](https://github.com/sezanhaque/kahf_flutter/tree/master/lib/src/features/home/presentation/widgets/video): ui widgets · Feed card, thumbnail, info, duration, and pip bar widgets · `lib/src/features/home/presentation/widgets/video`

### Player feature

Playback state and overlay controls

- [Player notifier](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/video_player/presentation/provider/video_player_notifier.dart): state provider · Playback and dialog control state · `lib/src/features/video_player/presentation/provider/video_player_notifier.dart`
- [Player state](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/video_player/presentation/provider/video_player_state.dart): ui state · Immutable playback state · `lib/src/features/video_player/presentation/provider/video_player_state.dart`
- [Player dialog](https://github.com/sezanhaque/kahf_flutter/blob/master/lib/src/features/video_player/presentation/screen/video_player_dialog.dart): overlay screen · Dialog-style playback UI · `lib/src/features/video_player/presentation/screen/video_player_dialog.dart`

### Platforms

Host shells for Flutter targets

- [Android](https://github.com/sezanhaque/kahf_flutter/tree/master/android): platform shell · Flutter host shell and native Android runner · `android`
- [iOS](https://github.com/sezanhaque/kahf_flutter/tree/master/ios): platform shell · Flutter host shell and native iOS runner · `ios`
- [Desktop](https://github.com/sezanhaque/kahf_flutter/tree/master/linux): platform shells · Linux, macOS, and Windows host runners · `linux`

## Connections

- main.dart → Splash: starts · App boots into the shared splash flow
- main.dart → DI setup: initializes · Bootstrap wires dependency injection
- Splash → Home screen: navigates to · Splash hands off to the main app experience
- DI setup → Base types: assembles · DI depends on shared result and exception types
- DI setup → Network API: provides · Registers networking dependencies
- DI setup → Video repo: binds · Exposes repository implementations to features
- Home screen → Video notifier: reads state · UI is driven by Riverpod-style state
- Video notifier → Video state: emits · Notifier updates immutable view state
- Video notifier → Video repo: uses · State controller requests content through repository contract
- Video repo → Video service: fetches via · Repository implementation delegates remote access to service
- Video service → Network API: calls · Service uses shared API endpoints/interceptors
- Video service → Video models: parses · Remote payloads are serialized into DTOs
- Video models → Video entity: maps to · API models are converted to domain entities
- Video entity → Video notifier: supplies · Domain content feeds the UI state layer
- Home screen → Video widgets: composes · Home screen is built from reusable video widgets
- Video widgets → Shared widgets: reuses · Feature UI leverages shared loading/error components
- Home screen → Player notifier: opens player · Home experience can launch playback controls
- Player notifier → Player state: emits · Playback controller updates immutable player state
- Player dialog → Player notifier: reads state · Dialog overlay is driven by player provider
- Android → main.dart: hosts · Native shell launches the Flutter app
- iOS → main.dart: hosts · Native shell launches the Flutter app
- Desktop → main.dart: hosts · Desktop runners launch the Flutter app