Centralized documentation and development standards for AI-powered Flutter development. This repository provides comprehensive coding standards, guidelines, and AI assistant configurations that can be shared across multiple Flutter projects, designed primarily for AI agents with human developer support.
- 🤖 AI Agent Optimized - Pre-configured for AI assistants (Augment, Cursor, etc.)
- 📚 Comprehensive Documentation - Complete Flutter coding standards and guidelines
- 🔗 One-Line Setup - Instant integration with any Flutter project
- 🔄 Auto-Update - Keep standards current across all projects
- 🎯 Tiered Approach - Guidelines for small, medium, and large projects
- 🏗️ Architecture Patterns - Clean Architecture, BLoC, Cubit, and more
Install in default directory: (/opt/flutter/flutter-docs)
curl -sSL https://raw.githubusercontent.com/solutionsunity/flutter-docs/main/install.sh | bashInstall in specific project directory:
# Syntax: bash -s [project_path]
curl -sSL https://raw.githubusercontent.com/solutionsunity/flutter-docs/main/install.sh | bash -s /path/to/projectWhat the installer does:
- 📥 Clones/updates the flutter-docs repository to
/opt/flutter/flutter-docs(standardized location) - 🔗 Creates symlinks to documentation and AI configuration
- 📝 Updates
.gitignorewith proper root-relative paths
If you already have flutter-docs installed, simply create symlinks from your project:
# From your Flutter project directory
/opt/flutter/flutter-docs/link.shWhat the linker does:
- 🔗 Creates symlink to
docs/directory - 🔗 Creates symlink to
.augment/directory - 📝 Updates
.gitignorewith proper root-relative paths (/docs,/.augment) - ✅ Validates target directory and prevents conflicts
- 🔄 Detects existing symlinks and avoids duplicates
If you prefer manual setup:
# 1. Clone the repository
git clone https://github.com/solutionsunity/flutter-docs.git /opt/flutter/flutter-docs
# 2. Navigate to your Flutter project
cd /path/to/your/flutter-project
# 3. Create symlinks and update .gitignore
/opt/flutter/flutter-docs/link.shflutter-docs/
├── .augment/ # 🤖 AI Assistant Configuration
│ └── rules/ # AI agent rules and guidelines
│ ├── README.md # Documentation index
│ ├── core-principles.md # Essential coding standards
│ ├── state-management-guide.md # Tiered state management
│ ├── testing-guide.md # Testing pyramid & best practices
│ ├── security-best-practices.md # Security guidelines
│ ├── package-reference.md # Official packages
│ ├── clean-architecture-guide.md # Clean Architecture
│ ├── bloc-pattern-guide.md # BLoC pattern
│ ├── cubit-pattern-guide.md # Cubit pattern
│ ├── supabase-integration-guide.md # Supabase
│ └── dartz-functional-programming-guide.md # Functional programming
├── docs/ # 📚 Legacy documentation
│ ├── legacy/ # Archived documentation
│ └── sync.sh # Synchronization script
├── install.sh # 🔧 One-line installer
├── link.sh # 🔗 Symlink creation script
└── README.md # This file
| Document | Description | Purpose |
|---|---|---|
| Core Principles | Essential coding standards | Code quality, Dart/Flutter best practices |
| State Management | Tiered approach | setState, Provider, BLoC/Cubit |
| Testing Guide | Testing pyramid | 70% unit, 20% widget, 10% integration |
| Security | Security best practices | API keys, secure storage, authentication |
| Package Reference | Official packages | flutter_bloc, equatable, supabase, etc. |
| Document | Description | Purpose |
|---|---|---|
| Clean Architecture | Three-layer architecture | Domain, Data, Presentation layers |
| BLoC Pattern | Event-driven state management | Complex state management |
| Cubit Pattern | Simplified state management | Simpler than BLoC |
| Supabase Integration | Backend integration | Auth, database, storage |
| Dartz FP | Functional programming | Either/Option types, error handling |
This repository is optimized for AI agents like Augment, Cursor, GitHub Copilot, and others:
.augment/rules/- Contains AI-specific instructions and context- Comprehensive docs - All standards in easily parseable markdown
- Auto-sync - AI can run
./docs/sync.shto get latest updates - Tiered approach - Guidelines scale from small to large projects
- Session start: Run
./docs/sync.shto ensure latest updates - Before coding: Reference
./.augment/rules/README.mdfor guidelines - During development: Follow standards in documentation
- State management: Use decision tree in state-management-guide.md
- Testing: Follow testing pyramid in testing-guide.md
Keep your documentation and standards current:
# From any project with symlinked docs
./docs/sync.shThis script automatically:
- Pulls the latest changes from this repository
- Updates all symlinked documentation across your projects
- Ensures you're always using the current standards
| Project Size | Screens | Developers | Timeline | State Management | Architecture |
|---|---|---|---|---|---|
| Small | 1-5 | 1-2 | <3 months | setState, ValueNotifier | Component-based |
| Medium | 5-20 | 2-5 | 3-12 months | Provider | Feature-first |
| Large | 20+ | 5+ | 12+ months | BLoC/Cubit | Clean Architecture |
- ✅ Explicit type declarations (no
dynamic) - ✅ Descriptive naming with auxiliary verbs
- ✅ Functions under 30 lines
- ✅ Early returns to avoid nesting
- ✅
constconstructors everywhere possible - ✅
ListView.builderfor long lists - ✅ Extract widgets to reduce nesting
- ✅ Avoid deeply nested widget trees
- ✅ 70% unit tests (business logic)
- ✅ 20% widget tests (UI components)
- ✅ 10% integration tests (user flows)
- ✅ Mock dependencies for fast, reliable tests
- ✅ CRITICAL: Never hardcode API keys or credentials
- ✅ CRITICAL: Use flutter_dotenv for environment variables
- ✅ Use flutter_secure_storage for sensitive data
- ✅ Always use HTTPS
- ✅ Validate all user input
- ✅ CRITICAL: Use StatelessWidget for screens with Cubit/BLoC
- ✅ Only use StatefulWidget for local UI state
- ✅ Avoid dual state management (setState + Cubit)
- ✅ Single source of truth for business logic
A: Simply run link.sh again after git init. The script detects git repositories and will create the .gitignore entries automatically.
git init
/opt/flutter/flutter-docs/link.shA: Yes! The link.sh script works in any directory. It will create symlinks but skip .gitignore updates if git isn't initialized.
A: Run ./docs/sync.sh from any project with symlinked docs. This pulls the latest updates from the central repository.
A: No! The .gitignore uses root-relative paths (/docs) that only ignore the symlinked docs directory at your repository root.
A: Both follow the same pattern but contain different technology-specific guidelines. This repository is for Flutter development, while odoo-docs is for Odoo development.
- Always symlink - Don't copy files, use symlinks to stay updated
- Sync regularly - Run
./docs/sync.shbefore starting work - Follow standards - Check documentation before coding
- Use tiered approach - Choose patterns based on project size
- Test thoroughly - Follow the testing pyramid (70/20/10)
We welcome contributions to improve these standards:
- Fork this repository
- Create a feature branch
- Make your improvements
- Submit a pull request
MIT License - Feel free to use and adapt for your projects.
Last Updated: 2025-11-16 Version: 2.1.0 Maintained by: Flutter Development Team