How jand19081/cse499-meal-planner works
1. Overall shape
- This is a Kotlin Multiplatform meal-planning app with a thin Android app shell and a shared composeApp module that holds almost all business logic, UI, and persistence.
- The architecture is strongly local-first: the app runs against a local Room database and does not appear to depend on any remote backend.
2. Application entry points
- androidApp contains the Android-specific launcher (MainActivity) and manifest.
- composeApp provides the shared app entry (App.kt) plus a JVM desktop entry (main.kt) under jvmMain.
- Both targets reuse the same shared feature, domain, and data layers, with platform-specific implementations injected where needed.
3. Presentation layer
- The feature/ package is the main UI layer and is split by product area: dashboard, calendar, meals, pantry, ingredients, recipes, shopping list, analytics, settings, kitchen, and inventory.
- Each feature typically has a View, ViewModel, and feature-specific model/state files.
- UI is built with Compose Multiplatform, and shared reusable widgets live under ui/components.
4. Navigation, theming, and app composition
- core/navigation/AppNavigation.kt defines the app’s screen flow and is the main boundary between feature screens.
- core/theme/Theme.kt centralizes styling.
- core/di/DependencyInjectionContainer.kt and ViewModelFactory.kt indicate a lightweight shared dependency injection layer used to wire repositories, use cases, and view models.
5. Domain layer
- The domain/ package isolates business rules from storage and UI.
- domain/model/ holds the core business entities such as FoodItem and MealSource.
- domain/logic/ contains the main use cases and calculators, including pantry consumption, recipe execution, cooking time, and price calculation.
- domain/repository/ defines repository interfaces, keeping the rest of the app independent from Room details.
6. Data layer and persistence
- data/db/ is the persistence core and uses Room + SQLite.
- The database is modeled in an ECS-like style: a base identity entity plus component-like tables and @Relation-based reconstruction.
- data/db/entity, relation, dao, and converters split the persistence concerns cleanly.
- composeApp/schemas/...json stores Room schema history, showing database versioning and migrations as a first-class architectural concern.
7. Repository boundary
- Concrete repositories under data/repository/ implement the domain repository interfaces using Room-backed data access.
- These repositories are the main bridge from business logic to storage and are likely the primary source of state for most view models.
- This keeps feature code from talking directly to DAOs or entities.
8. Meal-planning and kitchen workflows
- The app’s main business flow revolves around meal planning, recipe execution, pantry inventory, and shopping list generation.
- The kitchen/ and recipes/ features show a distinct “cook and consume” workflow, with models like KitchenTransaction, ConsumptionResult, and recipe execution state.
- The calendar/ and meals/ features likely schedule meals, while the shoppinglist/ feature aggregates required ingredients from scheduled meals and pantry availability.
9. Data transformation and utilities
- core/util/ contains important shared helpers: unit conversion, validation, mapping, enum definitions, and mock data.
- The README’s graph-based unit conversion suggests a central utility service used by recipe, pantry, and shopping features to normalize quantities.
- DataQualityValidator and related validators imply that user-entered item data is checked before it reaches domain logic or persistence.
10. Backup, export, and file transfer
- data/export/ implements structured backup/restore using BackupPayloadV1 and mapping helpers.
- core/util/FileTransferButtons.* has platform-specific implementations for Android and JVM, indicating file I/O and sharing are abstracted per target.
- This backup subsystem is a separate architectural boundary from the core runtime data path.
11. Notifications and platform-specific behavior
- notification/ is split into shared scheduling contracts and platform-specific workers/schedulers.
- Android has a MealNotificationWorker and Android scheduler implementation; JVM has its own scheduler implementation.
- Notifications are therefore treated as an optional platform service layered on top of the shared meal/calendar domain.
12. Testing and schema evolution
- composeApp/src/commonTest suggests shared tests for platform-independent logic.
- The preserved Room schema snapshots and design artifacts under Design/ indicate the project emphasizes data model evolution and documentation.
- For an architecture diagram, the key takeaway is a layered KMP app with a shared core, a Room persistence backend, feature-specific Compose screens, and small platform-specific adapters for notifications and file handling.
Main entry points: AppNavigation.kt Navigation · App.kt App · RoomFoodItemRepository.kt Room repos · MealPlannerDatabase.kt Room database
Components 28
Android app
Android-specific launcher shell and resources.
- MainActivity · Android entry activity and manifest-backed app shell.
MealPlanner/androidApp/src/main/kotlin/io/github/and19081/mealplanner/android/MainActivity.kt
Shared app
Common Compose Multiplatform application code reused across targets.
- App · Shared application root for Compose Multiplatform.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/App.kt - Desktop main · JVM desktop launcher for the shared app.
MealPlanner/composeApp/src/jvmMain/kotlin/io/github/and19081/mealplanner/main.kt - Navigation · Shared screen routing and app-level flow control.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/core/navigation/AppNavigation.kt - Theme · Centralized shared styling and theme definition.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/core/theme/Theme.kt - DI container · Lightweight dependency wiring for repositories and view models.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/core/di/DependencyInjectionContainer.kt - ViewModel factory · Shared view model construction support.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/core/di/ViewModelFactory.kt
Domain layer
Business rules, entities, and repository contracts.
- Domain models · Core business entities such as food items and meal sources.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/domain/model/FoodItem.kt - Business logic · Pantry consumption, recipe execution, cooking time, and price calculation.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/domain/logic/CommitConsumptionUseCase.kt - Repo contracts · Repository abstractions that decouple the app from storage details.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/domain/repository/Repository.kt
Data layer
Room persistence, repository implementations, and export/backup.
- Room database · Shared Room database and schema root.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/data/db/MealPlannerDatabase.kt - Entities · Room entity definitions for the local-first data model.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/data/db/entity/MealPlannerEntities.kt - DAOs · Room access layer for queries and mutations.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/data/db/dao/MealPlannerDaos.kt - Room repos · Concrete repository implementations backed by Room.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/data/repository/RoomFoodItemRepository.kt - Backup export · Structured backup and restore payload mapping.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/data/export/DataTransferService.kt
Feature UI
Compose screens and view models organized by product area.
- Main screen · Primary shared landing screen and its state model.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/main/MainView.kt - Dashboard · Overview screen for the app's main meal-planning state.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/dashboard/DashboardView.kt - Calendar · Meal scheduling and day-based planning interface.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/calendar/CalendarView.kt - Meals · Meal plan management and meal scheduling workflows.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/meals/MealsView.kt - Pantry · Inventory and pantry management UI.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/pantry/PantryView.kt - Ingredients · Ingredient browsing and editing interface.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/ingredients/IngredientsView.kt - Recipes · Recipe management and recipe execution flow.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/recipes/RecipesView.kt - Shopping list · Shopping aggregation and receipt drafting workflow.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/shoppinglist/ShoppingListView.kt - Analytics · Reporting and summary views over meal-planning data.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/analytics/AnalyticsView.kt - Settings · User preferences and app configuration screens.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/settings/SettingsView.kt - Kitchen · Consumption and recipe execution workflow interface.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/feature/kitchen/KitchenView.kt
Platform services
Target-specific adapters for notifications and file transfer.
- Notifications · Shared notification scheduling contract with platform adapters.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/notification/MealNotificationScheduler.kt - File transfer · Platform-specific file I/O and sharing helper implementations.
MealPlanner/composeApp/src/commonMain/kotlin/io/github/and19081/mealplanner/core/util/FileTransferButtons.kt
Connections 28
- MainActivity → App: launches · Android shell starts the shared Compose app.
- Desktop main → App: launches · JVM desktop entry starts the same shared app.
- App → Navigation: uses · App root delegates screen flow to navigation.
- App → Theme: uses · App root applies shared theme.
- App → DI container: wires · App root initializes dependencies.
- DI container → ViewModel factory: creates · Dependency container relies on the view model factory.
- Navigation → Main screen: routes to · Navigation connects the primary home surface.
- Navigation → Dashboard: routes to · Navigation connects dashboard screens.
- Navigation → Calendar: routes to · Navigation connects calendar screens.
- Navigation → Meals: routes to · Navigation connects meal plan screens.
- Navigation → Pantry: routes to · Navigation connects pantry screens.
- Navigation → Recipes: routes to · Navigation connects recipe workflows.
- Navigation → Shopping list: routes to · Navigation connects shopping list screens.
- Navigation → Settings: routes to · Navigation connects settings screens.
- Navigation → Kitchen: routes to · Navigation connects kitchen workflow screens.
- Dashboard → Business logic: uses · Dashboard reads derived business calculations.
- Meals → Repo contracts: uses · Meal planning screen works through repository contracts.
- Kitchen → Business logic: uses · Kitchen workflow executes consumption and recipe use cases.
- Business logic → Domain models: operates on · Use cases are built on shared business entities.
- Room repos → DAOs: queries · Room repositories access DAOs for persistence.
- Room repos → Room database: persists in · Repositories are backed by the shared Room database.
- Room database → Entities: stores · Database is defined by entity tables.
- Room database → DAOs: exposes · Database provides DAO entry points.
- Room repos → Repo contracts: implements · Concrete repositories satisfy domain contracts.
- Backup export → Room repos: reads from · Backup and restore layers serialize repository data.
- Backup export → Entities: maps · Transfer payloads are mapped from persistence models.
- Notifications → Calendar: supports · Scheduling is layered on top of meal/calendar data.
- File transfer → Backup export: supports · Platform file helpers enable backup and restore flows.