Clean Architecture, reactive state management, and scalable monetization
powering ShelfChef.
Architecture Overview
ShelfChef follows Clean Architecture principles combined with MVVM.
The system is designed to isolate business logic from UI and external services,
ensuring scalability, maintainability, and long-term extensibility.
Layer Responsibilities
Presentation Layer: Jetpack Compose UI + ViewModels using StateFlow.
Domain Layer: Core business models, use cases, and feature gating logic.
Data Layer: Repository implementations, Room database, API services, and cloud integrations.
Dependency Direction
Dependencies flow inward. The Domain layer defines interfaces.
The Data layer implements them. The Presentation layer depends only on Domain abstractions.
This prevents framework or API coupling from leaking into business logic.
System Architecture Diagram
This layered design isolates business rules, simplifies testing,
and enables portability to additional platforms such as web or React Native.
State Management Architecture
ShelfChef uses Kotlin Coroutines and StateFlow to implement reactive,
lifecycle-aware state management within MVVM.
Room DAO queries expose Flow streams.
Repositories transform and combine data sources.
ViewModels expose immutable UI state.
Compose observes state using collectAsState().
The architecture enforces unidirectional data flow:
user events move upward to ViewModels, and state flows downward to the UI.
This ensures predictable rendering and reduces inconsistent UI states.
Error Handling Strategy
Network Resilience
Retrofit responses wrapped in safe result objects.
HTTP failures converted into domain-level errors.
Graceful UI messaging for connectivity failures.
AI Fallback Strategy
Recipe parsing first attempts structured Schema.org extraction.
If unavailable, GPT-4o-mini processes raw HTML.
If AI fails, users receive clear actionable feedback.
Subscription Consistency
RevenueCat entitlement state acts as the single source of truth.
No feature is unlocked based solely on local flags.