Installation - App Courier

This guide provides detailed instructions for setting up the App Courier development environment and configuring the application for different scenarios.

System Requirements

Minimum Requirements

Operating System

macOS 11.0+ (for iOS development)
Windows 10/11 (64-bit)
Linux (64-bit)

Hardware

8 GB RAM (16 GB recommended)
10 GB free disk space
Intel i5 or equivalent processor

Software

Flutter SDK 3.7.2+
Dart SDK 3.7.2+
Git 2.0+

IDE (Choose one)

VS Code with Flutter extension
Android Studio 2022.1+
IntelliJ IDEA

Prerequisites Installation

Step 1: Install Flutter SDK

macOS
Windows
Linux

Download Flutter SDK:

cd ~/development
curl -O https://storage.googleapis.com/flutter_infra_release/releases/stable/macos/flutter_macos_3.7.2-stable.zip
unzip flutter_macos_3.7.2-stable.zip

Add Flutter to PATH:

# Add to ~/.zshrc or ~/.bash_profile
export PATH="$PATH:$HOME/development/flutter/bin"

# Reload shell
source ~/.zshrc

Verify installation:

flutter doctor

Download Flutter SDK from flutter.dev
Extract to a location (e.g., C:\src\flutter)
Add Flutter to PATH:
- Open System Properties → Environment Variables
- Add C:\src\flutter\bin to PATH
Verify installation:

flutter doctor

Download and extract Flutter:

cd ~/development
wget https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.7.2-stable.tar.xz
tar xf flutter_linux_3.7.2-stable.tar.xz

Add Flutter to PATH:

# Add to ~/.bashrc
export PATH="$PATH:$HOME/development/flutter/bin"

# Reload shell
source ~/.bashrc

Install dependencies:

sudo apt-get install curl git unzip xz-utils zip libglu1-mesa

Verify installation:

flutter doctor

Step 2: Install Platform-Specific Tools

Android Development
iOS Development (macOS only)

Install Android Studio

Download Android Studio
Install Android Studio and follow the setup wizard
Install required SDK components:
- Android SDK Platform, API 33 or higher
- Android SDK Build-Tools
- Android SDK Command-line Tools
- Android Emulator

Configure Android SDK

flutter config --android-sdk <path-to-android-sdk>
flutter doctor --android-licenses

Verify Android setup:

flutter doctor -v

Look for ✓ marks next to:

Android toolchain
Android Studio

Install Xcode

Download Xcode from the Mac App Store
Install Xcode Command Line Tools:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

Install CocoaPods

sudo gem install cocoapods
pod setup

Accept Xcode License

sudo xcodebuild -license accept

Verify iOS setup:

flutter doctor -v

Look for ✓ marks next to:

Xcode
CocoaPods

Step 3: Install IDE and Extensions

VS Code
Android Studio

Download and install VS Code
Install Flutter extension:
- Open VS Code
- Press Ctrl+Shift+X (or Cmd+Shift+X on macOS)
- Search for “Flutter”
- Install the official Flutter extension (this also installs Dart)
Verify installation:
- Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
- Type “Flutter: Run Flutter Doctor”

Project Setup

Clone and Initialize

Clone the repository

git clone <repository-url>
cd courier

Install dependencies

flutter pub get

This installs all packages from pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.9.0                    # HTTP client
  provider: ^6.0.5               # State management
  shared_preferences: ^2.2.2     # Local storage
  url_launcher: ^6.3.2           # Open URLs
  intl: ^0.20.2                  # Internationalization
  http: ^1.6.0                   # HTTP requests
  path_provider: ^2.1.5          # File paths
  permission_handler: ^12.0.1    # Permissions
  image_picker: ^1.2.1           # Camera/gallery
  fl_chart: ^0.66.2              # Charts
  pinput: ^6.0.2                 # PIN input
  pdf: ^3.11.3                   # PDF generation
  printing: ^5.14.2              # Print PDF
  flutter_launcher_icons: ^0.14.4 # App icons
  cupertino_icons: ^1.0.8        # iOS icons

Verify project structure

ls -la

You should see:

lib/ - Dart source code
android/ - Android platform code
ios/ - iOS platform code
assets/ - Images, documents, logos
pubspec.yaml - Project configuration

Configuration

API Configuration

The API client is configured in lib/core/api/api_client.dart:

class ApiClient {
  late final Dio _dio;

  ApiClient() {
    _dio = Dio(
      BaseOptions(
        baseUrl: 'https://api.eisegmi.facturador.es', // API endpoint
        validateStatus: (status) {
          return status != null && status >= 200 && status < 300;
        },
        connectTimeout: const Duration(seconds: 20),
        receiveTimeout: const Duration(seconds: 20),
        headers: {
          'Content-Type': 'application/json',
        },
      ),
    );
  }
}

Production
Staging/Development
Local Development

For production builds, use the default API endpoint:

baseUrl: 'https://api.eisegmi.facturador.es'

For development/staging environment:

baseUrl: 'https://staging-api.your-domain.com'

Or use environment-based configuration:

import 'package:courier/core/config/environment.dart';

ApiClient() {
  final baseUrl = Environment.useMockData 
    ? 'https://staging-api.your-domain.com'
    : 'https://api.eisegmi.facturador.es';
  
  _dio = Dio(BaseOptions(baseUrl: baseUrl));
}

For local backend development:

// Android emulator
baseUrl: 'http://10.0.2.2:3000'

// iOS simulator  
baseUrl: 'http://localhost:3000'

// Physical device (use your computer's IP)
baseUrl: 'http://192.168.1.100:3000'

