Archipelago

About Archipelago

Archipelago is a sophisticated Flutter starter kit designed for scalable applications using a monorepo architecture. Like its namesake — a chain of islands connected by water — Archipelago connects multiple Flutter packages and modules into a cohesive, maintainable ecosystem.

Key Features

Monorepo Structure

• Mason-powered Templates: Standardized package generation for consistency across your project
• Melos Workflow: Streamlined management of multiple packages with efficient versioning and publishing
• Smart Dependencies: Optimized internal package dependencies with proper versioning

Pre-configured Packages

• Core Module: Essential utilities, helpers, and shared functionality
• UI Kit: Ready-to-use custom widgets and design system
• Navigation: Pre-configured routing system with deep linking support
• Network SDK: HTTP client setup with interceptors and error handling
• Auth SDK: Authentication flow with multiple provider support
• Monitoring SDK: Logging, crash reporting, and analytics (with noop swap for release)
• State Management: Scalable BLoC-based state management

Developer Experience

• Code Generation: Automated code generation for models, APIs, and more
• Testing Setup: Pre-configured unit, widget, and integration testing
• CI/CD Templates: Ready-to-use GitHub Actions and Fastlane workflows
• Monorepo Toolkit: Affected package detection, test coverage pipeline, dependency graph enforcement
• AI Agent Support: Generated projects include configuration for AI coding assistants
• Hot Reload Support: Optimized for Flutter's hot reload across all packages
• Linting Rules: Consistent code style enforcement across packages

Getting Started

# Install archipelago globally
dart pub global activate archipelago_cli

# Check system requirements
archipelago doctor

# Create a new project
archipelago create

# Enable shell completion
archipelago completion install

Next, you can run the app using the pre-configured launch configs for VS Code or Android Studio.

Architecture

Archipelago follows a modular architecture pattern:

your_project/
├── app/                   # Application projects
│   ├── mobile/            # Main mobile application
│   └── widgetbook/        # UI component showcase
├── core/                  # Core utilities and helpers
├── features/              # Feature packages
│   ├── feature_*/         # Self-contained feature modules
├── packages/              # Shared packages
│   ├── ui_kit/            # Shared UI components & design system
│   ├── auth_sdk/          # Authentication SDK
│   ├── network_sdk/       # Network/HTTP SDK
│   └── monitoring_sdk/    # Monitoring & analytics SDK
├── devtools/              # Monorepo toolkit scripts
│   ├── affected/          # Changed package detection
│   ├── coverage/          # Test coverage pipeline
│   └── build_prepare/     # Build-time dependency swap
├── shared/                # Shared configuration
│   ├── config/            # Environment & flavor config
│   ├── dependencies/      # Shared BLoC dependencies
│   └── l10n/              # Localization
└── melos.yaml             # Monorepo configuration

Commands

Project

Command	Flags	Description
archipelago create	--config, --output, --provision-firebase, --provision-supabase	Create a new Archipelago project from scratch
archipelago generate (alias: gen)	--config, --output	Generate a brick into an existing project
archipelago doctor (alias: dr)	--verbose, --brick, --fix	Check system health, dependencies, and brick compatibility
archipelago update		Update the Archipelago CLI to the latest version

Cloud provisioning flags (archipelago create)

Flag	Description
--provision-firebase	After generation, verifies the Firebase CLI is installed, prints the exact commands needed to set up Firebase for your project, and writes a provision-firebase.sh script (.cmd on Windows) to the project directory.
--provision-supabase	Same as above but for Supabase — prints setup steps and writes provision-supabase.sh.

These flags are opt-in and purely informational. The CLI never runs firebase init, supabase init, or any cloud auth flow automatically — those require interactive user authentication and are left to you.

Example:

archipelago create --provision-firebase --provision-supabase --output ./my_app

After generation you will see something like:

Firebase Provisioning

  ✓ Firebase CLI detected (13.0.0)

  Next steps to provision Firebase:
    1. cd ./my_app/my_app
    2. firebase login
    3. firebase init --project <project-id>
    4. dart pub global run flutterfire_cli:flutterfire configure --project <your-project-id>

  → Provision script written to ./my_app/my_app/provision-firebase.sh

If the CLI is not installed you receive install instructions instead and can re-run the flag once it is.

Cloud CLI checks (archipelago doctor)

archipelago doctor now includes an optional Cloud CLIs section at the bottom of its output:

Cloud CLIs (optional — required for --provision-*)

  ✓ firebase  13.0.0
  ! gcloud    not installed (https://cloud.google.com/sdk/docs/install)
  ✓ supabase  1.131.7

These checks are never fatal. Missing cloud CLIs do not affect the doctor exit code — they are shown only as informational warnings so you know what to install before using --provision-*.

Authentication

Command	Flags	Description
archipelago auth login	--token, --interactive	Authenticate with your Archipelago account
archipelago auth logout		Sign out and clear stored credentials
archipelago auth status		Show current authentication and subscription status
archipelago auth activate	--promo	Activate a subscription or promo code
archipelago auth rotate-key		Rotate your device-bound API key

Brick Management

Command	Flags	Description
archipelago brick list (alias: ls)		List all available bricks for your subscription tier
archipelago brick download	--all	Download a specific brick or all bricks
archipelago brick update		Update cached bricks to the latest versions
archipelago brick info		Show detailed information about a specific brick

Utilities

Command	Description
archipelago --version	Show current version
archipelago completion install	Install shell completion

Use Cases

Archipelago is perfect for:

• Enterprise applications requiring scalable architecture
• Startups planning to scale their applications
• Teams working on multiple related Flutter projects
• Projects requiring consistent development patterns
• Applications with multiple flavors or white-label solutions

Philosophy

Archipelago embraces these core principles:

• Modularity: Independent yet connected packages, like islands in an archipelago
• Scalability: From small apps to enterprise solutions
• Maintainability: Clear structure and patterns
• Developer Experience: Efficient workflows and tools
• Best Practices: Industry-standard Flutter patterns

Documentation

• Getting Started
• Architecture Guide
• Brick Catalog
• Tutorials

License

Archipelago is available under the MIT License. See the LICENSE file for more info.

Support

• Documentation
• Discord Community
• Issue Tracker

---