Skip to content

README.md

Latest commit

 

History

History
180 lines (122 loc) · 5.2 KB

README.md

File metadata and controls

180 lines (122 loc) · 5.2 KB

API Documentation

Complete API reference for the Flutter Starter project.

Overview

This documentation provides comprehensive reference for all public APIs in the Flutter Starter project, organized by architectural layer and component type.

Documentation Structure

Core APIs

  • Errors - Exception and Failure types for error handling
  • Network - HTTP client, GraphQL template, and interceptors
  • Storage - Storage services and Offline Database template
  • Logging - Logging service and Crashlytics template
  • Utils - Utility classes (Result, JsonHelper, DateFormatter, Validators)

Feature APIs

Examples

Quick Start

For New Developers

  1. Start with Common Patterns to understand basic usage
  2. Review API Integration for integration patterns
  3. Refer to specific API documentation as needed

For Adding New Features

  1. Follow the guide in Adding Features
  2. Reference existing feature APIs (e.g., Auth) as examples
  3. Use Common Patterns for best practices

For API Reference

  1. Navigate to the appropriate section:
    • Core APIs for infrastructure components
    • Feature APIs for domain-specific APIs
  2. Find the specific class or method you need
  3. Review the examples and usage patterns

Key Concepts

Result Pattern

All repository and use case methods return Result<T> for type-safe error handling:

final result = await loginUseCase('user@example.com', 'password');
result.when(
  success: (user) => handleSuccess(user),
  failureCallback: (failure) => handleFailure(failure),
);

See Utils - Result for details.

Dependency Injection

All dependencies are provided via Riverpod providers:

// Access in widgets
final useCase = ref.read(loginUseCaseProvider);

// Access in providers
final repository = ref.watch(authRepositoryProvider);

See Auth - Providers for details.

Error Handling

Errors are represented as typed Failure objects wrapped in ResultFailure:

result.when(
  success: (data) => ...,
  failureCallback: (failure) {
    if (failure is AuthFailure) {
      // Handle auth error
    } else if (failure is NetworkFailure) {
      // Handle network error
    }
  },
);

See Errors for details.

Core vs Optional APIs

Core APIs (hard-fixed in starter)

  • Network foundation with Dio ApiClient and interceptors.
  • Routing and dependency injection through Riverpod providers.
  • Core storage (StorageService, SecureStorageService) used by auth/session flow.

Optional APIs (pluggable)

  • Remote feature flags provider implementations (Firebase or custom provider override).
  • RASP provider implementations (FreeRASP or custom/no-op).
  • Crashlytics output template for logging.
  • GraphQL template client.
  • ILocalDatabase implementations (e.g. Isar template).

Architecture Layers

Domain Layer

Business logic and entities, independent of external frameworks.

Key Components:

  • Repository interfaces
  • Use cases
  • Entities

Location: lib/features/*/domain/

Data Layer

Data sources and repository implementations.

Key Components:

  • Remote data sources
  • Local data sources
  • Repository implementations
  • Models

Location: lib/features/*/data/

Core Layer

Infrastructure components used across the application.

Key Components:

  • Network (ApiClient, Interceptors)
  • Storage (StorageService, SecureStorageService)
  • Configuration (AppConfig, EnvConfig)
  • Utilities (Result, JsonHelper, Validators, DateFormatter)
  • Error Handling (Failures, Exceptions)

Location: lib/core/

Shared Layer

Reusable components used across features.

Key Components:

  • Extensions (Context, String, DateTime)

Location: lib/shared/

Related Documentation

Contributing

When adding new APIs:

  1. Add comprehensive DartDoc comments to all public classes and methods
  2. Include usage examples in documentation
  3. Update this documentation if adding new layers or major components
  4. Follow existing patterns and conventions