Macro Gauge User Guide

Welcome to Macro Gauge — your comprehensive nutrition tracking platform powered by AI. Track calories, macros, water intake, and get personalized meal plans all in one beautifully designed application.

Getting Started

To begin using Macro Gauge, you'll need to create an account. The registration process is straightforward:

1. Click Register on the login page
2. Enter your email and create a secure password
3. Log in

Initial Setup

When you first log in, it is best to set your daily nutrition goals in the Settings Tab:

• Daily Calorie Goal - Your target daily calorie intake (default: 2000 kcal)
• Weekly Calorie Goal - Auto-calculated as daily × 7, or set manually
• Protein Goal - Daily protein target in grams (default: 150 g)
• Water Goal - Daily water intake target in liters (default: 2.0 L)

All four goals are saved with a single Save Goals button. Changes take effect immediately across the app.

Onboarding Tutorial

First-time users are greeted by a guided onboarding tour that walks through the core features of the app step by step. The tutorial highlights the key areas of the interface — Dashboard, Food Search, Calendar, Favourites, Workout Tracker, and Settings — with brief explanations for each.

• The tour launches automatically on first login
• A step counter shows your progress through the tour (e.g. "Step 3 of 7")
• You can advance with Next, go back with Previous, or exit early with Skip Tour
• Once completed or skipped, the tour does not appear again on subsequent logins

Dashboard Overview

The dashboard is your central hub for tracking daily nutrition. It's divided into several key sections:

Today's Summary

At the top of your dashboard, you'll see real-time statistics for:

Metric	Description
Calories	Total calories consumed vs. your daily goal
Protein	Grams of protein tracked for the day
Water	Liters of water logged vs. your hydration goal
Day Streak	Consecutive days you've met your goals

Quick Add Suggestions

The dashboard shows personalized suggestions based on your tracking history:

• Add more meals - When you're under your calorie goal
• Add more protein - When protein intake is low
• Stay hydrated - Reminder to log water intake

Food Search & Database

Macro Gauge offers three food database sources. You can switch between them at any time in Settings → Food Database.

Database Options

1. USDA Database (Default)

The USDA FoodData Central database provides comprehensive nutritional data for foods available in the United States. It includes:

• Branded products with barcodes
• Generic ingredients and whole foods
• Restaurant chain menu items
• USDA-verified nutritional accuracy

2. Open Food Facts (Global)

Open Food Facts is a collaborative, open-source database covering foods from around the world. When selected, you also choose a country to scope results. Supported countries:

Region	Countries Available
Global	World (all countries combined)
Americas	United States, Canada, Brazil, Mexico
Europe	United Kingdom, France, Germany, Italy, Spain, Belgium, Switzerland, Netherlands, Poland, Romania
Asia-Pacific	Australia, India, Japan, China

3. AI Smart Search (GPT-4o-mini)

The AI Smart Search uses GPT-4o-mini to look up nutritional information for any food you describe — including home-cooked meals, regional dishes, and items not in any traditional database.

• Multilingual — search in any language
• Flexible — describe dishes by their local name
• Estimated values — AI returns best-estimate macros based on standard recipes
• Limit: 10 AI searches per day per user (resets at midnight)

When AI Smart Search is selected in Settings, an info panel appears explaining the daily limit along with a live counter showing "X / 10 searches remaining today" — so you always know exactly how many lookups you have left before the midnight reset.

AI Natural Language Food Log

The AI Log button in the search bar opens a plain-text food logging panel. Instead of searching for individual items, simply describe your entire meal in natural language and let AI parse it into individual cart items.

1. Click the AI Log button (chat bubble icon) in the header search bar
2. Type a description of what you ate — e.g. "I had oatmeal with a banana and two scrambled eggs"
3. Press Parse & Add to Cart (or Ctrl/Cmd+Enter)
4. A preview panel shows each parsed item with estimated grams and macros — review before confirming
5. Click Add all to Cart to push all items to your cart at once

Manual Food Entry

In addition to searching the databases, you can enter any food completely manually using the Manual Entry form.

