Development

Development

This page covers development workflows, coding standards, and best practices for ExpoScholar.

Development Environment Setup

Starting Development Servers

Start Server:

./setup start-server
# or
cd server && python manage.py runserver

Server runs at http://localhost:8000

Start Mobile App:

./setup start-mobile
# or
cd mobile && flutter run

Start Android VM (Optional):

./setup start-mobile

This automatically creates and boots a QEMU-based Android virtual machine.

Development Workflow

Standard Workflow

1. Make Changes: Edit source files in server/ or mobile/
2. Test Locally: Run tests with ./setup test-server or ./setup test-mobile
3. Check Quality: Run linting and static analysis
4. Commit Changes: Follow the established commit message format

Hot Reload

Flutter:

• Press r in terminal for hot reload
• Press R for hot restart
• Press q to quit

Django:

• Server auto-reloads on file changes
• Manual restart: ./setup start-server

Code Quality Standards

Python (Server)

Style Guidelines:

• Follow PEP 8 style guidelines
• Maximum line length: 79 characters
• Use type hints where appropriate
• Write docstrings for all functions and classes

Example:

def process_order(order_id: int) -> dict:
    """
    Process an order and return the result.
    
    Args:
        order_id: The ID of the order to process
        
    Returns:
        Dictionary containing order processing results
    """
    # Implementation
    pass

Linting:

cd server
flake8 .
black --check .

Dart (Mobile)

Style Guidelines:

• Follow Dart style guide
• Use flutter analyze to check for issues
• Maintain zero analyzer warnings
• Write comprehensive tests

Example:

/// Processes synchronization data and returns the result.
Future<SyncResult> processSync(SyncData data) async {
  // Implementation
}

Analysis:

cd mobile
flutter analyze

Available Commands

Setup Script Commands

Installation:

• ./setup install - Full installation
• ./setup server - Server setup only
• ./setup mobile - Mobile setup only

Development:

• ./setup start-server - Start development server
• ./setup start-mobile - Start mobile app
• ./setup stop-server - Stop development server
• ./setup stop-mobile - Stop mobile app

Testing:

• ./setup test - Run all tests
• ./setup test-server - Run server tests
• ./setup test-mobile - Run mobile tests

Building:

• ./setup build-apk - Build Android APK
• ./setup build-aab - Build Android App Bundle
• ./setup build-ios - Build iOS app
• ./setup build-split - Build split APKs

Documentation:

• ./setup docs - Build documentation
• ./setup docs-info - Build Info format
• ./setup docs-html - Build HTML format
• ./setup docs-pdf - Build PDF format

Utilities:

• ./setup check - Validate system requirements
• ./setup help - Show all available commands

Makefile Targets

Setup:

• make setup - Full installation
• make setup-server - Server setup only
• make setup-mobile - Mobile setup only

Testing:

• make test - Run all tests
• make test-server - Run server tests
• make test-mobile - Run mobile tests

Quality:

• make lint - Run linting
• make format - Format code
• make analyze - Run static analysis

Building:

• make build - Build all components
• make docker-build - Build Docker images

Documentation:

• make docs - Build documentation
• make docs-html - Build HTML format
• make docs-pdf - Build PDF format

Cleanup:

• make clean - Clean build artifacts
• make clean-all - Clean all generated files

Help:

• make help - Show all targets

Testing

Server Testing

Run All Tests:

./setup test-server
# or
cd server && python manage.py test

Run Specific Test Suite:

cd server && python manage.py test apps.accounts.tests

With Coverage:

cd server && python manage.py test --coverage

Mobile Testing

Run All Tests:

./setup test-mobile
# or
cd mobile && flutter test

Run Specific Test:

cd mobile && flutter test test/unit/providers/sync_provider_test.dart

With Coverage:

cd mobile && flutter test --coverage

Static Analysis:

cd mobile && flutter analyze

Integration Testing

Integration tests are located in tests/integration/ and can be run with:

./setup test

Debugging

Server Debugging

Django Debug Toolbar:

• Automatically enabled in development
• Access at /__debug__/

Logging:

import logging
logger = logging.getLogger(__name__)
logger.debug('Debug message')

Management Commands:

python manage.py shell
python manage.py dbshell

Mobile Debugging

Flutter DevTools:

flutter pub global activate devtools
flutter pub global run devtools

Print Debugging:

print('Debug message');
debugPrint('Debug message');  // Recommended

Widget Inspector:

• Available in IDE or via DevTools
• Inspect widget tree
• View render tree

Code Organization

Server Structure

• apps/: Django applications (modular components)
• config/: Project configuration
• templates/: HTML templates
• static/: Static files
• media/: User-uploaded files

Mobile Structure

• lib/models/: Data models
• lib/providers/: State management
• lib/screens/: UI screens
• lib/widgets/: Reusable components
• lib/utils/: Utility functions
• test/: Test suites

Version Control

Git Workflow

1. Create Feature Branch:

git checkout -b feature/your-feature-name

2. Make Changes and Commit:

git add .
git commit -m "feat: add new feature"

3. Push and Create Pull Request:

git push origin feature/your-feature-name

Commit Message Format

Follow the established format:

<type>: <short summary>

OVERVIEW:
- Brief overview of changes

DETAILS:
- Detailed list of changes

TECHNICAL DETAILS:
- Technical implementation notes

TESTING:
- Testing procedures and results

FILES:
- List of modified files

Types:

• fix: Bug fixes
• feat: New features
• docs: Documentation changes
• refactor: Code refactoring
• test: Test additions or changes
• ci: CI/CD changes
• infra: Infrastructure changes

Best Practices

General

• Write clear, self-documenting code
• Add comments for complex logic
• Keep functions small and focused
• Use meaningful variable names
• Follow DRY (Don't Repeat Yourself) principle

Server

• Use Django ORM for database queries
• Validate input at the serializer level
• Use signals for cross-app communication
• Implement proper error handling
• Log important events

Mobile

• Use Provider for state management
• Keep widgets small and reusable
• Use const constructors where possible
• Implement proper error handling
• Handle network failures gracefully

Related Pages

• Installation - Installation instructions
• Architecture - System architecture
• Testing - Testing procedures
• Contributing - Contribution guidelines