# petercxy/shelter architecture

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

- Interactive diagram: https://gitdiagram.com/petercxy/shelter
- Repository: https://github.com/petercxy/shelter

## Overview

Shelter is an Android app for managing an isolated Work Profile: the user provisions the profile, browses its apps, and can install or clone apps and freeze or unfreeze them. MainActivity coordinates profile services, while ShelterService exposes profile operations and DummyActivity handles operations requiring an activity result. The README also documents automatic freezing and cross-profile file access. These links use the README, tree, and sampled excerpts; some subsystem wiring is inferred only where explicitly supported by those sources.

Main entry points: [`app/src/main/java/net/typeblog/shelter/ui/MainActivity.java`](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/MainActivity.java) (Main activity), [`app/src/main/java/net/typeblog/shelter/ui/DummyActivity.java`](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/DummyActivity.java) (Operation activity), [`app/src/main/java/net/typeblog/shelter/services/ShelterService.java`](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/ShelterService.java) (Profile service), [`app/src/main/java/net/typeblog/shelter/util/SettingsManager.java`](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/SettingsManager.java) (Settings manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Profile setup"]
  node_wizard["Setup wizard"]
end

subgraph group_management["App management"]
  node_main["Main activity<br/>[MainActivity.java]"]
  node_dummy["Operation activity<br/>[DummyActivity.java]"]
  node_app_list["Work app list"]
  node_adapter["App list adapter"]
end

subgraph group_services["Profile services"]
  node_shelter_service["Profile service"]
  node_aidl["Service IPC"]
  node_device_policy["Device policy APIs"]
  node_freeze["Auto-freeze service<br/>[FreezeService.java]"]
  node_killer["Service cleanup<br/>[KillerService.java]"]
  node_storage[("Local preferences")]
  node_settings["Settings manager"]
end

subgraph group_integrations["Cross-profile features"]
  node_documents["Cross-profile documents"]
  node_shuttle["File shuttle"]
  node_payment["Payment stub"]
end

node_user(("User"))
node_android["Android system"]

node_user -->|"opens"| node_main
node_user -->|"starts setup"| node_wizard
node_wizard -->|"requests provisioning"| node_android
node_main -->|"binds services"| node_shelter_service
node_main -->|"shows apps"| node_app_list
node_app_list -->|"invokes"| node_aidl
node_aidl -->|"dispatches IPC"| node_shelter_service
node_app_list -->|"renders apps"| node_adapter
node_shelter_service -->|"queries profile"| node_device_policy
node_shelter_service -->|"launches install"| node_dummy
node_dummy -->|"performs install"| node_android
node_dummy -->|"hides apps"| node_device_policy
node_main -->|"starts work actions"| node_dummy
node_freeze -->|"freezes apps"| node_device_policy
node_freeze -->|"receives screen lock"| node_android
node_main -->|"starts cleanup"| node_killer
node_killer -->|"stops services"| node_shelter_service
node_settings -->|"reads and writes"| node_storage
node_settings -->|"toggles components"| node_android
node_dummy -->|"applies settings"| node_settings
node_documents -.->|"bridges file access"| node_shuttle
node_shuttle -->|"reads files"| node_android
node_settings -->|"enables component"| node_payment
node_payment -->|"handles APDU"| node_android

click node_main "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/MainActivity.java"
click node_wizard "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/SetupWizardActivity.java"
click node_dummy "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/DummyActivity.java"
click node_app_list "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/AppListFragment.java"
click node_adapter "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/AppListAdapter.java"
click node_shelter_service "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/ShelterService.java"
click node_aidl "https://github.com/petercxy/shelter/blob/master/app/src/main/aidl/net/typeblog/shelter/services/IShelterService.aidl"
click node_freeze "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/FreezeService.java"
click node_killer "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/KillerService.java"
click node_storage "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/LocalStorageManager.java"
click node_settings "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/SettingsManager.java"
click node_documents "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/CrossProfileDocumentsProvider.java"
click node_shuttle "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/FileShuttleService.java"
click node_payment "https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/PaymentStubService.java"

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_wizard,node_user toneBlue
class node_main,node_dummy,node_app_list,node_adapter toneAmber
class node_shelter_service,node_aidl,node_device_policy,node_freeze,node_killer,node_storage,node_settings toneMint
class node_documents,node_shuttle,node_payment toneRose
class node_android toneIndigo
```

## Components

### Profile setup

- [Setup wizard](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/SetupWizardActivity.java): `app/src/main/java/net/typeblog/shelter/ui/SetupWizardActivity.java`

### App management

- [Main activity](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/MainActivity.java): `app/src/main/java/net/typeblog/shelter/ui/MainActivity.java`
- [Operation activity](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/DummyActivity.java): `app/src/main/java/net/typeblog/shelter/ui/DummyActivity.java`
- [Work app list](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/AppListFragment.java): `app/src/main/java/net/typeblog/shelter/ui/AppListFragment.java`
- [App list adapter](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/ui/AppListAdapter.java): `app/src/main/java/net/typeblog/shelter/ui/AppListAdapter.java`

### Profile services

- [Profile service](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/ShelterService.java): `app/src/main/java/net/typeblog/shelter/services/ShelterService.java`
- [Service IPC](https://github.com/petercxy/shelter/blob/master/app/src/main/aidl/net/typeblog/shelter/services/IShelterService.aidl): `app/src/main/aidl/net/typeblog/shelter/services/IShelterService.aidl`
- **Device policy APIs**
- [Auto-freeze service](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/FreezeService.java): `app/src/main/java/net/typeblog/shelter/services/FreezeService.java`
- [Service cleanup](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/KillerService.java): `app/src/main/java/net/typeblog/shelter/services/KillerService.java`
- [Local preferences](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/LocalStorageManager.java): `app/src/main/java/net/typeblog/shelter/util/LocalStorageManager.java`
- [Settings manager](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/SettingsManager.java): `app/src/main/java/net/typeblog/shelter/util/SettingsManager.java`

### Cross-profile features

- [Cross-profile documents](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/util/CrossProfileDocumentsProvider.java): `app/src/main/java/net/typeblog/shelter/util/CrossProfileDocumentsProvider.java`
- [File shuttle](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/FileShuttleService.java): `app/src/main/java/net/typeblog/shelter/services/FileShuttleService.java`
- [Payment stub](https://github.com/petercxy/shelter/blob/master/app/src/main/java/net/typeblog/shelter/services/PaymentStubService.java): `app/src/main/java/net/typeblog/shelter/services/PaymentStubService.java`

### Other components

- **User**
- **Android system**

## Connections

- User → Main activity: opens
- User → Setup wizard: starts setup
- Setup wizard → Android system: requests provisioning
- Main activity → Profile service: binds services
- Main activity → Work app list: shows apps
- Work app list → Service IPC: invokes
- Service IPC → Profile service: dispatches IPC
- Work app list → App list adapter: renders apps
- Profile service → Device policy APIs: queries profile
- Profile service → Operation activity: launches install
- Operation activity → Android system: performs install
- Operation activity → Device policy APIs: hides apps
- Main activity → Operation activity: starts work actions
- Auto-freeze service → Device policy APIs: freezes apps
- Auto-freeze service → Android system: receives screen lock
- Main activity → Service cleanup: starts cleanup
- Service cleanup → Profile service: stops services
- Settings manager → Local preferences: reads and writes
- Settings manager → Android system: toggles components
- Operation activity → Settings manager: applies settings
- Cross-profile documents → File shuttle: bridges file access
- File shuttle → Android system: reads files
- Settings manager → Payment stub: enables component
- Payment stub → Android system: handles APDU