appiq-solution/README.md

APPIQ SOLUTION: Flutter Mobile Development Extension for BMAD Method

# 📱 APPIQ SOLUTION: Flutter Mobile Development Extension

[![Version](https://img.shields.io/npm/v/appiq-solution?color=blue&label=version)](https://www.npmjs.com/package/appiq-solution)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)

**A specialized extension of the BMAD Method for Flutter Mobile App Development**

APPIQ SOLUTION extends the proven BMAD Method with first-class Flutter support featuring Clean Architecture, Cubit patterns, BLoC state management, dependency injection, and modern Mobile Development Best Practices.

## 🚀 Quick Start

**Simple and fast:**

```bash
npx appiq-solution
```

The Smart Installer configures:

✅ **Multi-IDE Support**: Cursor, Claude Code, Windsurf, VS Code + Cline, and more  
✅ **Auto-detect Tech Stack**: Flutter, React, Vue, Next.js, Angular, Fullstack, API-only  
✅ **Smart MCP Integration**: Agents know which MCP servers they can use (no auto-config)  
✅ **Planning Workflow**: Project idea → Plan generation → Approval → Development  
✅ **Full BMAD Flow**: Document sharding, Agent orchestration, Development cycle  
✅ **🎯 Advanced Flutter Support**: Dart MCP Server integration, Clean Architecture, Cubit patterns, BLoC state management, dependency injection with GetIt, proper testing strategies  
✅ **Modern Web**: shadcn/ui, v0.dev, Tailwind CSS integration  
✅ **Security First**: No API Keys stored or auto-configured

## What is BMAD Method?

APPIQ SOLUTION is built on the **BMAD Method** - a proven AI-driven development framework that uses specialized AI agents to handle the complete software development lifecycle.

**BMAD Method's Two Key Innovations:**

**1. Agentic Planning:** Dedicated agents (Analyst, PM, Architect) collaborate with you to create detailed, consistent PRDs and Architecture documents. Through advanced prompt engineering and human-in-the-loop refinement, these planning agents produce comprehensive specifications that go far beyond generic AI task generation.

**2. Context-Engineered Development:** The Scrum Master agent then transforms these detailed plans into hyper-detailed development stories that contain everything the Dev agent needs - full context, implementation details, and architectural guidance embedded directly in story files.

This two-phase approach eliminates both **planning inconsistency** and **context loss** - the biggest problems in AI-assisted development.

## 🎯 Available MCP Servers

Your agents know these MCP servers (you configure them manually in your IDE):

🧠 **Sequential Thinking**: Complex problem solving  
🌐 **Puppeteer**: Browser automation and testing  
🔗 **Claude Continuity**: Enhanced thread continuity  
💾 **Extended Memory**: Enhanced AI memory capabilities  
✨ **21st.dev Magic**: UI builder like v0 in your IDE  
📱 **Dart MCP**: Flutter/Dart development (auto-detected for Flutter projects)  
🔥 **Firebase**: Auth, Firestore, Functions integration  
⚡ **Supabase**: Database, auth, storage  
📚 **Context7**: Up-to-date library documentation  
💳 **Stripe**: Payment integration

## 📱 Flutter Features

🏗️ **Clean Architecture**: Domain-driven Design, clean layer separation  
🔄 **State Management**: Cubit patterns, BLoC integration  
🛠️ **Best Practices**: GetIt dependency injection, null safety  
🎨 **Material 3**: Modern UI components, theming  
🧪 **Testing**: Unit, Widget, and Integration tests  
📦 **Package Management**: Curated package recommendations

## 🎯 Step-by-Step Guide for Your Brownfield Flutter Project

### 1. Install BMAD Method in Your Existing Project

```bash
npx appiq-solution
```

**Important selections during installation:**
- Choose the `appiq-flutter-mobile-dev` Expansion Pack
- Provide the path to your existing Architecture MD file
- The system will install Flutter agents in `.bmad-core/`

### 2. Analyze Existing Architecture

Since you already have documented architecture, this is the perfect starting point:

```bash
@architect
```

**What happens here:**
- The Architect agent reads your architecture document
- Analyzes your existing code
- Creates a "Brownfield Analysis" with recommendations
- Defines how new features fit into your existing structure

### 3. Start the Master Flutter Workflow

Now use the **Master Flutter Orchestrator** to automatically handle everything:

```
/flutter-init-agent - Erstelle eine TikTok-ähnliche Livestream-UI mit:
- Vertical Video Player (Vollbild)
- Like Button mit Animation
- Share Button
- Kommentar-System (Real-time)
- Viewer Counter
- Follow Button

Target Folder: lib/features/livestream/
Screenshots: [Optional: Füge Screenshots oder Mockups hinzu]
```

### 4. Automatic End-to-End Workflow

The `flutter-init-agent` will **automatically orchestrate the complete development process**:

#### **🎯 Phase 1: Automatic Analysis**
- **Scans your existing codebase** using `npx appiq-solution flatten`
- **Analyzes architecture patterns** (routing, state management, DI)
- **Identifies integration points** with your existing features
- **Plans implementation strategy** for the new feature

#### **🏗️ Phase 2: Team Orchestration**
The agent automatically triggers this sequence:

**2.1 Product Owner (@po)**
- Creates user stories, epics, and acceptance criteria
- Defines feature breakdown and requirements

**2.2 Architect (@architect)**  
- Analyzes existing codebase structure
- Plans integration with current architecture
- Defines backend requirements (Supabase tables, etc.)
- Creates implementation guidelines

**2.3 UI Development (@flutter-ui-agent)**
- Creates pages and navigation integration
- Implements custom widgets and animations
- Ensures responsive design and accessibility

**2.4 State Management (@flutter-cubit-agent)**
- Implements Cubit/BLoC patterns matching your existing setup
- Handles error states and loading management
- Integrates with current state management

**2.5 Business Logic (@flutter-domain-agent)**
- Creates entities, use cases, and business rules
- Implements validation and business logic
- Defines repository interfaces

**2.6 Data Layer (@flutter-data-agent)**
- Implements repository pattern
- Creates API integration and caching
- Handles data serialization and persistence

**2.7 Backend Integration (MCP Supabase/Firebase)**
- Creates database tables and relationships
- Sets up authentication and security rules
- Implements real-time features

**2.8 Quality Assurance (@qa)**
- Performs code review against existing patterns
- Implements comprehensive testing strategy
- Validates architecture consistency

**2.9 Security Audit (@flutter-security-agent)**
- Checks for security vulnerabilities
- Validates API key protection
- Ensures data privacy compliance

**2.10 Git Integration**
- Commits changes with proper messages
- Creates feature branches
- Prepares for code review

### 5. Backend Integration

Since you also need backend functions:
```bash
@backend-dev
```

### 6. Automatic Quality Control

After each phase runs automatically:
- Code review against your existing patterns
- Consistency check with documented architecture
- Testing (Unit, Widget, Integration tests)
- Security validation

## 🔄 Your Complete Workflow

### **One-time setup:**
```bash
npx appiq-solution  # Choose appiq-flutter-mobile-dev
@architect          # Analyze existing architecture (optional)
```

### **For each new feature - Just one command:**
```
/flutter-init-agent - Erstelle ein Instagram-ähnliches Story Feature mit:
- Vollbild Story Viewer
- Progress Indicators  
- Swipe Navigation
- Story Creation (Foto/Video)
- Story Archive
- View Analytics

Target Folder: lib/features/stories/
Backend: Supabase (stories table, media storage)
Integration: Mit bestehendem User System
```

### **What happens automatically:**
✅ **Complete codebase analysis** and architecture understanding  
✅ **Automatic team orchestration** through all specialized agents  
✅ **End-to-end implementation** from UI to backend  
✅ **Quality assurance** and security validation  
✅ **Git integration** with proper commits  

**You only need to:**
- Provide the initial feature description
- Give feedback when agents ask for clarification
- Review and approve the final implementation

### **Available Flutter Agents:**
- `/flutter-init-agent` - Master orchestrator for complete features
- `/flutter-ui-agent` - UI components and design
- `/flutter-cubit-agent` - State management
- `/flutter-domain-agent` - Business logic
- `/flutter-data-agent` - Data layer and APIs
- `/flutter-security-agent` - Security auditing

## 🗂️ Codebase Context Management

Automatic context export after every feature/milestone:

```bash
# Manual execution
npx bmad-method flatten

# With custom output (for AI agents)
npx bmad-method flatten --output context/current-codebase.xml

# Automatically in package.json scripts:
{
  "scripts": {
    "flatten": "npx bmad-method flatten --output context/milestone-$(date +%Y%m%d).xml",
    "posttest": "npm run flatten",
    "postbuild": "npm run flatten"
  }
}
```

**Where it's saved:**
- **Standard**: `flattened-codebase.xml` in current directory
- **Custom**: Any path with `--output` parameter
- **Recommendation**: `context/` folder for better organization

**Benefits for Flutter development:**
✅ AI agents always have current codebase context  
✅ Perfect for code reviews and architecture discussions  
✅ Easy knowledge transfer between team members

## 📚 Documentation

📖 **[User Guide](bmad-core/user-guide.md)** - Complete guide to Flutter development with AI agents  
📱 **[Flutter Expansion Pack](expansion-packs/appiq-flutter-mobile-dev/)** - Specialized Flutter agents and templates  
🏗️ **[BMAD Core Architecture](docs/core-architecture.md)** - Technical deep dive into the framework

## Support

💬 [Discord Community](https://discord.gg/gk8jAdXWmj)  
🐛 [Issue Tracker](https://github.com/your-repo/appiq-solution/issues)  
💬 [Discussions](https://github.com/your-repo/appiq-solution/discussions)  
💖 [Support the Project via PayPal](https://paypal.me/yourusername)

## License

MIT © Viktor Hermann