# osama-alsharabi/nazarti architecture

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

- Interactive diagram: https://gitdiagram.com/osama-alsharabi/nazarti
- Repository: https://github.com/osama-alsharabi/nazarti

## Overview

1. This is a Flutter multi-platform client app. The same Dart codebase targets Android, iOS, web, Windows, macOS, and Linux, with each platform mostly using the standard Flutter runner shell plus minimal native bootstrap code.

2. The app entry point is `lib/main.dart`, which likely bootstraps shared initialization from `lib/core/helpers/app_init.dart` and then mounts the root widget in `lib/materail_app_widget.dart`. That root widget is the central composition point for theme, locale, routing, and dependency injection.

3. Cross-cutting app infrastructure lives under `lib/core`. The most important shared subsystems are:
   - `core/router`: route definitions, page transitions, and route groups for onboarding, auth, and home.
   - `core/cubits`: global state for theme and language.
   - `core/services/service_locator.dart`: dependency registration and lookup.
   - `core/theme`: light and dark theme definitions.
   - `core/widgets`: reusable UI components such as dialogs, buttons, inputs, snack bars, and loading indicators.

4. State management is organized around Cubits/BLoC-style components. Feature views consume cubit state through bloc consumers/listeners, while `safe_cubit.dart` and `simple_observer.dart` suggest standardization for lifecycle safety and debugging. Theme and language are app-wide cubits; feature-specific cubits live alongside their screens.

5. The app’s primary feature boundary is `lib/feature`, split into `onboarding`, `splash`, `auth`, and `home`. Each feature follows a layered structure where presentational widgets sit above cubits/view models, which sit above domain/data abstractions when needed.

6. `splash` is the first user-facing screen after startup. It likely handles initial routing decisions based on app state such as onboarding completion or authentication status. This is an important transition node in the architecture because it funnels users into onboarding, auth, or the main app.

7. `onboarding` is a self-contained flow with data, presentation, and view model layers. It includes page content, dot indicators, and a welcome screen. There is also an `onboarding_status_cubit`, implying persisted completion state that influences the startup route decision.

8. `auth` is the richest subsystem and is organized in classic clean-architecture style:
   - `data/data_sources`: local and remote sources for auth operations.
   - `data/models`: transport/storage model representations.
   - `data/repository`: repository implementation bridging data sources to domain.
   - `domain/entities`, `repos`, and `use_cases`: business-facing contracts and operations such as login, register, OTP verification, resend OTP, reset password, and update password.
   - `presentation`: login, register, forgot password, update password, and OTP verification screens with matching cubits.

9. The auth data flow is: UI form input -> feature cubit -> domain use case -> repository -> local or remote data source -> model/entity mapping -> state update back to the UI. The presence of both local and remote sources indicates the app can persist some auth state locally while also interacting with an external authentication service.

10. `home` appears to be the post-auth landing area. It includes a featured-app data source, a domain entity for featured apps, and UI for search, announcements, and featured content. Compared with `auth`, this feature looks lighter and more content-driven, with fewer clearly defined use cases exposed in the tree.

11. Shared utilities under `core` support the entire UI layer: asset paths, colors, text styles, validation helpers, responsive text helpers, and prebuilt widgets. `network_images` suggests centralized handling for remote image URLs, caching, and precaching, which is important for performance across the feature screens that use images heavily.

12. Localization is built in. The app uses ARB files in `lib/l10n` and generated locale code under `lib/generated/intl`, supporting at least Arabic and English. This means the architecture includes a localization boundary that affects almost all user-facing screens.

13. The repository also contains native platform runners for Android and iOS plus desktop/web scaffolding. These are mostly integration shells, while the app logic stays in Dart; the only platform-specific code visible is standard Flutter host setup such as `MainActivity.kt`, `AppDelegate.swift`, and desktop runner files.

14. For diagramming purposes, the key structural flow is:
   startup/bootstrap -> service locator + global cubits -> splash/onboarding/auth routing -> feature-specific cubits -> shared UI/widgets and utilities -> optional local/remote data sources.
   The main architectural boundaries are app-wide infrastructure, feature modules, and platform wrappers.

