# 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](./architecture.md) | [Next: Authentication & Login](./login-flow.md)