Building Flutter Apps (2/5) — QuietLeaf Technical Notes: Flutter Text Reader Architecture

Riverpod State Management, Hive Local Storage, 1,848 Tests, Multi-Format Rendering Design

ํ•ต์‹ฌ ์š”์•ฝ

  • DDD 3-Layer + Riverpod: Domain (pure business logic) → Data (10 Hive Boxes) → Presentation (UI). StateNotifier for composite reading state; FutureProvider for async file loading.
  • Multi-format: TXT (encoding fallback chain), EPUB (ZIP + HTML), PDF (page rendering), Image (pinch zoom). Separate providers per format.
  • Stabilization results: 24 categorized issues resolved across 3 rounds. Key axes: O(n)→O(1) lookups, controller leak elimination, async mounted checks, theme system consistency.
  • Tests: 82 files / 1,848 cases. AdMob timer conflict with pumpAndSettle resolved via pump(Duration) workaround.

What This Post Covers

This post documents the design decision points that recur when building a local text reader app with Flutter: encoding detection, format-specific rendering strategy, reading position restore, theme consistency, and the irreversibility of Hive schemas. For each topic, the focus is on what alternatives exist, the rationale for each choice, and what limitations remain. The app is QuietLeaf.

1. Tech Stack Selection

Item Choice Rationale
Framework Flutter 3.41 + Dart 3.11 Cross-platform, single codebase
State management Riverpod 3.3 StateNotifier for composite state, FutureProvider for async, testability
Local storage Hive CE 2.19 Key-value store, Box-level concern separation, low entry barrier
Routing go_router 17.1 Declarative routing, deep link support
PDF pdfrx 2.2 Page rendering
EPUB archive 4.0 + flutter_html ZIP parsing + HTML-style rendering
TTS flutter_tts 4.2 Text-to-speech, speed/pitch control
Ads google_mobile_ads 7.0 Rewarded ads (1 view → 16-hour ad removal)

Riverpod vs BLoC — Selection Criteria

The state space of a text reader is dominated by continuously updated values: scroll position, current page, progress, brightness, font size, theme. BLoC's event-state pattern requires declaring an event type for each update, causing boilerplate accumulation in this shape. StateNotifier modifies state through method calls, expressing the same functionality in roughly half the code.

FutureProvider handles the three states (loading / complete / error) at the framework level for async file loading scenarios like EPUB and PDF, eliminating the need to build a separate loader UI.

Conversely, BLoC is more appropriate for domains where event history tracking matters (e.g., game input logs). The selection criterion is whether state is a continuous value or an event stream.

Hive vs SQLite — Selection Criteria

At a solo-developer scale, Hive is usable without schema declarations, offers fast key-value access, and allows entity type separation at the Box level. 10 Box configuration:

documents, reading_states, bookmarks, collections,
app_settings, reading_sessions, monetization_state,
search_history, collection_items, highlights

Limitation: typeId and HiveField numbers cannot be rearranged once finalized. AppSettings has expanded to 45 fields, and intermediate numbers cannot be reused. If relational query requirements emerge later, SQLite migration costs apply. For domains where relational queries are core, SQLite is the better starting point.

2. DDD 3-Layer Architecture

Domain — Pure Business Logic

// Use Case example — no Flutter/Hive imports, pure Dart
class AddDocumentUseCase {
  final DocumentRepository repository;
  Future<Document> execute(String path) { ... }
}

The Domain layer contains no Flutter or Hive imports. It hosts AddDocumentUseCase, RestoreReadingStateUseCase, and SaveReadingStateUseCase. Repository implementation changes do not require Domain modifications.

Data — Persistence

Contains Hive services and repositories. Responsible for Box initialization, adapter registration, and CRUD operations.

Model definitions: - Document (typeId: 0) - ReadingState (typeId: 1) - Bookmark (typeId: 2) - AppSettings (typeId: 3, 45 fields) - Collection (typeId: 4) - MonetizationState (typeId: 6) - ReadingSession (typeId: 7)

Presentation — UI

5 main screens: - LibraryScreen — 5 tabs (directory browser, recent, bookmarks, search, highlights) - ReaderScreen — branching TXT/EPUB/PDF/image renderer - SettingsScreen — 45 setting fields - StatisticsScreen — daily/weekly reading statistics charts - ThemeBuilderScreen — custom theme seed color configuration

3. Multi-Format Rendering Strategy

TXT — Encoding Fallback Chain

Korean TXT files mix UTF-8, EUC-KR, and CP949; Japanese includes Shift-JIS; Chinese includes Big5. Automatic encoding detection cannot be solved with a single algorithm, so the approach is a fallback chain.

