# 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.

_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] (3 pts):** Create SQLite users table, password hashing logic, and token API.
  - **[Front] (2 pts):** Implement register and login forms routing to the API.
  - **[UX] (2 pts):** 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] (1 pt):** Implement session management and JWT token validation.
  - **[Front] (1 pt):** Handle session persistence in the browser via localStorage/cookies.
- **[US-03]** As an administrator, I want to ensure all credentials are encrypted.
  - **[Back] (1 pt):** 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] (4 pts):** 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] (2 pts):** Create a fast fuzzy-matching API endpoint `GET /api/food/search`.
  - **[Front] (2 pts):** 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] (2 pts):** 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] (2 pts):** Build the macro data UI components rendering calories, carbs, protein, and fat.
  - **[Design] (2 pts):** Design beautiful, responsive nutrient breakdown cards/charts.
- **[US-08]** As a user, I want to expand detailed nutritional info to see micronutrients.
  - **[Front] (2 pts):** Build an expandable, detailed view table for vitamins, minerals, and amino acids.
  - **[Back] (2 pts):** 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] (2 pts):** 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] (2 pts):** Build a dynamic form field enabling adding/removing multiple food items and gram inputs.
  - **[UX] (1 pt):** 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] (3 pts):** Create POST endpoint multiplying weights and summing macro/micro totals.
  - **[Front] (2 pts):** 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] (2 pts):** 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] (2 pts):** Create `saved_lists` database tables and the corresponding POST API point.
  - **[Front] (2 pts):** 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] (2 pts):** Implement a dashboard page executing fetches and displaying user's saved meals.
  - **[Design] (1 pt):** 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] (1 pt):** Implement PUT (edit) and DELETE API endpoints securely.
  - **[Front] (2 pts):** 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] (3 pts):** Build complex dynamic SQLite queries allowing deep sorting (e.g. `ORDER BY iron DESC`).
  - **[UX] (2 pts):** 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] (2 pts):** 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] (3 pts):** 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] (3 pts):** 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] (4 pts):** 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] (2 pts):** Scrape and sanitize the SearXNG website text inputs before feeding them to the LLM to prevent injection.
  - **[Front] (1 pt):** 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] (3 pts):** Engineer complex multi-prompt logic uniting daily kcal targets with database selections.
  - **[Design] (2 pts):** 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] (2 pts):** Add an intuitive "Allergies/Diet Preferences" settings page.
  - **[Back] (2 pts):** 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] (1 pt):** 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] (2 pts):** Enhance HTML/JS chat UI to reliably handle deeply nested long-form threads and scrolling.
  - **[Back] (2 pts):** 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] (3 pts):** 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] (2 pts):** Integrate a safe Markdown rendering library (like marked.js) handling bolding, lists, and tables seamlessly.
  - **[Design] (1 pt):** 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] (3 pts):** 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] (1 pt):** Process Git permission tasks natively on `git.btshub.lu`.
  - **[UX] (1 pt):** 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] (3 pts):** Write an automated bash `setup.sh` that checks system bounds (8 vCPU / 30GB limit), initiates a Python environment, and downloads the local LLM.
  - **[Back] (2 pts):** Author an exhaustive `README.md` containing full instructions and architecture blueprints.