Flutter Multi-Feature Starter Kit

A scalable Flutter starter kit for medium-to-large apps with:

• Feature-first structure
• Clean architecture boundaries
• Riverpod dependency injection and state management
• GoRouter app shell navigation
• Dio networking
• Drift local caching
• Demo auth and settings modules
• A complete reference feature for remote + local data flow

What This Starter Includes

This project is designed to be a strong baseline for product teams that want a clean, repeatable Flutter structure without starting from a single-screen demo app.

App Layer

• app/bootstrap.dart Handles app startup and environment loading.
• app/app.dart Builds the root MaterialApp.router.
• app/router/app_router.dart Defines top-level routes and shell navigation.
• app/shell/app_shell.dart Hosts the bottom navigation shell for multi-feature apps.

Core Layer

• core/config App config and environment parsing.
• core/errors Shared failure and result types.
• core/network Dio client creation and connectivity abstraction.
• core/theme Centralized app theming.

Features

• dashboard Product-style landing screen for the starter kit.
• auth Demo auth flow with repository contracts and use cases.
• posts Full reference feature with domain, repository contract, remote datasource, local datasource, cache, and UI.
• settings App-wide settings feature with theme preference handling.

Shared

• shared/widgets Reusable UI building blocks shared across features.

Architecture Style

Each feature follows a feature-first clean structure:

features/
  some_feature/
    data/
      datasources/
      models/
      repositories/
    domain/
      entities/
      repositories/
      usecases/
    presentation/
      providers/
      screens/
      widgets/

Rules:

• presentation talks to providers and use cases
• domain owns business entities and contracts
• data implements repositories and handles API/cache/db details
• core contains only app-wide shared infrastructure
• feature-specific code stays inside its own feature

Current Project Structure

lib/
  app/
    app.dart
    bootstrap.dart
    router/
      app_router.dart
    shell/
      app_shell.dart

  core/
    config/
    errors/
    network/
    providers/
    theme/

  features/
    auth/
      data/
      domain/
      presentation/
    dashboard/
      presentation/
    posts/
      data/
      domain/
      presentation/
    settings/
      data/
      domain/
      presentation/

  shared/
    widgets/

Reference Features

Posts

Use the posts feature as the main example when building new modules. It shows:

• repository contract in domain
• repository implementation in data
• use case orchestration
• remote API loading with Dio
• local cache with Drift
• connectivity-aware fallback logic
• UI feedback for live vs cached data

Auth

The auth feature is currently demo-backed with an in-memory repository, but the structure is ready for:

• API auth
• token persistence
• secure storage
• session refresh
• role-based routing

Settings

The settings feature is the place for app-level preferences such as:

• theme mode
• language
• onboarding flags
• notification preferences
• remote config toggles

Navigation

The starter currently includes:

• Dashboard
• Posts
• Settings
• Account

Dashboard, Posts, and Settings live inside the shell navigation. Account is routed separately.

Environment Setup

This project expects a .env file with:

BASE_URL=https://your-api-base-url.com

BASE_URL is required for the Dio client.

Getting Started

1. Install dependencies

flutter pub get

2. Generate code when needed

This starter uses Drift code generation.

dart run build_runner build

3. Run the app

flutter run

Quality Checks

Run these before pushing changes:

flutter analyze
flutter test

How To Add A New Feature

When adding a new feature like orders, notifications, or reports:

1. Create data, domain, and presentation folders inside lib/features/<feature_name>/.
2. Add domain entities, repository contracts, and use cases first.
3. Implement repositories and datasources in data/.
4. Add Riverpod providers in presentation/providers/.
5. Add screens/widgets in presentation/.
6. Register the feature in app/router/app_router.dart if it needs navigation.

Recommended Next Steps

If you want to grow this starter further, good next upgrades are:

1. Add persistent auth with secure storage.
2. Add API interceptors for auth tokens and retry handling.
3. Add flavors for dev, staging, and prod.
4. Add localization support.
5. Split large apps into packages/ when multiple teams/features grow independently.

Who This Starter Is For

This starter is a good fit for:

• startup apps that want clean foundations
• product teams building multiple modules
• internal enterprise apps
• Flutter apps that need both API and local cache support

It is intentionally not overengineered into full multi-package modularization yet, so teams can move quickly first and split later when the app grows.