Main entry points: [`lib/materail_app_widget.dart`](https://github.com/osama-alsharabi/nazarti/blob/main/lib/materail_app_widget.dart) (App widget), [`lib/feature/splash/presentation/view/splash_view.dart`](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/splash/presentation/view/splash_view.dart) (Splash), [`lib/main.dart`](https://github.com/osama-alsharabi/nazarti/blob/main/lib/main.dart) (main.dart), [`lib/core/widgets/custom_button_widget.dart`](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/widgets/custom_button_widget.dart) (Shared widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Core"]
  node_main["main.dart<br/>app entry<br/>[main.dart]"]
  node_app_init["App init<br/>bootstrap<br/>[app_init.dart]"]
  node_root_widget["App widget<br/>composition root"]
  node_service_locator["Service locator<br/>di registry"]
  node_app_router["App router<br/>routing<br/>[app_router.dart]"]
  node_router_paths["Route groups<br/>route map"]
  node_global_cubits["Global cubits<br/>state<br/>[theme_cubit.dart]"]
  node_theme_defs["Themes<br/>ui theme<br/>[light_theme.dart]"]
  node_widgets_shared["Shared widgets<br/>ui components"]
  node_l10n["Localization<br/>i18n<br/>[intl_en.arb]"]
end

subgraph group_features["Feature Modules"]
  node_splash["Splash<br/>startup screen<br/>[splash_view.dart]"]
  node_onboarding["Onboarding<br/>guided flow"]
  node_onboarding_state["Onboarding state<br/>cubit"]
  node_auth["Auth<br/>clean arch feature<br/>[login_view.dart]"]
  node_auth_domain["Auth domain<br/>use cases"]
  node_auth_data["Auth data<br/>repos/data"]
  node_auth_cubits["Auth cubits<br/>feature state"]
  node_home["Home<br/>post-auth area<br/>[home_view.dart]"]
  node_home_data["Home data<br/>content source"]
end

subgraph group_platforms["Platform Shells"]
  node_platform_mobile["Mobile runners<br/>native shell<br/>[MainActivity.kt]"]
  node_platform_desktop_web["Desktop/web shell<br/>host shell<br/>[index.html]"]
end

node_main -->|"starts"| node_app_init
node_app_init -->|"registers"| node_service_locator
node_app_init -->|"primes"| node_global_cubits
node_main -->|"mounts"| node_root_widget
node_root_widget -->|"resolves"| node_service_locator
node_root_widget -->|"configures"| node_app_router
node_root_widget -->|"provides"| node_global_cubits
node_root_widget -->|"uses"| node_theme_defs
node_root_widget -->|"renders"| node_widgets_shared
node_root_widget -->|"localizes"| node_l10n
node_app_router -->|"routes to"| node_router_paths
node_router_paths -->|"opens"| node_splash
node_splash -->|"checks"| node_onboarding_state
node_splash -->|"routes"| node_auth
node_splash -->|"routes"| node_home
node_onboarding -->|"updates"| node_onboarding_state
node_onboarding -->|"uses"| node_widgets_shared
node_auth -->|"drives"| node_auth_cubits
node_auth_cubits -->|"invokes"| node_auth_domain
node_auth_domain -->|"depends on"| node_auth_data
node_auth_data -.->|"feeds"| node_widgets_shared
node_home -->|"loads"| node_home_data
node_home -->|"uses"| node_widgets_shared
node_platform_mobile -.->|"hosts"| node_main
node_platform_desktop_web -.->|"hosts"| node_main

click node_main "https://github.com/osama-alsharabi/nazarti/blob/main/lib/main.dart"
click node_app_init "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/helpers/app_init.dart"
click node_root_widget "https://github.com/osama-alsharabi/nazarti/blob/main/lib/materail_app_widget.dart"
click node_service_locator "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/services/service_locator.dart"
click node_app_router "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/router/app_router.dart"
click node_router_paths "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/router/paths/onboarding_router.dart"
click node_global_cubits "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/cubits/theme/theme_cubit.dart"
click node_theme_defs "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/theme/light_theme.dart"
click node_widgets_shared "https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/widgets/custom_button_widget.dart"
click node_l10n "https://github.com/osama-alsharabi/nazarti/blob/main/lib/l10n/intl_en.arb"
click node_splash "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/splash/presentation/view/splash_view.dart"
click node_onboarding "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/onboarding/presentation/view/onboarding_view.dart"
click node_onboarding_state "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/onboarding/presentation/view_model/onboarding_status/onboarding_status_cubit.dart"
click node_auth "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/presentation/login/view/login_view.dart"
click node_auth_domain "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/domain/use_cases/login_use_case.dart"
click node_auth_data "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/data/repository/auth_repo_impl.dart"
click node_auth_cubits "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/presentation/login/view_model/cubit/login_cubit_cubit.dart"
click node_home "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/home/presentation/view/home_view.dart"
click node_home_data "https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/home/data/data_source/featured_data_source.dart"
click node_platform_mobile "https://github.com/osama-alsharabi/nazarti/blob/main/android/app/src/main/kotlin/com/example/nazarti/MainActivity.kt"
click node_platform_desktop_web "https://github.com/osama-alsharabi/nazarti/blob/main/web/index.html"

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_main,node_app_init,node_root_widget,node_service_locator,node_app_router,node_router_paths,node_global_cubits,node_theme_defs,node_widgets_shared,node_l10n toneBlue
class node_splash,node_onboarding,node_onboarding_state,node_auth,node_auth_domain,node_auth_data,node_auth_cubits,node_home,node_home_data toneAmber
class node_platform_mobile,node_platform_desktop_web toneMint
```

## Components

### App Core

Bootstrap, routing, shared state, themes, localization, and reusable UI infrastructure.

- [main.dart](https://github.com/osama-alsharabi/nazarti/blob/main/lib/main.dart): app entry · Bootstraps the app and launches the root widget. · `lib/main.dart`
- [App init](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/helpers/app_init.dart): bootstrap · Shared startup initialization before the widget tree mounts. · `lib/core/helpers/app_init.dart`
- [App widget](https://github.com/osama-alsharabi/nazarti/blob/main/lib/materail_app_widget.dart): composition root · Central composition point for theme, locale, routing, and dependency wiring. · `lib/materail_app_widget.dart`
- [Service locator](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/services/service_locator.dart): di registry · Registers and resolves app-wide dependencies. · `lib/core/services/service_locator.dart`
- [App router](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/router/app_router.dart): routing · Top-level route assembly and navigation configuration. · `lib/core/router/app_router.dart`
- [Route groups](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/router/paths/onboarding_router.dart): route map · Route definitions for onboarding, auth, and home flows. · `lib/core/router/paths/onboarding_router.dart`
- [Global cubits](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/cubits/theme/theme_cubit.dart): state · App-wide language and theme state. · `lib/core/cubits/theme/theme_cubit.dart`
- [Themes](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/theme/light_theme.dart): ui theme · Light and dark theme definitions used by the root app widget. · `lib/core/theme/light_theme.dart`
- [Shared widgets](https://github.com/osama-alsharabi/nazarti/blob/main/lib/core/widgets/custom_button_widget.dart): ui components · Reusable dialogs, buttons, inputs, snack bars, loading, and status bar helpers. · `lib/core/widgets/custom_button_widget.dart`
- [Localization](https://github.com/osama-alsharabi/nazarti/blob/main/lib/l10n/intl_en.arb): i18n · ARB files and generated locale support for Arabic and English. · `lib/l10n/intl_en.arb`

### Feature Modules

User-facing flows organized by onboarding, splash, auth, and home.

- [Splash](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/splash/presentation/view/splash_view.dart): startup screen · Initial screen that decides where the user should go next. · `lib/feature/splash/presentation/view/splash_view.dart`
- [Onboarding](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/onboarding/presentation/view/onboarding_view.dart): guided flow · Self-contained intro flow with persisted completion state. · `lib/feature/onboarding/presentation/view/onboarding_view.dart`
- [Onboarding state](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/onboarding/presentation/view_model/onboarding_status/onboarding_status_cubit.dart): cubit · Controls onboarding progression and completion status. · `lib/feature/onboarding/presentation/view_model/onboarding_status/onboarding_status_cubit.dart`
- [Auth](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/presentation/login/view/login_view.dart): clean arch feature · Login, registration, OTP, and password recovery subsystem. · `lib/feature/auth/presentation/login/view/login_view.dart`
- [Auth domain](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/domain/use_cases/login_use_case.dart): use cases · Business contracts and operations for authentication. · `lib/feature/auth/domain/use_cases/login_use_case.dart`
- [Auth data](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/data/repository/auth_repo_impl.dart): repos/data · Local and remote auth data sources plus repository implementation. · `lib/feature/auth/data/repository/auth_repo_impl.dart`
- [Auth cubits](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/auth/presentation/login/view_model/cubit/login_cubit_cubit.dart): feature state · Screen-level cubits for login, register, OTP, and password reset/update. · `lib/feature/auth/presentation/login/view_model/cubit/login_cubit_cubit.dart`
- [Home](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/home/presentation/view/home_view.dart): post-auth area · Content-focused landing area with search, announcements, and featured apps. · `lib/feature/home/presentation/view/home_view.dart`
- [Home data](https://github.com/osama-alsharabi/nazarti/blob/main/lib/feature/home/data/data_source/featured_data_source.dart): content source · Featured-app data source and related domain model for the home feed. · `lib/feature/home/data/data_source/featured_data_source.dart`

### Platform Shells

Flutter host runners for mobile, desktop, and web.

- [Mobile runners](https://github.com/osama-alsharabi/nazarti/blob/main/android/app/src/main/kotlin/com/example/nazarti/MainActivity.kt): native shell · Android and iOS host projects that wrap the Flutter runtime. · `android/app/src/main/kotlin/com/example/nazarti/MainActivity.kt`
- [Desktop/web shell](https://github.com/osama-alsharabi/nazarti/blob/main/web/index.html): host shell · Windows, macOS, Linux, and web scaffolding around the shared Dart app. · `web/index.html`

## Connections

- main.dart → App init: starts · Main entry performs shared initialization first.
- App init → Service locator: registers · Bootstrap wires dependencies into the locator.
- App init → Global cubits: primes · Startup prepares global theme and language state.
- main.dart → App widget: mounts · Main launches the root widget tree.
- App widget → Service locator: resolves · The composition root pulls dependencies from the locator.
- App widget → App router: configures · Root widget provides navigation and routing.
- App widget → Global cubits: provides · Theme and language cubits are exposed app-wide.
- App widget → Themes: uses · Root widget applies light and dark themes.
- App widget → Shared widgets: renders · Shared UI primitives are used throughout the app shell.
- App widget → Localization: localizes · App widget enables translated UI strings.
- App router → Route groups: routes to · Top-level router delegates to feature route groups.
- Route groups → Splash: opens · Startup navigation begins at splash.
- Splash → Onboarding state: checks · Splash uses completion state to decide the next screen.
- Splash → Auth: routes · Splash can forward users into authentication.
- Splash → Home: routes · Splash can forward users into the main app area.
- Onboarding → Onboarding state: updates · Onboarding flow records completion and progress.
- Onboarding → Shared widgets: uses · Onboarding UI relies on shared controls and indicators.
- Auth → Auth cubits: drives · Auth screens are controlled by feature cubits.
- Auth cubits → Auth domain: invokes · Cubits trigger authentication use cases.
- Auth domain → Auth data: depends on · Use cases depend on repositories and data sources.
- Auth data → Shared widgets: feeds · Auth state is surfaced through shared form and feedback widgets.
- Home → Home data: loads · Home view pulls featured content from its data layer.
- Home → Shared widgets: uses · Home screens reuse shared UI building blocks.
- Mobile runners → main.dart: hosts · Native mobile shells launch the Dart entry point.
- Desktop/web shell → main.dart: hosts · Desktop and web shells launch the same shared app code.
