# android/sunflower architecture

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

- Interactive diagram: https://gitdiagram.com/android/sunflower
- Repository: https://github.com/android/sunflower

## Overview

##### Project Type and Purpose
- The project is an Android application sample that focuses on showcasing best practices for using Jetpack Compose. It was originally a View-based app and has been migrated to use Compose for UI, thus serving as both an educational tool and a reference implementation.
- The README and file tree indicate that Sunflower leverages modern Android libraries such as Compose, utilizes the Unsplash API for loading images, and implements best practices like dependency injection (DI) and MVVM architecture.

##### Analyzing the File Structure
- Top-level directories such as “app” and “macrobenchmark” indicate distinct modules:
- The “macrobenchmark” directory shows a separate module dedicated to performance benchmarking.
- Within the “app” module, observe subdirectories such as:
- “src/main/java/com/google/samples/apps/sunflower/compose” – This houses the Jetpack Compose UI components (screens, composable functions, UI themes, and utilities).
- “src/main/java/com/google/samples/apps/sunflower/data” – This holds the data layer including data models, DAOs, database configuration (likely using Room), repositories (for garden plantings, plants, and Unsplash-related data), and converters.
- “src/main/java/com/google/samples/apps/sunflower/api” – Contains an Unsplash service for interacting with the external API, which introduces an external dependency.
- “src/main/java/com/google/samples/apps/sunflower/di” – This directory is clearly dedicated to dependency injection. Modules for database and networking are defined here.
- “src/main/java/com/google/samples/apps/sunflower/viewmodels” – Contains the ViewModel classes that mediate between the UI and business logic.
- “src/main/java/com/google/samples/apps/sunflower/workers” – Where background tasks, such as seeding the database, are handled through Android workers.
- Additionally, there are comprehensive sets of UI layout resources in “src/main/res”, test suites in “src/test” and “src/androidTest”, and CI/CD configuration in “.github” directories.

##### Key Architectural Components & Their Flow
a. UI Layer:
- Uses Jetpack Compose for building screens. Components such as “PlantListScreen”, “PlantDetailView”, “GalleryScreen”, and “HomeScreen” reside in the compose directories.
- Although Compose is the central UI framework, a fallback is provided through AndroidViewBinding for legacy TextViews embedded in Compose.
b. ViewModel Layer:
- Acts as the mediator between the UI and data sources. Files in the “viewmodels” directory manage the state and logic for various screens.
c. Data Layer:
- Contains repositories which abstract the source of data (from either local Room database or network sources).
- Database operations are handled via DAO classes and an AppDatabase defined in the “data” package.
d. Network/API Layer:
- The Unsplash API service (via “UnsplashService.kt”) and associated paging source function to fetch and display images in the gallery screen.
e. Dependency Injection (DI):
- The DI modules (DatabaseModule.kt, NetworkModule.kt) define how dependencies (database, network clients, etc.) are provided.
f. Background Processing:
- Workers such as “SeedDatabaseWorker.kt” are part of the background pipeline for preloading/seed data.
g. Benchmarking Module:
- The “macrobenchmark” module facilitates performance testing, ensuring that UI and API integrations perform efficiently.

##### Architectural Patterns & Design Principles
- MVVM (Model-View-ViewModel): Clearly visible from the separation of the UI (Compose) and underlying business logic (ViewModels) and data handling (repositories/DAOs).
- Dependency Injection: Implemented via DI modules that encapsulate the creation and lifetime management of core components.
- Modular Architecture: Separation between main application code and benchmarking tests, and clear modules dividing UI, data, network, and DI aspects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Android Sunflower Architecture"
        AppModule["Main Application (App Module)"]
        UILayer["UI Layer (Jetpack Compose Screens)"]
        ViewModels["View Models"]
        DataLayer["Data/Repository Layer"]
        NetworkLayer["Network/API Layer"]
        DI["Dependency Injection"]
        Workers["Background Processing (Workers)"]
        Benchmarking["Benchmarking Module"]
    end

    AppModule -->|"initializes"| UILayer
    UILayer -->|"calls"| ViewModels
    ViewModels -->|"accesses"| DataLayer
    DataLayer -->|"fetchesDataFrom"| NetworkLayer
    DI -->|"providesTo"| ViewModels
    DI -->|"providesTo"| DataLayer
    DI -->|"providesTo"| NetworkLayer
    DI -->|"providesTo"| Workers
    Workers -->|"populates"| DataLayer
    AppModule -->|"integrates"| DI
    AppModule -->|"hosts"| Workers
    Benchmarking -->|"tests"| AppModule

    classDef app fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ui fill:#a3d5ff,stroke:#333,stroke-width:2px;
    classDef vm fill:#aaffaa,stroke:#333,stroke-width:2px;
    classDef data fill:#ffeb99,stroke:#333,stroke-width:2px;
    classDef api fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef di fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef worker fill:#ffd9b3,stroke:#333,stroke-width:2px;
    classDef bench fill:#d9d9d9,stroke:#333,stroke-width:2px;

    class AppModule app;
    class UILayer ui;
    class ViewModels vm;
    class DataLayer data;
    class NetworkLayer api;
    class DI di;
    class Workers worker;
    class Benchmarking bench;

    click AppModule "https://github.com/android/sunflower/tree/main/app"
    click UILayer "https://github.com/android/sunflower/tree/main/app/src/main/java/com/google/samples/apps/sunflower/compose"
    click ViewModels "https://github.com/android/sunflower/tree/main/app/src/main/java/com/google/samples/apps/sunflower/viewmodels"
    click DataLayer "https://github.com/android/sunflower/tree/main/app/src/main/java/com/google/samples/apps/sunflower/data"
    click NetworkLayer "https://github.com/android/sunflower/blob/main/app/src/main/java/com/google/samples/apps/sunflower/api/UnsplashService.kt"
    click DI "https://github.com/android/sunflower/tree/main/app/src/main/java/com/google/samples/apps/sunflower/di"
    click Workers "https://github.com/android/sunflower/blob/main/app/src/main/java/com/google/samples/apps/sunflower/workers/SeedDatabaseWorker.kt"
    click Benchmarking "https://github.com/android/sunflower/tree/main/macrobenchmark"
```
