zuraffa 3.20.0

AI first Flutter Clean Architecture Framework and CLI with Result types, UseCase patterns, Dependency Injection and MCP server for building type-safe, scalable apps with AI agents.

🦒 Zuraffa

The AI-First Clean Architecture Framework for Flutter.

Zuraffa is a comprehensive toolkit designed to streamline Flutter development by enforcing Clean Architecture principles, ensuring type safety, and integrating seamlessly with modern AI coding assistants via MCP.

---

🦄 Why Zuraffa?

• 🤖 AI-Native (MCP): The first Flutter framework with a built-in Model Context Protocol server. AI agents (Trae, Cursor, Windsurf) can understand, generate, and refactor your code with 100% precision.
• 🏗️ Clean Architecture by Default: Strict separation of Domain, Data, and Presentation layers. No more spaghetti code.
• 🛡️ Type-Safe Everything: Uses Result<T, AppFailure> for error handling. Stop catching exceptions; start matching results.
• ⚡ Zero Boilerplate: The zfa CLI handles the heavy lifting—UseCases, Repositories, VPCs (View-Presenter-Controller), and Tests are generated in seconds.
• 🧩 Smart Caching & Sync: Built-in patterns for offline-first apps with configurable cache policies and automatic sync.
• 🧪 Mock-Ready: Instant mock data generation for rapid prototyping without a backend.

---

🤖 The AI Advantage (MCP)

Zuraffa exposes your project structure to AI agents through its MCP Server. This allows AI to:

• Contextual Generation: "Add a 'PlaceOrder' usecase to the existing 'Cart' domain."
• Smart Refactoring: "Rename this entity field and update all related layers."
• Automated Diagnostics: AI can run zfa doctor and fix architectural violations automatically.

To enable, just install Zuraffa. Compatible IDEs will detect the server automatically.

---

📦 Installation

Add Zuraffa to your pubspec.yaml:

dependencies:
  zuraffa: ^3.19.0

dev_dependencies:
  zuraffa: ^3.19.0
  build_runner: ^2.4.0
  zorphy_annotation: ^1.6.0 # Required for supercharged entities

Activate the CLI globally:

dart pub global activate zuraffa

---

⚡ Quick Start

1. Initialize

zfa init

2. Define an Entity

Zuraffa uses Zorphy for immutable, type-safe entities.

zfa entity create -n Product --field name:String --field price:double --field stock:int

3. Generate a Feature

Generate the full stack (Domain, Data, Presentation, Tests) in one go:

# Using Repository/DataSource (Default)
zfa feature scaffold Product --methods=get,getList,create --mock --vpcs --state --test

# Using Service/Provider (Alternative)
zfa feature scaffold Product --methods=get,getList --use-service --mock --vpcs --state --test

4. Granular Control (Make)

Need just a specific part? Use zfa make:

zfa make Search usecase --domain=search --params=SearchRequest --returns=Listing

5. Build

zfa build

---

🛠️ CLI Power Commands

Command	Description
zfa feature	High-level command to generate full feature slices.
zfa make	Low-level command for granular generation (UseCases, Mocks, DI, etc.).
zfa entity	Create and manage Zorphy entities with field validation.
zfa doctor	Lints your architecture and suggests fixes.
zfa build	Optimized wrapper for build_runner.

---

🔄 Revert & Negation

Smart Revert

Accidentally added a method or plugin? Use --revert to undo the change. Zuraffa's AST-aware reverter will remove only the specific code added, preserving your manual changes.

zfa make Product usecase --methods=watch --revert

Negatable Flags

Every boolean flag has a --no- counterpart to explicitly disable features.

zfa feature Product --data --no-zorphy # Generate data layer but skip Zorphy

---

📂 Project Layout

lib/src/
├── data/           # Models, DataSources, Repository Impls
├── domain/         # Entities, Repository Interfaces, UseCases
├── presentation/   # VPC (View, Presenter, Controller, State)
└── di/             # Automated Dependency Injection (GetIt)

---

🌐 Learn More

• Documentation: zuraffa.dev
• Example Project: Github Example
• Discord/Community: Join us!

Made with 🦒 and ⚡️ by Arrrrny.