> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remind.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment setup

# Development Environment Setup

This guide covers the complete setup of the development environment for Remind Tools, including all tools, configurations, and best practices.

## Quick Start

### Automated Setup (Recommended)

```bash theme={null}
# Clone the repository (if not already done)
git clone https://github.com/design4pro/remind_tools.git
cd remind_tools

# Run the automated setup script
./scripts/dev_setup.sh

# Install Git hooks for code quality
./scripts/install_hooks.sh
```

### Manual Setup

If you prefer to set up manually or encounter issues with the automated script:

```bash theme={null}
# 1. Bootstrap the workspace
melos bootstrap

# 2. Install Git hooks
git config core.hooksPath .githooks
chmod +x .githooks/*

# 3. Set up environment
cp .env.example .env
# Edit .env with your actual API keys

# 4. Generate code (if needed)
melos run generate

# 5. Verify setup
make doctor
```

## Environment Configuration

### Environment Files

The project uses multiple environment files for different deployment targets:

* **`.env`** - Your local development environment (not committed)
* **`.env.example`** - Template with placeholder values (committed)
* **`.env.development`** - Development environment settings (committed)
* **`.env.staging`** - Staging environment settings (committed)
* **`.env.production`** - Production environment settings (committed)

### Environment Variables

| Variable | Description | Required |
| - | - | - |
| `SUPABASE_URL` | Supabase project URL | Yes |
| `SUPABASE_ANON_KEY` | Supabase anonymous key | Yes |
| `SUPABASE_SERVICE_KEY` | Supabase service role key | Yes |
| `MAPBOX_ACCESS_TOKEN` | MapBox access token for maps | Yes |
| `MAPBOX_SECRET_TOKEN` | MapBox secret token | No |
| `GEMINI_API_KEY` | Google Gemini AI API key | Yes |
| `ENVIRONMENT` | Current environment (development/staging/production) | Yes |
| `DEBUG_MODE` | Enable debug features | Yes |
| `ENABLE_LOGGING` | Enable application logging | Yes |

### Switching Environments

Use the Makefile commands to quickly switch between environments:

```bash theme={null}
# Switch to development
make env-dev

# Switch to staging  
make env-staging

# Switch to production (be careful!)
make env-prod

# Check current environment
make env-status
```

## VSCode Configuration

The project includes comprehensive VSCode configuration for optimal Flutter development.

### Workspace Settings

The `.vscode/settings.json` file includes:

* **Flutter/Dart Configuration**: Hot reload, debugging, analysis
* **Code Formatting**: Auto-format on save, organize imports
* **File Management**: Hide generated files, nest related files
* **Performance**: Optimized analysis server settings
* **Terminal**: Proper PATH configuration for Dart tools

### Recommended Extensions

Install these extensions for the best development experience:

```json theme={null}
{
  "recommendations": [
    "dart-code.dart-code",
    "dart-code.flutter",
    "felix-angelov.bloc",
    "robert-brunhage.flutter-riverpod-snippets",
    "eamodio.gitlens",
    "usernamehw.errorlens",
    "supabase.supabase"
  ]
}
```

VSCode will automatically suggest these extensions when you open the project.

### Debug Configurations

Pre-configured launch configurations for:

* **Both Apps**: Debug, Profile, Release modes
* **Multi-Platform**: Web, macOS, iOS, Android
* **Testing**: Unit tests, Integration tests
* **Environment-Specific**: Development, Staging, Production

Use `Cmd+Shift+D` (macOS) or `Ctrl+Shift+D` (Windows/Linux) to access debug configurations.

## Code Generation

### Build Configuration

The `build.yaml` file configures code generation for:

* **Freezed**: Immutable data classes with copyWith, equality
* **JSON Serializable**: JSON serialization/deserialization
* **Auto Route**: Type-safe navigation
* **Riverpod**: State management providers

### Running Code Generation

```bash theme={null}
# Generate code once
melos run generate

# Watch and auto-generate on file changes
melos run generate:watch

# Clean generated files
make clean-generated
```

### Generated File Patterns

Generated files follow these patterns:

* `*.g.dart` - JSON serializable generated files
* `*.freezed.dart` - Freezed generated files
* `*.gr.dart` - Auto route generated files
* `*.config.dart` - Configuration files

These files are hidden in VSCode but visible in the file system.

