CrusaderArch

CrusaderArch is a micro-service architecture for building scalable Flutter applications that can be developed by multiple developers without turning the application into one tightly coupled codebase.

The idea is simple: split the Flutter application into independently versioned Dart/Flutter packages and plugins, give every service one clear responsibility, and connect them through explicit dependencies.

The repository contains a complete example implementation showing how the architecture is intended to be used.

I named the architecture CrusaderArch beacause i loved the original stronghold crusader game

Official documentation

Architecture

graph TD
    classDef foundation fill:#2d3748,stroke:#4a5568,color:#fff
    classDef shared fill:#2b6cb0,stroke:#3182ce,color:#fff
    classDef feature fill:#2f855a,stroke:#38a169,color:#fff
    classDef core fill:#d69e2e,stroke:#d69e2e,color:#fff
    classDef app fill:#c53030,stroke:#e53e3e,color:#fff

    subgraph Layer 5 - Feature Modules
        battles[example_battles]:::app
    end

    subgraph Layer 4 - Core Orchestration
        base[example_base]:::core
    end

    subgraph Layer 3 - Component & Navigation Layer
        router[example_router]:::feature
        widgets[example_widgets]:::feature
    end

    subgraph Layer 2 - Shared Layer
        shared[example_shared_dependencies]:::shared
    end

    subgraph Layer 1 - Core Foundation
        loc[example_localization]:::foundation
    end

    battles --> base
    battles --> router
    battles --> widgets
    battles --> shared
    battles --> loc

    base --> router
    base --> widgets
    base --> shared
    base --> loc

    widgets --> shared
    widgets --> loc

    router --> shared
    shared --> loc

Loading

The five layers

Layer	Name	Example	Type	Main responsibility
1	Core Foundation	example_localization	Flutter package	Localization only
2	Shared Layer	example_shared_dependencies	Flutter package	Shared dependencies, models, repositories, utilities
3	Component & Navigation	example_router, example_widgets	Flutter packages	Routes, widget contracts, reusable UI
4	Core Orchestration	example_base	Flutter plugin	Minimum runnable application and core flows
5	Feature Modules	example_battles	Flutter plugin	Product-specific features

Important rule

Each micro-service has its own Git repository and its own package version.

When changing a micro-service:

1. Update its CHANGELOG.md.
2. Bump its version in pubspec.yaml.
3. Publish the new version to the package repository.
4. Push the Git changes.
5. Update consumers to the new compatible version when required.

The example uses Cloudsmith as the private Dart package registry.

Package vs plugin

CrusaderArch deliberately separates services into Flutter packages and plugins.

Packages are used where the service should remain Dart/Flutter-only. Plugins are used when the service needs native platform integration. Flutter's package/plugin model follows this distinction: packages contain reusable Dart/Flutter code, while plugins can include platform-specific Android, iOS, web, desktop, or other implementations.

Project naming

The repository example is called example, so its services use the example_ prefix:

• example_localization
• example_shared_dependencies
• example_router
• example_widgets
• example_base
• example_battles

If your application is called x, the same convention becomes:

• x_localization
• x_shared_dependencies
• x_router
• x_widgets
• x_base
• x_<feature>

Where to go next

• GETTING_STARTED.md — build the architecture step by step.
• STORY.md — why CrusaderArch was created and the reasoning behind it.
• LAYER_1_CORE_FOUNDATION.md
• LAYER_2_SHARED.md
• LAYER_3_COMPONENT_NAVIGATION.md
• LAYER_4_CORE_ORCHESTRATION.md
• LAYER_5_FEATURE_MODULES.md

Example repository

The complete example is the main reference implementation. It is intentionally more than a minimal hello-world project: it demonstrates localization, shared infrastructure, navigation, reusable UI, authentication/account flows, application update handling, dependency initialization, generated code, and a native feature plugin.

CrusaderArch is an architectural approach, not a framework. You can replace individual libraries while preserving the boundaries and dependency direction.