# grapheneos/apps architecture

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

- Interactive diagram: https://gitdiagram.com/grapheneos/apps
- Repository: https://github.com/grapheneos/apps

## Overview

This is the GrapheneOS Apps app store: users browse and search a repository, inspect package details, and initiate package installation or updates. The tree also shows background update checking and automatic updates, settings, notifications, and an RPC entry point. The sampled code confirms repository retrieval and signature verification, UI navigation and refresh, and installer-session tracking; other subsystem links are limited to what the tree and excerpts support.

Main entry points: [`app/src/main/java/app/grapheneos/apps/core/PackageStates.kt`](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/PackageStates.kt) (Package state), [`app/src/main/java/app/grapheneos/apps/core/RepoRetriever.kt`](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/RepoRetriever.kt) (Repository retrieval), [`app/src/main/java/app/grapheneos/apps/ui/MainActivity.kt`](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/MainActivity.kt) (Main activity), [`app/src/main/java/app/grapheneos/apps/ui/DetailsScreen.kt`](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/DetailsScreen.kt) (Package details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_main_activity["Main activity<br/>[MainActivity.kt]"]
  node_package_screens["Package screens<br/>[PackagesScreen.kt]"]
  node_search_screen["Search<br/>[SearchScreen.kt]"]
  node_details_screen["Package details<br/>[DetailsScreen.kt]"]
  node_updates_screen["Updates screen<br/>[UpdatesScreen.kt]"]
  node_settings_screen["Settings<br/>[SettingsScreen.kt]"]
end

subgraph group_catalog["Repository and state"]
  node_package_states["Package state<br/>[PackageStates.kt]"]
  node_repo["Repository model<br/>[Repo.kt]"]
  node_repo_retriever["Repository retrieval<br/>[RepoRetriever.kt]"]
  node_verifier["Signature verifier<br/>[FileVerifier.kt]"]
  node_repo_cache[("Repository cache<br/>[AtomicFile2.kt]")]
end

subgraph group_install["Package installation"]
  node_installer_start["Install start<br/>[InstallStart.kt]"]
  node_install_task["Install task<br/>[InstallTask.kt]"]
  node_installer_sessions["Installer sessions"]
  node_rpc_provider["RPC provider<br/>[RpcProvider.kt]"]
end

subgraph group_background["Background operations"]
  node_auto_prefs["Update preferences<br/>[AutoUpdatePrefs.kt]"]
  node_check_job["Update check job<br/>[UpdateCheckJob.kt]"]
  node_auto_job["Auto-update job<br/>[AutoUpdateJob.kt]"]
  node_notifications["Notifications<br/>[Notifications.kt]"]
  node_download_service["Download service"]
end

node_user(("User"))
node_rpc_client(("RPC client"))
node_system_installer["Android installer"]
node_repository_service["Repository server"]

node_user -->|"opens"| node_main_activity
node_main_activity -->|"requests refresh"| node_package_states
node_main_activity -->|"navigates"| node_package_screens
node_user -->|"searches"| node_search_screen
node_user -->|"selects package"| node_details_screen
node_user -->|"reviews updates"| node_updates_screen
node_user -->|"configures"| node_settings_screen
node_package_screens -->|"observes state"| node_package_states
node_search_screen -->|"uses package state"| node_package_states
node_details_screen -->|"uses package state"| node_package_states
node_updates_screen -->|"observes state"| node_package_states
node_package_states -->|"requests repository"| node_repo_retriever
node_repo_retriever -->|"fetches metadata"| node_repository_service
node_repo_retriever -->|"verifies signature"| node_verifier
node_repo_retriever -->|"reads and writes"| node_repo_cache
node_repo_retriever -->|"parses metadata"| node_repo
node_package_states -->|"uses repository"| node_repo
node_details_screen -->|"starts install"| node_installer_start
node_installer_start -->|"creates task"| node_install_task
node_install_task -->|"uses sessions"| node_installer_sessions
node_installer_sessions -->|"manages sessions"| node_system_installer
node_rpc_client -.->|"calls"| node_rpc_provider
node_rpc_provider -.->|"initiates install"| node_installer_start
node_settings_screen -->|"configures updates"| node_auto_prefs
node_auto_prefs -->|"schedules"| node_check_job
node_auto_prefs -->|"schedules"| node_auto_job
node_check_job -->|"checks repository"| node_package_states
node_auto_job -->|"checks package state"| node_package_states
node_install_task -->|"keeps download alive"| node_download_service
node_download_service -->|"builds notification"| node_notifications

click node_main_activity "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/MainActivity.kt"
click node_package_screens "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/PackagesScreen.kt"
click node_search_screen "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/SearchScreen.kt"
click node_details_screen "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/DetailsScreen.kt"
click node_updates_screen "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/UpdatesScreen.kt"
click node_settings_screen "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/SettingsScreen.kt"
click node_package_states "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/PackageStates.kt"
click node_repo "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/Repo.kt"
click node_repo_retriever "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/RepoRetriever.kt"
click node_verifier "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/FileVerifier.kt"
click node_repo_cache "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/util/AtomicFile2.kt"
click node_installer_start "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/InstallStart.kt"
click node_install_task "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/InstallTask.kt"
click node_installer_sessions "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/InstallerSessions.kt"
click node_rpc_provider "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/RpcProvider.kt"
click node_auto_prefs "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/autoupdate/AutoUpdatePrefs.kt"
click node_check_job "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/autoupdate/UpdateCheckJob.kt"
click node_auto_job "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/autoupdate/AutoUpdateJob.kt"
click node_notifications "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/Notifications.kt"
click node_download_service "https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/PackageDownloadFgService.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_activity,node_package_screens,node_search_screen,node_details_screen,node_updates_screen,node_settings_screen,node_user,node_rpc_client toneBlue
class node_package_states,node_repo,node_repo_retriever,node_verifier,node_repo_cache toneAmber
class node_installer_start,node_install_task,node_installer_sessions,node_rpc_provider,node_repository_service toneMint
class node_auto_prefs,node_check_job,node_auto_job,node_notifications,node_download_service toneRose
class node_system_installer toneIndigo
```

## Components

### App interface

- [Main activity](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/MainActivity.kt): `app/src/main/java/app/grapheneos/apps/ui/MainActivity.kt`
- [Package screens](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/PackagesScreen.kt): `app/src/main/java/app/grapheneos/apps/ui/PackagesScreen.kt`
- [Search](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/SearchScreen.kt): `app/src/main/java/app/grapheneos/apps/ui/SearchScreen.kt`
- [Package details](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/DetailsScreen.kt): `app/src/main/java/app/grapheneos/apps/ui/DetailsScreen.kt`
- [Updates screen](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/UpdatesScreen.kt): `app/src/main/java/app/grapheneos/apps/ui/UpdatesScreen.kt`
- [Settings](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/ui/SettingsScreen.kt): `app/src/main/java/app/grapheneos/apps/ui/SettingsScreen.kt`

### Repository and state

- [Package state](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/PackageStates.kt): `app/src/main/java/app/grapheneos/apps/core/PackageStates.kt`
- [Repository model](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/Repo.kt): `app/src/main/java/app/grapheneos/apps/core/Repo.kt`
- [Repository retrieval](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/RepoRetriever.kt): `app/src/main/java/app/grapheneos/apps/core/RepoRetriever.kt`
- [Signature verifier](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/FileVerifier.kt): `app/src/main/java/app/grapheneos/apps/core/FileVerifier.kt`
- [Repository cache](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/util/AtomicFile2.kt): `app/src/main/java/app/grapheneos/apps/util/AtomicFile2.kt`

### Package installation

- [Install start](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/InstallStart.kt): `app/src/main/java/app/grapheneos/apps/core/InstallStart.kt`
- [Install task](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/InstallTask.kt): `app/src/main/java/app/grapheneos/apps/core/InstallTask.kt`
- [Installer sessions](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/core/InstallerSessions.kt): `app/src/main/java/app/grapheneos/apps/core/InstallerSessions.kt`
- [RPC provider](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/RpcProvider.kt): `app/src/main/java/app/grapheneos/apps/RpcProvider.kt`

### Background operations

- [Update preferences](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/autoupdate/AutoUpdatePrefs.kt): `app/src/main/java/app/grapheneos/apps/autoupdate/AutoUpdatePrefs.kt`
- [Update check job](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/autoupdate/UpdateCheckJob.kt): `app/src/main/java/app/grapheneos/apps/autoupdate/UpdateCheckJob.kt`
- [Auto-update job](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/autoupdate/AutoUpdateJob.kt): `app/src/main/java/app/grapheneos/apps/autoupdate/AutoUpdateJob.kt`
- [Notifications](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/Notifications.kt): `app/src/main/java/app/grapheneos/apps/Notifications.kt`
- [Download service](https://github.com/grapheneos/apps/blob/main/app/src/main/java/app/grapheneos/apps/PackageDownloadFgService.kt): `app/src/main/java/app/grapheneos/apps/PackageDownloadFgService.kt`

### Other components

- **User**
- **RPC client**
- **Android installer**
- **Repository server**

## Connections

- User → Main activity: opens
- Main activity → Package state: requests refresh
- Main activity → Package screens: navigates
- User → Search: searches
- User → Package details: selects package
- User → Updates screen: reviews updates
- User → Settings: configures
- Package screens → Package state: observes state
- Search → Package state: uses package state
- Package details → Package state: uses package state
- Updates screen → Package state: observes state
- Package state → Repository retrieval: requests repository
- Repository retrieval → Repository server: fetches metadata
- Repository retrieval → Signature verifier: verifies signature
- Repository retrieval → Repository cache: reads and writes
- Repository retrieval → Repository model: parses metadata
- Package state → Repository model: uses repository
- Package details → Install start: starts install
- Install start → Install task: creates task
- Install task → Installer sessions: uses sessions
- Installer sessions → Android installer: manages sessions
- RPC client → RPC provider: calls
- RPC provider → Install start: initiates install
- Settings → Update preferences: configures updates
- Update preferences → Update check job: schedules
- Update preferences → Auto-update job: schedules
- Update check job → Package state: checks repository
- Auto-update job → Package state: checks package state
- Install task → Download service: keeps download alive
- Download service → Notifications: builds notification