### Overview

The app uses SharedPreferences for local data persistence approach to manage different data scopes. For different platforms (ios, android, desktops) this storage has different naming. All these implementation are covered under one umbrella of flutter library [shared\_preferences](https://pub.dev/packages/shared_preferences). 

This document describes the architecture, data flow, categorisation, and naming convention.

<br>

### Architecture

#### Core Components

1\. **PreferencesStorage** - Low-level wrapper around SharedPreferences  
2\. **MultiUserPreferencesStorage** - Helper for multi-user data storage  
3\. **SettingsRepository** - Repository layer for accessing settings  
4\. **Use Cases** - Business logic layer (GetUserSettingUseCase, SaveUserSettingUseCase)  
5\. **BLoCs** - Presentation layer that uses Use Cases

####   

#### Data Flow

```txt
BLoC/Service
    ↓ (uses)
Use Case (GetUserSettingUseCase/SaveUserSettingUseCase)
    ↓ (gets current userId)
UserRepository
    ↓ (passes userId to)
SettingsRepository
    ↓ (uses)
MultiUserPreferencesStorage
    ↓ (uses)
PreferencesStorage (SharedPreferences wrapper)
```

###   

### Data Categories

Currently preferences are organised into four categories based on their scope and lifecycle:

#### 1\. Multi-User Preferences

**Scope**: Per-user data  
**Lifecycle**: Persists across logout (for user switching support)  
**Storage Format**: \`{&quot;userId1&quot;: data1, &quot;userId2&quot;: data2}\`  
**Access**: Via Use Cases (GetUserSettingUseCase/SaveUserSettingUseCase)

#### 2\. App-Level Preferences

**Scope**: Application-wide settings  
**Lifecycle**: Persists across all sessions and users  
**Storage Format**: Direct key-value pairs  
**Access**: Direct repository access (no Use Cases needed)

#### 3\. Instance-Level Preferences

**Scope**: OpenProject server configuration  
**Lifecycle**: Persists until instance is changed  
**Storage Format**: Direct key-value pairs  
**Access**: Via InstanceConfigurationRepository

#### 4\. _Legacy Preferences_

_**Scope**: Deprecated keys pending migration_  
_**Lifecycle**: Various_  
_**Status**: Should not be used in new code_

<br>

### Preference Keys Reference

#### Multi-User Preferences

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Key</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Type</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Description</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Used In</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_bottom_bar_configs</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">BottomBarConfiguration</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Bottom navigation bar customization per user</p></td><td class="op-uc-table--cell"><p class="op-uc-p">BottomBarConfigurationRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_timers</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">Timer</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Active time tracking timers per user</p></td><td class="op-uc-table--cell"><p class="op-uc-p">TimeEntriesRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_work_package_settings</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">WorkPackageSettings</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Work package display preferences (sorting, filtering, activities display)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_local_notification_settings</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">LocalNotificationsSettings</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Local notification preferences (enabled/disabled, participants, weekdays)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_home_widgets</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">HomeDashboardWidgets</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Home dashboard widget configuration and visibility</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_push_enabled</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">bool</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Push notification toggle per user</p></td><td class="op-uc-table--cell"><p class="op-uc-p">PreferencesStorage (direct)</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_projects_last_sync</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">int (timestamp)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Last project sync timestamp for incremental sync</p></td><td class="op-uc-table--cell"><p class="op-uc-p">ProjectsSyncPreferences</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">multi_user_default_page</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">int</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Default launch page index (which tab opens on startup)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr></tbody></table></figure>

#### App-Level Preferences

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Key</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Type</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Description</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Used In</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">app_theme</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">String (ThemeMode)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">App theme mode: light, dark, or system</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">app_locale</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">String</p></td><td class="op-uc-table--cell"><p class="op-uc-p">User's selected language code (e.g., "en", "de")</p></td><td class="op-uc-table--cell"><p class="op-uc-p">LocaleRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">app_developer_settings</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">DeveloperSettings</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Developer mode settings and feature toggles</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">app_feature_flags</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">FeatureFlags</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Feature flags configuration (experimental features)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SettingsRepository</p></td></tr></tbody></table></figure>

#### Instance-Level Preferences

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Key</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Type</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Description</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Used In</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">instance_base_url</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">String</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OpenProject instance base URL</p></td><td class="op-uc-table--cell"><p class="op-uc-p">InstanceConfigurationRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">instance_client_id</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">String</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OAuth client ID for the instance</p></td><td class="op-uc-table--cell"><p class="op-uc-p">InstanceConfigurationRepository</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">instance_instances_map</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">Map&lt;String, String&gt;</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Map of instance URLs to client IDs for multi-instance support</p></td><td class="op-uc-table--cell"><p class="op-uc-p">InstanceConfigurationRepository</p></td></tr></tbody></table></figure>

#### Legacy Preferences (need to be reviewed)

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Key</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Type</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Description</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Status</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><code class="op-uc-code">unreadNotificationsIdsPrefKey</code></p></td><td class="op-uc-table--cell"><p class="op-uc-p">List&lt;int&gt;</p></td><td class="op-uc-table--cell"><p class="op-uc-p">IDs of unread notifications</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Used in background service, needs migration</p></td></tr></tbody></table></figure>

##   

### Naming Convention

Follow the naming convention for new keys:  
\- Multi-user: `multi_user_<descriptive_name>`  
\- App-level: `app_<descriptive_name>`  
\- Instance-level: `instance_<descriptive_name>`