This folder contains technical documentation for the PIATRA project.

Index of all documentation.

Full API reference — all endpoints, request/response shapes, authentication requirements, and error codes.

High-level architecture diagram and data-flow descriptions covering how the Flutter app, FastAPI backend, Firebase, Spoonacular, and Gemini AI interact.

┌─────────────────────────────────────────────────────┐
│                  Flutter Mobile App                  │
│                                                      │
│  Screens: Home, Pantry, Scan, Recipes, Cooking,     │
│           Meal Plan, Analytics, Assistant, Profile   │
│                                                      │
│  State: UserProvider, RecipeProvider,                │
│         SavedRecipesProvider, ThemeProvider          │
│                                                      │
│  Local storage: SQLite (sqflite) — pantry cache      │
└──────────┬──────────────────────┬───────────────────┘
           │                      │
           │ REST (HTTP)           │ Firebase SDK
           ▼                      ▼
┌──────────────────┐   ┌─────────────────────────────┐
│  FastAPI Backend │   │         Firebase             │
│                  │   │                              │
│  /api/assistant  │   │  Firestore collections:      │
│  /api/users      │   │   • user_profiles/{uid}      │
│  /api/feedback   │   │   • pantry_items/{id}        │
│                  │   │   • meal_plans/{uid}/weeks   │
│  Gemini 2.5      │   │   • nutrition_logs/{uid}     │
│  Flash (text +   │   │   • recipe_history/{uid}     │
│  vision)         │   │   • saved_recipes/{uid}      │
└──────────────────┘   └─────────────────────────────┘
           │
           ▼
┌──────────────────┐
│   Spoonacular    │
│   Recipe API     │
│                  │
│  findByIngred.   │
│  complexSearch   │
│  informationBulk │
└──────────────────┘

1. User takes a photo in ScanScreen
2. PantryScanner sends the image (base64) to /api/assistant/chat with context = "VISION_SCAN::<mime>::<base64>"
3. Backend decodes context, calls Gemini Vision with a strict JSON-array prompt
4. Response is parsed into DetectionResult objects
5. User reviews and edits detected items in _DetectionResultsSheet
6. Confirmed items are written to SQLite via PantrySyncManager and pushed to Firestore

1. RecipeProvider.loadRecommendations() is called with the current UserProfileModel
2. Pass 1: SpoonacularService.findByIngredients() — pantry-first, returns up to 30 lightweight results
3. Pass 2: SpoonacularService.complexSearch() — diet/cuisine/intolerance filters applied, up to 20 results
4. Pass 3 (if cuisine filter active and < 5 matches): cuisine-only search without pantry constraint
5. All results are deduped and bulk-fetched for full nutrition/steps data
6. RecipeRankingEngine.rankAndFilter() scores and partitions results
7. UI renders ranked list with pantry-match bar, reason chips, and cuisine grouping

1. User taps "Start Cooking" on a recipe detail screen
2. CookingModeScreen renders steps with per-step timer (auto-detected from step text)
3. The AI sous-chef panel has full recipe + current step context
4. On "Finish!", NutritionHistoryService.logMeal() and RecipeHistoryService.recordCook() are called
5. Completion screen shows macros and offers navigation to Analytics

1. AssistantScreen._fetchAIResponse() builds context from local pantry (SQLite) + profile (UserProvider)
2. Sends { message, context, user_id } to /api/assistant/chat
3. Backend optionally enriches context further via ContextBuilder (Firestore pantry + profile)
4. Gemini response is formatted via format_gemini_response() (bold → Unicode bold, - → •)
5. Response rendered in chat bubble

Encapsulates all filter and sort criteria for the recipe ranking engine. Key fields: cuisines, diets, intolerances, dishTypes, maxReadyMinutes, minCalories, maxCalories, minProteinG, maxCarbsG, pantryOnlyMode, sortOrder.