# canopas/cloud-gallery architecture

> Architecture diagram of the GitHub repository canopas/cloud-gallery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/canopas/cloud-gallery
- Repository: https://github.com/canopas/cloud-gallery

## Overview

##### Project Type and Purpose
- The README clearly states that Cloud Gallery is a Flutter open-source project for viewing, uploading, and organizing photos and videos from both local storage and cloud services.
- It provides cross-platform compatibility (mobile, desktop, web) and uses cloud APIs for Google Drive and Dropbox.

##### File Structure
- The top-level directories include “app” (the Flutter application), “data” (backend logic such as APIs, domain models, services, repositories, and storage), and “style” (UI themes, fonts, animations, and components).
- Within the “app” directory, the structure is organized into native project setups (android, ios, linux, macos, windows, web), Flutter assets, and modularized Dart code under “lib”.
- The “lib” folder further divides into components, domain, UI flows (like albums, onboard, home, media transfer, media preview, etc.), and navigation, which indicates an MVVM (Model-View-ViewModel) approach combined with clean architecture and modularization.
- Configuration files (workflows under .github, pubspec.yaml in various modules) and platform-specific configuration (e.g., Android’s build.gradle, iOS’s project files) round out the architecture.

##### Main Components
a. Presentation/UI Layer (Flutter App)
- Core Components: Main screens (Onboard, Home, Albums, Accounts, Media Preview, Media Selection, and Media Transfer).
- UI Widgets, Components, Navigation (using Go Router Navigation 2.0 with code generation).
- Presentation state management using Riverpod.
b. Domain & Business Logic
- Domain Models: Media, Album, Dropbox entities, and tokens, among others.
- Use Cases and Formatters: DateFormatter, DurationFormatter, error handling extensions, etc.
- MVVM architecture: ViewModels (or State Notifiers) that handle UI logic and state transitions.
c. Data Layer
- Service APIs: Separate modules for Dropbox API, Google Drive API, and Local Media Services.
- Network: HTTP clients and interceptors using Dio, handling authentication (OAuth2).
- Repositories: Media process repository linking business logic to data sources.
- Storage: Local storage management with Shared Preferences and SQFLite.
d. Cloud Provider Integration
- Integration modules for both Google Drive and Dropbox, including API endpoints and interceptors.
e. Platform-Specific Modules
- Native modules for Android, iOS, macOS, Linux, Windows, and Web that focus on app packaging, deployment configuration, and platform-specific integrations.

##### Relationships & Data Flow
- User interactions occur in the UI layer which communicates with corresponding ViewModels or State Notifiers.
- The ViewModels invoke domain-level logic (e.g., handling media uploads, initiating cloud sync) via service classes or use-case functions.
- Data services (in the “data” layer) then make network/API calls to Google Drive or Dropbox through designated API service classes, including data conversion and error handling.
- The flow goes back up the stack, with responses updating the UI via the ViewModels.
- Local data storage (through SQFLite or SharedPreferences) interacts with service components if offline or for caching purposes.

##### Architectural Patterns & Design Principles
- Clean Architecture / MVVM: Separation of presentation (UI), domain (business logic), and data layers to promote modularity and testability.
- Flutter Modularization: Separation of code into self-contained modules (UI flows, components, domain logic) with dependency injection and type-safe navigation.
- Use of Dependency Injection for loosely-coupled components, plugging in third-party libraries (Dio, Riverpod, etc.).
- Code Generation: For navigation and possibly model mapping (using Freezed, JSON converters).

