https://github.com/arrrrny/zuraffa
🦒 Zuraffa AI first Flutter Clean Architecture Framework and CLI
https://github.com/arrrrny/zuraffa
clean-architecture cli code-generator flutter
Last synced: 3 months ago
JSON representation
🦒 Zuraffa AI first Flutter Clean Architecture Framework and CLI
- Host: GitHub
- URL: https://github.com/arrrrny/zuraffa
- Owner: arrrrny
- License: mit
- Created: 2026-01-23T16:04:40.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-04-05T19:23:33.000Z (3 months ago)
- Last Synced: 2026-04-05T19:23:47.940Z (3 months ago)
- Topics: clean-architecture, cli, code-generator, flutter
- Language: Dart
- Homepage: https://zuraffa.com
- Size: 7.05 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🦒 Zuraffa
[](https://pub.dev/packages/zuraffa)
[](https://opensource.org/licenses/MIT)
[](https://arrrrny.github.io/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` 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`:
```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:
```bash
dart pub global activate zuraffa
```
---
## ⚡ Quick Start
### 1. Initialize
```bash
zfa init
```
### 2. Define an Entity
Zuraffa uses **Zorphy** for immutable, type-safe entities.
```bash
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:
```bash
# 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`:
```bash
zfa make Search usecase --domain=search --params=SearchRequest --returns=Listing
```
### 5. Build
```bash
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.
```bash
zfa make Product usecase --methods=watch --revert
```
### Negatable Flags
Every boolean flag has a `--no-` counterpart to explicitly disable features.
```bash
zfa feature Product --data --no-zorphy # Generate data layer but skip Zorphy
```
---
## 📂 Project Layout
```text
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](https://arrrrny.github.io/zuraffa/)
* **Example Project**: [Github Example](https://github.com/arrrrny/zuraffa/tree/master/example)
* **Discord/Community**: [Join us!](https://github.com/arrrrny/zuraffa/issues)
Made with 🦒 and ⚡️ by [Arrrrny](https://github.com/arrrrny).