# Development Setup

This guide helps developers set up their environment for contributing to Flow Master or building custom extensions.

## Table of Contents
- [Prerequisites](#prerequisites)
- [Environment Setup](#environment-setup)
- [Project Structure](#project-structure)
- [Building and Running](#building-and-running)
- [Development Workflow](#development-workflow)
- [Testing](#testing)
- [Contributing](#contributing)

## Prerequisites

### Required Software
```
Development Requirements:
├── Flutter SDK: 3.29.3 or later
├── Dart SDK: 3.7.2 or later (included with Flutter)
├── Git: Version control system
├── IDE: VS Code, Android Studio, or IntelliJ IDEA
└── Platform-specific tools (see below)
```

### Platform-Specific Requirements

#### Windows Development
```bash
# Install Visual Studio Build Tools
winget install Microsoft.VisualStudio.2022.BuildTools

# Enable Windows desktop development
flutter config --enable-windows-desktop

# Verify setup
flutter doctor
```

#### macOS Development
```bash
# Install Xcode (from App Store)
# Install Xcode Command Line Tools
xcode-select --install

# Enable macOS desktop development
flutter config --enable-macos-desktop

# Verify setup
flutter doctor
```

#### Linux Development
```bash
# Install required packages (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y curl git unzip xz-utils zip libglu1-mesa

# Install build essentials
sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev

# Enable Linux desktop development
flutter config --enable-linux-desktop

# Verify setup
flutter doctor
```

### IDE Setup

#### VS Code (Recommended)
```json
// .vscode/extensions.json
{
  "recommendations": [
    "dart-code.dart-code",
    "dart-code.flutter",
    "ms-vscode.cmake-tools",
    "ms-vscode.cpptools"
  ]
}
```

#### Required VS Code Extensions
- **Dart**: Dart language support
- **Flutter**: Flutter framework support
- **GitLens**: Enhanced Git capabilities
- **Error Lens**: Inline error display

## Environment Setup

### Clone Repository
```bash
# Clone the repository
git clone https://github.com/your-repo/flow-master.git
cd flow-master

# Switch to development branch
git checkout develop
```

### Install Dependencies
```bash
# Get Flutter packages
flutter pub get

# Install Git hooks (optional)
git config core.hooksPath .githooks

# Install pre-commit hooks
chmod +x .githooks/pre-commit
```

### Generate Code
```bash
# Generate build files
dart run build_runner build

# Watch for changes during development
dart run build_runner watch
```

### Environment Configuration
```bash
# Copy environment template
cp .env.example .env

# Edit configuration (optional)
# Set API keys, database paths, etc.
nano .env
```

## Project Structure

### Directory Layout
```
flow_master/
├── lib/                          # Main application code
│   ├── core/                     # Core functionality
│   │   ├── automation/           # Automation engine
│   │   ├── database/             # Data management
│   │   ├── services/             # Business logic services
│   │   └── utils/                # Utility functions
│   ├── features/                 # Feature modules
│   │   ├── components/           # Component management
│   │   ├── flows/                # Flow management
│   │   ├── dashboard/            # Main dashboard
│   │   └── settings/             # Application settings
│   ├── shared/                   # Shared widgets and models
│   │   ├── models/               # Data models
│   │   ├── widgets/              # Reusable UI components
│   │   └── providers/            # State management
│   └── main.dart                 # Application entry point
├── test/                         # Test files
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   └── widget/                   # Widget tests
├── docs/                         # Documentation
├── assets/                       # Static assets
├── android/                      # Android platform code
├── ios/                          # iOS platform code
├── macos/                        # macOS platform code
├── windows/                      # Windows platform code
├── linux/                        # Linux platform code
├── web/                          # Web platform code
└── pubspec.yaml                  # Project configuration
```

### Key Files
- `pubspec.yaml`: Project dependencies and configuration
- `analysis_options.yaml`: Code analysis rules
- `.github/`: CI/CD workflows and templates
- `build_runner.yaml`: Code generation configuration

## Building and Running

### Development Build
```bash
# Run on desktop (auto-detects platform)
flutter run

# Run on specific platform
flutter run -d windows
flutter run -d macos
flutter run -d linux

# Run with hot reload
flutter run --hot
```

### Release Build
```bash
# Build for current platform
flutter build windows --release
flutter build macos --release
flutter build linux --release

# Build for mobile (if configured)
flutter build apk --release
flutter build ios --release
```

### Debug Build with Profiling
```bash
# Run with performance profiling
flutter run --profile

# Run with memory profiling
flutter run --debug --enable-asserts
```

## Development Workflow

### Branch Strategy
```
Git Flow:
├── main: Production-ready code
├── develop: Integration branch for features
├── feature/*: Individual feature development
├── hotfix/*: Critical bug fixes
└── release/*: Release preparation
```

### Feature Development
```bash
# Create feature branch
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: add new feature description"

# Push and create pull request
git push origin feature/your-feature-name
```

### Code Style
Follow these conventions:
- **Dart Style Guide**: Official Dart style conventions
- **File Naming**: Use snake_case for files
- **Class Naming**: Use PascalCase for classes
- **Variable Naming**: Use camelCase for variables
- **Constants**: Use SCREAMING_SNAKE_CASE

### Commit Messages
Use conventional commit format:
```
type(scope): description

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code formatting changes
- refactor: Code restructuring
- test: Test additions or changes
- chore: Build system or tool changes
```

## Testing

### Test Structure
```
Testing Strategy:
├── Unit Tests: Individual function/class testing
├── Widget Tests: UI component testing
├── Integration Tests: End-to-end flow testing
└── Platform Tests: Platform-specific functionality
```

### Running Tests
```bash
# Run all tests
flutter test

# Run specific test file
flutter test test/unit/automation_engine_test.dart

# Run tests with coverage
flutter test --coverage

# Generate coverage report
genhtml coverage/lcov.info -o coverage/html
```

### Writing Tests
```dart
// Example unit test
import 'package:flutter_test/flutter_test.dart';
import 'package:flow_master/core/automation/automation_engine.dart';

void main() {
  group('AutomationEngine', () {
    late AutomationEngine engine;

    setUp(() {
      engine = AutomationEngine();
    });

    test('should initialize correctly', () {
      expect(engine.isInitialized, isFalse);
      engine.initialize();
      expect(engine.isInitialized, isTrue);
    });
  });
}
```

### Test Guidelines
- **Write Tests First**: TDD approach recommended
- **Test Edge Cases**: Include boundary conditions
- **Mock Dependencies**: Use mocks for external services
- **Clear Test Names**: Describe what is being tested
- **Setup/Teardown**: Clean state between tests

## Contributing

### Code Review Process
1. **Create Feature Branch**: From develop branch
2. **Implement Feature**: With tests and documentation
3. **Run Tests**: Ensure all tests pass
4. **Submit PR**: With clear description and screenshots
5. **Address Feedback**: Respond to review comments
6. **Merge**: After approval from maintainers

### Quality Checklist
Before submitting:
- [ ] Code follows style guidelines
- [ ] All tests pass
- [ ] No lint warnings
- [ ] Documentation updated
- [ ] Screenshots for UI changes
- [ ] Performance impact considered

### Getting Help
- **Discord**: Join developer channel for real-time help
- **GitHub Issues**: Search existing issues first
- **Documentation**: Check docs for common questions
- **Code Comments**: Read inline documentation

### Development Tools

#### Useful Commands
```bash
# Check code quality
flutter analyze

# Format code
dart format lib/

# Update dependencies
flutter pub upgrade

# Clean build
flutter clean && flutter pub get

# Generate app icons
flutter pub run flutter_launcher_icons:main
```

#### VS Code Shortcuts
- `Ctrl+Shift+P`: Command palette
- `F5`: Start debugging
- `Ctrl+F5`: Run without debugging
- `Ctrl+Shift+R`: Hot reload
- `Ctrl+.`: Quick fix

### Performance Profiling
```bash
# Profile app performance
flutter run --profile --trace-startup

# Analyze bundle size
flutter build apk --analyze-size

# Memory profiling
flutter run --profile --enable-asserts
```

### Debugging
```dart
// Debug logging
import 'dart:developer' as developer;

void debugFunction() {
  developer.log('Debug message', name: 'FlowMaster');
  developer.debugger(); // Breakpoint in IDE
}
```

This setup guide should get you ready for Flow Master development. For additional help, check the other documentation files or reach out to the development team.