KeTMangi 🍝

A Flutter meal-planning app: plan your meals first, shop smarter, waste less.

🇮🇹 Leggi in italiano

KeTMangi flips the usual grocery routine on its head. Instead of buying food and then figuring out what to cook, you plan your meals for the week first — the app then builds an optimized, categorized shopping list for you automatically, and helps you track what's in your pantry so less food goes to waste.

• 🧙 Guided onboarding — set up dietary preferences, usual dishes and daily preferences in a multi-step wizard
• 📅 Automatic weekly plan — smart generation of a weekly meal plan based on your preferences
• 🛒 Shopping list — automatic ingredient aggregation, organized by supermarket category
• 🏠 Pantry management — track ingredients and expiry dates to reduce waste
• ❌ Handling changed plans — when you skip a planned meal, decide what to do with the ingredients you already have
• 📊 Dashboard — metrics and statistics on completed meals and food waste

• Flutter 3.16+ / Dart 3.2+
• Riverpod (flutter_riverpod, riverpod_annotation, riverpod_generator) — state management
• GoRouter — declarative navigation and bottom navigation
• Hive (hive, hive_flutter, hive_generator) — local, embedded persistence
• Dio — HTTP client
• Material Design 3 — UI components

📖 For the full Flutter vs. React Native analysis behind this project's stack, see TECH_DECISION.md.

lib/
├── main.dart                    # App entry point
├── models/                      # Data models
│   ├── ingredient.dart          # Ingredient & RecipeIngredient
│   ├── recipe.dart              # Recipe & enums
│   ├── user_profile.dart        # UserProfile & preferences
│   ├── meal_plan.dart           # MealPlan & DayMeals
│   ├── shopping_list.dart       # ShoppingList & ShoppingItem
│   └── pantry_item.dart         # PantryItem & expiry tracking
├── services/                    # Business logic
│   ├── meal_plan_generator.dart # Weekly plan generation algorithm
│   ├── shopping_list_generator.dart # Shopping list aggregation
│   ├── pantry_service.dart      # Pantry management & "didn't cook" flow
│   └── recipe_catalog.dart      # Predefined Italian recipes
├── providers/                   # Riverpod state management
│   └── app_providers.dart       # All app providers
├── router/                      # GoRouter configuration
│   └── app_router.dart          # Routes & bottom navigation
└── screens/                     # UI screens
    ├── onboarding/              # Multi-step setup wizard
    ├── meal_plan/               # Weekly plan view
    ├── shopping_list/           # Shopping list view
    ├── pantry/                  # Pantry management
    ├── dashboard/                # Home dashboard
    └── settings/                # App settings

1. Prerequisites: Flutter SDK 3.16+ (Dart 3.2+)
2. Install dependencies:

   flutter pub get

3. Run the app:

   flutter run

4. Run the tests:

   flutter test

If you change any model or provider annotated for code generation (riverpod_generator, hive_generator), regenerate the generated files with:

dart run build_runner build --delete-conflicting-outputs

The app ships with 15+ predefined Italian recipes, organized by:

• Difficulty: Quick (<30 min), Medium (30–60 min), Elaborate (>60 min)
• Type: First courses, main courses, single-dish meals
• Restrictions: Vegetarian, vegan, gluten-free, etc.

The docs/ folder contains a pre-built Flutter web release, used to serve the app via GitHub Pages. It is build output, not source — regenerate it with flutter build web and copy the contents of build/web/ into docs/ if you need to publish an updated version.

Unit and widget tests live under test/, covering the data models (test/models/), the business-logic services (test/services/) and the root widget (test/widget_test.dart).

flutter test

MIT © 2026 iAlias