Personal AI Mentor for Android

Personal AI Mentor for Android — Product & Build Specification #

Platform: Android only (native Kotlin, Jetpack Compose) · Audience: an AI coding agent or developer building the app from scratch

Overview #

Mentor is an Android-only, single-user, local-first AI mentor. On first launch the user connects their own AI provider (any OpenAI-compatible or Anthropic/Claude-compatible endpoint, with their own API key). They then complete a deep intake interview of 15 to 20 questions: 12 fixed core questions plus 3 to 8 follow-ups the AI writes for them. From these answers the app builds a profile and starts coaching across four areas: mindset, well-being, relationships and direction. Its feedback is honest and challenging, at a candor level the user chooses. The mentor remembers facts and patterns in a memory the user can edit. It produces insights about the user's personality, strengths and blind spots. It helps set clear, attainable goals and runs Personal Quests with a daily check-in.

Everything is stored encrypted on the phone. There is no account, no backend, no telemetry, no ads and no payment. The only network traffic is between the phone and the AI provider the user configured. The coaching method is an original framework called The Honest Compass (Section 9). It is built on public, non-proprietary psychology research, and its prompts can be edited in the app.

This document is self-contained. Each concern has one owning section, and other sections refer to it by number. Section 22 gives the build order. Section 23 tells the executor how to work through this document. Where a choice was open, it has been decided and recorded inline as a "Decision".

Table of Contents #

1. Before You Start
2. Product Overview & Vision
3. Technology Stack & Architecture
4. Conventions & Engineering Standards
5. Data Model & Local Storage
6. Security & Privacy
7. Data Export & Import
8. AI Provider Integration
9. Coaching Framework & Prompt Architecture
10. Onboarding & Deep Intake Interview
11. Mentor Chat
12. Memory System
13. Profile, Insights & Blind Spots
14. Goals & Direction
15. Quests & Daily Check-in
16. Notifications & Reminders
17. Settings, Provider Management & Prompt Editor
18. Design System
19. Navigation & Screen Inventory
20. Testing Strategy
21. Build, Release & Distribution
22. Milestones & Execution Plan
23. Executor Instructions

1. Before You Start #

1.1 How to use this section #

This document specifies a complete Android application. Before you write any code, settle the customization questions in Section 1.2. Each question has a working default. The defaults are production-quality choices, so a build made entirely from defaults is a complete, shippable product.

Procedure:

1. If you can talk to the person who commissioned the build, send one message that contains the whole table in Section 1.2 (question, default, and the allowed answers). Ask once. Do not ask follow-up questions on individual answers.
2. For every question that is not answered in that one reply, use the default.
3. If nobody can be asked, or nobody answers during your session, use every default.
4. Validate each answer against the "Allowed answers" column. An invalid answer is replaced by the default, and you record that substitution in step 5.
5. Create DECISIONS.md in the repository root before the first commit. Under the heading ## Customization answers, write one line per question in the form Q<n> <name>: <final value> (answered | default | default-substituted: <reason>). Every later deviation from this document is appended to the same file with a one-sentence reason.
6. Apply the answers exactly as described in Section 1.3, before milestone M1 begins (Section 22).

If no answers are given, build with every default — never block. Waiting for an answer is never an acceptable reason to stop work.

1.2 Customization questions and defaults #

Fixed values that are not customizable, because other sections depend on them as stable identifiers: Keystore aliases mentor_db_kek and mentor_secret_kek (Section 6), the DataStore file name mentor_prefs and its keys (Section 5), the backup file extension .mentorbackup and the magic header (Section 7), the notification channel ids checkin_reminders and quest_reminders (Section 16), the four coaching areas (Section 9), and the crisis-help link target (Section 6).

1.3 How each answer is applied #

1.4 Information the executor must not ask for #

The following are decided in this document and must never be put to the commissioner as questions: choice of libraries, module layout, database engine, encryption scheme, prompt wording, screen layouts, test strategy. If this document appears to be silent on a detail, choose the simplest option that satisfies the surrounding rules, record it in DECISIONS.md, and continue.

2. Product Overview & Vision #

2.1 What the product is #

"Mentor" (the default name; see Section 1) is an Android-only, single-user, local-first personal AI mentor. On first launch the user connects their own AI provider (any OpenAI-compatible or Anthropic-compatible endpoint). The user then completes a deep intake interview of 15–20 questions: 12 fixed core questions followed by 3–8 follow-ups that the connected model writes from the user's earlier answers. The app synthesises a personal profile and coaches the user in a chat-first experience across four coaching areas: Mindset, Well-Being, Relationships and Direction. It gives honest, challenging feedback at a candor level the user chooses, keeps an editable memory of facts and patterns, produces insights and blind spots, helps set clear and attainable goals, and runs Personal Quests with a daily check-in.

All data is encrypted on the phone. There is no account, no backend operated by the app's maker and no telemetry. The product is free, with no ads and no payments.

The product is inspired by popular AI-mentor apps built on modern self-help ideas. It does not reproduce anyone's text, branding or proprietary frameworks. Its coaching approach is an original framework (Section 9) grounded in public, non-proprietary research.

2.2 The problem #

Adults who want to grow run into four gaps:

1. Generic advice. Books, videos and generic chatbots do not know the person's situation, so the advice is broad and easy to ignore.
2. Flattery. Most AI assistants are tuned to agree and reassure. A person who needs to hear an uncomfortable truth, such as an avoided decision, a repeated pattern or a blind spot, rarely gets it.
3. No continuity. A conversation that ends is forgotten. Progress, commitments and patterns are not tracked, so each conversation starts from zero.
4. Privacy cost. Personal reflection is among the most sensitive data a person produces. Hosted coaching products ask the user to hand it to a company's servers and to create an account.

This product closes those gaps with a mentor that knows the user (intake, memory), is honest at the level the user asks for (candor), follows through (goals, quests, check-ins) and keeps everything on the phone, talking only to the AI provider the user selected.

2.3 Target users #

Adults seeking personal growth, direction and honest feedback who are comfortable with technology and are willing to bring their own AI provider so that their data stays on their phone. Two representative personas follow.

2.3.1 Persona 1: Maya, 29, product designer, "stuck at a crossroads" #

• Situation. Maya is deciding between a senior role at her current company and starting a freelance practice. She keeps going around in circles and talks about it with friends who tell her what she wants to hear.
• Setup. She already pays for an aggregator API account. During onboarding she picks the OpenRouter preset, pastes her key, taps "Test connection" and moves on.
• Scenario. After the intake, the Profile Reveal screen tells her that her answers show strong values around autonomy but a repeated pattern of delaying decisions until they are made for her. In the Direction area she asks, "Should I quit?" The mentor, at DIRECT candor, asks what she would do if no one would judge her, names the avoidance pattern kindly and plainly, and offers a goal card: "Decide by 30 November, using three conversations with freelancers". She adds the goal, starts a suggested quest with a daily step, and ticks it off in the evening check-in.
• What she needs from the product. Honest pushback, continuity from one chat to the next, small concrete next steps.

2.3.2 Persona 2: Daniel, 41, engineering manager, "privacy-conscious and overextended" #

• Situation. Daniel feels permanently on call, finds it hard to say no, and has strained relationships at home and at work. He distrusts cloud services with personal data and runs a model on a server in his home network.
• Setup. He picks the Ollama (LAN) preset, enters http://192.168.1.20:11434/v1, accepts the warning for plain HTTP on that provider, and chooses a model from the list the server returns.
• Scenario. In the Relationships area he describes an argument with his manager. The mentor reflects the feeling, separates what Daniel can control from what he cannot, and challenges him to state one boundary in an if-then plan. Later the memory list shows a new pattern, "Says yes to avoid conflict, then resents the workload", which Daniel edits to read more accurately. He exports an encrypted backup before changing phones.
• What he needs from the product. No account, no cloud, full control over what is remembered, the ability to delete or export everything, honest feedback that is not harsh.

2.4 Product principles #

These principles decide every ambiguous case in the rest of this document.

2.5 Feature summary #

2.6 Scope #

2.6.1 In scope for v1 #

• A native Android app (minSdk per Section 1, Q9), a single Activity, Jetpack Compose UI, English only, dark theme only.
• Everything in the feature summary in Section 2.5.
• Phone-side processing only: prompt assembly, memory retrieval, scoring of the personality assessment, crisis keyword detection, reminders, export and import.
• Calls from the phone directly to the user's configured provider endpoints.

2.6.2 Non-goals (out of scope for v1, and must not be built) #

2.7 Success criteria for v1 #

All criteria are measurable on the developer's machine or with the test devices below. None of them requires telemetry; nothing in the product measures or reports user behaviour.

Reference test targets: an API 28 emulator (2 GB RAM, 1080×2340) and an emulator on the latest stable API level. The automated instrumented suite runs on the managed device defined in Section 21.4.2; the API 28 and latest-API runs of the criteria below are part of the manual device matrix in Section 20.12.3, executed at milestones M2, M4, M5 and M11 (Section 22).

Every criterion has an owner: the last column names the automated test class (Section 20) or the milestone exit criterion (Section 22) that proves it.

2.8 Glossary #

Terms are capitalised in the specification where they refer to the concept defined here. The owning section holds the full rules.

3. Technology Stack & Architecture #

3.1 Version table #

All dependency versions are stated in this section only, as major/minor lines. Every other section says "the version in Section 3".

