SparkyFitness Documentation

SparkyFitness uses a client-server model with a clear separation of concerns:

• Frontend: A React application (Vite + TypeScript) that communicates with the backend via HTTP/API.
• Backend: A Node.js/Express.js API that handles business logic, authentication, and integrations.
• Data Layer: A PostgreSQL database (v15+) utilizing Row Level Security (RLS) for data isolation, alongside AI services (OpenAI, Anthropic, Google) and external APIs (Nutritionix, OpenFoodFacts, etc.).

The production Docker Compose setup consists of the following core services:

• sparkyfitness-db: A PostgreSQL 15 (Alpine) database server. Data is persisted in a Docker volume mapped to ../postgresql on the host.
• sparkyfitness-server: The Node.js backend application. It depends on sparkyfitness-db and uses environment variables for database connections, logging, API encryption, JWT secrets, and the frontend URL.
• sparkyfitness-frontend: The React frontend served via Nginx. It maps host port 3004 to container port 80. It depends on sparkyfitness-server.

Optional Service:

• sparkyfitness-garmin: A microservice for syncing data from Garmin Connect. This is commented out by default in docker-compose.yml; uncomment the block to enable it.

SparkyFitness is a privacy-first, self-hosted fitness tracking platform.

Core Capabilities:

• Track nutrition, exercise, hydration, sleep, fasting, mood, and body measurements.
• Set goals and perform daily check-ins.
• View interactive charts and long-term reports.
• Manage multiple user profiles and family access.
• Support for light/dark themes and secure authentication (OIDC, TOTP, Passkey, MFA).

Health & Device Integrations: Automatically syncs activity (steps, workouts, sleep) and health metrics (weight, body measurements) from platforms including Apple Health, Google Health Connect/API, Fitbit, Garmin Connect, Withings, Polar Flow, Strava, and various food databases (OpenFoodFacts, USDA, etc.).

SparkyAI (Beta): A conversational interface that allows users to log food, exercise, and body stats via chat or by uploading food images.

SparkyFitness provides the following capabilities:

• Nutrition Tracking: Log meals, create custom foods, and analyze trends.
• Exercise Logging: Record workouts and browse an exercise database.
• Body Measurements: Track weight and measurements with progress visualization.
• AI Nutrition Coach: Chat-based food logging with image recognition support.
• Goal Setting: Set and track fitness and nutrition goals.
• Comprehensive Reports: Detailed analytics and progress tracking.
• Privacy-First: Self-hosted architecture for complete data control.

The Period & Cycle Hub provides five distinct tracking modes designed for different physiological phases. Use the following summary to determine which mode fits your current needs:

SparkyFitness integrates with Apple HealthKit and Google Health Connect to provide fitness insights.

Data Collection

With explicit user permission, the App may read the following data from the device's health database:

• Active Energy Burned
• Basal Metabolic Rate
• Steps
• Workouts

The App may also write data (such as workout sessions) to these services when using tracking features.

Data Usage

• Display: Showing fitness progress and metrics within the App.
• Analysis: Calculating daily summaries (e.g., Total Calories).
• Storage: Health data is primarily processed locally on the device.

The application is built using the following technology stack:

• Frontend: React 18, TypeScript, Vite, and Tailwind CSS.
• Backend: Node.js, Express, and PostgreSQL.
• AI Integration: Multi-provider support including OpenAI, Anthropic, and Google.
• Deployment: Docker containers (supports both development and production configurations).
• Security: Implements Row Level Security (RLS), JWT authentication, and encrypted API keys.

The MCP server implements several security layers to protect your health data:

1. User Isolation (RLS): Tools are restricted by PostgreSQL Row Level Security. The AI can only access data belonging to the user authenticated by the provided API key.
2. Admin-Only Dev Tools: Debugging tools are off by default. They are only enabled if DEV_TOOLS_ENABLED=true and an admin API key is used. These tools bypass RLS and should only be used for active debugging.
3. Local First: If running SparkyFitness locally, your data remains on your infrastructure and is only sent to your chosen AI provider (e.g., Anthropic, OpenAI) when you interact with the assistant.

The chatbot-full.md file defines the persona and operational logic for Sparky, the AI nutrition and wellness coach. Sparky is designed to track food, exercise, and measurements, providing advice based on user data.

Key behaviors include:

• Direct Logging: When users state facts (e.g., "I ate X"), Sparky executes tool calls immediately without asking for permission.
• Data Retrieval: When asked about goals, calories, or progress, Sparky must use retrieval tools (e.g., sparky_get_goal_snapshot, sparky_get_nutrition_summary) rather than relying on memory.
• Clarification Logic: Sparky uses sparky_ask_user only when a lookup is ambiguous or requires weight conversions that cannot be safely inferred. Otherwise, it defaults to logging with safe assumptions (e.g., inferring meal type from time of day).