UTF-8 → EUC-KR → Shift-JIS → Big5 → Latin-1 (fallback)

Each step attempts decoding; if invalid byte sequences are detected, the next encoding is tried. Latin-1 accepts all single-byte values and therefore always succeeds. The goal is best-effort interpretation + crash prevention — displaying garbled text is acceptable; crashing is not.

Large files (10MB+) are read using 512KB chunk streaming. Loading the entire file into memory at once causes OOM on low-end devices.

EPUB — ZIP + HTML

The EPUB container structure places OPF/NCX/XHTML inside a ZIP archive. archive extracts the archive; flutter_html renders XHTML. Supports table of contents parsing, chapter navigation, and heading/bold/italic/blockquote styles.

PDF — Page-Level Rendering

Based on pdfrx. Includes page-level navigation, current page tracking, and progress display.

Image — Pinch Zoom

Supports JPG, PNG, WEBP, GIF, BMP. Pinch zoom (0.5x–5x) and panning. Handles manga and scanned-document use cases.

Each format uses a dedicated provider (epubContentProvider, pdfContentProvider). Reading state shares a common interface, but content loading logic differs per format, so providers are not shared.

4. Reading Experience Design

Position Restore — 500ms Debounce

Current position is saved to Hive 500ms after scrolling stops. Progress (0.0–1.0) is recorded simultaneously. Without debouncing, disk I/O fires on every scroll frame; 500ms is the tradeoff between perceived latency and I/O cost.

Theme System — 10 Presets + Custom

Light, Dark, Sepia, Paper, Night, Green, Cream, Mint, Lavender, Ocean. An additional custom seed mode leverages Material 3 dynamic color seeding.

Rule: no hardcoded colors. All colors are sourced from Theme.of(context).colorScheme. Violating this rule causes regressions where parts of the UI retain previous colors during theme transitions. The stabilization process identified and fixed 14 violations of this rule.

Highlights, Bookmarks, Search

Text highlighting in 5 colors with note attachment. Bookmarks support position jumping. In-document search is combined with a minimap.

TTS

Based on flutter_tts. Highlights the currently read paragraph in the UI; provides speed and pitch controls.

Accessibility

Semantics, textScaler, high-contrast mode, volume key navigation (opt-in), immersive mode (status bar and navigation bar hidden).

5. Monetization — Rewarded Ad Design

Google AdMob rewarded ads. 1 view → 16-hour ad removal, stackable up to 3 views (48 hours).

Banner ads are excluded because they fragment the reading flow. Rewarded ads surface only at the user's chosen moment and deliver an ad-free session as the reward, making them compatible with the reading experience. Ad network load failures fall back to ad-free continuation — UX must not be contingent on network quality.

6. Patterns Identified During Stabilization Rounds

3 stabilization rounds before release identified 24 issues. Pattern-level classification is more valuable than tracking individual bugs.

  • Lookup complexity: box.values iteration (O(n)) → box.get(id) direct access (O(1)). Eliminated points where latency scaled linearly with collection size.
  • Controller leaks: TextEditingController not disposed in 6 dialog locations. Dialogs wrapped in StatefulWidget with dispose() releasing the controller.
  • Async mounted check: missing mounted check before setState calls following async callbacks. Fixed via full codebase scan.
  • Theme consistency: 14 hardcoded color occurrences → replaced with Theme.colorScheme.
  • Backup restore order: original order was "clear → parse"; parse failure could cause data loss. Reordered to "parse → validate → clear" to preserve rollback capability.

These patterns are accumulated in tasks/lessons.md and used to catch the same mistakes early in subsequent sessions.

7. Claude Code-Based Development Pipeline

This project was developed via pair programming with Claude Code. Role separation:

Agent Model Role
orchestrator Opus Judgment, architecture design, simple implementation
executor Sonnet Complex code writing, refactoring
quality Sonnet Read-only review, code quality verification

Skills are triggered by keyword: brainstorming, code-review, deep-interview, flutter-hive, flutter-reader, flutter-test, git-commit, project-doctor, self-audit, testing, ux-ui-design, verification, writing-plans.

The highest-impact area was the stabilization rounds. Patterned issues (undisposed controllers, O(n) lookups, missing mounted checks) are caught faster through rule-based scanning than individual code review.

8. Play Store Deployment Considerations

Current Status

  • Internal testing track: published
  • Closed testing: under review (v2.0.0+22, 63.1MB AAB)
  • 14-day closed testing period required
  • Production release pending

MANAGE_EXTERNAL_STORAGE Permission

The core feature is directory browsing. SAF (Storage Access Framework) or MediaStore alone is insufficient for TXT file navigation. Without this permission, the app's core use case is structurally inoperable — submitted as justified cause during review.

