My App
Mobile App Docs

CLAUDE

SmartCrew Mobile - CLAUDE

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Smart Crew Mobile is a Flutter application for workforce management and time tracking. The app uses Firebase for backend services (Auth, Firestore, Functions, Crashlytics, Messaging), follows clean architecture principles, and uses Provider for state management.

Package name: clean_provider_architecture Current version: 2025.0.28+2025.0.28 SDK: Flutter 3.2.0+

Development Commands

Essential Commands

  • flutter pub get — Install dependencies
  • flutter run -d <device> — Run app (e.g., -d ios, -d chrome)
  • flutter analyze — Run static analysis (MUST pass before pushing)
  • flutter test — Run all tests
  • flutter test test/provider/services/<file>_test.dart — Run specific test file
  • dart format . — Format code (equivalent: flutter format .)
  • flutter pub run build_runner build — Generate code (assets, colors, fonts from flutter_gen)

Build Commands

  • flutter build apk --release — Build Android release APK
  • flutter build ios --release — Build iOS release
  • flutter clean — Clean build artifacts

Firebase Commands

  • flutterfire configure — Update Firebase configuration (regenerates lib/firebase_options.dart)
  • Set .env variables for Firebase emulator configuration:
    • EMULATOR_ACTIVE=true/false
    • EMULATOR_HOST=<ip>
    • AUTH_PORT=<port>

Architecture & Code Organization

High-Level Architecture Pattern

This project follows a layered clean architecture with clear separation of concerns:

Presentation Layer (UI)
    ↓
State Management Layer (Providers)
    ↓
Business Logic Layer (Services)
    ↓
Data Layer (Repositories)
    ↓
External Services (Firebase, APIs)

Key Architectural Components

1. Providers (lib/providers/)

  • Purpose: State management using Provider package (ChangeNotifier pattern)
  • Main Providers:
    • AuthProvider: Authentication state and user management
    • NetworkDataProvider: Singleton that aggregates multiple data providers via mixins
    • LocationProvider: Location tracking and geofencing
    • HomeProvider: Home screen state
    • NotificationsProvider: Push notification handling

NetworkDataProvider Pattern: Uses mixins to compose multiple data providers (WorkLogsProvider, CompanyProvider, ReportProvider, etc.). This provider is initialized after auth and loads all workspace data in parallel using Future.wait().

2. Services (lib/services/)

  • Purpose: Business logic and domain operations
  • Pattern: Most services extend BaseService for standardized logging
  • Key Service Categories:
    • logs/: Work log operations (clock in/out, breaks, calculations)
      • work_logs_state_manager.dart: UI state management for work logs (ChangeNotifier)
      • work_logs_data_service.dart: Data operations for work logs
      • work_logs_cache_manager.dart: Local caching for work logs
      • work_logs_business_service.dart: Business logic coordination
    • location/: Geolocation services (background tracking, jobsite enter/exit)
    • checkout/: Checkout questions and validation
    • status/: Status calculation services
    • storage/: Local storage (Hive) for recent selections and announcements

Service Design: Services are stateless and focused on single responsibilities. Complex workflows are orchestrated by higher-level services.

3. Repositories (lib/repositories/)

  • Purpose: Data access layer for Firestore operations
  • Current: WorkLogsRepository - handles all work log CRUD operations and queries
  • Pattern: Repositories abstract Firestore queries and provide clean API for services

4. Models (lib/models/)

  • Purpose: Data models and entities
  • Key Models: AppUser, DailyLog, Activity, BreakActivity, CheckoutQuestion, Company, Project, Equipment
  • Subpackages:
    • interfaces/: Interface definitions (activity, task, selection)
    • form_data/: Form-related data models
    • local/: Local storage models (Hive-annotated)

