From c4ff6eee7320e3fb81ac6b3888c1b005cd9ca752 Mon Sep 17 00:00:00 2001 From: Forketyfork Date: Mon, 5 Jan 2026 08:58:15 +0100 Subject: [PATCH] Update plan after Macro comparison --- Docs/PLAN.md | 794 ++++----------------------------------------------- 1 file changed, 48 insertions(+), 746 deletions(-) diff --git a/Docs/PLAN.md b/Docs/PLAN.md index 0d1a7d9..c3d3971 100644 --- a/Docs/PLAN.md +++ b/Docs/PLAN.md @@ -1,746 +1,48 @@ -# Food Tracker Plugin Enhancement Plan - -## Executive Summary - -This document outlines a comprehensive enhancement plan for the Food Tracker plugin to establish it as the premier nutrition tracking solution for Obsidian. The plan addresses critical missing features, improves existing functionality, and introduces advanced capabilities for comprehensive health and nutrition management. - -## Core Feature Enhancements - -### 1. Advanced Data Visualization System - -#### 1.1 Trend Graphs and Analytics - -**Objective**: Implement interactive, customizable charts showing nutrition trends over time with detailed analytics. - -**Technical Implementation**: - -- **Charting Library**: Integrate Chart.js or D3.js for flexible, interactive visualizations -- **Data Aggregation Engine**: - - Daily, weekly, monthly, and custom date range views - - Rolling averages and trend lines - - Comparative analysis (week-over-week, month-over-month) -- **Chart Types**: - - Line charts for macro trends over time - - Stacked bar charts for daily macro distribution - - Pie charts for macro percentage breakdowns - - Heat maps for meal pattern visualization - - Scatter plots for correlation analysis (e.g., calories vs. energy levels) - -**UI Components**: - -```typescript -interface ChartConfiguration { - type: "line" | "bar" | "pie" | "heatmap" | "scatter"; - dateRange: DateRange; - nutrients: NutrientType[]; - aggregation: "daily" | "weekly" | "monthly"; - showGoals: boolean; - showAverages: boolean; -} -``` - -**Data Structure**: - -```typescript -interface NutritionTrend { - date: Date; - nutrients: Map; - meals: MealEntry[]; - goals: NutrientGoals; - symptoms?: SymptomEntry[]; -} -``` - -#### 1.2 Interactive Dashboard View - -**Features**: - -- Dedicated view pane in Obsidian for comprehensive nutrition dashboard -- Customizable widget layout (drag-and-drop) -- Real-time data updates -- Export capabilities for charts (PNG, SVG, PDF) -- Dark/light theme support matching Obsidian theme - -**Implementation Details**: - -- Create new `DashboardView` class extending Obsidian's `ItemView` -- Implement widget system with pluggable components -- Use CSS Grid for responsive layout -- Cache rendered charts for performance - -### 2. Enhanced Food Entry System - -#### 2.1 Custom Portion Management - -**Objective**: Allow users to define and reuse custom portion sizes for frequently consumed items. - -**Technical Implementation**: - -**Data Model**: - -```typescript -interface CustomPortion { - id: string; - foodId: string; - name: string; // e.g., "my breakfast bowl", "standard lunch plate" - amount: number; - unit: NutritionUnit; - isDefault: boolean; - createdAt: Date; - lastUsed: Date; -} -``` - -**Storage**: - -- Store in dedicated `portions.json` file in plugin data folder -- Implement `PortionManager` service for CRUD operations -- Auto-suggest custom portions in food entry autocomplete - -**UI Features**: - -- Quick portion buttons in food entry modal -- "Save as custom portion" option after each entry -- Portion management tab in settings -- Smart defaults based on usage patterns - -#### 2.2 Meal Timestamp System - -**Objective**: Track exact meal times for pattern analysis and circadian rhythm insights. - -**Implementation**: - -**Entry Format Enhancement**: - -```markdown -#food @08:30 [[apple]] 150g -#food @lunch [[chicken-salad]] 250g -#food @2024-01-15T14:30 [[protein-bar]] 1 serving -``` - -**Time Parser**: - -```typescript -interface MealTiming { - timestamp: Date; - mealType?: "breakfast" | "lunch" | "dinner" | "snack"; - relativeTime?: string; // "30 min before workout" -} -``` - -**Features**: - -- Support multiple time formats (24h, 12h AM/PM, relative times) -- Automatic meal type detection based on time ranges -- Time-based analytics (eating windows, fasting periods) -- Meal frequency analysis -- Integration with symptom tracking for temporal correlation - -#### 2.3 Barcode Scanning Integration - -**Objective**: Enable quick food entry via barcode scanning on mobile devices. - -**Technical Implementation**: - -**Scanner Integration**: - -```typescript -interface BarcodeScanner { - scan(): Promise; - lookupProduct(barcode: string): Promise; - supportedFormats: BarcodeFormat[]; -} -``` - -**API Integration**: - -- Primary: OpenFoodFacts barcode API -- Fallback: USDA FoodData Central -- Local cache for frequently scanned items - -**Mobile Implementation**: - -- Use device camera API via Capacitor/Cordova plugin -- QuaggaJS for web-based scanning fallback -- Offline mode with cached barcode database - -**Workflow**: - -1. Tap barcode icon in mobile toolbar -2. Camera opens with scanning overlay -3. Automatic product lookup on successful scan -4. Pre-filled nutrition modal with product details -5. Quick portion adjustment before saving - -### 3. Health & Symptom Tracking - -#### 3.1 Comprehensive Symptom Logger - -**Objective**: Track physical symptoms and correlate with food intake for pattern identification. - -**Data Model**: - -```typescript -interface SymptomEntry { - id: string; - timestamp: Date; - symptoms: Symptom[]; - severity: 1 | 2 | 3 | 4 | 5; - notes?: string; - possibleTriggers?: string[]; - duration?: number; // minutes -} - -interface Symptom { - type: SymptomType; - location?: string; - characteristics?: string[]; -} - -enum SymptomType { - DIGESTIVE = "digestive", - HEADACHE = "headache", - FATIGUE = "fatigue", - SKIN = "skin", - RESPIRATORY = "respiratory", - MOOD = "mood", - ENERGY = "energy", - CUSTOM = "custom", -} -``` - -**Entry Format**: - -```markdown -#symptom @14:30 bloating severity:3 duration:45min -#symptom @16:00 headache severity:2 location:frontal -#symptom @evening fatigue severity:4 note:"after heavy lunch" -``` - -**Correlation Engine**: - -```typescript -class SymptomCorrelator { - analyzePatterns(timeWindow: number): CorrelationResult[]; - identifyTriggers(symptom: SymptomType): PotentialTrigger[]; - generateReport(dateRange: DateRange): HealthReport; -} -``` - -#### 3.2 AI-Powered Pattern Analysis - -**Objective**: Use machine learning to identify food-symptom correlations and provide insights. - -**Implementation Strategy**: - -**Local Analysis**: - -- Pattern matching algorithms for common triggers -- Statistical correlation analysis -- Time-series analysis for delayed reactions -- Elimination diet tracking and suggestions - -**Optional Cloud Analysis** (with user consent): - -- Integration with OpenAI API for advanced pattern recognition -- Natural language processing for symptom descriptions -- Personalized recommendation generation - -**Privacy Considerations**: - -- All analysis opt-in with clear data usage explanation -- Local-first approach with cloud as optional enhancement -- Data anonymization before any external transmission - -### 4. Hydration & Fluid Tracking - -#### 4.1 Fluid Intake Monitor - -**Objective**: Track water and beverage consumption with hydration goals. - -**Data Model**: - -```typescript -interface FluidEntry { - timestamp: Date; - type: FluidType; - amount: number; - unit: "ml" | "l" | "oz" | "cups"; - caffeine?: number; // mg - alcohol?: number; // grams - sugar?: number; // grams - electrolytes?: ElectrolyteProfile; -} - -enum FluidType { - WATER = "water", - COFFEE = "coffee", - TEA = "tea", - JUICE = "juice", - SODA = "soda", - ALCOHOL = "alcohol", - SPORTS_DRINK = "sports", - MILK = "milk", - OTHER = "other", -} -``` - -**Entry Format**: - -```markdown -#drink water 500ml -#drink @09:00 coffee 250ml caffeine:95mg -#drink green-tea 200ml -``` - -**Features**: - -- Hydration reminder system -- Daily/hourly intake goals -- Caffeine and alcohol tracking -- Hydration status indicator -- Integration with main nutrition dashboard - -### 5. Extended Nutrition Database - -#### 5.1 Micronutrient Tracking - -**Objective**: Expand beyond macros to track vitamins, minerals, and other nutrients. - -**Enhanced Nutrient Model**: - -```typescript -interface ExtendedNutrients { - // Existing macros - calories: number; - fats: number; - protein: number; - carbs: number; - fiber: number; - sugar: number; - sodium: number; - - // New additions - vitamins: { - a?: number; // IU or mcg RAE - b1?: number; // mg (thiamine) - b2?: number; // mg (riboflavin) - b3?: number; // mg (niacin) - b5?: number; // mg (pantothenic acid) - b6?: number; // mg - b7?: number; // mcg (biotin) - b9?: number; // mcg (folate) - b12?: number; // mcg - c?: number; // mg - d?: number; // IU or mcg - e?: number; // mg - k?: number; // mcg - }; - - minerals: { - calcium?: number; // mg - iron?: number; // mg - magnesium?: number; // mg - phosphorus?: number; // mg - potassium?: number; // mg - zinc?: number; // mg - copper?: number; // mg - manganese?: number; // mg - selenium?: number; // mcg - iodine?: number; // mcg - }; - - other: { - cholesterol?: number; // mg - transFat?: number; // g - monounsaturatedFat?: number; // g - polyunsaturatedFat?: number; // g - omega3?: number; // g - omega6?: number; // g - caffeine?: number; // mg - alcohol?: number; // g - }; -} -``` - -**Database Enhancement**: - -- Automatic nutrient data enrichment from OpenFoodFacts -- USDA database integration for comprehensive data -- Custom nutrient profile creation -- RDA (Recommended Daily Allowance) tracking - -### 6. Export & Integration System - -#### 6.1 Comprehensive Export Functionality - -**Objective**: Enable data export in multiple formats for analysis and sharing. - -**Supported Formats**: - -**CSV Export**: - -```typescript -interface CSVExporter { - exportDaily(date: Date): string; - exportRange(start: Date, end: Date): string; - exportCustom(options: ExportOptions): string; -} -``` - -**JSON Export**: - -- Structured data with full nutrient profiles -- Symptom correlations included -- Custom portion definitions -- Goals and achievements - -**PDF Reports**: - -- Weekly/monthly nutrition summaries -- Charts and visualizations included -- Symptom correlation reports -- Goal achievement tracking -- Professional formatting for healthcare provider sharing - -**Integration Formats**: - -- MyFitnessPal compatible format -- Cronometer compatible format -- Apple Health export (iOS) -- Google Fit export (Android) - -#### 6.2 API & Webhook System - -**Objective**: Enable third-party integrations and automation. - -**Features**: - -```typescript -interface APIEndpoints { - "/api/nutrition/today": NutritionSummary; - "/api/nutrition/range": NutritionData[]; - "/api/symptoms/recent": SymptomEntry[]; - "/api/correlations": CorrelationAnalysis; -} -``` - -**Webhook Support**: - -- Daily summary webhooks -- Goal achievement notifications -- Symptom alert webhooks -- Custom event triggers - -### 7. Advanced Entry Methods - -#### 7.1 Properties-Based Entry System - -**Objective**: Support Obsidian properties as alternative to tags. - -**Implementation**: - -**Properties Format**: - -```yaml ---- -meals: - - name: "Breakfast" - time: "08:30" - items: - - food: "[[oatmeal]]" - amount: 150 - unit: "g" - - food: "[[banana]]" - amount: 1 - unit: "medium" -hydration: - - type: "water" - amount: 500 - unit: "ml" - time: "09:00" -symptoms: - - type: "fatigue" - severity: 3 - time: "14:00" ---- -``` - -**Parser Implementation**: - -```typescript -class PropertiesParser { - parseNutrition(properties: any): NutritionEntry[]; - parseHydration(properties: any): FluidEntry[]; - parseSymptoms(properties: any): SymptomEntry[]; - validateSchema(properties: any): ValidationResult; -} -``` - -**Benefits**: - -- Structured data entry -- Better integration with Dataview queries -- Template support -- Bulk entry capabilities - -#### 7.2 Recipe & Meal Template System - -**Objective**: Create reusable meal templates and recipe calculations. - -**Recipe Management**: - -```typescript -interface Recipe { - id: string; - name: string; - servings: number; - ingredients: Ingredient[]; - instructions?: string; - nutritionPerServing: ExtendedNutrients; - tags: string[]; - prepTime?: number; - cookTime?: number; -} - -interface Ingredient { - food: string; - amount: number; - unit: string; - preparation?: string; -} -``` - -**Features**: - -- Recipe builder interface -- Automatic nutrition calculation -- Serving size adjustment -- Recipe sharing and import -- Integration with meal planning - -### 8. Smart Suggestions & Automation - -#### 8.1 Intelligent Food Recommendations - -**Objective**: Provide smart food suggestions based on goals and patterns. - -**Recommendation Engine**: - -```typescript -class SmartRecommender { - suggestNextMeal(currentIntake: NutritionSummary): FoodSuggestion[]; - suggestAlternatives(food: string): Alternative[]; - generateMealPlan(goals: NutrientGoals): MealPlan; - identifyDeficiencies(): NutrientDeficiency[]; -} -``` - -**Features**: - -- Goal-based meal suggestions -- Nutrient deficiency alerts -- Balanced meal recommendations -- Alternative food suggestions -- Meal timing optimization - -#### 8.2 Automated Data Entry - -**Objective**: Reduce manual entry through smart automation. - -**Implementation**: - -- Voice input support via Web Speech API -- Photo-based food recognition (via external API) -- Recurring meal templates -- Quick entry shortcuts -- Batch import from photos - -### 9. Performance & Architecture Improvements - -#### 9.1 Database Optimization - -**Objective**: Improve performance for large datasets. - -**Strategies**: - -- IndexedDB for client-side data storage -- Lazy loading for large nutrient databases -- Incremental search with debouncing -- Virtual scrolling for long lists -- Background data processing with Web Workers - -#### 9.2 Modular Architecture - -**Objective**: Create pluggable architecture for feature extensions. - -**Core Modules**: - -```typescript -interface PluginModule { - id: string; - name: string; - version: string; - initialize(): Promise; - cleanup(): void; - settings?: ModuleSettings; -} -``` - -**Planned Modules**: - -- Core nutrition tracking -- Symptom tracking -- Hydration monitoring -- Recipe management -- Export/import -- Analytics & visualization -- AI insights -- Social features - -### 10. User Experience Enhancements - -#### 10.1 Mobile-First Optimizations - -**Improvements**: - -- Touch-optimized controls -- Swipe gestures for quick entry -- Mobile-specific layouts -- Offline functionality -- Background sync - -#### 10.2 Accessibility Features - -**Implementation**: - -- Full keyboard navigation -- Screen reader support -- High contrast mode -- Font size adjustments -- Color blind friendly palettes - -#### 10.3 Onboarding & Education - -**Features**: - -- Interactive tutorial -- Sample data for testing -- Video guides -- Tooltips and help system -- Common recipe library - -## Implementation Priority & Timeline - -### Phase 1: Core Enhancements (Weeks 1-4) - -1. Trend graphs and basic analytics -2. Custom portion sizes -3. Meal timestamps -4. Basic symptom tracking -5. CSV export functionality - -### Phase 2: Advanced Features (Weeks 5-8) - -1. Comprehensive dashboard view -2. Extended nutrition database -3. Fluid tracking -4. Enhanced symptom correlation -5. PDF report generation - -### Phase 3: Smart Features (Weeks 9-12) - -1. Barcode scanning -2. AI-powered analysis -3. Recipe management -4. Smart recommendations -5. Properties-based entry - -### Phase 4: Integration & Polish (Weeks 13-16) - -1. Third-party integrations -2. API & webhooks -3. Performance optimizations -4. Mobile optimizations -5. Comprehensive testing - -## Technical Requirements - -### Development Environment - -- TypeScript 5.x with strict mode -- Jest for unit testing (>80% coverage target) -- ESLint & Prettier for code quality -- Webpack for bundling -- GitHub Actions for CI/CD - -### Dependencies - -- Chart.js or D3.js for visualizations -- RxJS for reactive state management -- IndexedDB for local storage -- jsPDF for PDF generation -- Papa Parse for CSV handling -- QuaggaJS for barcode scanning - -### Testing Strategy - -- Unit tests for all core functionality -- Integration tests for data flow -- E2E tests for critical user paths -- Performance benchmarks -- Accessibility testing - -### Documentation Requirements - -- API documentation for all public methods -- User guide with screenshots -- Video tutorials for complex features -- Developer documentation for contributors -- Migration guides for updates - -## Success Metrics - -### Performance Targets - -- Initial load time < 500ms -- Search response < 100ms -- Chart rendering < 300ms -- Cache hit rate > 90% -- Memory usage < 50MB - -### User Experience Goals - -- Setup time < 5 minutes -- Daily entry time < 2 minutes -- Zero data loss guarantee -- 99.9% calculation accuracy -- Mobile responsiveness score > 95 - -### Feature Adoption Targets - -- 80% users using trend graphs weekly -- 60% users tracking symptoms -- 50% users setting up custom portions -- 40% users using export features -- 30% users enabling AI insights - -## Risk Mitigation - -### Technical Risks - -- **Performance degradation**: Implement progressive loading and caching -- **Data corruption**: Regular backups and validation checks -- **API dependencies**: Fallback mechanisms and offline mode -- **Breaking changes**: Comprehensive migration system - -### User Experience Risks - -- **Feature complexity**: Progressive disclosure and smart defaults -- **Learning curve**: Interactive tutorials and documentation -- **Data privacy concerns**: Local-first approach with clear consent -- **Platform limitations**: Graceful degradation for unsupported features - -## Conclusion - -This comprehensive plan positions the Food Tracker plugin as the most advanced nutrition tracking solution for Obsidian. By addressing current limitations and introducing innovative features, the plugin will serve users ranging from casual food trackers to those with specific health monitoring needs. The modular architecture ensures sustainable growth while maintaining performance and usability. +# Food Tracker Plugin Plan (updated 2026-01-05) + +## Current capabilities + +- Nutrient database with YAML frontmatter and OpenFoodFacts lookup by name or barcode via the "Add nutrient" modal; filenames are normalized and cached with auto-refresh on vault changes. +- Smart entry parsing: configurable `#food`/`#workout` tags, linked or inline entries, unit conversion (g, kg, ml, l, oz, lb, cup, tbsp, tsp, pc), negative calories allowed only on the food tag, and autocomplete for food names plus nutrition/measure keywords (workout tag suggests calories only). +- Real-time totals: status bar or in-document display with goals-aware progress bars, calorie hints, and totals clamped to zero; nutrition totals are written to frontmatter using customizable property names and backfilled when missing. +- Goals and daily notes: goals file loader with highlight support; daily note matching via configurable filename pattern (e.g., `YYYY-MM-DD`) feeds totals and stats. +- Monthly statistics: ribbon command opens a month picker/table that aggregates frontmatter totals per day; falls back to recalculation when frontmatter is missing. +- Settings UX: type-ahead folder/file selectors, tag/workout tag/directory configuration, link style toggle (wikilink/markdown), and choice of showing totals in status bar or document. + +## Known gaps vs previous roadmap + +- No charting/dashboard view or trend graphs (current stats are table-only). +- Only a single default serving size per nutrient; no named reusable portion presets or quick-pick portions. +- No meal timestamps or eating-window analytics. +- No hydration or symptom logging. +- Barcode lookup exists, but there is no camera-based scanning flow. +- No exports (CSV/JSON/PDF), API/webhooks, or third-party integrations. +- No properties-based entry parser, recipes/meal templates, or smart recommendations/AI. + +## Prioritized roadmap (realistic next steps) + +1. **Custom portions & entry polish** + Keep the existing per-nutrient `serving_size`, and add user-named portion presets (e.g., "bowl", "scoop") that can be reused across entries and suggested in autocomplete. +2. **Time-aware logging** + Optional `@HH:mm`/`@breakfast` tokens on entries; persist timestamps to frontmatter and surface basic eating-window/frequency views in the stats modal (enables per-meal export and correlations). +3. **Symptom capture** + Simple `#symptom`/properties syntax with severity and notes; store alongside meal timestamps so users can manually correlate (no AI analysis yet). +4. **Lightweight exports** + CSV export per meal or per day/date-range using the frontmatter cache; copy-to-clipboard from the statistics modal for external analysis. +5. **Trend visuals** + Add small line/stacked-bar charts to the stats modal using a lightweight chart library (evaluate bundle size before choosing Chart.js vs. micro libs); reuse existing totals, no new storage. +6. **Barcode UX upgrade** + Keep current OpenFoodFacts lookup; add a "Scan barcode" action on mobile that opens the camera (QuaggaJS or native mobile hook) and pipes the result into the existing lookup. +7. **Properties-based entry option** + Allow meals, timestamps, portions, and symptoms to be logged via note properties as an alternative to tags; maintain both modes for compatibility. +8. **Fluid intake tracking (MVP)** + `#drink`/properties entries with volume and caffeine/alcohol fields; include in daily totals and optional hydration goal. + +## Deferred ideas (re-evaluate after the above) + +- Hydration tracking, symptom logger, micronutrient expansion, recipes/templates, API/webhooks, AI suggestions. +- Full dashboard view with drag-and-drop widgets. + +## Delivery cadence + +- Ship one scoped feature per release: custom portions (next), then time-aware logging, then exports. Reorder based on user feedback and performance impact.