Add mobile storage standards documentation

docs/mobile_standards.md

@@ -61,7 +61,11 @@ In short: “Crash early, fix quickly, and handle gracefully where it matters.
 
 - Nullable types are handled appropriately with safe calls and nullability checks.
 - Use of Kotlin's built-in null safety features where necessary.
-- Change Java files to Kotlin when Java-Kotlin intercompatibility introduces unnecessary and significant boilerplate code. 
+- Change Java files to Kotlin when Java-Kotlin intercompatibility introduces unnecessary and significant boilerplate code.
+
+### Mobile Data Storage
+
+- [Sqlite vs Shared Preferences](https://github.com/dimagi/open-source/blob/master/docs/mobile_storage_standards.md)
 
 ### Async Processing
 

docs/mobile_storage_standards.md

@@ -0,0 +1,68 @@
+# Mobile Storage: SQLite DB vs Shared Preferences
+
+## Use Shared Preferences for:
+
+Small, simple key-value data such as:
+
+* Theme / dark mode
+* Feature flags
+* First launch completed
+* Last sync timestamp
+* Selected language
+* User settings
+* Small primitive user state like number of times a user has been shown a specific prompt or reminder
+
+**Best when:**
+
+* Few values
+* Simple reads/writes
+* No querying needed
+* UI State
+
+---
+
+## Use SQLite DB for:
+
+Structured, growing, or queryable data such as:
+
+* Lists of records
+* Forms / submissions
+* Messages / history
+* Downloaded content
+* Offline business data
+* Queues / retries
+* Parent-child relationships
+* Data from Server APIs (generally structured persistent data)
+
+**Best when:**
+
+* Many records
+* Need search / sort / filter
+* Need transactions
+* Data evolves over time
+
+---
+
+## Quick Decision Rule
+
+| If data is...           | Use                |
+| ----------------------- | ------------------ |
+| App settings / flags    | Shared Preferences |
+| Single values           | Shared Preferences |
+| Records / lists         | SQLite             |
+| Searchable / filterable | SQLite             |
+| Growing over time       | SQLite             |
+
+---
+
+## Avoid
+
+* Using Shared Preferences for non-volatile data that might need backward compatibility or migrations across app versions
+* Using SQLite for isolated flags or intermediate properties
+
+---
+
+## Team Principle
+
+* If data is state → Shared Preferences
+* If data is records → SQLite**