mobile-core-kit

Reusable, opinionated boilerplate for Flutter mobile apps with core services, networking, theming, and shared UI components.

Overview

This repo is meant to be cloned and customized as a starting point for production apps. It hosts the shared “mobile core” (networking, auth, theming, analytics, config, etc.) that you can reuse across multiple Flutter projects instead of re‑building the same foundations every time.

Firebase note: this repo includes demo Firebase configuration so the template runs out of the box. Replace it with your own Firebase project before shipping a real app (see docs/engineering/firebase_setup.md).

Status: entering stable phase. The foundation is ready for comfortable use in new mobile products and will continue to receive maintenance and improvements.

Recommended stack

Mobile Core Kit is designed to work with backend-core-kit. The two kits share the API, error, auth, session, and current-user contracts. Using both means you can start with the project foundation already in place and focus on your product features.

• Flavor-aware configuration (dev, staging, prod) via .env/*.yaml + BuildConfig.
• Network layer (Dio, interceptors, API helpers, connectivity checks, logging).
• Auth feature slice (email/password) wired end-to-end.
• DI with GetIt (core/di/service_locator.dart + feature modules).
• Theming, typography, spacing, and responsive utilities.
• Firebase (Core + Crashlytics + Analytics) wired to flavors.
• Analytics abstraction (IAnalyticsService + AnalyticsTracker) with GoRouter integration.

Prerequisites

• Flutter (managed via FVM) – see .fvmrc for the pinned SDK version (3.41.4).
• Dart SDK bundled with Flutter.
• Firebase CLI if you want to reconfigure Firebase (flutterfire configure).

Getting Started

First use as a template

Copy this repository for a new product, then bootstrap the repository-local CLI and run the identity wizard before editing application code:

dart pub global activate --source path packages/mobile_core_kit_cli
mobilekit init

For reproducible setup, provide the same values through a non-secret YAML file:

dart run mobile_core_kit_cli:mobilekit init \
  --config path/to/project-input.yaml --yes

init writes .mobilekit/project.yaml, updates the allowlisted application and platform surfaces, then runs dependency acquisition and available generation workflows. Missing local .env/*.yaml values, Firebase, signing, domains, CI secrets, and store metadata remain explicit follow-up work. Run the read-only report when setup is complete:

dart run mobile_core_kit_cli:mobilekit doctor

After that, connect the backend, replace product branding and external platform configuration, and start building your main features.

See docs/template/first_use_checklist.md for the short copy-and-customize workflow, and docs/template/networking_backend_contract.md for the backend-core-kit integration.

Day-to-day development

1. Install dependencies

   fvm flutter pub get

2. Generate build config from .env

   dart run mobile_core_kit_cli:mobilekit config generate --env dev

   or staging / prod as needed. This writes lib/core/foundation/config/build_config_values.dart.

3. Run code generation (Freezed + JSON)

   dart run build_runner build --delete-conflicting-outputs

4. Run the app (dev flavor)

   fvm flutter run -t lib/main_dev.dart --dart-define=ENV=dev

5. Analyze & format

   dart run mobile_core_kit_cli:mobilekit lint
   fvm dart format .

6. Tests

   fvm flutter test

Architecture linting (IDE + CI)

This repo uses custom_lint to enforce architecture import boundaries in both IDEs and CI:

• Rules config: lint/architecture_lints.yaml
• Run locally: dart run mobile_core_kit_cli:mobilekit lint (also included in dart run mobile_core_kit_cli:mobilekit verify --env dev)
• Guardrails index: docs/engineering/guardrails.md
• If lints don’t show in the IDE after flutter pub get, restart the Dart analysis server:
  • VS Code: Dart: Restart Analysis Server
  • Android Studio: Tools > Dart > Restart Dart Analysis Server

Verify (one command)

Run all checks (config generation + analyze + custom lint + tests + format check):

dart run mobile_core_kit_cli:mobilekit verify --env dev

See docs/engineering/guardrails.md for the full list of guardrails (lints + CLI verification workflows + scaffolding).

Project Structure

• lib/core/
  • design_system/ – tokens + adaptive widgets + shared UI components (UI-only).
  • presentation/ – shared UI helpers (localization, formatters, error copy).
  • foundation/ – pure utilities + compile-time config surfaces.
  • domain/ – cross-cutting pure contracts (session/user).
  • infra/ – networking/storage/database wrappers.
  • platform/ – plugin/vendor adapters (connectivity, app links, etc.).
  • runtime/ – app orchestration/services (startup/session/user context).
  • di/ – global service locator (service_locator.dart).
  • dev_tools/ – dev-only tooling.
• lib/features/
  • auth/ – core auth slice (data/domain/presentation, value objects).
  • Each future feature follows the same vertical slice layout.
• lib/navigation/ – GoRouter setup and route lists per feature.
• .env/ – YAML per environment (dev.yaml, staging.yaml, prod.yaml).
• packages/mobile_core_kit_cli/ – internal mobilekit CLI implementation.
• packages/mobile_core_kit_lints/ – custom analyzer lint implementation.
• duplication/ – reviewed duplication-policy allowlists.
• docs/engineering/ – core architecture and implementation guides.
• docs/template/ – template customization guides (what to change when cloning).
• docs/contracts/ – cross-team/backend contracts (API/auth semantics, error codes).
• docs/explainers/ – deep dives on “how it works” (feature internals, complex flows).

Docs index: docs/README.md.

Configuration & Flavors

• .env/<env>.yaml holds environment-specific values like API hosts, logging, and analytics flags.
• mobilekit config generate reads these files and generates lib/core/foundation/config/build_config_values.dart used by BuildConfig.
• Entry points:
  • lib/main_dev.dart
  • lib/main_staging.dart
  • lib/main_prod.dart

Each main file:

• Initializes AppConfig, registers DI via registerLocator(), and bootstraps async services after the first frame via bootstrapLocator().
• During bootstrapLocator(), initializes Firebase using DefaultFirebaseOptions from firebase_options.dart.
• Configures Crashlytics to collect only in production (best effort).

See docs/engineering/firebase_setup.md for full details, including how to point the template at a different Firebase project.

Analytics

• Core abstraction:
  • IAnalyticsService (lib/core/runtime/analytics/analytics_service.dart)
  • AnalyticsServiceImpl (analytics_service_impl.dart) backed by FirebaseAnalytics.
  • AnalyticsTracker (analytics_tracker.dart) – feature-facing facade (screen views, logins, button clicks, searches).
  • AnalyticsRouteObserver – GoRouter observer that auto-tracks screen views.
• Configured via BuildConfig.analyticsEnabledDefault and BuildConfig.analyticsDebugLoggingEnabled (derived from .env).
• Feature-level IDs live next to their feature, e.g.:
  • lib/features/auth/analytics/auth_analytics_screens.dart
  • lib/features/auth/analytics/auth_analytics_targets.dart

See docs/engineering/analytics_documentation.md for patterns and examples.

Documentation

For deeper details on the architecture and patterns used in this template:

• docs/engineering/architecture_linting.md
• docs/engineering/mobilekit_cli_reference.md
• docs/engineering/guardrails.md
• docs/engineering/ai_agent_workflow.md
• docs/engineering/project_architecture.md
• docs/engineering/model_entity_guide.md
• docs/engineering/ui_state_architecture.md
• docs/engineering/validation_architecture.md
• docs/engineering/validation_cookbook.md
• docs/engineering/value_objects_validation.md
• docs/engineering/firebase_setup.md

Template customization guides:

• docs/template/first_use_checklist.md
• docs/template/rename_rebrand.md
• docs/template/deep_linking.md

AGENTS.md contains repo-specific tooling notes (verification commands, architecture constraints, authoring preferences).

See docs/engineering/architecture_linting.md for details on rule semantics and how to extend them.