Closer/Engineering_Reference_Manual_Plan.md

Engineering Reference Manual Review Plan — Phase 3 (2026-07-08)

Status: 🚧 IN PROGRESS — full evidence-first re-review of docs/Engineering_Reference_Manual.md.

Triggered by _null after the Phase 2 sync (213cfddb) + review pass (d31b58d2). Goal: cross-check every claim in the manual against the live repo + firestore.rules

• functions/src/ + iOS source + Android source, batch by batch. No skipped sections.

Approach

• 13 batches, each scoped to one major section of the manual.
• Evidence-first. For every factual claim (file path, function name, collection name, cron expression, preference field, threshold, AAD string), verify against the live source.
• One commit per batch per the standing git discipline (one batch = one commit = one push).
• Log findings to this file as each batch completes.
• Anchors + TOC verified at the end (Batch 13), not per-batch, to avoid churn.

Batches

Batch 1 — Front matter + System overview + Repository layout (Android + iOS + Cloud Functions + Shared configuration)

• Read: ## How to use this document through ### Shared configuration (lines ~1-260).
• Verify all directory paths under app/src/main/java/app/closer/, functions/src/, iphone/Closer/, res/drawable-*, Hilt module list.
• Cross-check Android package list against the live find app/src/main/java/app/closer -maxdepth 3 -type d.
• Cross-check iOS file list against ls iphone/Closer/....
• Cross-check Cloud Functions tree against find functions/src -name "*.ts".
• Flag missing or renamed directories/files.

Batch 2 — Authentication + pairing + couples doc model + rate limit + recovery

• Read: ## Authentication and pairing flow (lines ~270-370).
• Verify auth files in data/remote/FirebaseAuthDataSource.kt, data/repository/FirebaseAuthRepositoryImpl.kt, domain/repository/AuthRepository.kt.
• Verify couples/{coupleId} field list against acceptInviteCallable.ts + the domain Couple.kt model.
• Verify rate-limit env values against AuthRateLimiter.kt.
• Verify recovery phrase flow against RecoveryKeyManager.kt + CoupleEncryptionManager.kt.

Batch 3 — E2EE model (versions, Argon2id, Tink, sealed-answer, ECIES, single-device, iOS bridge)

• Read: ## End-to-end encryption model (lines ~370-475).
• Verify each Encryption versions row against firestore.rules regex helpers.
• Verify the Argon2id v1.3 parameter names + the AAD strings against the actual Kotlin/Swift code.
• Verify the keybox:v1: wire format against Keybox.swift + ReleaseKeyEncryptor.kt.
• Verify the wrapReleaseKeyCallable path against the function source.

Batch 4 — Daily question lifecycle + Reveal flow + Thread questions

• Read: ## Daily question lifecycle (lines ~480-575).
• Verify assignDailyQuestion schedule + the deterministic picker (DOW → mode map, daily_fun_mc exclusion) against functions/src/questions/assignDailyQuestion.ts + DailyModeResolver.kt.
• Verify the schemaVersion 2 reveal flow + the read-gated secure/payload subdoc against firestore.rules (the isCoupleAnswerCreate + isEncryptedPayloadUpdate helpers).
• Verify schemaVersion 3 sealed flow against SealedAnswerEncryptor.kt + isSealedAnswerCreate rules.
• Verify thread questions path against isSealedThreadAnswerCreate + the model.

Batch 5 — Firestore security rules

• Read: ## Firestore security rules (lines ~720-810).
• Line-by-line verify every per-collection note in the manual against firestore.rules.
• Cross-check helper-function names (coupleEncryptionEnabled, isCiphertext, isUpdatingCoupleRhythm, isUpdatingRecoveryWrap, isCoupleAnswerCreate, isEncryptedPayloadUpdate, isSealedAnswerCreate, isSealedAnswerUpdate, isSealedThreadAnswerCreate, isSealedThreadAnswerUpdate).
• Note any rules in the file not documented, or documented rules not in file.

Batch 6 — Cloud Functions

• Read: ## Cloud Functions (lines ~815-845).
• Verify function triggers, handlers, schedules, module responsibilities.
• Cross-check functions/src/ tree (already done in Batch 1 but verify exports).
• Cross-check Schedule table against each function's source.

Batch 7 — Billing

• Read: ## Billing (lines ~850-920).
• Verify RevenueCat integration files, entitlement checkers, webhook handler, Purchases.logIn identity link.
• Cross-check the "Gated features" list against the actual ViewModels that inject CouplePremiumChecker / EntitlementChecker.

Batch 8 — Notifications

• Read: ## Notifications (lines ~925-1020).
• Verify FCM setup + tokenRegistrar + quiet hours.
• Verify each reminder callable's actual schedule + dedupe.
• Verify game-push semantics against onGameSessionUpdate.ts + the part-finished triggers.
• Verify the foreground banner surface + the deep-link routing table against PartnerNotificationManager.kt.

Batch 9 — iOS-specific notes

• Read: ## iOS-specific notes (lines ~1023-1080).
• Verify Architecture, CloserTheme tokens, XcodeGen setup, build commands, E2EE gap status, CryptoKit guidance.
• Cross-check iphone/Closer/Theme/CloserTheme.swift for the actual color values.

Batch 10 — Build and release

• Read: ## Build and release (lines ~1080-1200).
• Verify Android module/package, biometric recovery phrase reveal, required build secrets, Gradle config, ProGuard rules.
• Cross-check the iOS build commands against the actual XcodeGen spec.

Batch 11 — Engineering conventions

• Read: ## Engineering conventions (lines ~1200-1280).
• Verify the architectural rules (Clean layers, package boundaries, what lives where) against the actual code.
• Verify the "what NOT to do" list (e.g. raw Firestore listeners, no FirebaseAuth.getInstance() in VMs) is still accurate.
• Check the version drift (build.gradle vs HISTORY.md) and ProGuard note.

Batch 12 — Known landmines and recent fixes

• Read: ## Known landmines and recent fixes (lines ~1280-1450).
• Verify EVERY landmine still applies:
  • Does the file/component it cites still exist?
  • Is the fix still in place?
  • Is the "Re-introduction risk" description still accurate?
• Look for any landmine whose fix is now in a different file.

Batch 13 — Where to look first

• Read: ## Where to look first (lines ~1450-end).
• Verify every file path still exists.
• Verify the "what to read first for a new area" list still applies to the current code.

Final pass

• TOC integrity + every anchor resolves.
• One final commit if any TOC/anchor cleanup is needed.