What needed to be engineered
Mobile readers lean on cloud subscriptions, ad-heavy web readers and fragile connectivity. Readers need a zero-latency, local-first library that downloads, indexes and renders PDFs with persistent page tracking, fully offline.
Boundaries & non-negotiables
- [01]Strict offline capability: downloaded books and reading state persist without external network calls.
- [02]High-performance PDF rendering for multi-hundred-page books with zero jank.
- [03]Clean decoupled architecture with explicit dependency injection via CompositionRoot.
- [04]Multi-platform support across Android, iOS and Linux.
System flow & boundary isolation
Layered Flutter architecture wired through a CompositionRoot: BLoC/Cubit state management drives a reactive UI, sqflite manages the offline catalog, and Dio crawlers fetch books into the Syncfusion viewer.
A user searches an online PDF library in real time through Dio HTTP crawlers with cookie persistence. Downloaded PDFs are saved to app documents via file system streams, metadata is indexed into SQLite, and the Syncfusion viewer opens the document while persisting exact reading progress.
Real-Time Web Crawler Search
A Dio HTTP client with session cookie persistence scrapes and normalizes search results from the online catalogue.
Background Download Pipeline
Multi-part binary stream downloads save book PDFs and cover images directly to sandboxed device storage.
Local SQLite Indexing
sqflite records book metadata, custom tags, user ratings, reviews and last-read page offsets.
Syncfusion In-App Reader
A high-performance canvas-accelerated PDF viewer with bookmarking, page jumping and light/dark theme toggles.
Explicit dependency injection in composition_root.dart isolates data sources, web services and BLoC state from Flutter widget trees, enforcing strict architectural boundaries and testability.
- SEC-[01]UI pages never talk directly to HTTP services or SQLite drivers: every interaction routes through BLoC/Cubit viewmodels.
- SEC-[02]Local storage lives in app-sandboxed directories, keeping offline file access safe from external leaks.
- SEC-[03]Web crawlers and Dio network clients sit behind abstract service contracts, shielding the UI from remote schema changes.
- SEC-[04]Permission handlers guard runtime filesystem access across Android, iOS and Linux desktop hosts.
Why this choice over alternatives
CompositionRoot Dependency Injection
Avoided magical service-locator singletons in favor of an explicit CompositionRoot that wires all datasources, services and cubits at startup.
Syncfusion PDF Viewer Integration
Chose syncfusion_flutter_pdfviewer over basic WebView rendering for fluid page turns, custom night mode support and precise scroll-position recovery.
Local-First SQLite Catalog
Stored book records, favorites and reading progress in local sqflite tables instead of a cloud database, prioritizing reader privacy and offline resilience.
Initial crawler implementation suffered cookie invalidation during deep paginated searches on the source site; resolved by adding persistent Dio cookie jar support.
Verified delivery & outcomes
Shipped v1.7.4-beta+5 on Android, iOS and Linux with offline library management, exact-page resume, dark mode and in-app book discovery.