Archipelago

About Archipelago

Archipelago is a CLI toolkit that generates production-ready Flutter apps from a modular monorepo template. Like its namesake — a chain of islands connected by water — each feature is a self-contained island, connected by shared infrastructure.

You generate a full workspace once with archipelago create, then drop in features and capabilities on demand with archipelago generate <brick>. Every brick is a Mason template validated against a living reference app.

Getting Started

# Install the CLI globally
dart pub global activate archipelago_cli

# Check system requirements
archipelago doctor

# Authenticate (required to generate)
archipelago auth login

# Scaffold a new project
archipelago create --output ./my_app

Then bootstrap the workspace:

cd my_app
dart pub get
melos bootstrap

Core Workflow

1. Create a project

archipelago create scaffolds the whole modular monorepo (it is a shortcut for archipelago generate flutter_modular_monorepo). Run it interactively and the CLI opens an ephemeral config file for you to fill in (app name, organization, state management, network library, vendors, etc.), or pass a pre-filled config for CI.

# Interactive — edit the generated config, save, continue
archipelago create --output ./my_app

# CI / non-interactive
archipelago create --config ci_config.json --output ./my_app

Flag	Description
--config, -c	Path to a pre-filled config JSON file (CI mode — skips the interactive prompt).
--output, -o	Output directory. Defaults to ..
--provision-firebase	After generation, print Firebase setup steps and write a provision-firebase.sh script (.cmd on Windows).
--provision-supabase	After generation, print Supabase setup steps and write a provision-supabase.sh script.

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

2. Generate features into an existing project

archipelago generate <brick> (alias gen) adds a feature or capability into an already-generated project. The brick's post-generation hooks wire it into the workspace, the app DI graph, and pubspec.yaml for you.

# Add features
archipelago generate auth_sdk
archipelago generate home_sdk
archipelago generate paywall_sdk
archipelago generate webview_sdk

# CI / non-interactive
archipelago gen auth_sdk --config auth_config.json

Flag	Description
--config, -c	Path to a pre-filled config JSON file (CI mode).
--output, -o	Output directory (project root). Defaults to ..
--local-bricks	Path to a local Archipelago repo. Bypasses the R2 download and loads the brick from bricks/<slug>/ or bundles/<slug>.bundle.

Run archipelago brick list to see every brick available for your subscription tier.

Brick Source

By default, bricks are fetched from Archipelago's Cloudflare R2 catalog. Two persistent overrides are available via archipelago config set:

# Default: download bricks from the hosted R2 catalog
archipelago config set source r2

# Enterprise: resolve bricks from your own git fork
archipelago config set source git
archipelago config set repo https://github.com/your-org/archipelago-fork.git

# Inspect the resolved configuration
archipelago config show

When source is git, every create/generate clones (and caches) the configured repo and stages bricks from bricks/<slug>/ instead of R2 — so Enterprise users can customize brick source while keeping the same workflow.

For a one-off override without changing the persistent config, pass --local-bricks <repo> to generate:

archipelago generate auth_sdk --local-bricks ../archipelago

Featured Bricks

Authentication & onboarding

• auth_sdk — login/register flow with event-driven listeners and scoped DI.
• social_auth_sdk, biometric_auth_sdk — social and biometric sign-in.
• introduction_sdk — onboarding/intro carousel.

Monetization

• paywall_sdk — pricing UI, mock purchase flow, subscription management.
• rating_review_sdk — in-app rating prompts.

WebView & mini-apps

Archipelago splits WebView into two bricks:

Brick	Tier	Capabilities
webview_sdk	Free	Basic WebView: URL loading, navigation controls, progress tracking, one-way JS calls, and URI-scheme interception. No JS bridge.
webview_sdk_advanced	Pro	Everything in webview_sdk plus a bidirectional JS bridge (typed handlers + Promises), request/response interceptors for auth-header injection, deeplink routing back to native, and a full mini-app container — a manifest registry, bridge dispatcher, lifecycle state machine, and capability handlers, config-driven via assets/config/mini_apps.yaml.

