User Manual: Functional and Technical System Document
Document Version: 1.6 (UML / Mermaid Syntax Fix)
Objective: Comprehensively and highly-detailedly outline the functional requirements, non-functional requirements, business rules, calculation memories, and flows of the How2Burn ecosystem (iOS, WatchOS, Widgets, and Intelligence Engines), using native UML modeling (via flow, class, state, and sequence diagrams).
1. System Overview (Macro Features)
How2Burn is a cognitive weight-loss engine that orchestrates energy balance, metabolic quality, and behavioral aspects across multiple touchpoints.
- Dynamic Dashboard: Real-time view of Deficit, Macros, Health Indices (Fat Loss Score), Biological Alerts, and Temporal Groupings.
- Log (Multimodal Logger): Insertion via Text, Vision (Gemini), NLP (Llama), TACO (Food Database), User History, and Mass Logs.
- Dr. Chama (AI Coach): The virtual persona that crosses data to provide prescriptive insights.
- Journeys: Customized parameterization of time frames to align caloric theory with actual weight.
- Apple Ecosystem (Watch & Widgets): Quick mirroring of metabolism on iPhone home screens and Apple Watch.
- Settings & Profile: Endocrine predictive engine adjustments and permissions.
2. Non-Functional Requirements (NFRs)
- NFR001 - HealthKit Integration: Bidirectionally extract Steps, Sleep, HRV, Workouts, and Weight in the background.
- NFR002 - Privacy and LLMs: Queries to LLMs (Gemini, Llama) must transit only food data, masking the user ID.
- NFR003 - Analytical Performance: Graphical groupings with "Range > 1" (weekly/monthly) must calculate in less than 500ms via CoreData.
- NFR004 - UI/UX Haptic Feedback: Hitting limits, alerts, or confirmations trigger CoreHaptics responses.
- NFR005 - Offline Persistence and Sync: Offline-first support, except for direct AI requests. Widgets use Timeline Providers in the background.
3. Macro Feature 1: Dynamic Dashboard
(Visual Ref: Screens/1.6.4/Painel/Painel_01.png to Painel_19.png)
3.1. Grouping by Date Ranges (> 1 Day)
When selecting a wide period (e.g., 7 days):
- The dashboard aggregates data and the circular chart transmutes into an aggregated bar chart.
- Clicking a bar displays a dynamic Tooltip crossing intake with the exact HRV of that day. (Ref: Painel_04.png, Painel_10.png)
3.2. Critical Substances Analysis (Sugar and Cholesterol)
- The card triggers an alert for high Sugar/Cholesterol. (Ref: Painel_05.png)
- Upon clicking: A Modal opens with technical details. Right below, the modal groups the offenders, sequentially listing the foods consumed today that caused the alert. (Ref: Painel_11.png, Painel_12.png)
3.3. Use Cases (UML Flowchart) and Calculation Memory
- Total Daily Energy Expenditure (TDEE):
TDEE = BMR + NEAT + EAT(Mifflin-St Jeor + Dynamic Adjustments). - Fat Loss Readiness (Burn Index): Score (0-100) based on Sleep (30%), Average HRV (40%), and Steps (30%).
flowchart LR
Actor([User]) --> UC1(Change Date Range >1)
UC1 -.->|include| UC2(View Bar Aggregation)
Actor --> UC3(Check Daily Burn Index)
Actor --> UC4(View Offenders in Modal)
4. Macro Feature 2: Dr. Chama (Intelligence & Coaching)
4.1. Overview and Flow
Dr. Chama acts as the app's metabolic tutor with active health context.
- The user summons Dr. Chama in the app.
- The system injects the biological context into the Prompt (E.g., "HRV 30ms, poor sleep, high deficit").
- Dr. Chama returns a prescriptive feedback: "Your HRV dropped. Focus on hydration and avoid a high deficit today to protect lean mass."
5. Macro Feature 3: Logger and Search Engines
(Visual Ref: Screens/1.6.4/Registrar/Registrar_01.png to Registrar_09.png)
5.1. Fallbacks and AI Architecture
- Local History: Ultra-fast cache search. (Ref: Registrar_05.png)
- TACO Database: Audited National Food Table (Unicamp).
- Llama AI: Scours global portals (USDA, FatSecret) and returns formatted JSON.
- Gemini: Extraction by Photo or Audio. (Ref: Registrar_04.png)
5.2. Expanded Range Logs Screen (> 1 Day)
- Top 5 Offenders: Shows a scoreboard with the 5 "Food Families" that brought the most calories in the long period.
- Mass Logging: Selecting a food allows checking "For all days in the range", triggering batch insertions in the database. (Ref: Registrar_02.png)
5.3. Activity Diagram (Search and Mass Logging)
stateDiagram-v2
[*] --> LogScreen
LogScreen --> Range1Day : Range = Today
LogScreen --> LongRange : Range > 1 Day
LongRange --> ShowTop5
LongRange --> MassLogging
MassLogging --> PropagateRange
PropagateRange --> [*]
Range1Day --> LocalSearch
LocalSearch --> TACOSearch : Not found
TACOSearch --> LlamaAI : Not found
LlamaAI --> ReturnMacros
ReturnMacros --> SaveLog
SaveLog --> [*]
6. Macro Feature 4: Ecosystem Extensions (Watch & Widgets)
6.1. iOS Widgets (Home Screen and Lock Screen)
- Home Screen Widgets: Display the Deficit "Ring", Macros, and Burn Index via Timeline updates.
- Lock Screen Widgets: Radial iPhone complications directly on the lock screen.
6.2. Apple Watch App (WatchOS)
- Wrist Dashboard: Daily Ring and standalone Macro bars.
- Quick Log: Buttons for dictation via Siri ("I ate a cheese bread").
- Complications (Watch Faces): Corner icons indicating real-time deficit status, with background refreshes.
7. Macro Feature 5: Journeys and Preventive Health
(Visual Ref: Screens/1.6.4/Jornadas/Jornadas_01.png to Jornadas_04.png)
7.1. Journey Creation Flow
The user defines a long-term interval (e.g., 90-day Project). (Ref: Jornadas_02.png)
- Retroactive Start Date: Allows the journey to start in the past.
- Starting Weight: Pulls actual weight from HealthKit on the exact start date.
- On the chart, the App compares the Theoretical Accumulated Deficit against an Actual Weight Moving Average to dampen distortions. (Ref: Jornadas_03.png)
classDiagram
class User {
+String uuid
+List~CustomFood~ customFoods
}
class Journey {
+UUID id
+Date startDate
+Date endDate
+Double startWeight
+Double goalWeight
+getTheoreticalWeightLoss()
+getActualWeightLoss()
}
class DailyAggregate {
+Date date
+Double tdee
+Double ingestedCalories
+Double vfcScore
+Double weighIn
}
User "1" *-- "many" Journey
Journey "1" *-- "many" DailyAggregate
8. Settings and Onboarding (Endocrine Conditions)
(Visual Ref: Screens/1.6.4/Onboarding/Onboarding_01.png to Onboarding_10.png and Screens/1.6.4/Configuracoes/Configuracoes_01.png to Configuracoes_16.png)
8.1. Metabolic Adaptation
- If the user reports PCOS (Polycystic Ovary Syndrome) or a history of Long Diets, the app injects a "Safety Reducer" (~15%) over the standard Mifflin BMR. (Ref: Onboarding_07.png, Onboarding_08.png) This prevents severe aggressions to the endocrine system and locks the maximum weight loss goal to prevent the rebound effect (regain).
sequenceDiagram
participant U as User
participant APP as Onboarding
participant ENG as Predictive Engine
U->>APP: Fills Basic Data
APP->>U: Asks Hormonal History (PCOS/Thyroid)
U->>APP: Answers "PCOS"
APP->>U: Asks about Long Diets
U->>APP: Confirms Goals
APP->>ENG: Sends Biometric Data
Note over ENG: BMR based on Mifflin.
15% reducer applied due to PCOS. ENG-->>APP: Returns Adjusted BMR (Lower) APP->>U: Finishes Setup
15% reducer applied due to PCOS. ENG-->>APP: Returns Adjusted BMR (Lower) APP->>U: Finishes Setup
9. Glossary of Terms
- Dr. Chama: Native AI Persona of the app with the user's clinical context.
- TDEE (Total Daily Energy Expenditure): Total Daily Expenditure (BMR + NEAT + EAT).
- HRV / VFC: Heart Rate Variability (stress level).
- TACO: Brazilian Table of Food Composition.
- LLM (Llama / Gemini): Artificial Intelligence models for semantic search, text extraction, and computer vision.
- Mass Logging: Simultaneous log of a food for multiple days at once (ideal for meal prep).
- Top 5 Offenders: Scoreboard displaying the 5 food groups that brought the highest caloric load within a date grouping.
- Moving Average: Visual statistic used in the Journeys chart to smooth out false weight gain peaks (water retention).
- WidgetKit / Complications: Apple tools to display the caloric ring on lock screens and watch faces.
Have any questions?
Contact the developer directly.