Environment Configuration

Modify lib/core/config/environment.dart for development settings:

class Environment {
  static const bool useMockData = false; // Set to true for testing without API
}

Android Configuration

Permissions

The app requires several permissions defined in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/> <!-- Android 13+ -->

These permissions are required for:

INTERNET: API communication
CAMERA: Taking package photos
STORAGE: Saving and accessing documents/images

App Name and Icon

The app name is set in AndroidManifest.xml:4:

<application
    android:label="EISEGMI"
    android:icon="@mipmap/ic_launcher">

To customize the app icon:

Place your logo at assets/logo/logo.png
Run the icon generator:

flutter pub run flutter_launcher_icons

Configuration is in pubspec.yaml:109-112:

flutter_launcher_icons:
  android: true
  ios: true
  image_path: "assets/logo/logo.png"

iOS Configuration

Info.plist Permissions

Add permission descriptions to ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access to take photos of packages</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access to select package images</string>

Bundle Identifier

Update the bundle identifier in ios/Runner.xcodeproj to match your organization.

Assets Setup

Ensure your assets directory structure matches pubspec.yaml:75-78:

assets/
├── images/      # General images
├── documents/   # PDF templates, etc.
└── logo/        # App logo
    └── logo.png

Create these directories if they don’t exist, or the app may fail to build.

Build and Run

Debug Build

# Run on connected device
flutter run

# Run on specific device
flutter run -d <device-id>

# Run with verbose logging
flutter run -v

Release Build

flutter build apk --release

# Output: build/app/outputs/flutter-apk/app-release.apk

Profile Build (Performance Testing)

flutter run --profile

Testing

Run Tests

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

Code Analysis

# Analyze code for issues
flutter analyze

# Format code
flutter format lib/

Troubleshooting

Common Build Issues

Gradle build fails on Android

cd android
./gradlew clean
cd ..
flutter clean
flutter pub get
flutter build apk

CocoaPods installation fails on iOS

cd ios
rm -rf Pods Podfile.lock
pod repo update
pod install
cd ..
flutter clean
flutter pub get

Dependency conflicts

flutter pub cache repair
flutter clean
flutter pub get

Assets not found

Ensure all asset directories exist and are declared in pubspec.yaml:

mkdir -p assets/images assets/documents assets/logo
flutter clean
flutter pub get

Permission errors at runtime

Ensure permissions are declared in AndroidManifest.xml
For iOS, add usage descriptions in Info.plist
Grant permissions manually in device settings

Debug Tools

Flutter Inspector

# While app is running, press 'v' to open DevTools
flutter run
# Press 'v'

Logging

Add debug logging to your code:

import 'dart:developer' as developer;

developer.log('Debug message', name: 'app.courier');

View logs:

flutter logs

Performance Optimization

Enable Code Shrinking (Android)

Edit android/app/build.gradle:

buildTypes {
    release {
        shrinkResources true
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
}

Optimize Images

Reduce asset size by compressing images:

# Install ImageMagick
convert assets/images/*.png -quality 85 assets/images/optimized/

Continuous Integration

GitHub Actions Example

name: Flutter CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    - uses: subosito/flutter-action@v2
      with:
        flutter-version: '3.7.2'
    
    - run: flutter pub get
    - run: flutter analyze
    - run: flutter test
    - run: flutter build apk --release

Next Steps

Quick Start

Get your first build running

Architecture

Learn about the app architecture

Development

Start building features

Configuration

Configure your environment

Get Started

Core Features

User Guides

Configuration

​System Requirements

​Minimum Requirements

Operating System

Hardware

Software

IDE (Choose one)

​Prerequisites Installation

​Step 1: Install Flutter SDK

​Step 2: Install Platform-Specific Tools

​Install Android Studio

​Configure Android SDK

​Verify Android setup:

​Install Xcode

​Install CocoaPods

​Accept Xcode License

​Verify iOS setup:

​Step 3: Install IDE and Extensions

​Project Setup

​Clone and Initialize

​Configuration

​API Configuration

​Environment Configuration

​Android Configuration

​Permissions

​App Name and Icon

​iOS Configuration

​Info.plist Permissions

​Bundle Identifier

​Assets Setup

​Build and Run

​Debug Build

​Release Build

​Profile Build (Performance Testing)

​Testing

​Run Tests

​Code Analysis

​Troubleshooting

​Common Build Issues

​Debug Tools

​Flutter Inspector

​Logging

​Performance Optimization

​Enable Code Shrinking (Android)

​Optimize Images

​Continuous Integration

​GitHub Actions Example

​Next Steps

Quick Start

Architecture

Development

Configuration

Build docs developers (and LLMs) love

System Requirements

Minimum Requirements

Prerequisites Installation

Step 1: Install Flutter SDK

Step 2: Install Platform-Specific Tools

Install Android Studio

Configure Android SDK

Verify Android setup:

Install Xcode

Install CocoaPods

Accept Xcode License

Verify iOS setup:

Step 3: Install IDE and Extensions

Project Setup

Clone and Initialize

Configuration

API Configuration

Environment Configuration

Android Configuration

Permissions

App Name and Icon

iOS Configuration

Info.plist Permissions

Bundle Identifier

Assets Setup

Build and Run

Debug Build

Release Build

Profile Build (Performance Testing)

Testing

Run Tests

Code Analysis

Troubleshooting

Common Build Issues

Debug Tools

Flutter Inspector

Logging

Performance Optimization

Enable Code Shrinking (Android)

Optimize Images

Continuous Integration

GitHub Actions Example

Next Steps