1. Click the Manual Entry tab in the food search panel
2. Fill in the food name, serving size in grams, and the per-100g nutritional values: calories, protein, fat, and carbs
3. A live preview panel instantly displays the calculated macros for your entered serving size as you type — no need to submit first
4. Animated proportion bars for protein, carbs, and fat update in real time to show the macro balance visually
5. Click Add to Cart to add the custom entry to your cart, exactly like a database search result

How to Search

1. Select your database source in Settings → Food Database
2. Type your food name in the search box on the main page
3. Browse results sorted by relevance (exact matches first)
4. Click a result to expand it and see full macro details

Search Tips

// Good searches
"chicken breast"
"olive oil"
"greek yogurt"

// More specific = better results
"grilled chicken breast 100g"
"extra virgin olive oil"
"plain greek yogurt 2%"

// AI Database examples
"Mămăligă cu brânză"
"Palak paneer restaurant portion"
"Homemade beef stew with potatoes"

Adding Food to Your Log

Once you find a food item:

1. Click the + Add button next to the result
2. Adjust serving size in grams if needed
3. The item is added to your cart for the current day
4. Click Log Meals to save the cart to your daily log

Serving Size Presets

When viewing a food's detail panel in the search results, a row of quick preset buttons lets you jump to common serving sizes instantly: 100 g, 150 g, 200 g, 250 g, and 300 g. Clicking a preset fills the grams input and highlights the active button — no manual typing needed for standard portions.

Cart & Favourites

The Cart holds foods you've added before logging. You can:

• Adjust grams for any item before logging
• Remove items from the cart
• Save the entire cart as a Favourite (named group) for quick re-use

The Favourites Matrix stores your saved meal groups. From there you can:

• Quick-add a favourite to the cart
• Log a favourite directly to a specific calendar date
• Delete favourites you no longer need

Inline Editing

Click the Edit button on any favourite card to open an inline edit panel directly below it — no modal, no page navigation. From the edit panel you can:

• Rename the favourite
• Adjust the gram weight of individual items — macros rescale proportionally in real time
• Remove individual items from the group
• Add or remove tags (see below)
• Save or cancel without leaving the favourites page

Tags & Folders

Organise your favourites with tags. Each favourite can have multiple tags, and a filter bar above the favourites list lets you narrow results by tag instantly.

• Preset tags: Breakfast, Lunch, Dinner, Snack, Bulk, Cut, Cheat Meal, Pre-workout, Post-workout
• Custom tags: type any label in the custom tag input and click Add
• Click a tag chip in the filter bar to show only favourites with that tag
• Click the active tag again (or click All) to clear the filter
• Tags are saved to your account in the cloud and persist across devices

Calendar & Historical Tracking

The Calendar view lets you track and review nutrition data across any date range.

Calendar Features

• Visual Day Indicators — Green = goal met, Yellow = partial, Gray = no data, Red = exceeded goal
• Date Navigation — Click any date to open a full-day summary popup showing all logged meals, water intake, and workout sessions
• Week View — See 7 days at a glance with macro totals per day
• Monthly Analytics — Track streaks and average daily intake for the month

Daily Notes

Every calendar day supports a freeform text note. Open any day's popup and use the notes field to record how you felt, what affected your eating, or any other context you want to remember alongside your macro data.

• Notes are saved per-date and persist in the cloud
• Days with a saved note show a small indicator icon on the calendar tile
• Notes are visible in the day summary popup and can be edited or deleted at any time

AI Meal Planner

The AI Meal Planner uses GPT-4o-mini to generate personalized 7-day meal plans based on your preferences and goals.

How It Works

The meal planner guides you through an 8-question quiz covering:

1. Goal - Weight loss, maintenance, or muscle gain
2. Dietary Restrictions - Vegan, vegetarian, keto, gluten-free, etc.
3. Calorie Target - Auto-filled from your settings, editable
4. Foods to Avoid - Allergens or personal dislikes
5. Cuisine Preferences - Italian, Asian, Mediterranean, etc.
6. Meals Per Day - 3, 4, 5, or 6 meals
7. Budget - Low, medium, or high
8. Shopping Preference - Minimal ingredients vs. complex recipes

