development

Development Documentation

Overview

This section contains documentation for developers working on Elluminar, including architecture guidelines, development setup, platform-specific configurations, and best practices.

Quick Start

Development Environment Setup

1. Flutter SDK: Version 3.10+ required
2. IDE: VS Code or Android Studio with Flutter/Dart plugins
3. Platform SDKs: Xcode (macOS/iOS), Android Studio (Android)
4. Database: Supabase account and project access

Running the App

# Get dependencies
flutter pub get

# Run on different platforms
flutter run -d macos       # macOS development
flutter run -d ios         # iOS simulator
flutter run -d android     # Android emulator
flutter run -d chrome      # Web development

Documentation Structure

🏗️ Architecture

• architecture.md - App architecture overview and design patterns

🎯 State Management

• state-management.md - Riverpod state management patterns

🖥️ Platform-Specific

• platform-specific/macos-setup.md - macOS development setup and considerations

Architecture Overview

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Flutter App   │    │   Supabase      │    │   Database      │
│                 │    │                 │    │                 │
│ • Screens       │◄──►│ • Auth          │◄──►│ • Users         │
│ • Widgets       │    │ • Real-time     │    │ • Profiles      │  
│ • Services      │    │ • Storage       │    │ • Triggers      │
│ • Providers     │    │ • Edge Funcs    │    │ • RLS Policies  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Key Design Patterns

State Management (Riverpod)

• Providers: Global state management
• State Notifiers: Complex state logic
• Future Providers: Async data loading
• Stream Providers: Real-time data

Authentication Flow

• Trigger-Based: Database triggers handle user creation
• Multi-Platform: Email auth for macOS, OAuth for mobile/web
• Session Management: Persistent login state

Data Layer Architecture

• Services: Business logic layer
• Models: Data structures and serialization
• Providers: State management and data flow

Development Workflow

Feature Development

1. Planning: Review architecture and patterns
2. State Design: Plan Riverpod providers and state
3. UI Development: Create screens and widgets
4. Service Integration: Connect to backend services
5. Testing: Unit, widget, and integration tests
6. Documentation: Update relevant docs

Code Organization

lib/
├── config/           # App configuration
├── models/           # Data models
├── providers/        # Riverpod providers
├── screens/          # UI screens
├── services/         # Business logic
├── theme/            # UI theming
└── widgets/          # Reusable components

Coding Standards

Dart/Flutter Best Practices

• Null Safety: Always use null-safe code
• Immutability: Prefer immutable data structures
• Async/Await: Use proper async patterns
• Error Handling: Comprehensive error management

Architecture Patterns

• Single Responsibility: Each class has one purpose
• Dependency Injection: Use Riverpod for dependencies
• Clean Architecture: Separate concerns clearly
• Testability: Write testable code

Platform-Specific Development

macOS Development

Key Considerations:

• OAuth Limitations: Email authentication only
• Desktop UX: Different interaction patterns
• Entitlements: Proper security settings
• Podfile Management: CocoaPods dependency management

Documentation: macOS Setup Guide

iOS Development

Key Considerations:

• Apple Sign-In: Required for App Store
• Permissions: Camera, microphone, notifications
• App Store Guidelines: Compliance requirements
• Testing: Simulator and device testing

Android Development

Key Considerations:

• Google Services: OAuth and push notifications
• Permissions: Runtime permission handling
• Play Store: Release signing and validation
• Testing: Multiple device sizes and versions

Web Development

Key Considerations:

• Browser Compatibility: Cross-browser testing
• PWA Features: Progressive Web App capabilities
• Performance: Bundle size optimization
• SEO: Search engine optimization

State Management Guide

Riverpod Architecture

The app uses Riverpod for state management with the following patterns:

Provider Types

• Provider: Immutable data or computed values
• StateProvider: Simple mutable state
• StateNotifierProvider: Complex state logic
• FutureProvider: Async data fetching
• StreamProvider: Real-time data streams