5. Screens (lib/screens/)

  • Organization:
    • logged_out/: Authentication screens
    • logged_in/home_tabs/: Main app tabs (home, docs, reports, profile, jobsites, projects, news)
    • logged_in/viewer_pages/: Detail/viewer screens
    • logged_in/onboarding/: Onboarding flow
    • splash_screen.dart: Initial loading screen

6. Components (lib/components/)

  • Purpose: Reusable UI widgets
  • Subpackages:
    • base/: Foundation widgets (bottom sheets, etc.)
    • custom/: Custom widgets
    • modal/: Modal dialogs
    • selection/: Selection components
    • checkout/: Checkout-specific components

7. Generated Code (lib/gen/)

  • Auto-generated by flutter_gen (DO NOT edit manually)
  • assets.gen.dart: Type-safe asset references
  • colors.gen.dart: Colors from assets/colors/colors.xml
  • fonts.gen.dart: Font family constants
  • Regenerate: flutter pub run build_runner build

Data Flow Example: Work Logs

  1. User Action (UI) → triggers method in WorkLogsStateManager (service)
  2. State Manager → calls business service (WorkLogsBusinessService)
  3. Business Service → uses data service (WorkLogsDataService)
  4. Data Service → calls repository (WorkLogsRepository)
  5. Repository → executes Firestore query
  6. Result → bubbles back up, state manager calls notifyListeners()
  7. UI → rebuilds with new state

Key Design Patterns

  1. Singleton Pattern: NetworkDataProvider uses singleton to ensure single instance
  2. Mixin Pattern: NetworkDataProvider composes functionality via mixins
  3. Repository Pattern: Data access abstracted through repositories
  4. Service Layer Pattern: Business logic separated from presentation
  5. ChangeNotifier Pattern: State management via Provider's ChangeNotifier
  6. Factory Pattern: Model classes often have factory constructors (e.g., fromJson)

Coding Standards

Strict Analysis Rules

The project enforces strict type safety and code quality via analysis_options.yaml:

  • No implicit casts or dynamics: implicit-casts: false, implicit-dynamic: false
  • Always specify types: always_specify_types: error
  • TODO comments are errors: todo: error
  • Required parameters must not be missing: missing_required_param: error
  • Prefer const: Use const constructors and literals wherever possible
  • Trailing commas: Required for better formatting (require_trailing_commas)
  • Single quotes: Use single quotes for strings (prefer_single_quotes)
  • Relative imports: Prefer relative imports within lib (prefer_relative_imports)

Naming Conventions

  • Files: snake_case.dart (e.g., work_logs_state_manager.dart)
  • Classes/Types: UpperCamelCase (e.g., WorkLogsService, DailyLog)
  • Members/Variables: lowerCamelCase (e.g., userId, dailyLog)
  • Constants: lowerCamelCase (e.g., defaultTimeout)
  • Enums: UpperCamelCase for type, lowerCamelCase for values

Logging

  • Use appLogger (singleton) for all logging: appLogger.d(), appLogger.i(), appLogger.w(), appLogger.e()
  • Services extending BaseService get automatic logging methods: logDebug(), logInfo(), logWarning(), logError()
  • Initialize logger in main.dart via appLogger.initialize()

Firebase Integration

  • Auth: Firebase Auth with phone number authentication
  • Firestore: Primary data store (users, daily_logs, companies, projects, etc.)
  • Functions: Cloud Functions for server-side operations (region: us-central1)
  • Crashlytics: Automatic error reporting
  • FCM: Push notifications via Firebase Messaging
  • Emulator: Can run with local Firebase emulator (configure via .env)

Testing

Test Structure

  • Mirror lib/ structure in test/
  • Test files must end with _test.dart
  • Current tests focus on services and providers
  • Example test paths:
    • test/provider/services/switch_log_service_test.dart
    • test/provider/services/add_manual_log_service_test.dart

Running Tests

  • Run all tests: flutter test
  • Run single test file: flutter test test/provider/services/<file>_test.dart
  • Generate coverage: flutter test --coverage
  • View coverage HTML (if lcov installed): genhtml coverage/lcov.info -o coverage/html