These version lines are a known-good floor, not a lockfile. At build time, install the current stable release of each dependency (npm install <pkg>@latest, or your ecosystem's equivalent), confirm the major line still matches, and let the lockfile record the exact resolved versions.

For this Gradle project the "ecosystem equivalent" is: read the latest stable release from the Google Maven repository and Maven Central (the maven-metadata.xml file of each artifact lists releases), skip alpha, beta, release-candidate and milestone releases, confirm that the major line (and, where a minor line is given, the minor line) matches the table, write the exact resolved version into gradle/libs.versions.toml, and let Gradle dependency locking record every transitive version (Section 3.8.5). Rows that say "Latest stable" have no fixed major line: use the newest stable release that supports the resolved Kotlin and AGP versions.

3.1.1 Dependencies that must not be added #

3.2 Platform requirements #

• Android 9 (API 28) and later by default. The UI is a single Activity, Compose only, portrait-first; landscape and large screens must remain usable (content width is capped by the design system, Section 18) but are not separately designed.
• The only permissions the app declares itself are INTERNET, POST_NOTIFICATIONS (requested at runtime only when a reminder toggle is switched on) and RECEIVE_BOOT_COMPLETED. Permissions merged in from AndroidX libraries are allowed within the allow-list in Section 21.5.4. No storage, contacts, location, camera, microphone or exact-alarm permission is declared (Sections 6, 16).

3.3 Architecture in one page #

• Pattern. MVVM with unidirectional data flow. A ViewModel exposes StateFlow<UiState>, receives user actions through onEvent(UiEvent), and sends one-shot effects (navigation, snackbar, share sheet) through a Channel.
• Data access. Repositories return Flow for observable reads and AppResult<T> for writes and network calls. Errors are values (Section 4.4); exceptions do not cross module boundaries except CancellationException.
• Dependency injection. Hilt. No service locators, no manual singletons.
• Concurrency. Kotlin coroutines and Flow only (Section 3.9).
• Background work. WorkManager for deferrable work: memory extraction, insight refresh, conversation summary. Reminders use AlarmManager.setWindow with a 15-minute window, so no exact-alarm permission is needed. Alarms are rescheduled on BOOT_COMPLETED, TIME_SET, TIMEZONE_CHANGED and MY_PACKAGE_REPLACED (Section 16). Quest expiry and suggestion cleanup are not background jobs: they run in the foreground reconciliation of Section 15.7.4.
• Persistence. Room over SQLCipher for all user content; DataStore Preferences for non-sensitive preferences; Android Keystore for key material (Sections 5, 6).
• Networking. OkHttp straight to the user's configured provider; no intermediary (Section 8).
• There is no server. The product has no backend of its own, so there is no server configuration, no environment file and no remote configuration. Configuration items are listed in Section 3.12.

3.4 Gradle modules and dependency rules #

Rules:

1. Dependencies point downward only, as drawn below. A cycle is a build error.
2. :core:model has no Android dependency.
3. :core:ai never sees Android storage, never reads the database and never decrypts anything: it receives a ready-to-use ResolvedProvider object (the provider configuration, the API key and custom header values wrapped in Secret, Section 6.6) created by ProviderRepository.resolveActive() in :core:data (Section 8.2.3).
4. :core:database exposes DAOs and entities only to :core:data. No feature code in :app imports a DAO or an entity class (entities live in app.mentor.core.database.entity; the :app module does not have :core:database on its compile classpath, see the implementation rule in Section 3.8.4).
5. Feature code in :app never imports from app.mentor.core.ai implementation packages; it uses the interfaces re-exported by :core:data.
6. :core:testing is added to other modules as testImplementation and androidTestImplementation only. It depends on :core:data while :core:data tests depend on it; this is allowed because test source sets are not consumed by dependants. The build fails if a non-test configuration depends on it (the test-only-guard plugin, Section 21.2.4).

                          +--------------------+
                          |        :app        |
                          +----------+---------+
                                     |
        +-------------+--------------+--------------+-----------------+
        |             |              |              |                 |
        v             v              v              |                 |
 :core:designsystem   |         :core:data <---------+                 |
        |             |        /   |   |   \                          |
        |             |       /    |   |    \                         |
        |             |      v     v   v     v                        |
        |             |  :core:ai  |   |  :core:security              |
        |             |      |     |   |        |                     |
        |             |      |     v   |        |                     |
        |             |      |  :core:database  |                     |
        |             |      |     |   |        |                     |
        +-------------+------+-----+---+--------+---------------------+
                              all of them depend on
                                  :core:model

The same relationship as a table of allowed edges (a module may use only the edges listed in its row):

:app gets :core:security only for the startup hook that shows the recovery screen; it never encrypts or decrypts. Hilt aggregates bindings across modules at the application level, so :app does not need compile access to implementation modules to use them through interfaces (Section 3.7).

3.4.1 The Limits object #

Every numeric limit used by more than one layer (maximum message length 4,000, memory content 500, goal title 80, and so on) is a named const val in app.mentor.core.model.Limits. The values are owned by the section that introduces them (data fields in Section 5, behaviour in Sections 10–16). Code and tests import the constant; a number literal that equals a limit is a review failure. The customizable intake follow-up bounds are Limits.INTAKE_FOLLOWUP_MIN and Limits.INTAKE_FOLLOWUP_MAX (Section 1, Q6).

3.5 Package structure inside each module #

The root package is app.mentor (customizable, Section 1 Q2). Module namespace: :app uses the root; others use <root>.core.<name>.

3.5.1 :app #

app.mentor
  MentorApplication.kt            // @HiltAndroidApp, WorkManager Configuration.Provider
  MainActivity.kt                 // single Activity, splash, FLAG_SECURE handling, notification-target intake
  startup/                        // StartupViewModel, StartupState, StartupFailure, StartupDestination, recovery screens
  navigation/                     // MentorNavHost, routes (@Serializable), bottom-bar model
  notification/                   // ReminderReceiver, RescheduleReceiver (boot, time change), notification tap routing (EXTRA_TARGET)
  feature/
    onboarding/                   // welcome, privacy and not-therapy screen, provider step, completion
    intake/                       // core questions, follow-ups, synthesis progress, Profile Reveal
    chat/                         // chat screen, conversation sheet, composer, suggestion cards
    memory/                       // memory list, detail/edit, archived, pause/delete-all
    insights/                     // insights list, Big Five assessment
    goals/                        // goals list, detail/edit, milestones, sharpen
    quests/                       // quest list, detail, suggestions, completion history
    checkin/                      // check-in screen, history (calendar + list)
    you/                          // profile summary, hub for memory, check-in history, settings
    settings/                     // settings, provider management, prompt editor, export/import UI, diagnostics
    common/                       // UiText, ErrorPresentation, shared feature helpers

Each feature/<name>/ package contains, as applicable: <Name>Route.kt (stateful entry point), <Name>Screen.kt (stateless), <Name>ViewModel.kt, <Name>Contract.kt (UiState, UiEvent, Effect), and a components/ subpackage. The screen inventory and route names are owned by Section 19.

3.5.2 :core:model (app.mentor.core.model) #

error/        AppError.kt, AppResult.kt, AppResultExt.kt, AppErrorExt.kt, CryptoReason.kt, TimeoutKind.kt, BackupErrorCode.kt
time/         AppClock.kt, LocalDateExt.kt
id/           IdGenerator.kt
log/          AppLogger.kt, LogLevel.kt
coaching/     CoachingArea.kt, Candor.kt
profile/      UserProfile.kt, ProfileSynthesis.kt
intake/       IntakeSession.kt, IntakeQuestion.kt, IntakeAnswer.kt
chat/         Conversation.kt, Message.kt, MessageRole.kt, MessageStatus.kt, SuggestionBlock.kt, SuggestionState.kt
memory/       MemoryItem.kt, MemoryKind.kt, MemorySource.kt, MemoryStatus.kt
insight/      Insight.kt, InsightCategory.kt, Confidence.kt, BigFiveScores.kt
goal/         Goal.kt, GoalMilestone.kt, GoalStatus.kt
quest/        Quest.kt, QuestStep.kt, QuestStatus.kt, QuestDifficulty.kt, QuestCadence.kt
checkin/      CheckIn.kt
provider/     ProviderConfig.kt, ProviderType.kt, ResolvedProvider.kt (ResolvedProvider, ResolvedHeader), Secret.kt
prompt/       PromptTemplateKey.kt, PromptTemplate.kt
ai/           task result DTOs (@Serializable) for structured outputs
Limits.kt, Defaults.kt

3.5.3 :core:designsystem (app.mentor.core.designsystem) #

theme/        MentorTheme.kt, Color.kt, Type.kt, Shape.kt, Spacing.kt, Elevation.kt
component/    shared composables (buttons, cards, inputs, chips, banners, dialogs, empty state)
icon/         MentorIcons.kt (references vector drawables)
preview/      MentorPreviews.kt (multipreview annotation), preview helpers
res/font/     inter.ttf, fraunces.ttf (variable fonts, Section 18.3.1)
res/drawable/ ic_*.xml

3.5.4 :core:security (app.mentor.core.security) #

keystore/     KeystoreKeyProvider.kt (key creation, StrongBox then TEE fallback)
passphrase/   DbPassphraseStore.kt (generate, wrap, unwrap, file at filesDir/keys)
secret/       SecretCipher.kt (AES-256-GCM encrypt/decrypt for API keys and header values)
backup/       BackupKeyDerivation.kt (PBKDF2 helpers used by export/import)
di/           SecurityModule.kt

3.5.5 :core:database (app.mentor.core.database) #

MentorDatabase.kt
DatabaseFactory.kt               // SQLCipher SupportOpenHelperFactory wiring
entity/                          // XxxEntity classes, one file per table
dao/                             // XxxDao interfaces
converter/                       // type converters (if Section 5 declares any)
migration/                       // Migration_N_M.kt
fts/                             // memory_item_fts entity and helpers
mapper/                          // Entity <-> domain mappers (toDomain, toEntity)
di/                              // DatabaseModule.kt
schemas/ (project dir)           // exported Room schema JSON, committed

3.5.6 :core:ai (app.mentor.core.ai) #

LlmClient.kt                     // interface
RoutingLlmClient.kt              // the bound LlmClient; delegates on ProviderType
HttpClients.kt                   // streaming / complete / models Call.Factory holder (Section 8.14)
openai/                          // OpenAiClient, request/response DTOs, SSE event mapping
anthropic/                       // AnthropicClient, DTOs, SSE event mapping
sse/                             // SseParser (line-based, shared)
structured/                      // StructuredOutputParser (fence stripping, brace slicing, repair retry hook)
token/                           // TokenEstimator
validation/                      // ProviderConfigValidator
http/                            // OkHttp extensions (suspend await), UrlPolicy (validate + normalize), CleartextGuardInterceptor, ErrorMapper (HTTP -> AppError)
di/                              // AiModule.kt

3.5.7 :core:data (app.mentor.core.data) #

repository/                      // interfaces (ChatRepository, ProviderRepository, PromptTemplateRepository, MemoryRepository, ...)
repository/impl/                 // implementations, bound by Hilt
usecase/                         // SendMessageUseCase, RegenerateReplyUseCase, intake use cases, ...
chat/                            // ChatStreamCoordinator, StreamingBuffer
prompt/                          // PromptAssembler, PromptRenderer, PromptDefaultsSynchronizer
memory/                          // MemoryRetriever, MemoryScorer, MemoryOperationsApplier, MemoryExtractionScheduler, IntakeMemorySeeder
safety/                          // CrisisDetector
quest/                           // QuestLifecycle (foreground reconciliation, Section 15.7.4)
worker/                          // MemoryExtractionWorker, InsightRefreshWorker, ConversationSummaryWorker
reminder/                        // ReminderScheduler, NextTrigger, NotificationHelper
backup/                          // BackupExporter, BackupImporter, BackupFormat, BackupMutex
prefs/                           // AppPreferences (DataStore)
time/                            // SystemAppClock, DayChangeObserver
log/                             // RoomAppLogger : AppLogger (diagnostic_log writer), LogSanitizer
startup/                         // AppInitializer
error/                           // defaultThrowableMapping
di/                              // DataModule.kt, DispatchersModule.kt, WorkModule.kt

There is no title worker and no suggestion-cleanup worker: conversation titles are generated in the application scope (Section 11.2.4) and old suggested quests are deleted by QuestLifecycle (Section 15.7.4).

3.5.8 :core:testing (app.mentor.core.testing) #

clock/        FakeAppClock
id/           FakeIdGenerator
ai/           FakeLlmClient, ScriptedStream, mock-server helpers
repository/   in-memory fake repositories
rule/         MainDispatcherRule, TestDispatchersModule
data/         builders: aMessage(), aMemoryItem(), aGoal(), ...

3.5.9 Canonical class names #

Each concept has exactly one class name in the whole document and in the code. A variant spelling is a review failure.

3.6 Layering rules #

The call direction is fixed:

Composable screen  ->  ViewModel  ->  Use case (optional)  ->  Repository  ->  DAO  /  LlmClient  /  DataStore  /  SecretCipher

Use cases are required in exactly these cases and optional elsewhere (a ViewModel may call a repository directly for simple CRUD). These names are canonical; the feature sections and the milestone plan use them unchanged:

Additional rules:

1. A repository's public API contains domain models only (from :core:model), never Room entities and never DTOs.
2. Writes that touch several tables run in one Room transaction owned by the repository (or a @Transaction DAO method).
3. A ViewModel never calls viewModelScope.launch to perform work that must survive the screen (chat replies, imports); such work runs in the application scope or WorkManager (Section 3.9).
4. State flows only downward as UiState; events flow only upward as UiEvent.

3.7 Dependency injection graph #

Hilt, one SingletonComponent graph plus ViewModelComponent for ViewModels. Hilt workers are created by HiltWorkerFactory from the singleton graph. No Activity-scoped or Fragment-scoped bindings exist.

Rules:

1. Constructor injection everywhere. Field injection only in Android entry points (Application, Activity, BroadcastReceiver).
2. @HiltViewModel for all ViewModels; SavedStateHandle is used for navigation arguments and the chat composer draft.
3. Qualifiers are the only way to request a dispatcher or scope. Hard-coding Dispatchers.IO outside DispatchersModule is forbidden (detekt rule InjectDispatcher). Code samples in this document follow the same rule.
4. Workers are @HiltWorker with @AssistedInject. WorkManager's automatic initialisation is switched off by removing only its meta-data entry from the androidx.startup provider (the XML is in Section 6.10, tools:node="remove" on androidx.work.WorkManagerInitializer). The provider itself is never removed, because it also initialises ProcessLifecycleOwner, which Sections 15.7.4 and 16.7 depend on.
5. MentorDatabase must not be touched before AppInitializer has finished the key unwrap (Section 3.10). Components that can run before the UI (workers, receivers) call appInitializer.awaitReady() first; it is idempotent and thread-safe (a single shared Deferred).
6. LlmClient is the singleton RoutingLlmClient; it holds no secret. The decrypted ResolvedProvider (secrets wrapped in Secret) is created per operation by ProviderRepository.resolveActive(), passed into the call, and never stored in a singleton field.

3.8 Gradle setup #

3.8.1 Repository layout #

settings.gradle.kts
build.gradle.kts                  // plugin declarations only (apply false), plus the resolveAndLockAll task (Section 3.8.5)
gradle.properties
gradle/libs.versions.toml         // version catalog
gradle/wrapper/
version.properties                // VERSION_NAME, VERSION_BUILD (Section 21.7.1)
build-logic/                      // included build with convention plugins (Section 21.2.4)
  settings.gradle.kts
  convention/build.gradle.kts
  convention/src/main/kotlin/...
config/detekt/detekt.yml
config/compose/stability.conf     // Compose stability configuration (Section 4.11)
.editorconfig
app/                              // gradle.lockfile in each module directory
core/{model,designsystem,security,database,ai,data,testing}/
DECISIONS.md
README.md

Each module directory (and build-logic) holds its own gradle.lockfile (Section 3.8.5).

3.8.2 settings.gradle.kts essentials #

• pluginManagement { includeBuild("build-logic"); repositories { google(); mavenCentral(); gradlePluginPortal() } }.
• dependencyResolutionManagement { repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS; repositories { google(); mavenCentral() } }. No other repository (no JitPack, no snapshots).
• Apply the Foojay toolchain resolver plugin so that JDK 21 can be provisioned automatically.
• include(":app", ":core:model", ":core:designsystem", ":core:security", ":core:database", ":core:ai", ":core:data", ":core:testing").
• Enable type-safe project accessors (enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") if the resolved Gradle major line still requires it).

3.8.3 Version catalog (gradle/libs.versions.toml) #

Structure, with every version filled with the exact release resolved at build time (the placeholders below show the key names only):

[versions]
kotlin = "<resolved 2.4.x>"
ksp = "<resolved, matches kotlin>"
agp = "<resolved 9.x>"
composeBom = "<resolved 2026.x>"
hilt = "<resolved 2.x>"
androidxHilt = "<resolved 1.x>"
room = "<resolved 2.8.x>"
sqlcipher = "<resolved 4.x>"
androidxSqlite = "<resolved 2.x>"
okhttp = "<resolved 5.x>"
serializationJson = "<resolved 1.x>"
coroutines = "<resolved 1.x>"
datetime = "<resolved 0.x>"
compileSdk = "36"        # or the latest stable API level
targetSdk = "36"         # equal to compileSdk
minSdk = "28"            # Section 1, Q9

[libraries]
# one entry per artifact in Section 3.1, e.g.
# room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
# compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }

[bundles]
compose = [ui, ui-graphics, ui-tooling-preview, foundation, material3, activity-compose, navigation-compose]   # no material-icons artifacts
unit-test = [junit, coroutines-test, turbine, mockk, robolectric]
android-test = [androidx-test-runner, androidx-test-rules, androidx-test-ext-junit, compose-ui-test-junit4, hilt-android-testing, room-testing, work-testing]

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
room = { id = "androidx.room", version.ref = "room" }
ktlint = { id = "org.jlleitschuh.gradle.ktlint", version = "<resolved>" }
detekt = { id = "<dev.detekt or io.gitlab.arturbosch.detekt>", version = "<resolved>" }
kover = { id = "org.jetbrains.kotlinx.kover", version = "<resolved>" }
aboutlibraries = { id = "com.mikepenz.aboutlibraries.plugin", version = "<resolved>" }

Build modules only use libs.* accessors; a version string in any build.gradle.kts is a review failure.

3.8.4 Convention plugins (decision: yes, in an included build-logic build) #

Eight modules would otherwise repeat the same fifty lines, so shared build configuration lives in the included build-logic build. The plugin ids (app.mentor.convention.android-application, android-library, kotlin-jvm, hilt, compose, quality and test-only-guard), what each applies and what each configures are defined once, in Section 21.2.4. Lint policy is Section 21.3.3, signing is Section 21.7.2, and the dependency-locking rule is Section 3.8.5.

Decisions kept in this section:

• Bytecode. The toolchain is JDK 21 (so the build runs on a current, supported JDK), but Android modules and :core:model compile to Java 17 bytecode (jvmTarget = 17, sourceCompatibility/targetCompatibility = JavaVersion.VERSION_17) for the widest D8/R8 desugaring support. Do not set any module to 21 bytecode.
• Dependency configurations. Modules declare dependencies with implementation, not api, except :core:data, which exposes :core:model through api (domain models appear in its public API). :app declares implementation(project(":core:data")), :core:model, :core:designsystem and :core:security; it does not declare :core:database or :core:ai, so the compiler enforces rule 4 and rule 5 in Section 3.4. Hilt generated components reach those modules through the Hilt Gradle plugin's aggregating mode (enableAggregatingTask), which is on by default.
• Warnings. Kotlin warnings are errors in every module (allWarningsAsErrors = true). Android lint warnings are reported and the fatal list of Section 21.3.3 is promoted to errors.

3.8.5 Dependency locking #

1. Every project applies the quality convention plugin (Section 21.2.4), which calls dependencyLocking { lockAllConfigurations() }. Lockfiles are gradle.lockfile in each module directory, using Gradle's default lock mode.

2. ./gradlew dependencies --write-locks resolves only the configurations of the project it runs in, so the root build registers one task that resolves every resolvable configuration of every project:

   Copy

   tasks.register("resolveAndLockAll") {
       notCompatibleWithConfigurationCache("resolves configurations")
       doFirst { require(gradle.startParameter.isWriteDependencyLocks) }
       doLast { allprojects.forEach { p -> p.configurations.filter { it.isCanBeResolved }.forEach { it.resolve() } } }
   }

3. Generate locks once after resolving versions: ./gradlew resolveAndLockAll --write-locks (and ./gradlew -p build-logic dependencies --write-locks for the build-logic build). Commit every gradle.lockfile.

4. Update intentionally with ./gradlew resolveAndLockAll --write-locks --update-locks '*:*', review the diff, then run the full verification (Section 4.13).

5. Verification builds run in Gradle's default mode: a changed resolution without a lock update fails the build.

3.8.6 gradle.properties #

org.gradle.jvmargs=-Xmx3g -Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
kotlin.code.style=official
android.useAndroidX=true
android.nonTransitiveRClass=true

Room schema export is configured only through the Room Gradle plugin, in :core:database: room { schemaDirectory("$projectDir/schemas") }. Do not set the room.schemaLocation KSP argument as well: the plugin fails the build when both are present. The exported schema JSON files are committed (Section 5).

3.8.7 Build types #

The full property table is in Section 21.3.2. No product flavors exist.

3.9 Threading and dispatchers #

Rules:

1. Only the code that owns a dispatcher qualifier switches context (withContext(io) in repositories and clients, never in ViewModels).
2. Streamed text updates reach the UI at most every 50 ms (batched), so Compose does not recompose per token.
3. Process death: composer drafts and navigation arguments survive through SavedStateHandle; intake answers are saved per question (Section 10). A streamed reply is persisted as a placeholder message row with status = STREAMING that the coordinator checkpoints about every 2 seconds; after process death the row is recovered at the next start and the chat shows the retry affordance. The row lifecycle is owned by Section 11.6 (recovery in Section 11.6.7) and the columns by Section 5.4.5.

3.10 App startup sequence #

Goal: from process start to first interactive frame in ≤ 2.0 s (Section 2.7, S1), with nothing that touches user content running on the main thread.

StartupState is a sealed interface: Loading, Ready(destination), Failed(failure: StartupFailure) and MigrationBlocked(kind) (the migration-blocked case is specified in Section 5.9). StartupFailure carries the failure outcomes of the startup gate defined in Section 6.4.1:

@Serializable
enum class StartupFailure {
    KEY_UNRECOVERABLE, BLOB_CORRUPT, BLOB_MISSING, DB_UNREADABLE, DB_MISSING, KEYSTORE_UNAVAILABLE,
}

Components that run without the Activity (alarm receiver, boot receiver, workers) call appInitializer.awaitReady() before touching the database. awaitReady runs steps 2.0–2.3 if they have not yet run in this process and returns AppResult<Unit>.

3.11 End-to-end data flows #

Class names introduced here are the canonical names used by the feature sections (Section 3.5.9).

3.11.1 Sending a chat message with streaming #

1. Tap send. ChatScreen emits ChatUiEvent.SendClicked. ChatViewModel trims the draft; it ignores the event if the text is empty or a reply is already streaming in this conversation, and shows the over-length hint for more than 4,000 characters (Limits.MESSAGE_MAX). It clears the draft and calls SendMessageUseCase(conversationId, text).
2. Crisis check. CrisisDetector.check(text) runs locally (Section 6). On a hit, ChatViewModel shows the crisis card; the message is still sent.
3. Persist the user message. ChatRepository.insertUserMessage writes a message row (new UUID, next seq, created_at from AppClock, crisis_flagged from step 2). Room re-emits the message Flow, so the bubble appears at once.
4. Resolve the provider. ProviderRepository.resolveActive() returns a ResolvedProvider (the secrets are decrypted just-in-time with SecretCipher and wrapped in Secret), or AppError.NoProviderConfigured, or AppError.ProviderNeedsKey when the provider's key is not on this phone (Section 8.2.3).
5. Insecure URL check. UrlPolicy.validate(baseUrl, allowInsecureHttp) returns AppError.InsecureUrlBlocked for plain HTTP when the provider's toggle is off (Section 8).
6. Assemble the prompt. PromptAssembler.assemble(conversationId, tokenBudget) follows the order and budgets in Section 9: framework, coaching-area text, candor text, profile summary, up to 12 relevant memories (≤ 1,500 tokens, retrieved by MemoryRetriever), active goals and quests, today's check-in, rolling summary, output-format rules, safety block; then history newest-first until the budget is used. If older history had to be dropped and no valid rolling summary covers it, the chat still sends; ConversationSummaryWorker is enqueued after the reply as decided by Section 11.14.2.
7. Start the stream. SendMessageUseCase hands over to ChatStreamCoordinator, a singleton that runs in @ApplicationScope (so leaving the screen does not cancel the reply). The coordinator inserts the MENTOR placeholder row (status = STREAMING, empty content) and collects llmClient.streamChat(provider, request) on @IoDispatcher. Events: text deltas, completion, error.
8. Display. Deltas append to an in-memory StreamingBuffer for that conversation. The repository publishes the buffer content as a StateFlow<StreamingState> at most every 50 ms, and the coordinator writes the buffer to the placeholder row about every 2 seconds (Section 11.6.1). A suggestion-block filter withholds any text from an opening fence tagged mentor-goal or mentor-quest until the block closes, so raw JSON never flashes on screen. The ViewModel merges StreamingState with the persisted messages into ChatUiState.
9. Completion. On the end event: finalise the placeholder row (status = COMPLETE, content stored verbatim, model name, token estimate); update the conversation's updated_at and last_message_at; clear the buffer; call MemoryExtractionScheduler.enqueue(conversationId, 10) (Section 12.3.2); if this was the first exchange, run title generation in the application scope (Section 11.2.4). Suggestion blocks are parsed at render time (Section 9.8) and their card state is stored in suggestion_state and suggestion_entity_id (Section 5.4.5).
10. Errors. An error before any text arrived is retried by :core:ai according to Section 8 (up to two retries). An error after text arrived is never retried automatically: the partial text stays visible, the row becomes FAILED with error_code, and an inline error with "Try again" appears. The AppError is shown with the copy in Section 4.5.
11. Stop. ChatUiEvent.StopClicked cancels the streaming job. The OkHttp call is cancelled; the row becomes STOPPED when it has text (an empty placeholder row is deleted) (Section 11.6.4); AppError.Cancelled is never displayed.
12. Process death mid-stream. The user message and the checkpointed placeholder row are in the database. At the next start the recovery routine of Section 11.6.7 deletes an empty STREAMING row or marks one with text FAILED, and the chat shows the retry affordance.

3.11.2 Memory extraction job #

Section 12.3 owns the full behaviour; this is the end-to-end summary.

1. Trigger. Three triggers call MemoryExtractionScheduler.enqueue(conversationId, delayMinutes) (Section 12.3.2), which enqueues the unique work memory_extract_<conversationId>: (a) a completed or stopped mentor reply (10-minute initial delay, so a busy conversation extracts once after it goes quiet); (b) the user taps "End session" or starts a new session (no delay); (c) startup re-enqueue (Section 3.10, step 2.6). The work is not expedited. Constraint: NetworkType.CONNECTED. Input data: the conversation id only (no content).

2. Start. MemoryExtractionWorker (@HiltWorker) calls appInitializer.awaitReady().

3. Guards. If memory_paused is true, no provider is active, or the provider needs its key, return success without work. Load the messages with seq greater than the conversation's last_extracted_seq (Section 5.4.4). If there are fewer than two new user messages (or fewer than 60 characters in total, Section 12.3.1), return success.

4. Build the request. RunMemoryExtractionUseCase renders the memory_extraction template (Section 9) with the new transcript chunk, up to 40 existing memories (pinned first, then by retrieval score, Section 12.3.5) and the format rules. Non-streaming call, temperature 0.2, default max output tokens for this task (Section 8).

5. Call and parse. llmClient.complete(...) then StructuredOutputParser (strip code fences, first { to last }, ignoreUnknownKeys, validation). On a parse or validation failure the parser sends the error back for one repair retry (Section 8); a second failure yields AppError.ParseFailure.

6. Apply operations in one transaction. The model returns at most 8 operations and the app applies at most 8 (Section 9.6.13). For each: ADD (validate content 1–500 characters and importance 1–5, skip near-duplicates), UPDATE(id) (the id must exist, be ACTIVE and not user-locked), ARCHIVE(id) (status becomes ARCHIVED). When active items exceed 1,000, archive the oldest, lowest-importance, unpinned items until the count is 1,000. In the same transaction advance last_extracted_seq to the last processed message. After the commit, increment insights_stale_counter as Section 12.2.6 specifies.

7. Result mapping (Section 12.3.8 owns the table; at most 3 attempts, exponential backoff from 30 seconds):

   Outcome	Worker result
   Success	Result.success()
   Network, Offline, Timeout, RateLimited, ProviderServer, StreamInterrupted, InvalidResponse, EmptyResponse	Result.retry() until the third attempt, then Result.failure(); the cursor is not moved, so the next trigger processes the same messages
   NoProviderConfigured, ProviderNeedsKey	Result.success() without work (the next trigger tries again)
   Auth, QuotaExceeded, ModelNotFound, EndpointNotFound, ProviderMisconfigured, TlsFailure, BadRequest, ContextTooLong, ContentFiltered, InsecureUrlBlocked, Crypto, StorageFull, Unknown	Result.failure() immediately; the cursor is not moved
   ParseFailure	Result.retry() on attempts 1 and 2; on the third attempt the cursor advances past the current chunk without changing memories, so a chunk the model cannot handle does not block extraction forever

   Every non-success outcome writes one diagnostic-log row with the error code only (Section 4.7).

8. Observation. The Memory screen observes the memory Flow, so new items appear without any explicit notification.

3.12 Configuration items #

The product has no server, no environment file and no remote configuration. The complete list of configuration is:

There are no other configuration items. In particular, no URL, key or identifier of the app's maker is compiled into the app.

4. Conventions & Engineering Standards #

These conventions apply to every module and every milestone. A rule marked "enforced" is checked by a tool; a rule marked "review" is checked against the Definition of Done in Section 4.13.

4.1 Kotlin style and static analysis #

4.1.1 Style #

• Follow the official Kotlin coding conventions and the ktlint_official code style. Four-space indentation, no tabs, maximum line length 120, trailing commas on declaration sites and call sites when the construct spans several lines, final newline in every file.
• No wildcard imports. Imports are ordered lexicographically with java, javax and kotlin imports last (the ktlint default).
• Prefer val to var, immutable data classes, sealed interface for closed hierarchies, enum class for fixed sets, object only for stateless singletons and constants.
• Explicit visibility: everything is internal unless another module needs it. The public API of a module is deliberate; explicitApi() is not enabled, and review checks that nothing is public by accident.
• No !! (enforced). Use safe calls, requireNotNull(x) { "reason" } or checkNotNull(x) { "reason" } for true invariants, or return an AppResult.
• No TODO(), FIXME, STOPSHIP, commented-out code, or placeholder implementations in committed code (enforced by the detekt ForbiddenComment rule).
• Functions do one thing and fit on a screen: at most 60 lines for non-Composable functions (enforced).
• Expression bodies for one-line functions. Named arguments for any call with two or more arguments of the same type, or with a boolean literal.
• KDoc on every public class, interface and function that is not self-evident from its name; no KDoc that merely repeats the name.
• Comments explain why, never what. No author tags, no dates, no ticket numbers.

4.1.2 .editorconfig #

The repository root contains an .editorconfig with at least:

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4

[*.{kt,kts}]
ktlint_code_style = ktlint_official
max_line_length = 120
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma_on_call_site = true
ij_kotlin_imports_layout = *,java.**,javax.**,kotlin.**,^
ktlint_function_naming_ignore_when_annotated_with = Composable
ktlint_standard_filename = enabled
ktlint_standard_no-wildcard-imports = enabled

[*.{xml,json,toml,yml,yaml,md}]
indent_size = 2

4.1.3 detekt rules (decided) #

config/detekt/detekt.yml starts from the detekt defaults (buildUponDefaultConfig = true) with maxIssues: 0 and no baseline file. A violation is fixed or the code is changed; it is never suppressed with @Suppress unless the line carries a comment explaining why, and each such suppression is limited to the rules listed under "Allowed suppressions" below. Code style formatting is enforced by ktlint (Section 4.1.4), not by a detekt formatting ruleset. The plugin wiring is in Section 21.2.4 and the remaining thresholds are mirrored in Section 21.3.3.

Allowed suppressions (each with an inline reason): TooGenericExceptionCaught in appCatching; MagicNumber in migration files; LongMethod/LargeClass in generated or schema-mirroring code only; ForbiddenMethodCall for android.util.Log inside the debug-only Logcat mirror of RoomAppLogger (Section 4.7.1), which is the single place allowed to import android.util.Log.

4.1.4 Commands #

• Format: ./gradlew ktlintFormat.
• Verify (must pass with zero findings): ./gradlew ktlintCheck detekt. The aggregate CI gate ciGate (Section 21.4.1) runs both.
• Kotlin warnings are errors (allWarningsAsErrors = true, Section 3.8.4). Android lint reports warnings and fails on the fatal list of Section 21.3.3.

4.2 Naming conventions #

Class names are canonical across the document (Section 3.5.9); a second spelling of the same concept is a review failure.

4.2.1 Database naming #

4.2.2 Resource naming #

4.3 IDs and time handling #

4.3.1 IDs #

• Every row id is a UUID v4 string in the canonical lowercase hyphenated form, generated in application code through the injected IdGenerator (fun newId(): String; production implementation UuidIdGenerator uses UUID.randomUUID().toString()). The database never generates ids.
• Exceptions: prompt_template uses its key as the primary key (Section 5); check_in is identified by its local_date uniqueness as defined in Section 5 but still has a UUID id; diagnostic_log.id is an auto-increment integer (Section 5.4.17).
• Ids are opaque: no code parses them, orders by them, or encodes meaning in them.
• Tests use FakeIdGenerator, which returns id-1, id-2, … or a supplied sequence.

4.3.2 Time #

• Time is read only through the injected AppClock. System.currentTimeMillis(), Instant.now(), LocalDate.now() and Clock.System are forbidden outside SystemAppClock (review).

package app.mentor.core.model.time

import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone

interface AppClock {
    /** Current instant as epoch milliseconds, UTC. */
    fun nowMillis(): Long

    /** The device's current time zone. */
    fun timeZone(): TimeZone

    /** The current calendar day in [timeZone]. */
    fun today(): LocalDate
}

• The production SystemAppClock (in :core:data) uses the standard library clock for nowMillis() and TimeZone.currentSystemDefault() for timeZone(). FakeAppClock in :core:testing has settable nowMillis and timeZone and a helper advanceBy(duration).
• Persisted instants are epoch milliseconds UTC as Long. Columns end in _at. Domain models hold Long, not Instant.
• local_date rules.
  1. local_date is the ISO yyyy-MM-dd calendar day of the event in the device time zone at the moment the event is recorded: Instant.fromEpochMilliseconds(createdAt).toLocalDateTime(clock.timeZone()).date.
  2. It is stored once and never recomputed. If the user later changes time zone, old rows keep their dates.
  3. Days roll over at local midnight. Daylight-saving shifts are handled by the time-zone rules; a day may have 23 or 25 hours.
  4. A "day" in a comparison (check-in of the day, today's quest steps, streaks, quest day index) always means local_date. Counting days between two local dates uses daysUntil on LocalDate, never millisecond arithmetic.
  5. A check-in is editable only while its local_date equals clock.today().
  6. Features that show "today" must update when the day changes while the app is open. DayChangeObserver (:core:data) registers a receiver for ACTION_DATE_CHANGED, ACTION_TIME_CHANGED and ACTION_TIMEZONE_CHANGED while the process is alive, using ContextCompat.registerReceiver(context, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED) (lint UnspecifiedRegisterReceiverFlag is fatal), and exposes today: StateFlow<LocalDate>; ViewModels that depend on the current day combine with it. On resume, the observer re-reads the clock.
• kotlinx-datetime is used for LocalDate, LocalTime, LocalDateTime, TimeZone, DayOfWeek and conversions only. Durations use kotlin.time.Duration. Date arithmetic uses the library's own operations (LocalDate.minus(1, DateTimeUnit.DAY), LocalDate.daysUntil(other), LocalDateTime.toInstant(TimeZone)), never java.time methods such as minusDays. LocalDate in every section means kotlinx.datetime.LocalDate.
• java.time is used only in the UI layer for formatting. NextTrigger (Section 16.6.1) uses kotlinx-datetime (LocalDateTime.toInstant(TimeZone)), not java.time; its inputs come from AppClock.
• Display formatting (UI layer only, through helper functions in :app feature/common): dates with DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM), times with DateTimeFormatter.ofLocalizedTime(FormatStyle.SHORT), both with the device locale so the system 12/24-hour setting is honoured; relative labels "Today" and "Yesterday" for the current and previous local_date; message timestamps inside a conversation show time only for today and date plus time otherwise.
• Reminder times are stored as HH:mm strings in DataStore (Section 5) and interpreted in the device's current time zone each time the alarm is scheduled.

4.4 AppResult and AppError #

4.4.1 AppResult #

Every operation that can fail for a reason the user or the program can act on returns AppResult. It lives in :core:model (app.mentor.core.model.error).

sealed interface AppResult<out T> {
    data class Ok<out T>(val value: T) : AppResult<T>
    data class Err(val error: AppError) : AppResult<Nothing>
}

inline fun <T, R> AppResult<T>.map(transform: (T) -> R): AppResult<R> = when (this) {
    is AppResult.Ok -> AppResult.Ok(transform(value))
    is AppResult.Err -> this
}

inline fun <T, R> AppResult<T>.flatMap(transform: (T) -> AppResult<R>): AppResult<R> = when (this) {
    is AppResult.Ok -> transform(value)
    is AppResult.Err -> this
}

inline fun <T> AppResult<T>.onOk(block: (T) -> Unit): AppResult<T> = also { if (it is AppResult.Ok) block(it.value) }
inline fun <T> AppResult<T>.onErr(block: (AppError) -> Unit): AppResult<T> = also { if (it is AppResult.Err) block(it.error) }
fun <T> AppResult<T>.getOrNull(): T? = (this as? AppResult.Ok)?.value
fun <T> AppResult<T>.errorOrNull(): AppError? = (this as? AppResult.Err)?.error

Rules:

1. Expected failures (network, parsing, validation, storage, crypto) are Err values, not exceptions.
2. Programming errors (violated invariants) throw IllegalStateException or IllegalArgumentException through check/require; they are not converted into AppError.
3. CancellationException is never converted into an AppResult; it is always rethrown. The AppError.Cancelled case is produced only by user-initiated stop actions that complete normally (for example the Stop button in chat).
4. Repository reads return Flow<T>. A storage failure inside a read flow is caught inside the repository with the catch operator, logged, and turned into an empty result; a ViewModel never sees a raw Throwable.

4.4.2 AppError hierarchy #

AppError lives in :core:model. It carries no user-facing text (the text is in strings.xml, Section 4.8). code is a stable identifier used by the diagnostic log (Section 4.7). This hierarchy is the only one: the provider layer (Section 8), the security layer (Section 6) and the backup code (Section 7) all use these cases, and no section may add a case without changing this one.

package app.mentor.core.model.error

sealed class AppError(val code: String) {
    /** No provider has been saved or none is active. */
    data object NoProviderConfigured : AppError("NO_PROVIDER")

    /** The active provider's key is not on this phone (for example after restoring a backup) or a stored header value is empty. */
    data object ProviderNeedsKey : AppError("PROVIDER_NEEDS_KEY")

    /** The device has no network connection at all. */
    data object Offline : AppError("OFFLINE")

    /** The provider could not be reached (DNS, connection refused, connection reset). The host name is never carried. */
    data object Network : AppError("NETWORK")

    /** The provider did not answer within the allowed time; [kind] says which timeout fired. */
    data class Timeout(val kind: TimeoutKind) : AppError("TIMEOUT")

    /** TLS handshake or certificate verification failed. */
    data object TlsFailure : AppError("TLS_FAILURE")

    /** HTTP 401 or 403: key missing, wrong or not allowed. [status] is 401 or 403. */
    data class Auth(val status: Int) : AppError("AUTH")

    /** The provider says the account's credit or plan limit is used up. */
    data object QuotaExceeded : AppError("QUOTA_EXCEEDED")

    /** HTTP 429. [retryAfterSeconds] comes from the Retry-After header, null if absent. */
    data class RateLimited(val retryAfterSeconds: Int?) : AppError("RATE_LIMITED")

    /** Provider-side failure (5xx and similar); [status] is the HTTP status code. */
    data class ProviderServer(val status: Int) : AppError("PROVIDER_SERVER")

    /** The provider rejected the request (4xx other than the cases above). */
    data class BadRequest(val message: String) : AppError("BAD_REQUEST")

    /** The configured model name does not exist at the provider. */
    data object ModelNotFound : AppError("MODEL_NOT_FOUND")

    /** The base URL path was not recognised by the provider (HTTP 404 that is not about the model). */
    data object EndpointNotFound : AppError("ENDPOINT_NOT_FOUND")

    /** The provider answered with a redirect, which the app does not follow. */
    data object ProviderMisconfigured : AppError("PROVIDER_MISCONFIGURED")

    /** The assembled prompt plus requested output exceeds the model's context window. */
    data object ContextTooLong : AppError("CONTEXT_TOO_LONG")

    /** Plain HTTP to a provider whose "Allow insecure HTTP" toggle is off. */
    data object InsecureUrlBlocked : AppError("INSECURE_URL_BLOCKED")

    /** The provider's reply was not in the expected wire format. */
    data object InvalidResponse : AppError("INVALID_RESPONSE")

    /** The provider returned a successful but empty answer. */
    data object EmptyResponse : AppError("EMPTY_RESPONSE")

    /** The provider's content filter stopped the answer. */
    data object ContentFiltered : AppError("CONTENT_FILTERED")

    /** The connection dropped while a streamed reply was being written. */
    data object StreamInterrupted : AppError("STREAM_INTERRUPTED")

    /** The model's structured answer could not be parsed or validated, even after the repair retry. The task kind is logged, not carried. */
    data object ParseFailure : AppError("PARSE_FAILURE")

    /** The user stopped the operation. Never shown as an error. */
    data object Cancelled : AppError("CANCELLED")

    /** The device storage is full. */
    data object StorageFull : AppError("STORAGE_FULL")

    /** Key handling failed. [reason] says which kind of failure. */
    data class Crypto(val reason: CryptoReason) : AppError("CRYPTO")

    /** An export or import failed; [code] is one of the fixed codes defined in Section 7.10. */
    data class BackupError(val code: BackupErrorCode) : AppError("BACKUP_ERROR")

    /** Anything not covered above. */
    data object Unknown : AppError("UNKNOWN")
}

enum class TimeoutKind {
    /** Connecting to the provider took longer than the connect timeout. */
    CONNECT,

    /** No bytes arrived for the idle period while streaming. */
    IDLE,

    /** A non-streaming call exceeded its total time. */
    TOTAL,
}

enum class CryptoReason {
    /** The Keystore key was lost or invalidated; stored secrets or the database cannot be unlocked. */
    KeyInvalidated,

    /** A single stored secret (for example an API key) could not be decrypted. */
    DecryptionFailed,
}

BackupErrorCode (:core:model, error/BackupErrorCode.kt) has exactly the entries of the code column of Section 7.10 except the inline-only PASSPHRASE_INVALID row: EXPORT_WRITE_FAILED, EXPORT_NO_SPACE, EXPORT_TOO_LARGE, NOT_A_BACKUP, NEWER_FORMAT, NEWER_SCHEMA, WRONG_PASSPHRASE, CORRUPT, TOO_LARGE, READ_FAILED, IMPORT_FAILED, IMPORT_NO_SPACE. Section 7.10 owns their titles, bodies and buttons.

Properties derived from the case (implemented as extension properties in :core:model, AppErrorExt.kt):

isProviderConfiguration marks the cases the user fixes in the provider settings; onboarding shows the action "Fix provider settings" for them (Section 10.6.5). AppErrorExt.kt also provides AppError.toLogDetail(): String, which renders the "logged detail" column as space-separated key=value pairs (for example error=PROVIDER_SERVER status=503) for use in AppLogger calls (Section 4.7).

4.4.3 Where each layer creates and handles errors #

4.4.4 The single catch-all helper #

Exceptions from platform APIs are translated in exactly one place per layer, using this helper from :core:model (which has no Android dependency, so the mapping function is a required parameter):

suspend inline fun <T> appCatching(
    crossinline mapError: (Throwable) -> AppError,
    crossinline block: suspend () -> T,
): AppResult<T> = try {
    AppResult.Ok(block())
} catch (e: CancellationException) {
    throw e
} catch (@Suppress("TooGenericExceptionCaught") e: Throwable) {
    AppResult.Err(mapError(e))
}

The standard mapping function, defaultThrowableMapping, lives in :core:data (app.mentor.core.data.error) and uses the helper Throwable.toCryptoErrorOrNull() exported by :core:security. It maps SQLiteFullException → StorageFull; KeyPermanentlyInvalidatedException, UnrecoverableKeyException → Crypto(KeyInvalidated); AEADBadTagException, BadPaddingException → Crypto(DecryptionFailed); kotlinx.serialization.SerializationException → ParseFailure; IOException (non-network contexts, such as file writes) → StorageFull when the message indicates no space left on the device, otherwise Unknown; everything else → Unknown. Export and import code passes its own mapper that produces BackupError(EXPORT_NO_SPACE) or BackupError(EXPORT_WRITE_FAILED) for write failures (Section 7.10). :core:ai supplies its own mapError (Section 8) for network exceptions.

4.5 User-facing error copy #

4.5.1 Copy catalogue #

Every AppError case has exactly one title, one message, and a recovery action, except where noted. Copy is final and lives in strings.xml under the resource names in Section 4.2.2. In a resource the app name, when present, is always %1$s, and the dynamic value takes the next position. Without the app name: {n}/{status} = %1$d, {message} = %1$s. With it (only the two RateLimited messages): The provider is asking %1$s to slow down. Try again in %2$d seconds. In the quoted strings below the word "Mentor" stands for the app name: the resource uses %1$s bound to app_name (Section 1.3, Q1). "Check provider" and "Edit provider" are the same action: open the active provider's editor.

Rules for the dynamic parts:

• {message} (for BadRequest) is the provider's error message, stripped of control characters, collapsed to a single line, and truncated to 300 characters with an ellipsis. If the provider sent no message, the whole message is replaced with: "The provider said the request was not valid."
• {n} is a whole number of seconds, clamped to 1–3,600; values above 3,600 display as "Try again later." in place of the sentence (title unchanged).

4.5.2 Presentation rules (ErrorPresentation) #

ErrorPresentation is a function in :app (feature/common) that maps an AppError to a UiError(title: UiText, message: UiText, primary: ErrorAction?, secondary: ErrorAction?, surface: ErrorSurface). The recovery action is an ErrorAction enum (OpenProviderEditor, FocusApiKey, OpenModelPicker, Retry, NewSession, ChooseFile, Close, OpenDiagnosticLog). Crypto(KeyInvalidated) has no UiError: when it occurs while the app is running, the app re-runs the startup gate (Section 3.10), which shows recovery screen A.

Common rules: titles use the screen-reader heading role; the error container is a polite live region; the primary action meets the 48 dp touch-target rule; error colours follow Section 18 and are never the only signal (an icon accompanies them); an error is cleared when its operation is retried or when the user dismisses it. Provider errors in forms and in the test-connection result may show a collapsible "Details" line with the HTTP status and the provider's message (at most 300 characters, control characters stripped, passed through the sanitiser of Section 6.12.4); the line is never logged and never shown for any other case. In onboarding, the cases with isProviderConfiguration = true (Section 4.4.2) show the action "Fix provider settings" (Section 10.6.5).

4.6 Error handling at layer boundaries #

1. Repositories and use cases return AppResult; they never throw for expected failures.
2. A ViewModel handles an Err by setting UiState.error (persistent, inline) or sending a ShowError effect (transient, snackbar), as given in Section 4.5.2.
3. Background workers translate AppError to Result.retry() or Result.failure() (example in Section 3.11.2) and write one diagnostic-log row.
4. Never show raw exception messages to the user. Never show an AppError.code. The only dynamic provider text allowed on screen is BadRequest.message and the "Details" line, under the limits in Section 4.5.

4.7 Logging #

The app writes no logs to Logcat in release builds and sends no logs anywhere. The only persistent log is the local diagnostic_log table (columns and the 500-row cap are defined in Section 5.4.17; redaction and the export format in Section 6.12).

4.7.1 API #

package app.mentor.core.model.log

enum class LogLevel { INFO, WARN, ERROR }

interface AppLogger {
    fun log(
        level: LogLevel,
        code: String,
        httpStatus: Int? = null,
        providerType: ProviderType? = null,
        durationMs: Long? = null,
        detail: String? = null,
    )
}

• code is a stable lowercase dotted event code, in the form <area>.<event> (for example provider.http_error, memory.extraction_skipped_chunk, worker.failed, security.secret_unreadable, db.migration_failed, export.failed, import.failed). The set of codes is open but every code is app-authored and constant; a code is never built from user content.
• detail is optional, app-authored only and limited to 300 characters. It carries structured key=value pairs for task kind, attempts and counts (for example task=CHAT attempts=2 tokens=3900 or the output of AppError.toLogDetail(), Section 4.4.2). Call sites never pass user content, provider messages or exception messages.
• Calls return immediately: RoomAppLogger (:core:data) sends rows to a buffered channel drained by one coroutine in @ApplicationScope that inserts rows and trims the table to the newest 500 rows. A full channel drops the oldest pending entries; logging never blocks or throws.
• android.util.Log, println and printStackTrace are forbidden (Section 4.1.3). The single exception is the debug-only Logcat mirror inside RoomAppLogger: in debug builds with BuildConfig.VERBOSE_LOGGING = true it additionally mirrors each entry to Logcat with the same restrictions. Release builds strip Log.v, Log.d and Log.i calls with the R8 rule of Section 21.5.1.

4.7.2 What may and may not be logged #

Defence in depth: every detail value passes through LogSanitizer, whose rules are defined once, in Section 6.12.4. The sanitizer is a safety net, not a licence to pass content.

The user can view, copy and export the log from Settings (Section 17.7); the log is excluded from backups (Section 7).

4.8 String resources #

1. Every user-visible string is in app/src/main/res/values/strings.xml (and feature-neutral strings used by :core:designsystem in that module's own strings.xml). English only; no other values-xx folders (non-goal N5).
2. No hard-coded user-visible text in Kotlin, including previews of production screens (previews use the real resources). Lint treats HardcodedText as an error; review catches strings inside Kotlin.
3. ViewModels and use cases never hold a Context. They express text through UiText:

sealed interface UiText {
    data class Resource(@StringRes val id: Int, val args: List<Any> = emptyList()) : UiText
    data class Plural(@PluralsRes val id: Int, val count: Int, val args: List<Any> = emptyList()) : UiText
    /** User-authored or model-authored content that must not be translated or formatted. */
    data class Dynamic(val text: String) : UiText
}

A composable resolves it with UiText.asString() (a @Composable helper). 4. Use positional format arguments (%1$s, %2$d); never concatenate fragments of a sentence; use <plurals> for counts. 5. Strings are named by Section 4.2.2. Do not reuse a string between unrelated screens, even if the wording matches; shared wording belongs in a shared component with its own resource. UI copy that names the app uses %1$s bound to app_name (Section 1.3, Q1). 6. The prompt template texts (Section 9) are product content, not UI strings; they are managed as defined in Section 9 and must not be placed in strings.xml. 7. Tone of voice for UI copy: plain, calm, second person, no exclamation marks, no emoji, no jargon (for example "provider", never "endpoint" in user-facing text), sentence case for buttons and titles.

4.9 Accessibility conventions #

The target is WCAG 2.2 AA (Section 18 defines the colour tokens that satisfy it).

1. Touch targets. Every interactive element is at least 48 dp × 48 dp (use Modifier.minimumInteractiveComponentSize() or explicit sizes); spacing between adjacent targets is at least 8 dp.
2. Labels. Every icon-only button has a contentDescription from a *_cd string; purely decorative images use contentDescription = null and Modifier.clearAndSetSemantics {} where needed. Text fields have a visible label or a hint plus a semantic label.
3. Semantics. Screen titles use Modifier.semantics { heading() }; toggles and checkboxes use toggleable/selectable with the proper Role; custom controls expose stateDescription (for example "Selected", "3 of 5"). Cards that are clickable merge their descendants (mergeDescendants = true) and expose one action label.
4. Streaming replies. Streamed text is not a live region (announcing every token makes TalkBack unusable). The finished reply is announced once, with a polite live region on the "Reply received" status. A "Stop" button has the label "Stop reply".
5. Errors and status. Error banners, snackbars and validation messages are polite live regions; validation messages are tied to their field (error semantics) and also shown as text, never only as colour.
6. Colour. No information is conveyed by colour alone (a status chip carries text or an icon). Text contrast ≥ 4.5:1 (≥ 3:1 for large text and UI component boundaries). The token pairs are validated in Section 18.
7. Font scale. All text sizes are in sp, all layout in dp. Layouts must remain usable at the system font scale up to 200%: no fixed-height text containers, no clipped text, multi-line wrapping instead of truncation for content the user must read; screens scroll when content grows.
8. Motion. Animations are short (≤ 300 ms) and are disabled or replaced by instant changes when the system animator duration scale is 0.
9. Focus and order. Reading order follows visual order; after a dialog or sheet closes, focus returns to the control that opened it; the composer keeps focus after sending.
10. Gestures. Every swipe or long-press action has a visible, labelled button alternative or a custom accessibility action.
11. Testing. Every screen has a Compose test that checks labels and touch targets, and one run at font scale 2.0 (Section 20). TalkBack is exercised with the manual script in Section 20.

4.10 Coroutine and Flow rules #

1. Structured concurrency only: no GlobalScope (enforced). Long-lived work uses @ApplicationScope or WorkManager (Section 3.9).
2. Dispatchers are injected (Section 3.7). runBlocking is allowed only in test code and in nothing else (enforced).
3. Every suspend function is main-safe: it switches dispatcher itself if it does blocking work.
4. Catching Throwable/Exception around suspending code must rethrow CancellationException. The only generic catch is appCatching (Section 4.4.4).
5. Repositories expose cold Flow for reads. ViewModels convert them with stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), initialValue) or combine them into UiState.
6. UI collects with collectAsStateWithLifecycle(); collectAsState() is not used.
7. State is a StateFlow updated with MutableStateFlow.update { it.copy(...) }; never mutate a collection held in state. Collections in state are read-only List, Set, Map values that are replaced, never modified.
8. One-shot effects use Channel<Effect>(Channel.BUFFERED) exposed with receiveAsFlow(); SharedFlow is not used for effects. Navigation and snackbars are effects, never state.
9. Use flatMapLatest for queries driven by changing input, debounce(250) for search-as-you-type (every search field, including the memory search, uses 250 ms), distinctUntilChanged before expensive work, conflate for display-only streams.
10. Cancellation must be cooperative and prompt: a cancelled network call cancels the OkHttp Call; loops call ensureActive() when they do not suspend.
11. Time-outs use withTimeout/withTimeoutOrNull or OkHttp's own time-outs (Section 8); never delay-based polling.
12. Do not launch coroutines from composables except through LaunchedEffect, rememberCoroutineScope for event handlers, or ViewModel calls.
13. Flows that touch Room use distinctUntilChanged() only when the mapped value is cheap to compare; otherwise let Room's invalidation tracker drive emissions.

4.11 Compose rules #

1. State hoisting. Each screen has a stateful XxxRoute (obtains the ViewModel with hiltViewModel(), collects state, handles effects) and a stateless XxxScreen(state, onEvent, modifier) that is previewable. Reusable components take state and callbacks only.
2. Single event entry. A screen passes one onEvent: (UiEvent) -> Unit down; leaf components take specific lambdas.
3. Previews. Every screen and every shared component has at least one @Preview. A multipreview annotation @MentorPreviews in :core:designsystem renders each preview in the Mentor theme at default font scale and at font scale 2.0. Screens additionally preview empty, loading, error and populated states. Previews use sample data builders, not live repositories.
4. Stability. The Kotlin compiler's strong skipping mode is on (default). Mark UI model classes as @Immutable only when they are truly deeply immutable. Domain classes from :core:model are declared stable in config/compose/stability.conf (app.mentor.core.model.**, kotlin.collections.*, kotlinx.datetime.*) and must never contain mutable collections or var properties.
5. Lists. Lazy lists supply key = { item.id } and contentType; item composables take only what they render; no lambda allocation that captures a whole list.
6. Remember and derive. Use remember for objects, derivedStateOf for values derived from fast-changing state (scroll position, text length), rememberSaveable for transient UI state worth surviving rotation.
7. No work in composition. No I/O, no time reads, no random IDs, no collect. Side effects live in LaunchedEffect(key) with correct keys, DisposableEffect for registrations.
8. Modifiers. Every reusable composable accepts modifier: Modifier = Modifier and applies it to its root; modifier order is deliberate (size and padding before background and clickable areas where the touch target matters).
9. Theming. Only MentorTheme tokens (Section 18) are used: no raw colour, text size, corner radius or elevation literals in feature code (review). Spacing uses the spacing scale.
10. Navigation. Routes are type-safe @Serializable types (Section 19); ViewModels receive arguments through SavedStateHandle; composables never receive a NavController; navigation is requested through effects handled in the Route composable.
11. Size. A composable function longer than 120 lines is split. A file holding more than one screen-level composable is split.
12. Text input. Text fields hoist their value; the chat composer keeps its draft in SavedStateHandle; IME actions are set explicitly; imePadding() is applied once at the screen level.
13. Window insets. Edge-to-edge is on (enableEdgeToEdge()); every screen consumes system bar and IME insets explicitly.

4.12 Git conventions #

1. Repository. One Git repository, initialised before M1. The default branch is main.
2. Branches. Work happens on one branch per milestone, named m<N>-<slug> (for example m3-chat-streaming). A branch is merged into main with a fast-forward or a squash-free merge commit only after the milestone's Definition of Done (Section 4.13) is met. main always builds and passes ./gradlew ktlintCheck detekt unitTest.
3. Commits. Small, buildable, one purpose each. Message format is Conventional Commits: <type>(<scope>): <summary>, where type is one of feat, fix, refactor, perf, test, docs, build, chore; scope is a module or feature name (chat, core-ai, database); the summary is imperative, lower case, under 72 characters, no full stop. A body explaining why is added for any non-obvious change. The commit that closes a milestone is chore(milestone): M<n> <name>.
4. Tags. Tag the merge commit of each finished milestone milestone-<N>, and the release v<versionName>.
5. Never commit: keystores (*.jks, *.keystore) or any signing material (release signing comes only from environment variables, Section 21.7.2), local.properties, API keys or tokens (test fixtures use obviously fake values such as test-key-0000), build output, IDE caches, personal data or device dumps. The .gitignore includes build/, .gradle/, .idea/, *.iml, local.properties, keystore.properties, *.jks, *.keystore, captures/, .cxx/, *.hprof.
6. Committed on purpose: gradle/libs.versions.toml, every gradle.lockfile, the Gradle wrapper, version.properties, Room schema JSON files, config/ files, DECISIONS.md, README.md, and the milestone records in docs/milestones/.
7. README.md states what the app is, how to build and test it, the module map, and how to run a debug build on a device or emulator. DECISIONS.md records the customization answers (Section 1.1) and every deviation or gap-filling decision, one line each, with a reason.

4.13 Definition of Done #

A milestone in Section 22 is finished only when every item below is true. The executor checks the list at the end of each milestone, records the result in docs/milestones/M<N>.md (one line per item and M<N>: DoD verified), and fixes failures before moving on.

5. Data Model & Local Storage #

This section is the single canonical definition of everything the app persists: the encrypted Room database (17 tables including one FTS index), the DataStore preferences file, the migration policy, seed data, retention rules and size limits. Every other section refers to tables, columns, enum values and preference keys by the names defined here. If another section appears to disagree with a name or limit in this section, this section wins and the other section is corrected.

5.1 Storage stack and global conventions #

5.1.1 JSON-in-column policy #

Decision: avoid JSON in columns. Every list or structured value that the app queries, filters or edits is a real table or a real set of columns. Exactly three exceptions exist, all opaque to SQL:

JSON appears in two other places that are not database columns: the bundled prompt-defaults asset (Section 9.9.3) and the export file (Section 7).

5.2 Enumerations #

All enums live in :core:model (pure Kotlin) in package app.mentor.core.model. The database stores the constant name as TEXT.

5.3 Entity-relationship diagram #

erDiagram
    intake_session ||--o{ intake_answer : "has answers (CASCADE)"
    intake_session |o--o{ user_profile : "produced (SET NULL)"
    conversation ||--o{ message : "contains (CASCADE)"
    conversation |o--o{ memory_item : "source of (SET NULL)"
    memory_item ||--|| memory_item_fts : "indexed by rowid"
    goal ||--o{ goal_milestone : "has (CASCADE)"
    goal |o--o{ quest : "linked from (SET NULL)"
    quest ||--o{ quest_step : "has (CASCADE)"
    quest_step ||--o{ quest_step_completion : "ticked as (CASCADE)"
    quest ||--o{ quest_step_completion : "denormalised (CASCADE)"
    check_in
    insight
    provider_config
    prompt_template
    diagnostic_log

Tables with no foreign keys (check_in, insight, provider_config, prompt_template, diagnostic_log) are drawn without edges on purpose. check_in and quest_step_completion are related only by local_date, never by a foreign key. insight.evidence_json references memory ids and intake keys softly (Section 5.1.1). provider_config is referenced softly by the DataStore key active_provider_id.

5.4 Table definitions #

Index names follow Room's default (index_<table>_<column list>). "Uniqueness" lists every unique rule, including those enforced in code because SQL cannot express them.

5.4.1 user_profile #

Purpose: the synthesised profile produced after the intake interview (Section 10), one row per profile version. Redoing the intake adds a new version; old versions are kept as history (shown read-only under Section 13.2.4) and are never sent to the model. The row with is_current = 1 is the profile. Field limits for the synthesised text are those of the profile_synthesis output schema in Section 9.6.12.

• Primary key: id.
• Foreign keys: intake_session_id -> intake_session(id) ON DELETE SET NULL.
• Indexes: unique index_user_profile_version on (version); index_user_profile_is_current on (is_current); index_user_profile_intake_session_id on (intake_session_id).
• Uniqueness: version unique. "Exactly one current" enforced in code; every reader uses is_current = 1, never "highest version".
• Mini-IPIP scores belong to the person, not to an intake: when a new version is created the previous bf_* values and bf_completed_at are copied forward unless the user retakes the assessment. Only the five sums are stored, never the 20 item answers and never an earlier result: a retake overwrites the six columns and "Delete my result" sets all six to NULL on every version row (Section 13.11.6). The mean of a trait is sum / 4.0 and is computed at display time.
• The model-written starter quests are not stored here; they are quest rows with status = SUGGESTED (Section 10.9.3).

5.4.2 intake_session #

Purpose: one run of the intake interview. A user has one session after onboarding and one more for each redo from Settings.

• Primary key: id. Foreign keys: none.
• Indexes: index_intake_session_status on (status).
• Uniqueness: at most one row with status = 'IN_PROGRESS' (enforced in IntakeDao.startSession, which first marks any existing in-progress session DISCARDED in the same transaction).

5.4.3 intake_answer #

Purpose: one question and (once answered) its answer, saved per question so the interview is resumable. The question text is snapshotted into the row so the data is self-contained and the AI-generated follow-ups are preserved.

• Primary key: id.
• Foreign keys: session_id -> intake_session(id) ON DELETE CASCADE.
• Indexes and uniqueness: unique index_intake_answer_session_id_position on (session_id, position); unique index_intake_answer_session_id_question_key on (session_id, question_key).
• The 12 core rows are inserted (UNANSWERED) when the session starts; follow-up rows are inserted in one transaction when the follow-up call succeeds, at positions 13 onward. Total rows per session: 15-20 when follow-ups were generated, 12 when they were skipped.
• In prompts, answers are labelled by position: [Q01]..[Q12] for core rows and [F01]..[F08] for follow-ups, and an evidence code Qnn or Fnn maps back to the row's question_key (Section 9.4.3).

5.4.4 conversation #

Purpose: one chat thread with the mentor, bound to one coaching area.

• Primary key: id. Foreign keys: none.
• Indexes: index_conversation_last_message_at on (last_message_at); index_conversation_area on (area).
• A conversation with zero messages is deleted automatically when the user leaves it (Section 11) and by the startup cleanup in Section 5.13.

5.4.5 message #

Purpose: one user or mentor message in a conversation.

• Primary key: id.
• Foreign keys: conversation_id -> conversation(id) ON DELETE CASCADE.
• Indexes and uniqueness: unique index_message_conversation_id_seq on (conversation_id, seq); index_message_created_at on (created_at).
• Only the first valid mentor-goal or mentor-quest block of a reply produces a card (one card per reply, Section 9.8), which is why one state column and one entity column are enough.
• Streaming persistence: when a reply starts, the chat coordinator inserts a MENTOR row with status = STREAMING and empty content, writes the text received so far to content every 2 seconds, and finalises the row as COMPLETE, STOPPED or FAILED. A reply that fails before any text arrived leaves no row (the empty row is deleted). Startup recovery of rows left in STREAMING by a process death is specified in Section 11.6.7.

5.4.6 memory_item #

Purpose: one remembered fact or pattern about the user (Section 12). The searchable text is mirrored into memory_item_fts (Section 5.5).

• Primary key: id.
• Foreign keys: source_conversation_id -> conversation(id) ON DELETE SET NULL (deleting a conversation never deletes what the user's mentor learned from it).
• Indexes: index_memory_item_status_pinned_importance on (status, pinned, importance); index_memory_item_source_conversation_id on (source_conversation_id); index_memory_item_kind on (kind); index_memory_item_source_ref on (source_ref).
• Uniqueness: none in SQL. Duplicate detection is semantic and done by the extraction task and MemoryRepository (Section 12), not by a constraint.
• Never use OnConflictStrategy.REPLACE for this table: REPLACE deletes and re-inserts the row, which can change its implicit rowid and desynchronise the FTS index. Use @Insert for new rows and @Update / UPDATE ... WHERE id = :id for changes.

5.4.7 memory_item_fts #

Virtual FTS4 table; defined fully in Section 5.5. It has one indexed column, content, whose docid equals memory_item.rowid.

5.4.8 insight #

Purpose: one generated insight card (Section 13). A generation run replaces the previous insights except the ones the user marked "Doesn't fit", which are retained as recorded feedback (rule below).

• Primary key: id. Foreign keys: none.
• Indexes: index_insight_category on (category); index_insight_feedback on (feedback).
• Uniqueness: none. A run stores 3-12 insights, at most 3 per category (the model is asked for 6-12, Section 9.6.14; invalid ones are dropped and the run fails below 3 valid, Section 13.4), plus up to 30 retained DOESNT_FIT rows from earlier runs.
• Replacement rule (Section 13.5.3): in one transaction the new rows are inserted, all older rows with feedback = NONE are deleted, and older DOESNT_FIT rows are kept (oldest feedback_at deleted first beyond 30). There is no other insight history.

5.4.9 goal #

Purpose: one user goal (Section 14).

• Primary key: id. Foreign keys: none.
• Indexes: index_goal_status on (status).
• Uniqueness: at most 5 rows with status = 'ACTIVE', enforced in GoalRepository.activate/create inside one transaction that counts active rows first (no trigger, so the rule stays testable in Kotlin).

5.4.10 goal_milestone #

Purpose: an optional checklist item under a goal.

• Primary key: id. Foreign keys: goal_id -> goal(id) ON DELETE CASCADE.
• Indexes: index_goal_milestone_goal_id_position on (goal_id, position) (non-unique, so re-ordering never violates uniqueness mid-update).
• Uniqueness: none in SQL. At most 10 milestones per goal, enforced in code.

5.4.11 quest #

Purpose: one Personal Quest (Section 15), from suggestion to its final state.

• Primary key: id.
• Foreign keys: goal_id -> goal(id) ON DELETE SET NULL.
• Indexes: index_quest_status on (status); index_quest_goal_id on (goal_id).
• Uniqueness: at most 3 rows with status = 'ACTIVE', enforced transactionally in QuestRepository.accept.
• A quest has 1-10 steps (quest_step), enforced in code.

5.4.12 quest_step #

• Primary key: id. Foreign keys: quest_id -> quest(id) ON DELETE CASCADE.
• Indexes and uniqueness: unique index_quest_step_quest_id_position on (quest_id, position).

5.4.13 quest_step_completion #

Purpose: records that a step was done on a local day. A DAILY step can have one row per quest day; a ONCE step has at most one row in total (enforced in code, since SQL uniqueness is per day).

• Primary key: id.
• Foreign keys: step_id -> quest_step(id) ON DELETE CASCADE; quest_id -> quest(id) ON DELETE CASCADE.
• Indexes and uniqueness: unique index_quest_step_completion_step_id_local_date on (step_id, local_date); index_quest_step_completion_quest_id_local_date on (quest_id, local_date); index_quest_step_completion_local_date on (local_date).
• Un-ticking a step deletes the row.

5.4.14 check_in #

Purpose: the one daily check-in (Section 15).

• Primary key: id. Foreign keys: none.
• Indexes and uniqueness: unique index_check_in_local_date on (local_date). One check-in per local day; editing the same day updates the row.

5.4.15 provider_config #

Purpose: one saved AI provider (Sections 8 and 17). Secrets are stored only as AES-GCM ciphertext (Section 6.5).

• Primary key: id. Foreign keys: none.
• Indexes and uniqueness: unique index_provider_config_name on (name) with COLLATE NOCASE.
• At most 10 rows (enforced in ProviderRepository.create). Exactly one provider is active, recorded in DataStore key active_provider_id (Section 5.11), not in this table.

5.4.16 prompt_template #

Purpose: editable coaching prompts and their shipped defaults (Section 9 owns the texts and the seeding algorithm; Section 17 the editor).

• Primary key: key. Foreign keys: none.
• Indexes: index_prompt_template_sort_order on (sort_order).

5.4.17 diagnostic_log #

Purpose: a small local ring buffer of redacted technical events the user can view and export (rules: Section 6.12).

• Primary key: id. Foreign keys: none.
• Indexes: index_diagnostic_log_created_at on (created_at).
• Retention: 500 rows. After each insert, DiagnosticLogDao.trim() removes older rows (SQL in Section 5.7.12).

5.5 Full-text search: memory_item_fts #

Memory retrieval (Section 12) uses SQLite FTS4, an external-content index over memory_item.content. There are no embeddings.

CREATE TRIGGER room_fts_content_sync_memory_item_fts_BEFORE_UPDATE
  BEFORE UPDATE ON memory_item BEGIN DELETE FROM memory_item_fts WHERE docid = OLD.rowid; END;
CREATE TRIGGER room_fts_content_sync_memory_item_fts_BEFORE_DELETE
  BEFORE DELETE ON memory_item BEGIN DELETE FROM memory_item_fts WHERE docid = OLD.rowid; END;
CREATE TRIGGER room_fts_content_sync_memory_item_fts_AFTER_UPDATE
  AFTER UPDATE ON memory_item BEGIN INSERT INTO memory_item_fts(docid, content) VALUES (NEW.rowid, NEW.content); END;
CREATE TRIGGER room_fts_content_sync_memory_item_fts_AFTER_INSERT
  AFTER INSERT ON memory_item BEGIN INSERT INTO memory_item_fts(docid, content) VALUES (NEW.rowid, NEW.content); END;

Rules that keep the index correct:

1. memory_item has a TEXT primary key, so its rowid is implicit. SQLite may renumber implicit rowids during VACUUM. Decision: the app never runs VACUUM and never enables auto_vacuum.
2. As a safety net, the index is rebuilt with INSERT INTO memory_item_fts(memory_item_fts) VALUES('rebuild') (a) at the end of every import (Section 7.8), (b) at the end of every migration that touches memory_item (Section 5.9), and (c) by the hidden maintenance action MaintenanceDao.rebuildSearchIndex() that the startup cleanup (Section 5.13) calls when SELECT COUNT(*) FROM memory_item_fts_docsize differs from SELECT COUNT(*) FROM memory_item.
3. Archived memories stay in the index; every retrieval query filters memory_item.status = 'ACTIVE'.
4. User-supplied search text is never passed to MATCH raw. Query construction (keyword extraction, stop words, escaping and the "token*" prefix terms joined by OR) is specified in Sections 12.5.2 and 12.5.3 and implemented by FtsQueryBuilder in :core:data. An empty term list skips the FTS query. Note that the prefix star sits inside the quotes ("worry*"); a star outside the quotes is not a prefix operator in FTS4.

5.6 Kotlin entity reference #

The following three entities are normative. All other entities follow exactly the same pattern with the columns in Section 5.4. Package: app.mentor.core.database.entity.

@Entity(
    tableName = "memory_item",
    foreignKeys = [
        ForeignKey(
            entity = ConversationEntity::class,
            parentColumns = ["id"],
            childColumns = ["source_conversation_id"],
            onDelete = ForeignKey.SET_NULL,
        ),
    ],
    indices = [
        Index(value = ["status", "pinned", "importance"]),
        Index(value = ["source_conversation_id"]),
        Index(value = ["kind"]),
        Index(value = ["source_ref"]),
    ],
)
data class MemoryItemEntity(
    @PrimaryKey
    @ColumnInfo(name = "id") val id: String,
    @ColumnInfo(name = "kind") val kind: MemoryKind,
    @ColumnInfo(name = "content") val content: String,
    @ColumnInfo(name = "importance", defaultValue = "3") val importance: Int = 3,
    @ColumnInfo(name = "source") val source: MemorySource,
    @ColumnInfo(name = "source_conversation_id") val sourceConversationId: String? = null,
    @ColumnInfo(name = "source_ref") val sourceRef: String? = null,
    @ColumnInfo(name = "pinned", defaultValue = "0") val pinned: Boolean = false,
    @ColumnInfo(name = "user_locked", defaultValue = "0") val userLocked: Boolean = false,
    @ColumnInfo(name = "status", defaultValue = "'ACTIVE'") val status: MemoryStatus = MemoryStatus.ACTIVE,
    @ColumnInfo(name = "use_count", defaultValue = "0") val useCount: Int = 0,
    @ColumnInfo(name = "last_used_at") val lastUsedAt: Long? = null,
    @ColumnInfo(name = "created_at") val createdAt: Long,
    @ColumnInfo(name = "updated_at") val updatedAt: Long,
    @ColumnInfo(name = "archived_at") val archivedAt: Long? = null,
)

@Fts4(contentEntity = MemoryItemEntity::class, tokenizer = FtsOptions.TOKENIZER_PORTER)
@Entity(tableName = "memory_item_fts")
data class MemoryItemFtsEntity(
    @ColumnInfo(name = "content") val content: String,
)

@Entity(
    tableName = "quest",
    foreignKeys = [
        ForeignKey(
            entity = GoalEntity::class,
            parentColumns = ["id"],
            childColumns = ["goal_id"],
            onDelete = ForeignKey.SET_NULL,
        ),
    ],
    indices = [Index(value = ["status"]), Index(value = ["goal_id"])],
)
data class QuestEntity(
    @PrimaryKey
    @ColumnInfo(name = "id") val id: String,
    @ColumnInfo(name = "title") val title: String,
    @ColumnInfo(name = "why", defaultValue = "''") val why: String = "",
    @ColumnInfo(name = "area", defaultValue = "'GENERAL'") val area: CoachingArea = CoachingArea.GENERAL,
    @ColumnInfo(name = "goal_id") val goalId: String? = null,
    @ColumnInfo(name = "duration_days") val durationDays: Int,
    @ColumnInfo(name = "difficulty", defaultValue = "'MEDIUM'") val difficulty: QuestDifficulty = QuestDifficulty.MEDIUM,
    @ColumnInfo(name = "status", defaultValue = "'SUGGESTED'") val status: QuestStatus = QuestStatus.SUGGESTED,
    @ColumnInfo(name = "source", defaultValue = "'GENERATED'") val source: QuestSource = QuestSource.GENERATED,
    @ColumnInfo(name = "started_at") val startedAt: Long? = null,
    @ColumnInfo(name = "start_date") val startDate: String? = null,
    @ColumnInfo(name = "end_date") val endDate: String? = null,
    @ColumnInfo(name = "created_at") val createdAt: Long,
    @ColumnInfo(name = "updated_at") val updatedAt: Long,
    @ColumnInfo(name = "completed_at") val completedAt: Long? = null,
    @ColumnInfo(name = "ended_at") val endedAt: Long? = null,
    @ColumnInfo(name = "reflection_note") val reflectionNote: String? = null,
)

@Entity(
    tableName = "provider_config",
    indices = [Index(value = ["name"], unique = true)],
)
data class ProviderConfigEntity(
    @PrimaryKey
    @ColumnInfo(name = "id") val id: String,
    @ColumnInfo(name = "name", collate = ColumnInfo.NOCASE) val name: String,
    @ColumnInfo(name = "type") val type: ProviderType,
    @ColumnInfo(name = "base_url") val baseUrl: String,
    @ColumnInfo(name = "model") val model: String,
    @ColumnInfo(name = "api_key_ciphertext", typeAffinity = ColumnInfo.BLOB) val apiKeyCiphertext: ByteArray? = null,
    @ColumnInfo(name = "api_key_iv", typeAffinity = ColumnInfo.BLOB) val apiKeyIv: ByteArray? = null,
    @ColumnInfo(name = "api_key_last4") val apiKeyLast4: String? = null,
    @ColumnInfo(name = "custom_headers_ciphertext", typeAffinity = ColumnInfo.BLOB) val customHeadersCiphertext: ByteArray? = null,
    @ColumnInfo(name = "custom_headers_iv", typeAffinity = ColumnInfo.BLOB) val customHeadersIv: ByteArray? = null,
    @ColumnInfo(name = "custom_header_count", defaultValue = "0") val customHeaderCount: Int = 0,
    @ColumnInfo(name = "secrets_pending", defaultValue = "0") val secretsPending: Boolean = false,
    @ColumnInfo(name = "temperature_override") val temperatureOverride: Double? = null,
    @ColumnInfo(name = "max_output_tokens_override") val maxOutputTokensOverride: Int? = null,
    @ColumnInfo(name = "context_window_tokens", defaultValue = "32000") val contextWindowTokens: Int = 32_000,
    @ColumnInfo(name = "allow_insecure_http", defaultValue = "0") val allowInsecureHttp: Boolean = false,
    @ColumnInfo(name = "created_at") val createdAt: Long,
    @ColumnInfo(name = "updated_at") val updatedAt: Long,
    @ColumnInfo(name = "last_test_at") val lastTestAt: Long? = null,
    @ColumnInfo(name = "last_test_ok") val lastTestOk: Boolean? = null,
) {
    // ByteArray members make the generated equals/hashCode compare by reference; override both.
    override fun equals(other: Any?): Boolean =
        other is ProviderConfigEntity && id == other.id && updatedAt == other.updatedAt
    override fun hashCode(): Int = 31 * id.hashCode() + updatedAt.hashCode()
}