Localization

Korean, English, Japanese, Chinese. 267+ keys managed via ARB.

9. Test Coverage

82 files / 1,848 cases.

Coverage scope: - Hive persistence (CRUD per model) - Riverpod provider state transitions - Use cases (document add, reading state restore, backup) - Settings cascade (45 fields) - Encoding detection - File browsing - TTS paragraph tracking

Known issue: AdMob rewarded ads contain an internal timer that does not satisfy pumpAndSettle's termination condition. Widget tests enter an infinite wait state; AdMob-dependent paths use pump(Duration) for explicit time increments.

10. Metrics Summary

Item Value
App version v2.0.0+22
AAB size 63.1MB
Supported formats TXT, EPUB, PDF, Image (5 types)
Themes 10 presets + custom
Hive Boxes 10
Settings fields 45
Tests 1,848 (82 files)
Stabilization fixes 24 (3 rounds)
Learned patterns 28
Localization keys 267 × 4 languages
Skills 14

Applicability and Open Questions

Applicability - For local-first Flutter apps, the Riverpod + Hive combination is well-suited to composite state and non-relational persistence. - The encoding fallback chain is portable to any reader or viewer handling multilingual text. - Stabilization round pattern categories (controller leaks, complexity, async mounted, theme consistency) apply broadly across Flutter apps.

Open Questions - At what point does Hive's typeId immutability exceed the cost of SQLite migration in long-term maintenance? How can early signals of relational query demand be detected? - By what metric should the rewarded ad value-time exchange (1 view ↔ 16 hours) be tuned to balance retention and revenue? - Can the theme consistency rule (Theme.colorScheme only) be enforced via static analysis automation?

Series overview: Series index

๋Œ“๊ธ€

๋Œ“๊ธ€ ์“ฐ๊ธฐ

์ด ๋ธ”๋กœ๊ทธ์˜ ์ธ๊ธฐ ๊ฒŒ์‹œ๋ฌผ

Agent Memory Engine (2/10) — Building an AI Agent Memory System with SQLite Alone

← 1/10 SQLite Memory Engine f… ๐Ÿ“š Series Index 3/10 memcore Completed → A memory engine that runs without daemons, without dependencies, anywhere ํ•ต์‹ฌ ์š”์•ฝ This post covers how to design an AI agent memory engine (memcore) on a single-file SQLite backend. - Structure: 25 modules, ~6,464 lines, 22 DB tables - Principles: no daemon, single-file portability, no required external dependencies, host-agnostic - Core techniques: 4-layer hybrid search (topic · vector · FTS5 · LIKE), U-tag dialectic-based confidence evolution, ingestion-layer bias rejection rules What This Post Covers One approach to building AI agent memory without a server or cloud vector DB. Specifically: (1) the limitations of text-file-based memory, (2) vector DB alternatives compared and selection criteria, (3) how to layer search tiers, (4) how to evolve confidence scores over time, and (5) how to block biased memory accumulation at the ingestion stage. Design Principles: Why Single-File SQLite Text-file-based ...
Read more »

"ML Foundations (9/9) — PyTorch vs TensorFlow, and the Road to Local LLMs"

์ด๋ฏธ์ง€
← 8/9 Deep Learning Architec… ๐Ÿ“š Series Index (series end) The final part. So far we've focused on models. Now we focus on the tools that actually run them . We'll lay out the philosophical difference between PyTorch and TensorFlow, and trace how Hugging Face transformers , llama.cpp , MLX , and Ollama built the bridge to running large language models on your own machine. By the end you should have the full mental model of "download a pretrained LLM and serve it locally." 0. Learning Objectives Explain the eager-vs-graph difference between PyTorch and TensorFlow. Explain, in graph terms, how autograd automates the backward pass. Use Hugging Face transformers ' AutoModel , AutoTokenizer , and pipeline abstractions. Describe llama.cpp's GGUF quantization, INT4 inference, and CPU-first flow. Describe Apple MLX's use of unified memory and how it differs from PyTorch. Run a local LLM with Ollama and call it through an OpenAI-compatible API. ...
Read more »

"RAG Core Study (14/26) — Evaluation Sets with RAGAS & DeepEval"