Common Workflows

Adding a New Feature

  1. Define models in lib/models/
  2. Create repository for data access in lib/repositories/
  3. Create services for business logic in lib/services/
  4. Create provider for state management in lib/providers/
  5. Build UI components in lib/components/ and screens in lib/screens/
  6. Add mixins to NetworkDataProvider if needed for global data
  7. Write tests in test/
  8. Run flutter analyze to ensure no issues

Working with Assets

  1. Add assets to appropriate directory under assets/
  2. Declare in pubspec.yaml under flutter.assets
  3. Run flutter pub run build_runner build to regenerate lib/gen/assets.gen.dart
  4. Use generated constants: Assets.images.logo (example)

Working with Colors

  1. Edit assets/colors/colors.xml
  2. Run flutter pub run build_runner build to regenerate lib/gen/colors.gen.dart
  3. Use via AppColors.colorName or theme extensions

Working with Work Logs

Work logs are the core domain of the app. Key concepts:

  • DailyLog: Represents a day's work with activities, breaks, and metadata
  • Composite ID: Daily logs use composite IDs: {userId}_{YYYY-MM-DD}
  • State Management: WorkLogsStateManager manages UI state (loading, current log, week logs, status per day)
  • Business Logic: Coordinated by WorkLogsBusinessService
  • Caching: WorkLogsCacheManager handles local caching for offline support
  • Status Types: DayLogType enum defines log statuses (submitted, notSubmitted, off, scheduled, no_log, weekend)

Important Notes

Firebase Configuration

  • Firebase config in lib/firebase_options.dart is auto-generated by FlutterFire CLI
  • Update using: flutterfire configure
  • Platform-specific configs:
    • Android: android/app/google-services.json
    • iOS: ios/Runner/GoogleService-Info.plist

Code Generation

Files in lib/gen/ are auto-generated. Always regenerate after changes to:

  • assets/ directory
  • assets/colors/colors.xml
  • pubspec.yaml fonts or assets sections

Environment Variables

.env file contains:

  • EMULATOR_ACTIVE: Enable/disable Firebase emulator
  • EMULATOR_HOST: Emulator host IP
  • AUTH_PORT: Auth emulator port

Platform-Specific Changes

Any changes to android/ or ios/ directories should be explicitly documented in PRs as they may affect native configurations.

State Management Best Practices

  • Providers should call notifyListeners() after state changes
  • Use Consumer<T> or context.watch<T>() to listen to provider changes
  • Use context.read<T>() for one-time reads without listening
  • Dispose of streams and subscriptions properly in services

Git Workflow

  • Main branch: main
  • Feature branches: feature/<name>
  • Fix branches: fix/<name>
  • Commit format: <type>: <description> (e.g., feat: add clock out validation, fix: break calculation)
  • PRs require: passing flutter analyze, clear description, linked issues

Architecture

SmartCrew Mobile - Architecture

DOCUMENTATION

SmartCrew Mobile - Documentation

On this page

CLAUDE.mdProject OverviewDevelopment CommandsEssential CommandsBuild CommandsFirebase CommandsArchitecture & Code OrganizationHigh-Level Architecture PatternKey Architectural Components1. Providers (lib/providers/)2. Services (lib/services/)3. Repositories (lib/repositories/)4. Models (lib/models/)5. Screens (lib/screens/)6. Components (lib/components/)7. Generated Code (lib/gen/)Data Flow Example: Work LogsKey Design PatternsCoding StandardsStrict Analysis RulesNaming ConventionsLoggingFirebase IntegrationTestingTest StructureRunning TestsCommon WorkflowsAdding a New FeatureWorking with AssetsWorking with ColorsWorking with Work LogsImportant NotesFirebase ConfigurationCode GenerationEnvironment VariablesPlatform-Specific ChangesState Management Best PracticesGit Workflow