immish/docs/structure.md

Project Structure

This document explains the organization of the mobile app codebase.

Top-Level Directory Structure

mobile/
├── lib/                    # Main application code
├── assets/                 # Static assets (images, fonts, animations)
├── fonts/                  # Custom fonts
├── openapi/                # Auto-generated API client
├── integration_test/       # Integration tests
├── test/                   # Unit tests
├── android/                # Android platform code
├── ios/                    # iOS platform code
└── pigeon/                 # Native platform interface definitions

Main Source Directory (lib/)

Core Application

lib/
├── main.dart               # App entry point
├── constants/              # App-wide constants
│   ├── constants.dart      # General constants
│   ├── enums.dart          # Enumerations
│   ├── errors.dart         # Error definitions
│   ├── colors.dart         # Color definitions
│   └── locales.dart        # Supported locales

Domain Layer

lib/domain/
├── interfaces/             # Abstract interfaces
├── models/                 # Domain models
│   ├── album/              # Album models
│   ├── asset/              # Asset models
│   ├── user.model.dart     # User model
│   ├── person.model.dart   # Person (face) model
│   ├── memory.model.dart   # Memory model
│   └── ...
├── services/               # Domain services
│   ├── asset.service.dart
│   ├── timeline.service.dart
│   ├── local_sync.service.dart
│   └── ...
└── utils/                  # Domain utilities

Services Layer

lib/services/
├── api.service.dart        # API client wrapper
├── auth.service.dart       # Authentication
├── backup.service.dart     # Photo backup
├── album.service.dart      # Album management
├── search.service.dart     # Search functionality
├── download.service.dart   # Asset download
├── share.service.dart      # Sharing
├── trash.service.dart      # Trash management
├── memory.service.dart     # Memories
├── partner.service.dart    # Partner sharing
├── background.service.dart # Background tasks
└── ...

Repository Layer

lib/repositories/
├── api.repository.dart         # Base API repository
├── asset.repository.dart       # Asset data access
├── album.repository.dart       # Album data access
├── auth.repository.dart        # Auth data access
├── auth_api.repository.dart    # Auth API calls
├── album_api.repository.dart   # Album API calls
├── asset_api.repository.dart   # Asset API calls
├── backup.repository.dart      # Backup state
├── download.repository.dart    # Download management
└── ...

Infrastructure Layer

lib/infrastructure/
├── entities/               # Database entities
│   ├── remote_asset.entity.dart
│   ├── local_asset.entity.dart
│   ├── remote_album.entity.dart
│   ├── user.entity.dart
│   └── ...
├── repositories/           # Infrastructure repositories
│   ├── db.repository.dart  # Database access
│   ├── api.repository.dart # HTTP client
│   └── ...
├── loaders/                # Image loaders
│   ├── image_request.dart
│   ├── local_image_request.dart
│   └── remote_image_request.dart
└── utils/                  # Infrastructure utilities

State Management (Providers)

lib/providers/
├── api.provider.dart           # API service provider
├── auth.provider.dart          # Auth state
├── asset.provider.dart         # Asset state
├── db.provider.dart            # Database provider
├── websocket.provider.dart     # WebSocket connection
├── theme.provider.dart         # Theme state
├── user.provider.dart          # User state
├── album/                      # Album providers
├── backup/                     # Backup providers
├── search/                     # Search providers
├── timeline/                   # Timeline providers
├── asset_viewer/               # Asset viewer providers
└── ...

UI Layer - Pages

lib/pages/
├── login/
│   ├── login.page.dart         # Login screen
│   └── change_password.page.dart
├── photos/
│   ├── photos.page.dart        # Main timeline
│   └── memory.page.dart        # Memory view
├── search/
│   ├── search.page.dart        # Search screen
│   ├── all_people.page.dart    # People browser
│   ├── all_places.page.dart    # Places browser
│   └── map/                    # Map views
├── albums/
│   └── albums.page.dart        # Albums list
├── album/
│   ├── album_viewer.page.dart  # Album detail
│   ├── album_options.page.dart # Album settings
│   └── ...
├── library/
│   ├── library.page.dart       # Library home
│   ├── favorite.page.dart      # Favorites
│   ├── archive.page.dart       # Archive
│   ├── trash.page.dart         # Trash
│   ├── locked/                 # Locked folder
│   ├── partner/                # Partner pages
│   └── ...
├── backup/
│   ├── backup_controller.page.dart
│   ├── backup_album_selection.page.dart
│   └── ...
├── common/
│   ├── splash_screen.page.dart # Splash screen
│   ├── settings.page.dart      # Settings
│   ├── gallery_viewer.page.dart# Asset viewer
│   └── ...
├── editing/
│   ├── edit.page.dart          # Image editor
│   ├── crop.page.dart          # Crop tool
│   └── filter.page.dart        # Filters
└── onboarding/
    └── permission_onboarding.page.dart

UI Layer - Widgets

lib/widgets/
├── common/                     # Shared widgets
│   ├── immich_app_bar.dart
│   ├── immich_image.dart
│   ├── immich_thumbnail.dart
│   ├── immich_loading_indicator.dart
│   └── ...
├── asset_grid/                 # Grid components
│   ├── multiselect_grid.dart
│   ├── asset_grid_data_structure.dart
│   └── ...
├── asset_viewer/               # Viewer components
│   ├── gallery_app_bar.dart
│   ├── bottom_gallery_bar.dart
│   ├── detail_panel/
│   └── ...
├── album/                      # Album components
├── backup/                     # Backup components
├── search/                     # Search components
├── settings/                   # Settings components
├── memories/                   # Memory components
├── map/                        # Map components
└── forms/                      # Form components
    └── login/
        └── login_form.dart

Routing

lib/routing/
├── router.dart             # Route definitions
├── auth_guard.dart         # Authentication guard
├── duplicate_guard.dart    # Prevent duplicate routes
├── backup_permission_guard.dart
├── gallery_guard.dart
└── locked_guard.dart

Models

lib/models/
├── auth/
│   ├── login_response.model.dart
│   └── auxilary_endpoint.model.dart
├── backup/
│   ├── backup_candidate.model.dart
│   ├── current_upload_asset.model.dart
│   └── error_upload_asset.model.dart
├── albums/
├── search/
├── shared_link/
├── upload/
└── ...

Utilities

lib/utils/
├── bootstrap.dart          # App initialization
├── image_url_builder.dart  # URL construction
├── hash.dart               # Hashing utilities
├── debounce.dart           # Debounce helper
├── throttle.dart           # Throttle helper
├── diff.dart               # List diffing
├── migration.dart          # Database migration
├── hooks/                  # Custom hooks
└── cache/                  # Caching utilities

Extensions

lib/extensions/
├── asset_extensions.dart
├── string_extensions.dart
├── datetime_extensions.dart
├── build_context_extensions.dart
└── ...

Theming

lib/theme/
├── theme_data.dart         # Theme definitions
├── color_scheme.dart       # Color schemes
└── dynamic_theme.dart      # Dynamic theming

Platform Communication

lib/platform/
├── background_worker_api.g.dart
├── connectivity_api.g.dart
├── local_image_api.g.dart
├── network_api.g.dart
└── ...

Generated Code

Some code is auto-generated:

• openapi/ - API client from OpenAPI spec
• *.g.dart - Code generation (serialization, providers)
• *.drift.dart - Database schema

Test Structure

test/
├── services/               # Service tests
├── domain/                 # Domain tests
├── infrastructure/         # Repository tests
├── modules/                # Feature module tests
├── fixtures/               # Test data stubs
└── mocks/                  # Mock objects

---

Previous: Architecture Overview | Next: Authentication & Login