##### Relevant Technologies and Frameworks
- Flutter & Dart (for cross-platform UI)
- Riverpod (state management)
- Dio (network requests with interceptors)
- Google Drive API / Dropbox API (cloud integrations)
- SQFLite, Shared Preferences (for local storage)
- Go Router & Go Router Builder (for navigation)
- Crashlytics, Analytics, and Code Generation using Freezed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI/Presentation Layer
    subgraph "UI/Presentation Layer"
        UI["Flutter App UI: Onboard,Home,Albums,Accounts,MediaPreview,MediaTransfer"]:::ui
    end

    %% MVVM/ViewModels Layer
    subgraph "MVVM/ViewModels"
        AVM["Accounts ViewModel"]:::view
        HVM["Home ViewModel"]:::view
    end

    %% Domain & Business Logic Layer
    subgraph "Domain/Business Logic"
        Domain["Domain Models & Use Cases"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        Data["Repositories,Services,Network&Storage"]:::data
    end

    %% Cloud Provider Services
    subgraph "Cloud Provider Services"
        Dropbox["Dropbox API Integration"]:::cloud
        GDrive["Google Drive API Integration"]:::cloud
        LocalMedia["Local Media Service"]:::cloud
    end

    %% Platform Specific Modules
    subgraph "Platform Specific Modules"
        Android["Android"]:::platform
        iOS["iOS"]:::platform
        Linux["Linux"]:::platform
        macOS["macOS"]:::platform
        Windows["Windows"]:::platform
        Web["Web"]:::platform
    end

    %% Data Flow Connections
    UI -->|"triggers"| AVM
    UI -->|"triggers"| HVM

    AVM -->|"calls"| Domain
    HVM -->|"calls"| Domain

    Domain -->|"dataRequest"| Data

    Data -->|"sync/upload"| Dropbox
    Data -->|"sync/upload"| GDrive
    Data -->|"localAccess"| LocalMedia

    Dropbox -->|"response"| Data
    GDrive -->|"response"| Data
    LocalMedia -->|"response"| Data

    Domain -->|"update"| AVM
    Domain -->|"update"| HVM

    %% Packaging Connections
    UI -->|"packagedFor"| Android
    UI -->|"packagedFor"| iOS
    UI -->|"packagedFor"| Linux
    UI -->|"packagedFor"| macOS
    UI -->|"packagedFor"| Windows
    UI -->|"packagedFor"| Web

    %% Click Events
    click UI "https://github.com/canopas/cloud-gallery/tree/main/app/lib/ui"
    click AVM "https://github.com/canopas/cloud-gallery/blob/main/app/lib/ui/flow/accounts/accounts_screen_view_model.dart"
    click HVM "https://github.com/canopas/cloud-gallery/blob/main/app/lib/ui/flow/home/home_screen_view_model.dart"
    click Domain "https://github.com/canopas/cloud-gallery/tree/main/app/lib/domain"
    click Data "https://github.com/canopas/cloud-gallery/tree/main/data/lib"
    click Dropbox "https://github.com/canopas/cloud-gallery/tree/main/data/lib/apis/dropbox"
    click GDrive "https://github.com/canopas/cloud-gallery/tree/main/data/lib/apis/google_drive"
    click LocalMedia "https://github.com/canopas/cloud-gallery/blob/main/data/lib/services/local_media_service.dart"
    click Android "https://github.com/canopas/cloud-gallery/tree/main/app/android"
    click iOS "https://github.com/canopas/cloud-gallery/tree/main/app/ios"
    click Linux "https://github.com/canopas/cloud-gallery/tree/main/app/linux"
    click macOS "https://github.com/canopas/cloud-gallery/tree/main/app/macos"
    click Windows "https://github.com/canopas/cloud-gallery/tree/main/app/windows"
    click Web "https://github.com/canopas/cloud-gallery/tree/main/app/web"

    %% Styles
    classDef ui fill:#b3cde0,stroke:#000,stroke-width:2px;
    classDef view fill:#ccebc5,stroke:#000,stroke-width:2px;
    classDef domain fill:#decbe4,stroke:#000,stroke-width:2px;
    classDef data fill:#fed9a6,stroke:#000,stroke-width:2px;
    classDef cloud fill:#fbb4ae,stroke:#000,stroke-width:2px;
    classDef platform fill:#ffffcc,stroke:#000,stroke-width:2px;
```
