Skip to Content
Tech debtMigrations

In-flight Migrations

The three large migrations in progress. Incomplete migration = the project’s biggest active debt, because each leaves the codebase in a partially-converted state. Back to register.

1. Mobile consolidation onto shared UI + Koin (TD-01)

Goal: one mobile UI living in shared/, used by both iOS and Android, on a single DI system (Koin). Android drops its Hilt + Room/offline layer and its *_presentation UI. Big-bang on branch design-system-foundation.

Source of truth: plans/mobile-consolidation-koin.md

Current debt / status

StepWhatStatus
S1Koin foundation on Android (deps, AndroidAppModule, startKoin, Hilt removed from androidApp)✅ Done
S2androidApp hosts SharedAppNavHost; :androidApp:compileDevDebugKotlin green✅ Done
S3Shell to mobile prototype (frosted tab bar, tab set)✅ Partial
S4Close shared-UI feature gaps (every feature + detail/edit sub-route in commonMain)⬜ Not verified
S5Delete old Android UI + Hilt + offline (≈56 @HiltViewModel, 66 hiltViewModel() sites, LoggedScreen, NavHostWrapper, all *_presentation)⬜ Not done
S6Cleanup + device run-verify (assembleDevDebug, click every route)⬜ Not done
S7Responsive breakpoints across all screens (shared OterWindowSize)⬜ Not done

Note: the orphaned old feature/lib module folders (finance, tasks, … core-ui, test-core, etc.) were already deleted from disk (2026-06). What remains for S5 is the Hilt/Room/*_presentation code inside androidApp/core and the Hilt gradle wiring — see infra.md for the leftover version pins.

Risks

  • Runtime feature gaps (S4): compile-green ≠ working app. A feature missing a shared screen/service/sub-route silently disappears at runtime. Must exercise every tab + detail/edit flow on a device before S5.
  • High blast radius (S5): deletion touches the Android UI, DI, and persistence layers together.
  • Lost offline: dropping Room means network-only; flaky connectivity degrades UX. Accepted by the user, but a regression to track. → architecture.md
  • Test infra: the Hilt-based test-core was removed; tests must move to koin-test. → testing.md
  • Android-only infra (FCM, widgets, global timer, walkthrough): each must be re-bridged from androidMain via Koin or explicitly dropped during S5.

Target state

androidApp and iosApp both render the same shared/commonMain screens via SharedAppNavHost + MobileAppShell, with Koin-provided VMs/services, and one responsive layout system across phone/tablet/desktop.

2. Web frontend: Kotlin/JS React → TypeScript React (TD-05)

Goal: replace the old Kotlin/JS web client with a TypeScript/Next.js app (web-frontend/), keeping business logic on the Kotlin server.

Source of truth: infra/web-migration-plan.md · web-frontend/IMPROVEMENTS.md

Current debt / status

  • web-frontend/ exists and is the active client (Next.js 16, React 19.2, TypeScript 5, Tailwind 4, Zustand 5, Axios).
  • Component library + hooks + design system built; feature parity incomplete — the harder pieces (real-time/WebSocket, file uploads, push notifications) are not fully ported.
  • Doc duplication: WEB_MIGRATION_PLAN.md exists at both repo root and docs/infra/ — dedupe (TD-13).

Target state

TypeScript React frontend at full feature parity; the old Kotlin/JS client fully retired; one canonical migration doc.

3. Design-token consolidation (Figma ↔ code 1:1) (TD-06)

Goal: one set of design tokens, name-for-name between Figma variables and the Compose Oter.* tokens (currently there are three sources of truth: Figma, code, prototype spec).

Source of truth: design-system/tokens.md

Current debt / status

  • Positive: the design-token guard baseline (config/design-token-guard-baseline.txt) is empty — no files are currently exempt, i.e. the guarded screens are migrated to Oter.*.
  • Open: 5 token DECISIONS still unresolved (primitives tier missing in code, translucent fills, light-theme status colors dangerLight/warningLight/infoLight, tag colors, elevation/motion/typography kept code-only). Figma↔code is not yet 1:1.

Target state

Figma variables and code tokens are identical and three-tier (primitives → semantic → scales); the guard stays green in --strict. → design-system.md

RegisterArchitecture