template:
  id: flutter-mobile-architecture-template-v1
  name: Flutter Mobile Architecture Document
  version: 1.0
  output:
    format: markdown
    filename: docs/flutter-architecture.md
    title: "{{project_name}} Flutter Mobile Architecture Document"

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: introduction
    title: Introduction
    instruction: |
      Review provided documents including PRD, UX-UI Specification, and main Architecture Document. Focus on mobile-specific requirements and Flutter implementation details.
    elicit: true
    content: |
      This document outlines the Flutter mobile architecture for {{project_name}}, following Clean Architecture principles with Cubit state management, dependency injection, and multi-language support.
      
      This architecture ensures scalable, testable, and maintainable mobile applications that can be released to production with confidence.
    sections:
      - id: changelog
        title: Change Log
        type: table
        columns: [Date, Version, Description, Author]
        instruction: Track document versions and changes

  - id: flutter-tech-stack
    title: Flutter Tech Stack
    instruction: Define the complete Flutter technology stack with specific versions and rationale.
    elicit: true
    sections:
      - id: tech-stack-table
        title: Technology Stack Table
        type: table
        columns: [Category, Technology, Version, Purpose, Rationale]
        rows:
          - ["Mobile Framework", "Flutter", "{{flutter_version}}", "Cross-platform mobile development", "{{flutter_rationale}}"]
          - ["Language", "Dart", "{{dart_version}}", "Programming language", "{{dart_rationale}}"]
          - ["State Management", "{{state_management}}", "{{version}}", "Application state management", "{{state_rationale}}"]
          - ["Dependency Injection", "get_it + injectable", "{{di_version}}", "Dependency management", "{{di_rationale}}"]
          - ["Code Generation", "freezed + json_serializable", "{{codegen_version}}", "Model and serialization generation", "{{codegen_rationale}}"]
          - ["Networking", "dio", "{{dio_version}}", "HTTP client", "{{dio_rationale}}"]
          - ["Local Storage", "{{local_storage}}", "{{storage_version}}", "Local data persistence", "{{storage_rationale}}"]
          - ["Error Handling", "dartz", "{{dartz_version}}", "Functional error handling", "{{dartz_rationale}}"]
          - ["Routing", "go_router", "{{router_version}}", "Navigation and routing", "{{router_rationale}}"]
          - ["Localization", "flutter_localizations", "{{l10n_version}}", "Multi-language support", "{{l10n_rationale}}"]
          - ["Backend Service", "{{backend_service}}", "{{backend_version}}", "Backend integration", "{{backend_rationale}}"]
          - ["Authentication", "{{auth_service}}", "{{auth_version}}", "User authentication", "{{auth_rationale}}"]
          - ["Testing Framework", "flutter_test + bloc_test", "{{test_version}}", "Unit and widget testing", "{{test_rationale}}"]
          - ["Build Tool", "build_runner", "{{build_version}}", "Code generation", "{{build_rationale}}"]

  - id: clean-architecture
    title: Clean Architecture Implementation
    instruction: Define the Clean Architecture layers and their responsibilities in Flutter context.
    elicit: true
    sections:
      - id: architecture-layers
        title: Architecture Layers
        template: |
          **Presentation Layer (UI)**
          - Pages and Widgets for user interface
          - Cubit for state management
          - BlocConsumer/BlocBuilder for state consumption
          
          **Domain Layer (Business Logic)**
          - Entities representing business objects
          - Use Cases containing business rules
          - Repository interfaces for data abstraction
          
          **Data Layer (External Concerns)**
          - Repository implementations
          - Data sources (remote and local)
          - Models with JSON serialization
          - API clients and local storage
      
      - id: architecture-diagram
        title: Clean Architecture Diagram
        type: mermaid
        mermaid_type: graph
        instruction: |
          Create a Mermaid diagram showing the Clean Architecture layers and dependencies:
          - UI Layer (Widgets, Pages, Cubits)
          - Domain Layer (Entities, Use Cases, Repository Interfaces)
          - Data Layer (Repository Implementations, Data Sources, Models)
          - External (APIs, Databases, File System)

  - id: project-structure
    title: Project Structure
    instruction: Define the exact Flutter project structure following Clean Architecture principles.
    elicit: true
    type: code
    language: plaintext
    template: |
      lib/
      ├── core/                    # Shared Core Functionality
      │   ├── constants/          # API endpoints, app constants
      │   ├── di/                # Dependency injection setup
      │   │   ├── injection_container.dart
      │   │   └── injection_container.config.dart
      │   ├── error/             # Error handling (failures, exceptions)
      │   │   ├── failures.dart
      │   │   └── exceptions.dart
      │   ├── network/           # Networking setup
      │   │   ├── api_client.dart
      │   │   └── network_info.dart
      │   ├── local_storage/     # Local storage services
      │   │   └── hive_service.dart
      │   └── utils/             # Core utilities
      │       ├── validators.dart
      │       └── formatters.dart
      ├── features/              # Feature-based modules
      │   └── {{feature_name}}/    # Individual features
      │       ├── data/          # Data layer
      │       │   ├── datasources/   # Remote/Local data sources
      │       │   │   ├── {{feature}}_remote_datasource.dart
      │       │   │   └── {{feature}}_local_datasource.dart
      │       │   ├── models/        # Data models
      │       │   │   └── {{feature}}_model.dart
      │       │   └── repositories/  # Repository implementations
      │       │       └── {{feature}}_repository_impl.dart
      │       ├── domain/        # Domain layer
      │       │   ├── entities/      # Business entities
      │       │   │   └── {{feature}}_entity.dart
      │       │   ├── repositories/  # Repository interfaces
      │       │   │   └── {{feature}}_repository.dart
      │       │   └── usecases/     # Business use cases
      │       │       ├── get_{{feature}}_usecase.dart
      │       │       ├── create_{{feature}}_usecase.dart
      │       │       └── update_{{feature}}_usecase.dart
      │       └── presentation/  # Presentation layer
      │           ├── cubit/        # State management
      │           │   ├── {{feature}}_cubit.dart
      │           │   └── {{feature}}_state.dart
      │           ├── pages/        # UI pages/screens
      │           │   ├── {{feature}}_list_page.dart
      │           │   └── {{feature}}_detail_page.dart
      │           └── widgets/      # Feature-specific widgets
      │               └── {{feature}}_list_item.dart
      ├── shared/                # Shared UI components
      │   ├── theme/            # Theme management
      │   │   ├── app_theme.dart
      │   │   └── theme_cubit.dart
      │   ├── widgets/          # Reusable widgets
      │   │   ├── base_scaffold.dart
      │   │   ├── loading_widget.dart
      │   │   └── error_widget.dart
      │   ├── constants/        # UI constants
      │   │   └── app_constants.dart
      │   └── utils/            # Shared utilities
      │       ├── navigation_service.dart
      │       └── dialog_service.dart
      ├── l10n/                 # Localization
      │   ├── app_en.arb        # English translations
      │   ├── app_de.arb        # German translations
      │   └── l10n.yaml         # Localization configuration
      └── main.dart             # Application entry point

  - id: state-management-architecture
    title: State Management Architecture
    instruction: Define the Cubit-based state management approach with detailed patterns.
    elicit: true
    sections:
      - id: cubit-pattern
        title: Cubit Pattern Implementation
        type: code
        language: dart
        template: |
          // State class with Equatable
          class {{Feature}}State extends Equatable {
            const {{Feature}}State({
              this.status = {{Feature}}Status.initial,
              this.{{feature}}s = const [],
              this.selectedEntity,
              this.message,
            });

            final {{Feature}}Status status;
            final List<{{Feature}}Entity> {{feature}}s;
            final {{Feature}}Entity? selectedEntity;
            final String? message;

            {{Feature}}State copyWith({
              {{Feature}}Status? status,
              List<{{Feature}}Entity>? {{feature}}s,
              {{Feature}}Entity? selectedEntity,
              String? message,
            }) {
              return {{Feature}}State(
                status: status ?? this.status,
                {{feature}}s: {{feature}}s ?? this.{{feature}}s,
                selectedEntity: selectedEntity ?? this.selectedEntity,
                message: message ?? this.message,
              );
            }

            @override
            List<Object?> get props => [status, {{feature}}s, selectedEntity, message];
          }

          enum {{Feature}}Status { initial, loading, success, failure }

          // Cubit implementation
          @injectable
          class {{Feature}}Cubit extends Cubit<{{Feature}}State> {
            {{Feature}}Cubit(this._useCase) : super(const {{Feature}}State());

            final Get{{Feature}}sUseCase _useCase;

            Future<void> get{{Feature}}s() async {
              emit(state.copyWith(status: {{Feature}}Status.loading));

              final result = await _useCase();
              result.fold(
                (failure) => emit(state.copyWith(
                  status: {{Feature}}Status.failure,
                  message: failure.message,
                )),
                ({{feature}}s) => emit(state.copyWith(
                  status: {{Feature}}Status.success,
                  {{feature}}s: {{feature}}s,
                )),
              );
            }
          }

  - id: dependency-injection
    title: Dependency Injection Setup
    instruction: Define the dependency injection configuration using get_it and injectable.
    elicit: true
    sections:
      - id: di-setup
        title: DI Container Setup
        type: code
        language: dart
        template: |
          // injection_container.dart
          import 'package:get_it/get_it.dart';
          import 'package:injectable/injectable.dart';
          import 'injection_container.config.dart';

          final getIt = GetIt.instance;

          @InjectableInit(
            initializerName: 'init',
            preferRelativeImports: true,
            asExtension: true,
          )
          Future<void> configureDependencies() async => getIt.init();

          // Usage in main.dart
          void main() async {
            WidgetsFlutterBinding.ensureInitialized();
            await configureDependencies();
            runApp(MyApp());
          }

  - id: localization-setup
    title: Localization Setup
    instruction: Define the multi-language support implementation with ARB files.
    elicit: true
    sections:
      - id: l10n-config
        title: Localization Configuration
        type: code
        language: yaml
        template: |
          # l10n.yaml
          arb-dir: lib/l10n
          template-arb-file: app_en.arb
          output-localization-file: app_localizations.dart
          output-class: AppLocalizations
          
      - id: arb-example
        title: ARB File Example
        type: code
        language: json
        template: |
          // app_en.arb
          {
            "@@locale": "en",
            "appTitle": "{{project_name}}",
            "@appTitle": {
              "description": "The title of the application"
            },
            "welcomeMessage": "Welcome, {userName}!",
            "@welcomeMessage": {
              "description": "Welcome message with user name",
              "placeholders": {
                "userName": {
                  "type": "String",
                  "example": "John"
                }
              }
            },
            "loading": "Loading...",
            "error": "An error occurred",
            "retry": "Retry",
            "cancel": "Cancel",
            "save": "Save",
            "delete": "Delete",
            "edit": "Edit"
          }

  - id: backend-integration
    title: Backend Integration
    instruction: Define the backend service integration (Firebase, Supabase, or custom API).
    elicit: true
    sections:
      - id: api-client-setup
        title: API Client Configuration
        type: code
        language: dart
        template: |
          // api_client.dart
          @LazySingleton()
          class ApiClient {
            late final Dio _dio;

            ApiClient() {
              _dio = Dio(
                BaseOptions(
                  baseUrl: '{{api_base_url}}',
                  connectTimeout: const Duration(seconds: 30),
                  receiveTimeout: const Duration(seconds: 30),
                  headers: {
                    'Content-Type': 'application/json',
                    'Accept': 'application/json',
                  },
                ),
              );

              _dio.interceptors.add(LogInterceptor());
              _dio.interceptors.add(AuthInterceptor());
            }

            Future<Response> get(String path) => _dio.get(path);
            Future<Response> post(String path, {dynamic data}) => _dio.post(path, data: data);
            Future<Response> put(String path, {dynamic data}) => _dio.put(path, data: data);
            Future<Response> delete(String path) => _dio.delete(path);
          }

  - id: testing-strategy
    title: Testing Strategy
    instruction: Define comprehensive testing approach for Flutter Clean Architecture.
    elicit: true
    sections:
      - id: testing-pyramid
        title: Testing Pyramid
        template: |
          **Unit Tests** (70%)
          - Use Cases testing
          - Repository testing
          - Cubit testing
          - Utility function testing
          
          **Widget Tests** (20%)
          - Individual widget testing
          - Widget interaction testing
          - UI component testing
          
          **Integration Tests** (10%)
          - End-to-end feature testing
          - API integration testing
          - Navigation flow testing

      - id: test-examples
        title: Test Examples
        type: code
        language: dart
        template: |
          // Use Case Test
          void main() {
            group('Get{{Feature}}sUseCase', () {
              late {{Feature}}Repository mockRepository;
              late Get{{Feature}}sUseCase useCase;

              setUp(() {
                mockRepository = Mock{{Feature}}Repository();
                useCase = Get{{Feature}}sUseCase(mockRepository);
              });

              test('should return list of {{feature}}s when repository call is successful', () async {
                // arrange
                final {{feature}}List = [{{Feature}}Entity(id: '1', name: 'Test')];
                when(() => mockRepository.get{{Feature}}s())
                    .thenAnswer((_) async => Right({{feature}}List));

                // act
                final result = await useCase();

                // assert
                expect(result, Right({{feature}}List));
                verify(() => mockRepository.get{{Feature}}s()).called(1);
              });
            });
          }

  - id: security-implementation
    title: Security Implementation
    instruction: Define security measures and best practices for Flutter mobile app.
    elicit: true
    sections:
      - id: security-checklist
        title: Security Checklist
        template: |
          **Data Security**
          - [ ] Use flutter_secure_storage for sensitive data
          - [ ] Implement certificate pinning for API calls
          - [ ] Validate all user inputs
          - [ ] Encrypt local database if needed
          
          **Authentication Security**
          - [ ] Secure token storage
          - [ ] Implement token refresh mechanism
          - [ ] Handle authentication errors properly
          - [ ] Implement biometric authentication if required
          
          **Network Security**
          - [ ] Use HTTPS for all API calls
          - [ ] Implement request/response logging (excluding sensitive data)
          - [ ] Handle network errors securely
          - [ ] Implement timeout configurations
          
          **Code Security**
          - [ ] Obfuscate release builds
          - [ ] Remove debug information from release
          - [ ] Validate all external data
          - [ ] Implement proper error handling

  - id: performance-optimization
    title: Performance Optimization
    instruction: Define performance optimization strategies for Flutter app.
    elicit: true
    sections:
      - id: performance-guidelines
        title: Performance Guidelines
        template: |
          **Widget Performance**
          - Use const constructors wherever possible
          - Implement proper widget keys for list items
          - Avoid rebuilding expensive widgets unnecessarily
          - Use RepaintBoundary for complex widgets
          
          **State Management Performance**
          - Keep state as local as possible
          - Use proper Equatable implementation
          - Avoid emitting identical states
          - Implement proper loading states
          
          **Network Performance**
          - Implement proper caching strategies
          - Use image caching for network images
          - Implement pagination for large data sets
          - Handle offline scenarios gracefully
          
          **Memory Management**
          - Dispose controllers and streams properly
          - Use object pooling for frequently created objects
          - Monitor memory usage in debug mode
          - Implement proper error boundaries

  - id: deployment-strategy
    title: Deployment Strategy
    instruction: Define the deployment process for iOS and Android.
    elicit: true
    sections:
      - id: build-configuration
        title: Build Configuration
        template: |
          **Android Configuration**
          - Minimum SDK: {{min_sdk_version}}
          - Target SDK: {{target_sdk_version}}
          - Build variants: debug, release
          - Signing configuration for release builds
          - ProGuard/R8 obfuscation enabled
          
          **iOS Configuration**
          - Minimum iOS version: {{min_ios_version}}
          - Build configurations: Debug, Release
          - Code signing for distribution
          - App Transport Security configuration
          
          **CI/CD Pipeline**
          - Automated testing on pull requests
          - Automated builds for releases
          - Code quality checks (linting, analysis)
          - Security scanning
          - Automated deployment to app stores

  - id: development-workflow
    title: Development Workflow
    instruction: Define the standard development workflow for Flutter features.
    elicit: true
    sections:
      - id: feature-development-process
        title: Feature Development Process
        template: |
          **Standard Workflow**
          1. Think through the problem and read existing codebase
          2. Write implementation plan to tasks/todo.md with checkable items
          3. Get plan verified before beginning work
          4. Work on todo items marking them complete as you go
          5. Provide high-level explanations of changes made
          6. Keep changes simple - impact as little code as possible
          7. Add review section to todo.md with summary
          8. Make git commit after each fully finished task
          
          **Agent Workflow (UI → Cubit → Domain → Data)**
          1. **UI Agent**: Design and implement user interface
          2. **Cubit Agent**: Implement state management based on UI requirements
          3. **Domain Agent**: Create business logic based on Cubit needs
          4. **Data Agent**: Implement data layer based on domain requirements
          5. **Shared Components Agent**: Extract reusable components
          
          **Quality Gates**
          - All code follows DRY principles
          - Code is readable and well-documented
          - Architecture is maintainable and scalable
          - Performance requirements are met
          - All code is thoroughly tested
          - Security requirements are satisfied
          - All text uses localization keys

  - id: checklist-results
    title: Checklist Results Report
    instruction: Execute flutter-architecture-checklist and populate results here.