Meal Plan Output

After submitting the quiz, you receive:

• 7-Day Plan - Monday through Sunday meals
• Macro Breakdown - Calories, protein, carbs, fat for each meal
• Daily Totals - Per-day calorie sum aligned to your goal
• CSV Export - Download your plan as a spreadsheet

Sample Meal Plan Structure

Day	Breakfast	Lunch	Dinner	Total
Monday	Oatmeal with Berries (350 kcal)	Grilled Chicken Salad (450 kcal)	Salmon with Vegetables (550 kcal)	1,350 kcal

Re-generate

If you want a new plan, click the Re-generate button. Before discarding your current plan, an inline confirmation panel appears:

• "This will delete your current plan. Are you sure?"
• Confirm to launch the quiz again and generate a fresh plan
• Cancel to keep your existing plan unchanged

Shopping List

Once a meal plan is generated, a Shopping List tab appears alongside the plan. The list is auto-generated from all 7 days of meals — ingredients are grouped by category (Proteins, Vegetables, Grains & Starches, Dairy, Fruits, Fats & Oils, Legumes, Nuts & Seeds, Condiments & Spices, Other) and deduplicated so the same ingredient doesn't appear twice.

• Check off items as you shop — checked state is saved in your browser
• Use Copy All to copy the full list to your clipboard
• Use Export to download the list as a text file
• Use Uncheck All to reset the checklist for a new shopping trip

7-Day Cooldown

To prevent excessive API usage, there's a 7-day cooldown between meal plan generations. After generating:

• The Re-generate button shows a live countdown timer: 6d 23h 41m 12s
• Re-generation is locked until the cooldown expires
• Your existing plan remains fully visible and exportable during the cooldown

Export to CSV

Click Export CSV to download your meal plan in spreadsheet format:

Day,Meal Type,Meal Name,Calories,Protein (g),Carbs (g),Fat (g)
Monday,Breakfast,Paneer Bhurji,400,28,8,30
Monday,Lunch,Palak Paneer,450,22,14,36
Monday,Dinner,Dal Makhani with Rice,520,18,72,14

Workout Tracker

The Workout Tracker is a full exercise logging module built into Macro Gauge. Log workout sessions, build custom routines from a library of 100+ exercises, estimate calorie burn, and get an AI-generated weekly training plan.

Exercise Library

The built-in library covers exercises across all major muscle groups and movement categories:

Muscle Groups	Categories
Chest, Back, Shoulders	Strength, Compound, Isolation
Biceps, Triceps, Core	Bodyweight, Plyometric
Legs, Glutes	Olympic, Cardio, Stability
Cardio, Full Body	100+ exercises total

Session Builder

Build your workout session before or during training:

1. Browse or search the exercise library and click Add Exercise
2. For each exercise, enter the number of sets, reps, and rest time between sets
3. Calorie burn is estimated automatically per exercise using the MET (Metabolic Equivalent of Task) formula: MET × bodyweight (kg) × duration (hours)
4. Build up your full session and click Log Workout to save it

Progressive Overload Suggestions

When adding an exercise that you've logged before, the session builder automatically checks your history and displays a progressive overload suggestion — a recommended weight and rep count based on a 2.5% increase from your last logged session.

• The hint appears as a banner below the exercise with the suggested weight (rounded to nearest 0.5 kg) and reps
• Click Apply to instantly fill the inputs with the suggested values
• Ignore the suggestion to enter your own values as usual
• No suggestion appears for exercises you've never logged — the system only shows it when history is available

Workout Templates

Save any session you've built as a reusable template so you can start identical sessions without rebuilding them from scratch each time.

1. Build a session in the session builder
2. Click Save as Template, enter a name, and confirm
3. Open the Templates tab to see all saved templates
4. Click Load Template on any template to populate the session builder with its exercises instantly
5. Delete templates you no longer need with the trash icon