archipelago generate webview_sdk           # free, basic
archipelago generate webview_sdk_advanced  # Pro: JS bridge + mini-app container

The mini-app container ships inside webview_sdk_advanced — there is no longer a standalone mini-app brick. webview_sdk_advanced requires webview_sdk to be installed first.

AI

• ai_chat_sdk — Pro streaming chat UI with multi-provider support (OpenAI, Anthropic).

Infrastructure & capabilities

network_sdk, websocket_sdk, monitoring_sdk, analytics_sdk, feature_flag_sdk, connectivity_sdk, push_notification_sdk, feedback_sdk, permission_guard, launch_tracker_sdk, shorebird_sdk, and more.

Monorepo Toolkit (devtools/)

Every generated project ships a free monorepo toolkit at devtools/, exposed through a monorepo_toolkit CLI. The most-used commands for day-to-day flavored development:

# From the project root, via the devtools toolkit:
dart run monorepo_toolkit <command>

Command	Description
build-prepare <debug|release>	Swap debug/release dependencies (e.g. monitoring_impl → monitoring_noop) at the pubspec.yaml level before a build, then restore.
env switch <flavor>	Switch the active environment (.env := .env.<flavor>) for the selected flavor. Also: env init, env add <KEY>, env sync.
flavor	Manage flavors defined in flavors.yaml (flavor list, flavor add, flavor sync, flavor generate).
run	Interactive runner — pick an app, flavor, and device, then launch flutter run with the right --flavor and entry point. Pass --app, --flavor, --device to skip the prompts in CI.

The toolkit also bundles affected change detection, coverage, graph (dependency-graph enforcement), deps, app/workspace scaffolding, and asset/size tooling.

All Commands

Project

Command	Flags	Description
archipelago create	--config, --output, --provision-firebase, --provision-supabase	Scaffold a new modular-monorepo project.
archipelago generate (alias gen)	--config, --output, --local-bricks	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 (via pub).

Authentication

Archipelago uses device-bound API tokens — your token is pinned to the device that logged in.

Command	Flags	Description
archipelago auth login	--token, --interactive	Authenticate with your API token (or open the browser to fetch one).
archipelago auth logout		Sign out and clear stored credentials.
archipelago auth status		Show current authentication and subscription status.
archipelago auth activate	--promo	Activate a free trial with a promo code.
archipelago auth rotate-key		Rotate your device-bound API key.

archipelago auth login --token <your-api-token>
archipelago auth activate --promo LAUNCH2026

Configuration

Command	Description
archipelago config show	Print the resolved CLI configuration (source, repo, telemetry).
archipelago config set <key> <value>	Set source (r2/git) or repo (enterprise fork URL).
archipelago config telemetry	--enable, --disable, --status — manage anonymous usage telemetry.

archipelago config telemetry --disable
archipelago config show

Brick management

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

Utilities

Command	Description
archipelago --version	Show the current CLI version.
archipelago completion install	Install shell completion.

Cloud CLI checks (archipelago doctor)

archipelago doctor includes an optional Cloud CLIs section. These checks (Firebase, gcloud, Supabase) are never fatal — they are informational so you know what to install before using the --provision-* flags.

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

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

Generated Project Includes

• Dual-GetIt DI — global scope for SDKs/infrastructure, local scope per feature.
• FeatureSDK + Registry — features self-register and contribute routes before the router is built.
• Two-phase init — blocking pre-launch (DI, routes) + non-blocking post-launch (analytics, flags).
• build_prepare — swap debug/release dependencies to strip debug-only code from release builds.
• Fastlane — iOS + Android build/deploy lanes.
• CI/CD — GitHub Actions or GitLab CI workflows.
• AI agent support — generated CLAUDE.md / AGENTS.md so AI coding assistants understand the architecture.

Philosophy

• Modularity: independent yet connected packages, like islands in an archipelago.
• Scalability: from small apps to enterprise solutions.
• Maintainability: clear structure and consistent patterns.
• Developer Experience: efficient workflows and tooling.

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

---