SmartCrew Mobile Architecture

This document summarizes the core Flutter architecture used in SmartCrew Mobile. The goal is to keep business logic isolated from UI, keep screens modular, and keep data flow consistent across features.

Layered structure

UI: lib/screens/ and lib/components/
State: lib/providers/ (feature providers)
Domain services: lib/services/ (reusable business logic)
Data: lib/repositories/ and lib/models/
Shared utilities: lib/util/, lib/theme/, lib/animations/

Feature folder pattern

lib/
  providers/<feature>/
    <feature>_provider.dart
    services/
    helpers/
    dto/
  screens/<feature>/
    <feature>_screen.dart
    components/
    sections/

State management

Providers own business state and expose async actions.
UI widgets consume provider state and avoid direct data access.
Shared UI state uses ValueNotifier or controller classes.

Data flow

UI triggers provider action.
Provider calls services/repositories.
Repositories talk to Firebase or local storage.
Provider updates state and notifies UI.

Error and feedback strategy

Providers emit user-facing errors as structured messages.
UI feedback (snackbars/toasts) is centralized to avoid context leaks.

Performance notes

Prefer lightweight widgets and keep heavy work in services.
Cache frequently accessed data locally when possible.
Avoid setState for shared or cross-screen state.

Architecture