How osama-alsharabi/nazarti works
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: materail_app_widget.dart App widget · splash_view.dart Splash · main.dart main.dart · custom_button_widget.dart Shared widgets
Components 21
App Core
Bootstrap, routing, shared state, themes, localization, and reusable UI infrastructure.
- main.dart · Bootstraps the app and launches the root widget.
lib/main.dart - App init · Shared startup initialization before the widget tree mounts.
lib/core/helpers/app_init.dart - App widget · Central composition point for theme, locale, routing, and dependency wiring.
lib/materail_app_widget.dart - Service locator · Registers and resolves app-wide dependencies.
lib/core/services/service_locator.dart - App router · Top-level route assembly and navigation configuration.
lib/core/router/app_router.dart - Route groups · Route definitions for onboarding, auth, and home flows.
lib/core/router/paths/onboarding_router.dart - Global cubits · App-wide language and theme state.
lib/core/cubits/theme/theme_cubit.dart - Themes · Light and dark theme definitions used by the root app widget.
lib/core/theme/light_theme.dart - Shared widgets · Reusable dialogs, buttons, inputs, snack bars, loading, and status bar helpers.
lib/core/widgets/custom_button_widget.dart - Localization · 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 · Initial screen that decides where the user should go next.
lib/feature/splash/presentation/view/splash_view.dart - Onboarding · Self-contained intro flow with persisted completion state.
lib/feature/onboarding/presentation/view/onboarding_view.dart - Onboarding state · Controls onboarding progression and completion status.
lib/feature/onboarding/presentation/view_model/onboarding_status/onboarding_status_cubit.dart - Auth · Login, registration, OTP, and password recovery subsystem.
lib/feature/auth/presentation/login/view/login_view.dart - Auth domain · Business contracts and operations for authentication.
lib/feature/auth/domain/use_cases/login_use_case.dart - Auth data · Local and remote auth data sources plus repository implementation.
lib/feature/auth/data/repository/auth_repo_impl.dart - Auth cubits · Screen-level cubits for login, register, OTP, and password reset/update.
lib/feature/auth/presentation/login/view_model/cubit/login_cubit_cubit.dart - Home · Content-focused landing area with search, announcements, and featured apps.
lib/feature/home/presentation/view/home_view.dart - Home data · 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 · Android and iOS host projects that wrap the Flutter runtime.
android/app/src/main/kotlin/com/example/nazarti/MainActivity.kt - Desktop/web shell · Windows, macOS, Linux, and web scaffolding around the shared Dart app.
web/index.html
Connections 25
- 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.