Workout History & Progressive Overload

Every logged session is saved to your account in the cloud, organized by date. You can review past workouts by selecting a date, seeing all exercises, sets, reps, and calorie burn for that session. All data syncs across devices automatically.

The workout history includes progressive overload tracking: for each exercise, the history panel shows how the weight or resistance has changed across previous sessions — helping you spot stagnation and plan smart increases.

Workout ↔ Nutrition Integration

Logged workout sessions are now reflected in your daily nutrition dashboard. The calories burned during a session are automatically deducted from your net calorie total for the day, giving you an accurate picture of your energy balance without any manual adjustment.

Plan vs. Reality Weekly View

The Workout tab now includes a Plan vs. Reality panel that compares your AI-generated weekly training plan against what you actually logged:

• Each day of the week shows the planned session alongside any sessions you actually completed
• Days where you trained but had no plan are flagged as unplanned sessions
• Rest days in the plan are compared against rest days in your log
• Gives an at-a-glance view of how closely you followed the plan — no AI usage, purely data-driven

AI Weekly Workout Plan

The AI Weekly Workout Plan feature uses GPT-4o-mini to generate a structured 7-day training plan tailored to your goal.

• Select your training goal: Build Muscle, Lose Fat, Improve Endurance, or similar
• The AI returns a full week with specific exercises, sets, reps, and rest days assigned to each day
• Your generated plan is cached in your account so it persists across page reloads — no need to regenerate every session
• A server-side cooldown (configured via environment settings) prevents excessive API calls between regenerations

Progress Tracker

The Progress Tracker has two sections: Analytics & Charts (calorie/macro trends, streaks, personal records, and weekly breakdowns from your daily logs) and Body Composition (weight and measurement tracking over time).

Streak Counters

The analytics dashboard shows four separate streak counters, each tracking a different daily goal:

• Calorie Streak — consecutive days your calorie goal was met
• Protein Streak — consecutive days your protein goal was met
• Water Streak — consecutive days your hydration goal was met
• Perfect Day Streak — consecutive days all three goals (calories, protein, and water) were met simultaneously

Monthly Overview

The monthly overview section shows aggregate stats for the current month:

• Total calories logged and average daily calories, plus percentage of daily goal achieved
• Same stats for protein and water intake

Personal Records

Your best-ever single-day performances are tracked automatically:

• Best Day — the date, calories, and protein logged on your top-performing day
• Highest Protein Day — highest single-day protein intake ever recorded
• Best Hydration Day — highest single-day water intake ever recorded
• Longest Streak — your all-time longest streak of any kind

Weekly Averages Breakdown

The analytics section displays 4 separate weekly panels, each showing the average calories, protein, and water logged during that calendar week. This lets you identify patterns and compare performance week by week within a month.

Chart Types

Three chart types are available, toggled with tab buttons:

• Macros Trend — line chart showing Calories, Protein, Fat, and Carbs across the month (desktop: full month; mobile: 7 days)
• Hydration Chart — bar chart of daily water intake over the selected period
• Goals Achievement — chart showing how close you came to your daily goals each day

All charts are powered by Chart.js with smooth animations.

Workout Analytics

Alongside nutrition and hydration, the Analytics page now includes a dedicated Workout Analytics section that reads from your logged training sessions:

• Monthly workout stats — sessions logged, active training days, total calories burned (with per-session average), total sets and unique exercises performed, and total volume lifted (weight × reps × sets)
• Workout personal records — your all-time Heaviest Lift (ranked by Brzycki one-rep-max estimate), Top Calorie Burn session, Top Volume session, and Workout Streak counting consecutive weeks with at least one logged session
• Muscle group distribution — ranked horizontal bars showing how many sets you've trained per muscle group during the current month, making imbalances easy to spot at a glance

All workout analytics refresh live whenever a session is logged or deleted — no manual refresh needed.

Body Composition Tracker

Log your physical measurements over time and visualize trends with an interactive Chart.js line chart.

Weight Entries