## Development Scripts

### Available Scripts

Use `make help` to see all available commands, including:

#### Development

```bash theme={null}
make dev-trips        # Run Trips app
make dev-money        # Run Money app  
make dev-trips-web    # Run Trips app on web
make dev-money-macos  # Run Money app on macOS
```

#### Code Quality

```bash theme={null}
make analyze          # Static analysis
make format-fix       # Format code
make lint            # Full linting
make pre-commit      # Pre-commit checks
```

#### Testing

```bash theme={null}
make test            # All tests
make test-unit       # Unit tests only
make coverage        # Coverage report
```

#### Building

```bash theme={null}
make build-android   # Android APK
make build-ios       # iOS app
make build-web       # Web build
make build-all       # All platforms
```

### Git Hooks

Pre-commit hooks automatically run:

1. **Code Formatting**: Auto-formats staged Dart files
2. **Static Analysis**: Runs `melos run analyze`
3. **Security Checks**: Prevents committing real secrets
4. **Unit Tests**: Runs unit tests if available
5. **Code Generation**: Checks for generated file updates

To bypass hooks temporarily:

```bash theme={null}
git commit --no-verify
```

## Debugging and Logging

### Debug Configuration

The project includes comprehensive debug configuration:

```dart theme={null}
// Check if in debug mode
if (DebugConfig.isDebugMode) {
  // Debug-only code
}

// Environment-aware logging
if (DebugConfig.enableLogging) {
  logger.info('Debug message');
}
```

### Logging System

Use the built-in logging system:

```dart theme={null}
import 'package:core/core.dart';

// Use global loggers
Loggers.app.info('Application started');
Loggers.network.debug('API request sent');
Loggers.ui.warning('User interaction warning');

// Or create custom logger
final logger = AppLogger.withTag('MyFeature');
logger.error('Something went wrong', error, stackTrace);

// Use extension method
class MyClass {
  void myMethod() {
    logger.info('Method called');
  }
}
```

### Debug Features

Available debug features:

* **Network Inspector**: Log all HTTP requests/responses
* **Performance Profiling**: Measure execution times
* **Memory Leak Detection**: Track memory usage
* **Flutter Inspector**: Widget tree debugging
* **Layout Debugging**: Visual debugging aids

## Platform-Specific Setup

### macOS Development

```bash theme={null}
# Install Xcode from App Store
# Install Android Studio
# Verify setup
flutter doctor

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

### Web Development

```bash theme={null}
# Enable web development
flutter config --enable-web

# Install Chrome for debugging
# Web builds use CanvasKit renderer by default
```

### Mobile Development

```bash theme={null}
# iOS (macOS only)
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

# Android
# Set ANDROID_HOME environment variable
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

## Troubleshooting

### Common Issues

#### "Melos not found"

```bash theme={null}
dart pub global activate melos
export PATH="$PATH":"$HOME/.pub-cache/bin"
```

#### "Flutter doctor issues"

```bash theme={null}
flutter doctor
# Follow the suggestions to fix issues
```

#### "Build failures"

```bash theme={null}
# Clean and rebuild
make clean
make bootstrap
melos run generate
```

#### "Git hooks not working"

```bash theme={null}
# Reinstall hooks
./scripts/install_hooks.sh
```

#### "VSCode extensions not working"

```bash theme={null}
# Reload VSCode window
Cmd+Shift+P -> "Developer: Reload Window"
```

### Getting Help

1. **Check Documentation**: Review `/docs` directory
2. **Run Diagnostics**: Use `make doctor` and `flutter doctor`
3. **Clean Setup**: Try `make reset` for a fresh start
4. **Team Support**: Ask in team channels with error details

## Next Steps

After setup, you can:

1. **Start Development**: Use `make dev-trips` or `make dev-money`
2. **Explore Code**: Check `packages/` for shared code
3. **Run Tests**: Use `make test` to verify everything works
4. **Read Architecture**: Review `/docs/architecture/`
5. **Check Issues**: Look at GitHub Issues for current tasks

## Continuous Integration

The setup works seamlessly with CI/CD:

* **GitHub Actions**: Uses same melos commands
* **Codemagic**: Pre-configured build scripts
* **Quality Gates**: Automated testing and analysis
* **Multi-Platform**: Builds for all supported platforms

This ensures consistency between local development and production builds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.