Refactoring a Chat Assistant: Applying SRP, DIP, OCP & Surviving JNI Pitfalls
This article details a systematic refactoring of a chat assistant Android app, applying SRP, DIP, OCP, layered architecture, and naming conventions to eliminate god classes and tight coupling, while uncovering a JNI symbol mismatch bug that only appears at runtime, and sharing insights on AI-assisted coding limitations.
Background
The author recounts a full-day refactoring of a chat assistant Android application after initial "vibe coding" with AI produced a tangled codebase: a god class ( MemoryRepository) handling six responsibilities, UI mixed with business logic, and concrete implementations directly instantiated everywhere. The goal was not new features but maintainability and extensibility.
Before refactoring, the architecture showed classic bad smells. After refactoring, the layers are clean: Presentation (UI) → Domain/Services (AI) → Data, with peripherals (accessibility, bubble, OCR) and a cross-layer event bus (AppBus) each in their place.
1. SRP: Splitting the God Class into Collaborators
The original MemoryRepository did six things: logging replies, invoking LLM for learning, generating embeddings, building injection text, reading/writing database, and maintaining UI state flow. Any change risked ripple effects.
After splitting, MemoryRepository becomes a pure orchestrator delegating to single-responsibility collaborators: ReplyLog (raw records), MemoryEmbedder (memory→vector), MemoryInjector (memory→prompt), MemoryDao (persistence). Even the AiService used for learning is now injected rather than hard-coded.
The same surgery applied to the floating bubble: FloatingBubbleService handles only lifecycle and orchestration; view building moves to BubblePanel ; drawables to BubbleStyle .
Benefit: Each class can be described in one sentence; changing one no longer drags others.
2. DIP: Depend on Abstractions, Not Implementations
The memory layer needs to turn text into vectors and store them, but it shouldn't care whether the embedding engine is MNN, online, or offline. So it depends only on a minimal Embedder interface.
Concrete native encoder ( Encoder), model resources ( ModelAssets), and vector codec ( VectorCodec) are hidden behind a private facade MnnEmbedder. High-level modules depend on abstractions; low-level modules implement those abstractions — dependency direction inverted.
Benefit: Memory layer can be unit-tested with a fake Embedder; swapping embedding engines requires zero changes to memory layer; concrete classes are invisible outside the package.
Configuration and memory storage are also interfaced ( SettingsStore , MemoryStore ), combined with MVVM ViewModel constructor injection so UI no longer touches singletons.
3. OCP: Open for Extension, Closed for Modification
The app has two natural variation axes: inference running cloud vs. on-device, and memory retrieval using lexical vs. semantic scoring. Instead of scattering if/else, variation points are pinned to interfaces: AiClient ← CloudClient,
LocalClientRelevanceScorer← LexicalRelevance, EmbeddingRelevance Adding a new implementation requires zero changes to callers. Lexical scoring also serves as an elegant offline fallback when semantic scoring is unavailable — graceful degradation under the same interface.
4. Naming as Design: Let Names Explain Architecture
Significant time was spent on naming because names are the cheapest, highest-frequency documentation.
Renaming the pseudo-repository: AiRepository didn't handle persistence; it was an orchestrator → renamed to AiService.
Unified naming axis: Cloud and local clients are two implementations of the same dimension, so they should be named CloudClient and LocalClient (not OpenAiCompatClient and LocalClient — one by protocol, one by deployment).
Removing package-name redundancy: Package already named ai.embedding, so classes inside drop the Embedding prefix: EmbeddingEngine → Encoder, EmbeddingCodec → VectorCodec, EmbeddingModelManager → ModelAssets (also eliminating the vague Manager).
Good naming makes "which layer this class belongs to and what role it plays" instantly obvious — naming itself is part of architecture.
5. Cross-Language Reef: JNI Symbols Follow Package Names
The most dangerous lesson: on-device inference and embedding use JNI to call native .so libraries. JNI symbol names are mangled from the declaring class's fully qualified name (FQN) and resolved at runtime.
Moving LlmEngine from data.local to ai.local changed the expected Kotlin-side symbol from ..._data_local_... to ..._ai_local_..., while the old .so still exported the old symbol — compile-time saw nothing, but invoking local inference threw UnsatisfiedLinkError at runtime.
Fix: update jni.cpp exported symbols to match new FQN, rebuild two JNI bridges with NDK (linking existing engine libraries and headers, lightweight), and verify release build's R8 did not obfuscate those two classes.
Lesson: Any coupling invisible at compile-time but exploding at runtime must be validated by running the actual code path on a real device, not just by a successful build.
6. Extensibility in Practice: Internationalization & Multi-Theme
Architecture's resilience shows when adding a new dimension — does it break bones or slide in?
Internationalization: All UI copy externalized to resources; added values-en; enum display names switched to @StringRes; AI reply language follows conversation content (reply in English if user writes English), decoupled from UI language — achieved with a single prompt instruction.
Multi-theme: One ThemeVariant enum with persistence; produced two families (Japanese deep blue and New Chinese Morandi) each with light/dark variants (six total), cool tones as base with warm accents.
Adding languages and themes touched zero business logic — the earlier abstractions are paying off.
7. Verification Is Observation: Compile Success ≠ Correctness
The refactoring insisted on one rule: after a change, watch it run on a real device, don't just trust "compiles fine".
Embeddings: In advanced settings, seeing "vectorized N/N items" proves native encoder works end-to-end.
Local LLM: Local mode "test connection" actually emits a reply, proving nativeLoad / nativeChat symbols resolve in release package.
R8: Cross-check mapping.txt to confirm classes with native methods weren't renamed; verify .so exported symbols match Kotlin FQN.
This discipline forced the JNI reef in section 5 to surface — otherwise it would have lurked until users hit it.
8. AI Coding Bugs: Which Need Human Intervention
Heavy AI use for renaming, class extraction, interface extraction, package moves — fast and stable. Bugs fall into two categories: some AI catches via reasoning; others absolutely require human intervention.
① AI Can Catch: Cross-Language Contracts Invisible to Compiler
AI moved LlmEngine package; Kotlin side clean, build green. But AI reasoned: JNI symbols are mangled from FQN; package change breaks native .so symbols; local inference will crash with UnsatisfiedLinkError. So before human discovery, AI flagged it proactively , updated jni.cpp symbols, rebuilt, and self-verified with llvm-nm and mapping.txt (see section 5). When the causal chain is clear, AI can catch "compiler-invisible" pits.
② AI Cannot See: Visuals & Layout
AI-written Compose compiles and logic is correct, but rendering may be broken. Four reply-style chips forced into a single Row; last chip squashed into a tall narrow strip, huge whitespace, clipped off-screen — AI has no eyes . Human spotted "excessive whitespace", AI used uiautomator to measure 58×196 vertical chips, switched to FlowRow.
③ Distinguishing Real Bugs from Environment/Usage
User reported "floating bubble doesn't dismiss after refactor" — sounded like regression. AI didn't rush to fix; instead compared show/hide logic ( setBubbleVisible, hideRunnable, onForeground) byte-for-byte — identical . Root cause: test device lacked accessibility service, while auto-hide relies on accessibility foreground events. Verdict: environment issue, no code change. Human provides reproduction conditions; AI falsifies. Avoids being led astray by a single report. Historically, same logic had a real bug: accessibility couldn't get rootInActiveWindow, fell back to IME or system window package name, misjudged "left chat" and hid bubble permanently (floating window gone). That time required code fix (only accept activity window package name, skip if unavailable); this time required cognitive fix (environment) — two sides of the same coin, proving "distinguish real bug from environment first" is critical.
④ Platform Semantics: Default-Value Traps
Historical "tapping notification repeatedly creates new Activity" was: MainActivity default standard launch mode + PendingIntent with only NEW_TASK → each tap spawns new instance. Fix: singleTask + SINGLE_TOP for reuse. Such "framework default" landmines, AI tends to write defaults unless reminded. Meanwhile "screenshot OCR picks up keyboard letters into chat, bottom messages clipped" are edge cases from real app interaction — only discoverable by human on real device.
⑤ Tooling Can't Capture Scene → Build Observability for AI
Target app (Hz, com.immomo.vchat) uses view hierarchy parsing, but its node tree is shielded from uiautomator dump; logcat also restricted on some devices — AI can't see real IDs, classes, bounds, so can't write parsing rules. Solution: built an in-app "View Raw Node Tree" debug panel: accessibility service streams node tree (including IDs like tv_chat_content_self, tv_chat_content_others) to display; human feeds tree back to AI, which then wrote ChatParser routing and speaker detection.
In one sentence: AI can reason its way into some deep pits (like JNI symbols tracking FQN) and execute large-scale structural changes fast and reliably; but invisible rendering/structure, real-bug-vs-environment discrimination, and unobservable runtime scenes still need human backup. Good collaboration: human as eyes (watch rendering), real device (run paths), observability (build debug panels to feed data), guardrails (enforce verification red lines); AI as the fast, precise hand.
Retrospective: Which Design Ideas Landed
SRP — Split MemoryRepository, FloatingBubbleService into coordinators + collaborators
DIP — Memory layer depends only on Embedder abstraction; implementation hidden behind facade
OCP — AiClient, RelevanceScorer strategized; new implementations require zero caller changes
Layering, MVVM — ui / ai / data layers; one ViewModel per screen; side effects out of Composables
Naming as Documentation — Renamed AiService, unified Cloud/Local axis, removed package-name redundancy
Facade, Encapsulation — MnnEmbedder facade; concrete engine invisible outside package
Cross-Language Contract — JNI symbols follow FQN; rename = contract change; must rebuild & real-device verify
Extensibility — i18n, multi-theme added as new dimensions smoothly without touching business logic
The endpoint of refactoring is never "prettier code", but making the next change cheaper . When adding a language, a theme, or swapping an inference engine means merely "implement an interface, add a resource", these design ideas have truly landed.
The entire refactoring relied on human judgment and direction, sometimes using exploratory discussion to find better modifications — "Is this change good? Any better suggestions to avoid my own cognitive fixation?" Next step: introduce TDD test practices. Pure vibe-coding architecture indeed has many problems; generated code takes the most direct path, e.g., Chinese strings hard-coded in source.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