Log your body weight with optional body fat percentage:

• Enter date, weight (kg or lb), and optional body fat %
• All entries are saved to the backend and persist across sessions
• The weight history table shows all entries chronologically
• Delete any entry with the trash icon

Measurement Entries

Log body measurements in centimeters:

Field	Description
Chest	Chest circumference (cm)
Waist	Waist circumference (cm)
Hips	Hip circumference (cm)
Arms	Upper arm circumference (cm)
Legs	Thigh circumference (cm)
Body Fat %	Optional — can be logged here or with weight

Goal Weight

Set a target weight to display as a reference line on your weight chart. The goal bar shows how far you are from your target and fills as you approach it.

Chart Controls

The body composition chart supports three time period filters:

• 1 Month - Last 30 days
• 3 Months - Last 90 days
• All Time - Every entry ever logged

Settings & Customization

Access Settings from the sidebar. The settings page is organized into five panels: Goals, Food Database, Profile, Appearance, and Account.

Goals Panel

Set all four nutrition targets in one place:

• Daily Calorie Goal — Main daily energy target (kcal)
• Weekly Calorie Goal — Set manually or let it auto-fill as daily × 7
• Protein Goal — Daily protein target in grams
• Fat Goal — Daily fat target in grams (optional)
• Carbs Goal — Daily carbohydrate target in grams (optional)
• Water Goal — Daily hydration target in liters

Click the single Save Goals button to save all values at once.

Food Database Panel

Choose your preferred food search source:

• USDA — US-focused, high accuracy for American products
• Open Food Facts — Global coverage; shows a country selector when active
• AI Smart Search — GPT-4o-mini lookup for any food in any language; 10 searches/day limit

When Open Food Facts is selected, a country dropdown appears. Choose from 18 countries including World (global), US, UK, France, Germany, Italy, Spain, Canada, Australia, Belgium, Switzerland, Netherlands, Poland, Romania, Brazil, Mexico, India, Japan, and China.

When AI Smart Search is selected, an info panel appears beneath the selector with a live counter: "X / 10 searches remaining today". The counter updates after each search.

Profile Panel

Personalise your Macro Gauge identity:

• Display Name — Set a nickname shown in the app (up to 30 characters). Defaults to your email username if not set
• Avatar — Upload a profile picture. Images are automatically resized for storage efficiency. Your avatar appears in the header and wherever your profile is shown
• Click Save Profile to apply changes

Appearance Panel

Switch between the two visual themes:

• Dark — The default dark cyber theme (deep navy backgrounds, indigo accents)
• Light — A clean light theme with soft backgrounds and the same indigo accent palette

Your preference is saved locally and applied immediately on every page load — no account setting required. Switching between themes is instant.

Account Panel

• Displays your username and registered email
• Change Password — Update your login password
• Delete Account — Permanently removes your account and all associated data (irreversible)

Troubleshooting

Common Issues

Food search returns no results

• Try simplifying your search term
• Switch to the other database (USDA ↔ Open Food Facts)
• Check spelling and remove brand names

Data not saving

• Check your internet connection
• Refresh the page and try again
• Clear browser cache and cookies
• Contact support if issue persists

Meal planner won't generate

• Verify you're not in the 7-day cooldown period
• Complete all 8 quiz questions
• Check that input fields don't contain special characters

Tips & Best Practices

For Accurate Tracking

1. Log meals immediately after eating
2. Use a kitchen scale for portion accuracy
3. Save frequent foods to Favorites
4. Review weekly averages, not daily fluctuations

For Better Meal Plans

1. Be specific in the "Foods to Avoid" field (e.g., "no shellfish" is better than "no seafood")
2. Choose cuisines you genuinely enjoy eating regularly
3. Match meals per day to your actual eating schedule
4. Export to CSV immediately — the 7-day cooldown means you can't re-generate for a week
5. Click Re-generate only when you're sure — it permanently replaces your current plan

Support

Need help? We're here for you:

• Email: contact@web-runner.net
• Documentation: This page (bookmark it!)