State Organization

// Global providers
final authStateProvider = StateNotifierProvider<AuthStateNotifier, AuthState>(...);
final themeProvider = StateProvider<ThemeMode>(...);

// Feature-specific providers
final consultantListProvider = FutureProvider<List<Consultant>>(...);
final activeCallProvider = StateProvider<VideoCall?>(...);

Testing Strategy

Testing Types

Unit Tests

• Services: Business logic testing
• Models: Data structure validation
• Providers: State management testing
• Location: test/unit/

Widget Tests

• Screens: UI component testing
• Widgets: Reusable widget testing
• User Interactions: Tap, scroll, input testing
• Location: test/widget/

Integration Tests

• Auth Flow: Complete authentication testing
• User Journeys: End-to-end workflows
• API Integration: Backend service testing
• Location: test/integration/

Running Tests

# Unit tests
flutter test

# Widget tests
flutter test test/widget/

# Integration tests
flutter test integration_test/

# Coverage report
flutter test --coverage

Build & Deployment

Development Builds

# Debug builds (development)
flutter run --debug

# Profile builds (performance testing)
flutter run --profile

# Release builds (production-like)
flutter run --release

Production Builds

# iOS App Store
flutter build ios --release

# Android Play Store  
flutter build appbundle --release

# macOS App Store
flutter build macos --release

# Web deployment
flutter build web --release

Performance Optimization

Flutter Performance

Widget Optimization

• const Constructors: Use const widgets where possible
• Widget Rebuilds: Minimize unnecessary rebuilds
• ListView Optimization: Use ListView.builder for large lists
• Image Optimization: Proper image caching and sizing

State Management Performance

• Provider Scoping: Scope providers appropriately
• State Normalization: Keep state flat and normalized
• Memoization: Cache expensive computations
• Lazy Loading: Load data on demand

Database Performance

Query Optimization

• Indexed Queries: Use proper database indexes
• Pagination: Implement proper pagination
• Selective Loading: Only fetch needed data
• Caching: Cache frequently accessed data

Security Best Practices

Code Security

• API Keys: Never commit secrets to version control
• Input Validation: Validate all user inputs
• Error Handling: Don't expose sensitive errors
• Logging: Don't log sensitive information

Authentication Security

• Token Storage: Secure token management
• Session Timeout: Implement appropriate timeouts
• Permission Checking: Always verify user permissions
• HTTPS Only: Ensure all network traffic is encrypted

Debugging & Troubleshooting

Development Tools

Flutter DevTools

• Widget Inspector: UI debugging
• Performance View: Performance profiling
• Network Tab: HTTP request monitoring
• Logging: Application log viewing

Platform Tools

• Xcode: iOS/macOS debugging
• Android Studio: Android debugging and profiling
• Chrome DevTools: Web debugging

Common Issues

Build Issues

• Dependency Conflicts: Clean and reinstall dependencies
• Platform Updates: Update platform-specific configurations
• Cache Issues: Clear Flutter and platform caches

Runtime Issues

• State Management: Check provider scoping and updates
• Authentication: Verify token validity and permissions
• Network: Check API endpoints and connectivity

Getting Help

Internal Resources

1. Architecture Questions: Review architecture.md
2. State Management: Check state-management.md
3. Platform Issues: See platform-specific guides

External Resources

1. Flutter Documentation: flutter.dev
2. Riverpod Guide: riverpod.dev
3. Supabase Docs: supabase.com/docs

Contributing

Development Process

1. Branch: Create feature branches from dev
2. Develop: Follow coding standards and patterns
3. Test: Write appropriate tests
4. Review: Submit pull request for review
5. Deploy: Merge to appropriate branch

Code Review Checklist

• Follows architecture patterns
• Includes appropriate tests
• Updates documentation
• Handles errors gracefully
• Follows coding standards

Related Documentation

• Authentication - Authentication system integration
• Database - Database schema and operations
• OAuth - OAuth provider configuration