LocalFoodAI_FerRo988/user_stories.md

User Stories & Taiga Sprint Plan (Sprints 4 - 13)

Vision Statement: A local food AI that provides full nutritional value information on any food and can generate complete menu proposals based on the user's specification.

Development Rules:

• Commit Format: Every commit MUST use the format: TG-<task_id>: <description>.
• Review Policy: Antigravity must generate an Implementation Plan and wait for Tech Lead (User) approval before writing code.
• Privacy: 100% local. No external API calls. No data leaves the VM.

Note: Sprints 1–3 covered initial VM setup, Ollama framework installation, Gogs repository creation, and the first AI chat interface prototype. Each Sprint below totals exactly 10 points.

---

🏃 Sprint 4: User Accounts & Core Authentication

Total Points: 10 | Goal: Establish a secure, fully local user authentication system so user data can be saved locally.

• [US-01] As a new user, I want to create an account with a username and password so that I can personalize my experience.
  • Back: Create SQLite users table, password hashing logic, and token API.
  • Front: Implement register and login forms routing to the API.
  • UX: Design the login/register workflow and error state alerts.
• [US-02] As a returning user, I want to log in securely so that I can access my saved food data.
  • Back: Implement session management and JWT token validation.
  • Front: Handle session persistence in the browser via localStorage/cookies.
• [US-03] As an administrator, I want to ensure all credentials are encrypted.
  • Back: Implement local-only security configurations preventing external access.

🏃 Sprint 5: Local Food Database Setup & Basic Search

Total Points: 10 | Goal: Integrate a local database of food and nutritional info fitting CPU/RAM constraints.

• [US-04] As a DB admin, I want to seed a local SQLite database with core food items.
  • Back: Parse an open dataset (USDA/OpenFoodFacts subset), design the SQLite schema, and import data cleanly.
• [US-05] As a user, I want to search for a specific food item by name.
  • Back: Create a fast fuzzy-matching API endpoint GET /api/food/search.
  • Front: Implement the search bar component with real-time fetch autocomplete.
• [US-06] As a developer, I want to connect the AI logic to the local database securely.
  • Back: Equip the Llama 3.1 8B agent with local SQL lookup tools so it can query the DB.

🏃 Sprint 6: Comprehensive Nutritional Information

Total Points: 10 | Goal: Expose deep nutritional data (macros, minerals, vitamins, amino acids) to the user.

• [US-07] As a user, I want to view complete macronutrient information for any specified food.
  • Front: Build the macro data UI components rendering calories, carbs, protein, and fat.
  • Design: Design beautiful, responsive nutrient breakdown cards/charts.
• [US-08] As a user, I want to expand detailed nutritional info to see micronutrients.
  • Front: Build an expandable, detailed view table for vitamins, minerals, and amino acids.
  • Back: Ensure the API properly aggregates and serves all extended JSON fields.
• [US-09] As the AI, I want to extract and summarize this complete nutritional profile accurately.
  • Back: Build a specific prompt template that forces the AI to summarize DB outputs without hallucinating data.

🏃 Sprint 7: Food Combinations & Aggregations

Total Points: 10 | Goal: Allow users to build a "meal" by entering multiple foods and getting aggregate nutritional totals.

• [US-10] As a user, I want to enter quantities of several foods at once to calculate an entire meal.
  • Front: Build a dynamic form field enabling adding/removing multiple food items and gram inputs.
  • UX: Layout the intuitive "meal builder" interface seamlessly.
• [US-11] As a user, I want the system to calculate and display the total combined nutritional value.
  • Back: Create POST endpoint multiplying weights and summing macro/micro totals.
  • Front: Dynamically render the totals component with the derived data on-the-fly.
• [US-12] As a developer, I want to ensure the mathematical aggregations account for varying portion sizes uniformly.
  • Back: Implement strict mathematical unit tests ensuring correct scaling (e.g., from base 100g to custom weights).

🏃 Sprint 8: Saved Lists & Combinations Management

Total Points: 10 | Goal: Implement the ability for users to save, edit, and organize their food combinations.

• [US-13] As a user, I want to save a calculated food combination as a named list (e.g., "Post-Workout Smoothie").
  • Back: Create saved_lists database tables and the corresponding POST API point.
  • Front: Add "Save Meal" button and a name entry modal component.
• [US-14] As a user, I want to view all my previously saved lists in a personal dashboard.
  • Front: Implement a dashboard page executing fetches and displaying user's saved meals.
  • Design: Design the aesthetic layout for the saved list cards.
• [US-15] As a user, I want to edit or delete my saved lists to keep my preferences up to date.
  • Back: Implement PUT (edit) and DELETE API endpoints securely.
  • Front: Implement edit mode, remove buttons, and dynamic state updates across the UI.