์ด๋ฏธ์ง€
Series overview: Series index ๐Ÿ“š Series Index Without an evaluation set, every RAG improvement is a story, not evidence. RAG systems fail in more than one place: retrieval, context selection, answer generation, and grounding. That means "looks better" is not a metric. Part 14 explains how to build a golden dataset , how RAGAS and DeepEval fit into the workflow, and why teams must separate retrieval quality from answer quality if they want tuning decisions to hold up. 0. Prerequisites Part 13 reranking — system quality now depends on multi-stage ranking. Part 1 grounding — a correct-looking answer is not enough. Part 12 Hybrid — multiple retrieval settings need comparison on fixed data. 1. Learning Objectives Build a small but useful golden dataset for RAG. Distinguish retrieval metrics from answer metrics . Use RAGAS and DeepEval in the right roles. Avoid the common traps in judge-model-based evaluation. 2. ํ•ต์‹ฌ ์š”์•ฝ An evaluation set for RAG is ...
Read more »

"ML Foundations (8/9) — Deep Learning Architectures: CNN, RNN, Attention"

์ด๋ฏธ์ง€
← 7/9 Deep Learning Training ๐Ÿ“š Series Index 9/9 PyTorch vs TensorFlow → What did we keep adding on top of an MLP? Vision went CNN, sequences went RNN/LSTM, and eventually both converged on Attention and the Transformer. Each architecture is easier to remember if you read it as what it gave up to gain something else . This part is the one-line summary of the decisive inflection points: LeNet → AlexNet → ResNet → LSTM → Attention → Transformer. 0. Learning Objectives Explain why CNN's convolution, pooling, and weight sharing match images so well. Trace what got unblocked from LeNet → AlexNet → VGG → ResNet as depth grew. State BPTT for RNNs and the vanishing/exploding gradient problem. Write the LSTM gate equations (forget, input, output) with intuition. Write the attention formula in query/key/value form and the scaled dot-product variant. State the precise reasons Transformers replaced RNNs (parallelism + long-range dependencies). 1. ํ•ต์‹ฌ ์š”์•ฝ CNN : weight sharin...
Read more »

"ML Foundations (7/9) — Deep Learning Training: Optimizers, Regularization, Initialization"

← 6/9 Neural Networks ๐Ÿ“š Series Index 8/9 Deep Learning Architec… → Building an MLP, as we did in Part 6, is not the same as getting it to train well . The right optimizer, regularization, initialization, and learning rate — when these line up, deep networks converge. When they don't, the network refuses to learn at all. This part is the catalog of those crafts, with formulas, paper citations, and code in one place. 0. Learning Objectives Compare and write the update rules for SGD, Momentum, Nesterov, and Adam. Explain how Dropout, BatchNorm, and LayerNorm work and where they belong in a model. Derive the variance formulas for Xavier and He initialization and match them to activations. Implement step, cosine, and warmup learning-rate schedules in PyTorch. Explain why gradient clipping is effectively required for RNNs and Transformers. Diagnose the most common training failures (NaN, plateau, overfitting) and apply first-line fixes. 1. ํ•ต์‹ฌ ์š”์•ฝ SGD : \(w \leftarro...
Read more »

OpenClaw to Hermes Migration (2/13) — What to Preserve, Partially Port, or Discard

← 1/13 Current Structure Inve… ๐Ÿ“š Series Index 3/13 What Moves to Hermes → A code review record classifying operational scripts into three tiers: preserve, partial-preserve, and discard. What This Post Covers An asset classification framework (preserve / partial-preserve / discard) for migrating a legacy agent system to a successor A concrete case applying the Strangler Fig + Subset Migration strategy to a memory pipeline Classification results evaluated across LOC, external dependencies, and replaceability axes A method for slimming down a bloated single file (1,310 LOC) using the migration as a natural entry point Problem Definition: Port Everything or Cut Deep? The OpenClaw inventory comprises multiple agents, multiple scheduler/daemon processes, and multiple operational scripts. When moving to the successor system, Hermes, the choice is not binary. A full port carries accumulated technical debt along with it; a minimal port discards hard-won domain logic. Code-revie...
Read more »

AI Agents I Built (5/7) — Building an Automated Blogger API Publishing System

← 4/7 My Life Organizer Agent ๐Ÿ“š Series Index 6/7 Dual → Designing a Markdown-Based Auto-Publish Pipeline with Blogger API v3 + OAuth 2.0 Key Summary Blogger API v3 + OAuth 2.0 enables a pipeline that converts Markdown files into publishable HTML posts blogger_publish.py handles the full flow — frontmatter parsing → body cleanup → HTML conversion → CSS injection → API post — in a single script For bulk publishing, quota management (delay, retry, TOC suppression) is the critical design concern Platform Selection Criteria API access is mandatory for AI agent-driven content publishing. A comparison of platforms: Platform API Cost AdSense Decision WordPress.com REST API Paid plan required Paid only Cost overhead Ghost REST API Self-hosted or paid Manual setup Ops overhead Blogger v3 API Free Native integration Adopted Blogger is free, exposes a REST API, and integrates natively with AdSense. For personal blog automation, this combination i...
Read more »