🦒 zuraffa_flutter #

The Flutter UI layer of the AI-first Clean Architecture framework for Flutter.

zuraffa_flutter is the Flutter UI layer for Zuraffa — views, controllers, presenters, shells, xray, and state widgets, generated from the same entity-first architecture as the core package. It re-exports the entire pure-Dart core (zuraffa), so depending on zuraffa_flutter gives you the full framework through a single import. It is published in lockstep with the core: every zuraffa_flutter release shares the core's version number.

Zuraffa v6 standardizes code generation around one canonical workflow:

1. zfa entity create
2. zfa make
3. zfa build

zfa make is the primary generation surface. zfa feature still exists, but only as a wrapper over the normalized feature preset.

Sponsor #

[https://zuzu.dev]

Thanks to ZikZak AI for sponsoring this project!

ZikZak AI is an AI-Powered Price Comparison app that you scan barcodes, and discover amazing savings instantly. Your personal shopping assistant that never sleeps.

[assets/app-store-badge.png] [assets/google-play-badge.png]

Why zuraffa_flutter? #

• One import, full framework: zuraffa_flutter re-exports the pure-Dart core (zuraffa) plus the Flutter UI layer (Controller, Presenter, View, Shells, XRay, state widgets). You depend on one package, not two.
• Flutter-first UI: controllers, presenters, responsive/adaptive views, application shells, and an XRay debugging overlay built specifically for Flutter.
• Generated, not hand-written: the same zfa codegen that builds your core architecture also emits the Flutter UI layer that this package wraps.
• Lockstep with core: published at the same version as zuraffa, so the UI layer always matches the core it wraps.
• Inherited framework guarantees: Zorphy-first entities, immutable typed entities, and Result<T, AppFailure>-based failures come straight from the core.

Installation #

Add zuraffa_flutter to your Flutter app's pubspec.yaml:

dependencies:
  zuraffa_flutter: ^6.1.0

That's it — zuraffa_flutter re-exports zuraffa (the pure-Dart core), so you do not need to list zuraffa separately. A single import gives you the full framework, core types and Flutter UI together:

import 'package:zuraffa_flutter/zuraffa_flutter.dart';

The code-generation CLI (zfa) lives in the core zuraffa package. Activate it globally to put zfa on your PATH:

dart pub global activate zuraffa

For code generation in your app, add the core dev dependencies as described in the zuraffa README:

dev_dependencies:
  zuraffa: ^6.1.0
  zorphy_annotation: ^1.7.0
  build_runner: ^2.4.0

Quick Start: the canonical v6 flow #

The zfa workflow below is the shared core-zuraffa codegen that produces both the core architecture and the Flutter UI layer that zuraffa_flutter wraps.

1. Create an entity #

Entities are always generated under lib/src/domain/entities in v6.

zfa entity create -n Product \
  --field id:String \
  --field name:String \
  --field price:double \
  --field description:String?

2. Generate architecture with make #

Use zfa make as the default way to build the architecture around that entity.

zfa make Product \
  --preset=crud \
  --methods=get,getList,create,update,delete \
  --with=vpc \
  --state \
  --di \
  --test

That expands to a normalized plan that generates the domain, data, presentation, and test layers for Product — the presentation layer is what zuraffa_flutter provides the types for.

3. Run the build step #

zfa build

Use zfa build instead of calling build_runner directly in docs and agent workflows.

Core v6 commands #

These commands are provided by the core zuraffa CLI.

Fixed project layout #

Zuraffa v6 assumes a fixed architecture root:

lib/src/
├── data/
├── di/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── usecases/
└── presentation/

Entity files must live at:

lib/src/domain/entities/{entity_snake}/{entity_snake}.dart

Example:

lib/src/domain/entities/product/product.dart

.zfa.json defaults and .zfa/ project memory #

Zuraffa v6 separates project defaults from project memory:

• .zfa.json: active project configuration such as plugin defaults and entity-first rules.
• .zfa/: the canonical v6 project-memory model for plans, runs, decisions, blueprints, manifests, and future agent context.

A useful mental model for humans and AI agents is:

.zfa.json      -> what this project prefers by default
.zfa/          -> what has been planned, generated, and decided over time

Canonical .zfa/ layout #

.zfa/
├── plans/
├── runs/
├── blueprints/
├── decisions/
├── manifests/
└── context.json

During the v6 migration, some internal surfaces may still reference older storage paths. Treat the structure above as the public documentation contract going forward.

make first, feature second #

If you see both commands in the codebase, prefer this rule:

• Use zfa make when you want explicit control.
• Use zfa feature scaffold only when you intentionally want the feature preset wrapper.

Equivalent example:

zfa make Product --preset=feature --plan

zfa feature scaffold Product --plan

AI-agent contract #

For Zuraffa v6 projects:

• Generate architecture code with zfa, not by hand.
• Create entities with zfa entity create.
• Generate layers with zfa make.
• Run zfa build after generation.
• Handcraft only manual UI composition/layout zones and normal business implementation details that generation does not own.

The pipeline rule #

If an AI agent is asked to build a feature, it should always start by asking:

1. Does a new entity need to exist? → use zfa entity create
2. Does the architecture skeleton need to exist or change? → use zfa make
3. Do generated annotations/build outputs need to be finalized? → use zfa build

Zuraffa owns the architecture skeleton. Human or agent implementation work should narrow to the remaining business logic, datasource implementation, styling, and manual UI composition after that pipeline runs.

Migration notes #

If you are coming from pre-v6 guidance:

• the old one-shot generator command is gone,
• zfa make is now the canonical generator,
• zfa feature is a wrapper, not the primary public workflow,
• the domain root is fixed to lib/src/domain, and
• v6 public docs assume Zorphy-based entities.

See doc/MIGRATION_GUIDE.md (in the core zuraffa package) for a focused migration walkthrough.

Mock data & prototyping (v6.1.0) #

# Generate Dart mock data
zfa mock Product

# Generate JSON mock data with fromJson-based helpers
zfa mock json Product

JSON mocks produce standalone JSON files under data/mock_json/{domain}/ and Dart helpers that load them via fromJson. Swap JSON content for instant prototyping without code changes or regeneration.

final products = await ProductMockJson.loadProducts();
final sample = await ProductMockJson.loadSampleProduct();

See website/docs/features/mock-data.md for details.

Learn more #

• zuraffa_flutter on pub.flutter-io.cn
• Core zuraffa README
• CLI_GUIDE.md (core zuraffa)
• AGENTS.md
• SKILL.md
• zuraffa docs

Made with 🦒 and ⚡ by the Zuraffa project.