🏃 Sprint 9: Nutrient-Specific Sorting and Filtering

Total Points: 10 | Goal: Allow users to explore foods based on specific nutrient deficiencies or goals.

• [US-16] As a user, I want to search the database for foods high in a specific nutrient (e.g., "Foods high in Iron").
  • Back: Build complex dynamic SQLite queries allowing deep sorting (e.g. ORDER BY iron DESC).
  • UX: Design the advanced filtering UI, slider toggles, and dropdown menus.
• [US-17] As a user, I want the resulting list of foods to be sortable interactively.
  • Front: Implement an interactive data table structure allowing instant column sorting.
• [US-18] As the AI, I want to be able to generate natural language explanations of these sortable lists.
  • Back: Pass the top sorted database vectors to the LLM context to formulate explanations for "why these foods fit the goal."

🏃 Sprint 10: Local Web Search Integration (SearXNG)

Total Points: 10 | Goal: Give the AI the ability to securely and anonymously search the broader web when local data is missing.

• [US-19] As a system administrator, I want to deploy the SearXNG local web search tool on the VM.
  • Back: Install and configure the SearXNG instance on the Ubuntu 24.04 VM locally.
• [US-20] As the AI, I want to autonomously query SearXNG if the local DB lacks information on a food.
  • Back: Implement advanced LangChain custom Tool logic giving parsing ability to Llama 3.1.
• [US-21] As a user, I want the AI to fetch and summarize nutritional info on niche foods from the web anonymously.
  • Back: Scrape and sanitize the SearXNG website text inputs before feeding them to the LLM to prevent injection.
  • Front: Display an elegant "Web Search Active" UI indicator so the user understands minor delays.

🏃 Sprint 11: AI Menu Proposals & Constraint Logic

Total Points: 10 | Goal: Leverage the LLM to creatively generate menus that strictly respect nutritional limits and allergies.

• [US-22] As a user, I want to ask the AI for a full daily menu proposal that hits specific nutritional targets.
  • Back: Engineer complex multi-prompt logic uniting daily kcal targets with database selections.
  • Design: Design a visually distinct "Menu Plan" view (e.g., split into breakfast, lunch, dinner cards).
• [US-23] As a user, I want to specify constraints such as food allergies (e.g., structurally no peanuts).
  • Front: Add an intuitive "Allergies/Diet Preferences" settings page.
  • Back: Modify database query architecture to absolutely EXCLUDE flagged ingredients via SQL safety before the LLM step.
• [US-24] As a developer, I want to guarantee unsafe ingredients are filtered out globally.
  • Back: Write automated unit testing verifying that constraints heavily reject prohibited allergens.

🏃 Sprint 12: General Nutrition Chat & AI Refinement

Total Points: 10 | Goal: Polish the conversational capabilities, lock down topics, and refine the interface.

• [US-25] As a user, I want to chat freely about any nutrition-related topic and get competent, science-backed answers.
  • Front: Enhance HTML/JS chat UI to reliably handle deeply nested long-form threads and scrolling.
  • Back: Implement rolling conversational memory tracking via database records for session context.
• [US-26] As a developer, I want to refine system prompting so the LLM strictly refuses non-nutrition topics.
  • Back: Build system Guardrails and robust boundary prompts locking behavior to nutrition.
• [US-27] As a user, I want the AI's responses beautifully formatted in markdown.
  • Front: Integrate a safe Markdown rendering library (like marked.js) handling bolding, lists, and tables seamlessly.
  • Design: Style specific markdown elements cleanly inside the message chat bubbles.

🏃 Sprint 13: Deployment Polish & Open Source Handover

Total Points: 10 | Goal: Finalize the codebase for public access, clear confidential keys, and organize the Git repo on Gogs.

• [US-28] As a developer, I want to review the entire codebase for confidential data.
  • Back: Implement strict python-dotenv .env logic and build comprehensive .gitignore rules cleaning the repo.
• [US-29] As an admin, I want to add my teacher (id: evegi144) to the Gogs repo and freeze visual assets.
  • Back: Process Git permission tasks natively on git.btshub.lu.
  • UX: Do a full-application UX pass checking spacing, margins, and fixing responsive mobile bugs.
• [US-30] As an open-source user, I want a clear setup script and guide so I can clone and run LocalFoodAI securely.
  • Back: Write an automated bash setup.sh that checks system bounds (8 vCPU / 30GB limit), initiates a Python environment, and downloads the local LLM.
  • Back: Author an exhaustive README.md containing full instructions and architecture blueprints.