### Quick Start Server Setup with Docker Compose

Source: https://github.com/codewithcj/sparkyfitness/blob/main/README.md

This snippet outlines the steps to quickly set up a SparkyFitness server using Docker Compose. It includes downloading necessary files and starting the application. Ensure you have Docker and Docker Compose installed.

```bash
# 1. Create a new folder
mkdir sparkyfitness && cd sparkyfitness

# 2. Download Docker files only
curl -L -o docker-compose.yml https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/docker-compose.prod.yml
curl -L -o .env https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/default.env.example

# 3. (Optional) Edit .env to customize database credentials, ports, etc.

# 4. Start the app
docker compose pull && docker compose up -d

# Access application at http://localhost:8080
```

--------------------------------

### Backend Setup and Development Server

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Steps to set up the backend locally, including installing dependencies, configuring environment variables, running migrations, and starting the development server.

```bash
# Navigate to server directory
cd SparkyFitnessServer

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your database credentials

# Run database migrations
npm run migrate

# Start development server
npm run dev
```

--------------------------------

### Install SparkyFitness with Default Helm Settings

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/5.kubernetes.md

Use this command to install SparkyFitness with default configurations, including a bundled PostgreSQL and no ingress. This is the quickest way to get started.

```bash
# 1. Install with default settings (bundled PostgreSQL, no ingress)
helm install sparkyfitness oci://ghcr.io/codewithcj/charts/sparkyfitness
```

--------------------------------

### Quick Start Development Environment Setup

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/3.contributing.md

Clone the repository, copy the environment template, and start the development environment using Docker.

```bash
git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness

cp docker/.env.example .env

./docker/docker-helper.sh dev up
```

--------------------------------

### Clone and Start Development Environment with Docker

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Clone the SparkyFitness repository, set up the environment file, and start the development environment using the Docker helper script. This is the recommended quick start method.

```bash
git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness

cp docker/.env.example .env

./docker/docker-helper.sh dev up

# Access the application at http://localhost:8080
```

--------------------------------

### Install SparkyFitness from Source with Helm

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/5.kubernetes.md

Clone the SparkyFitness repository and install the Helm chart directly from the local source. This allows for easier modification of the chart before installation.

```bash
# -- OR install directly from source --
git clone https://github.com/CodeWithCJ/SparkyFitness.git
helm install sparkyfitness ./SparkyFitness/helm/chart
```

--------------------------------

### Frontend Development Server

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Commands to install frontend dependencies and start the development server for the SparkyFitness application.

```bash
# Navigate to project root
cd ..

# Install dependencies
npm install

# Start development server
npm run dev
```

--------------------------------

### Example API Key

Source: https://github.com/codewithcj/sparkyfitness/wiki/Apple-Health-Integration

An example of a valid API key format for authorization.

```text
Bearer MyAPIKey123123123123123123123123123
```

--------------------------------

### Start Metro Server

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/development.md

Starts the Metro server without running the app. Useful if you have a development build already installed and just need the server running.

```bash
npx expo start
```

--------------------------------

### Server Development Commands

Source: https://github.com/codewithcj/sparkyfitness/blob/main/AGENTS.md

Commands for starting the server, validation, testing, and test coverage.

```bash
pnpm start
pnpm run validate
pnpm test
pnpm run test:coverage
```

--------------------------------

### User Authentication Request Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/sync_api.md

An example HTTP GET request to the /auth/user endpoint, demonstrating the use of an API key for authentication.

```http
GET /auth/user
Authorization: Bearer <api_key>
```

--------------------------------

### Start Development Server

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessServer/CLAUDE.md

Starts the development server with hot reloading. Watches for changes in routes, services, models, integrations, config, db, and security directories.

```bash
pnpm start
```

--------------------------------

### Install SparkyFitness with Custom Helm Values

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/5.kubernetes.md

Install SparkyFitness using a custom values file to override default configurations. This is useful for setting up external databases, ingress, OIDC, or email services.

```bash
# 2. (Optional) Customize values
helm install sparkyfitness ./SparkyFitness/helm/chart -f my-values.yaml
```

--------------------------------

### Start PostgreSQL Container

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/8.postgres-upgrade.md

Bring up only the PostgreSQL database container to initialize the new volume and prepare for data restoration. Wait for initialization before proceeding.

```bash
docker compose up -d sparkyfitness-db
```

--------------------------------

### Create Food Request Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/food_api.md

Example JSON body for a POST /api/foods request, used to create a new custom food item.

```json
{
  "name": "Protein Shake",
  "brand": "Homemade",
  "user_id": "some-uuid-here",
  "is_custom": true,
  "is_quick_food": true,
  "barcode": null,
  "provider_external_id": null,
  "provider_type": null,
  "serving_size": 1,
  "serving_unit": "serving",
  "calories": 250,
  "protein": 30,
  "carbs": 15,
  "fat": 8,
  "saturated_fat": 2,
  "polyunsaturated_fat": null,
  "monounsaturated_fat": null,
  "trans_fat": 0,
  "cholesterol": null,
  "sodium": null,
  "potassium": null,
  "dietary_fiber": null,
  "sugars": 5,
  "vitamin_a": null,
  "vitamin_c": null,
  "calcium": null,
  "iron": null,
  "is_default": true,
  "glycemic_index": null,
  "custom_nutrients": {}
}
```

--------------------------------

### Install Sparkyfitness Helm Chart

Source: https://github.com/codewithcj/sparkyfitness/blob/main/helm/README.md

Deploys Sparkyfitness with a bundled PostgreSQL instance, auto-generated secrets, and default settings.

```bash
helm install sparkyfitness ./chart
```

--------------------------------

### Create Food Entry Response Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/food_api.md

Example JSON response for a successful POST /api/food-entries/ request, detailing a logged food entry.

```json
{
  "id": "15ff0d7d-aa8e-4a1e-bc78-cc5e0269e869",
  "user_id": "999838ee-15ce-4c24-ac56-875c5e9416a9",
  "food_id": "94b12152-4b3b-4a90-af9c-df6900efe5a5",
  "quantity": 100,
  "unit": "g",
  "entry_date": "2026-02-24T06:00:00.000Z",
  "created_at": "2026-02-24T11:27:50.252Z",
  "variant_id": "86687b55-7d88-4d19-8bda-31ae4ee9b810",
  "meal_plan_template_id": null,
  "created_by_user_id": "999838ee-15ce-4c24-ac56-875c5e9416a9",
  "food_name": "Sprite Bottle, 2 Liters",
  "brand_name": "Coca-Cola",
  "serving_size": 100,
  "serving_unit": "g",
  "calories": 39,
  "protein": 0,
  "carbs": 11,
  "fat": 0,
  "saturated_fat": null,
  "polyunsaturated_fat": null,
  "monounsaturated_fat": null,
  "trans_fat": null,
  "cholesterol": null,
  "sodium": null,
  "potassium": null,
  "dietary_fiber": null,
  "sugars": null,
  "vitamin_a": null,
  "vitamin_c": null,
  "calcium": null,
  "iron": null,
  "glycemic_index": null,
  "updated_by_user_id": "999838ee-15ce-4c24-ac56-875c5e9416a9",
  "meal_id": null,
  "food_entry_meal_id": null,
  "custom_nutrients": {},
  "meal_type_id": "d7bbfb6c-a5fb-48e0-9444-718bd20e7885"
}
```

--------------------------------

### Create and Configure PostgreSQL Database Locally

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

SQL commands to create the SparkyFitness database and a user with password authentication. Ensure PostgreSQL 15+ is installed.

```sql
CREATE DATABASE sparkyfitness;
CREATE USER sparky WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE sparkyfitness TO sparky;
```

--------------------------------

### Download Docker Compose and Environment Files

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/1.docker-compose.md

Create a directory for SparkyFitness, navigate into it, and download the production Docker Compose file and an example environment file using curl.

```bash
mkdir sparkyfitness && cd sparkyfitness
curl -o docker-compose.yml https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/docker-compose.prod.yml    
curl -L -o .env https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/default.env.example
```

--------------------------------

### SparkyFitness Environment Variables Setup

Source: https://github.com/codewithcj/sparkyfitness/wiki/Sample-Setup

Lists the necessary environment variables for configuring the SparkyFitness application.

```dotenv
SPARKY_FITNESS_DB_NAME=sparkyfitness_db
SPARKY_FITNESS_DB_USER=sparky
SPARKY_FITNESS_DB_PASSWORD=password
SPARKY_FITNESS_FRONTEND_URL=https://fit.domain.com
SPARKY_FITNESS_LOG_LEVEL=ERROR
NODE_ENV=production
TZ=Etc/UTC
SPARKY_FITNESS_API_ENCRYPTION_KEY=******
BETTER_AUTH_SECRET=******=
SPARKY_FITNESS_ADMIN_EMAIL=myemail@gmail.com
SPARKY_FITNESS_EMAIL_HOST=smtp.gmail.com
SPARKY_FITNESS_EMAIL_PORT=587
SPARKY_FITNESS_EMAIL_SECURE=false
SPARKY_FITNESS_EMAIL_USER=myemail@gmail.com
SPARKY_FITNESS_EMAIL_PASS=******
SPARKY_FITNESS_EMAIL_FROM=myemail@gmail.com
SPARKY_VERSION=latest
SPARKY_FITNESS_APP_DB_USER=sparky_asd
SPARKY_FITNESS_APP_DB_PASSWORD=password
SPARKY_FITNESS_DB_PORT=5434

```

--------------------------------

### Start SparkyFitness Services with Docker Compose

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/3.administration/3.manual_backup_restore.md

This command starts all the services defined in the Docker Compose file in detached mode, ensuring the SparkyFitness application is running after a restore.

```bash
docker compose up -d
```

--------------------------------

### Copy Environment Template

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Copies the example environment file to be used for local configuration. This file contains all necessary variables for database, application, and frontend settings.

```bash
cp docker/.env.example .env
```

--------------------------------

### Start SparkyFitness Application with Docker Compose

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/1.docker-compose.md

Pull the latest Docker images and start the SparkyFitness services in detached mode. This command ensures all necessary services are running in the background.

```bash
docker compose pull && docker compose up -d
```

--------------------------------

### Mobile Development Commands

Source: https://github.com/codewithcj/sparkyfitness/blob/main/AGENTS.md

Commands for starting the mobile app, running on iOS/Android, validation, and specific test configurations.

```bash
pnpm start
pnpm run ios
pnpm run android
pnpm run validate
pnpm run test:run -- --watchman=false --runInBand
npx expo prebuild -c
```

--------------------------------

### Start Development Database with Docker Compose

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docker/Docker_deploy_manual_command.md

Starts the development database service in detached mode using a specified Docker Compose file. This is useful for setting up the database environment for local development.

```bash
docker-compose -f docker-compose.db_dev.yml up -d
```

--------------------------------

### Run App on Android

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/development.md

Starts the Metro server and runs the app on an Android simulator or device. Prebuild is performed if necessary.

```bash
npx expo run:android
```

--------------------------------

### Repository Pattern Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/3.contributing.md

Illustrates the use of the repository pattern for database operations, including transaction management with BEGIN, COMMIT, and ROLLBACK.

```javascript
const userRepository = {
  async createUser(userData) {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      // Database operations
      await client.query('COMMIT');
      return result;
    } catch (error) {
      await client.query('ROLLBACK');
      throw error;
    } finally {
      client.release();
    }
  }
};
```

--------------------------------

### Install PostgreSQL Extensions and Grants

Source: https://github.com/codewithcj/sparkyfitness/blob/main/helm/chart/templates/NOTES.txt

Installs required PostgreSQL extensions and grants necessary privileges to the database owner for application functionality. Ensure you are connected to the correct database.

```sql
\c {{ .Values.externalDatabase.database }}

    -- Standard extensions
    CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
    CREATE EXTENSION IF NOT EXISTS "pgcrypto";

    -- Performance monitoring (requires shared_preload_libraries = 'pg_stat_statements')
    CREATE EXTENSION IF NOT EXISTS "pg_stat_statements";

    -- Grant extension functions to the DB owner so the app can delegate them
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO "<owner>" WITH GRANT OPTION;
```

--------------------------------

### Run App on iOS

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/development.md

Starts the Metro server and runs the app on an iOS simulator or device. Prebuild is performed if necessary.

```bash
npx expo run:ios
```

--------------------------------

### Run Development Docker Compose with Live Reloading

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Starts the development services defined in the docker-compose.dev.yml file, enabling live reloading.

```bash
docker-compose -f docker/docker-compose.dev.yml up
```

--------------------------------

### Verified Commands for SparkyFitnessServer

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessServer/AGENTS.md

A collection of verified commands for managing the SparkyFitnessServer package, including starting the server, running checks, testing, and linting.

```bash
pnpm start
pnpm run validate
pnpm run typecheck
pnpm run lint
pnpm run lint:fix
pnpm run format:check
pnpm run format
pnpm test
pnpm run test:watch
pnpm run test:coverage
pnpm run test:ci
pnpm exec vitest run tests/mealRoutes.test.ts
pnpm exec eslint routes/v2/foodRoutes.ts services/foodCoreService.ts
```

--------------------------------

### Run Full Test Suite Command

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/3.contributing.md

Command to run the full test suite, including application tests and manual testing setup.

```bash
# Test the application thoroughly
./docker/docker-helper.sh dev up
# Test your changes manually
# Run any automated tests
```

--------------------------------

### Frontend Test File Structure

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/7.testing.md

Illustrates the typical location of test files within the frontend project, including global setup and component tests.

```text
SparkyFitnessFrontend/
  src/tests/
    setupTests.ts              # Global test setup (jest-dom, polyfills)
    components/                # Component tests
      MealBuilder.test.tsx
      MealManagement.test.tsx
      MealPlanCalendar.test.tsx
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/2.features/15.mcp-server.md

Example JSON configuration for adding the SparkyFitness MCP server to Claude Desktop. Ensure you replace 'YOUR_SPARKY_FITNESS_API_KEY' with your actual API key.

```json
{
  "mcpServers": {
    "sparky-fitness": {
      "serverURL": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SPARKY_FITNESS_API_KEY"
      }
    }
  }
}
```

--------------------------------

### Get Foods Response Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/food_api.md

Example JSON response for the GET /api/foods endpoint, showing a list of Food objects and the total count.

```json
{
  "foods": [ /* array of Food objects */ ],
  "totalCount": 42
}
```

--------------------------------

### Start Production Environment with Docker

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Launches the production stack using the Docker helper script, providing optimized builds and an Nginx proxy for the application. The service is accessible via http://localhost:3004.

```bash
./docker/docker-helper.sh prod up
```

--------------------------------

### GET /api/measurements/check-in-measurements-range/{start}/{end}

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/CLAUDE.md

Retrieves measurements within a specified date range. This endpoint is part of the measurementsApi.

```APIDOC
## GET /api/measurements/check-in-measurements-range/{start}/{end}

### Description
Retrieves measurements within a specified date range.

### Method
GET

### Endpoint
/api/measurements/check-in-measurements-range/{start}/{end}

### Parameters
#### Path Parameters
- **start** (string) - Required - The start date for the range.
- **end** (string) - Required - The end date for the range.
```

--------------------------------

### Start Development Environment with Docker

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Initiates the development stack using the Docker helper script, enabling live reloading for frontend and backend. Services are accessible via specified local ports.

```bash
./docker/docker-helper.sh dev up
```

--------------------------------

### Configure External Database Environment Variables

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/7.external-database.md

Example .env file configuration for connecting to an external PostgreSQL database. Ensure these values match your database host, name, user, password, and port.

```bash
SPARKY_FITNESS_DB_HOST=your-db-host
SPARKY_FITNESS_DB_NAME=sparkyfitness_db
SPARKY_FITNESS_DB_USER=sparky_admin
SPARKY_FITNESS_DB_PASSWORD=your_secure_password
SPARKY_FITNESS_DB_PORT=5432
```

--------------------------------

### USDA Food Search Result Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/external_providers.md

Example JSON response for a USDA food search query, detailing a specific food item and its nutrients.

```json
{
  "foods": [
    {
      "fdcId": 2116605,
      "description": "BLUEBERRY",
      "dataType": "Branded",
      "gtinUpc": "070920005263",
      "publishedDate": "2021-10-28",
      "brandOwner": "Conagra Brands, Inc.",
      "brandName": "KNOTT'S BERRY FARM",
      "ingredients": "SUGAR, BLUEBERRIES, FRUIT PECTIN, CITRIC ACID.",
      "marketCountry": "United States",
      "foodCategory": "Jam, Jelly & Fruit Spreads",
      "modifiedDate": "2018-02-21",
      "dataSource": "LI",
      "packageWeight": "10 oz/284 g",
      "servingSizeUnit": "g",
      "servingSize": 20,
      "householdServingFullText": "1 Tbsp",
      "tradeChannels": [
        "NO_TRADE_CHANNEL"
      ],
      "allHighlightFields": "<b>Ingredients</b>: SUGAR, <em>BLUEBERRIES</em>, FRUIT PECTIN, CITRIC ACID.",
      "score": 1152.7708,
      "microbes": [],
      "foodNutrients": [
        {
          "nutrientId": 1003,
          "nutrientName": "Protein",
          "nutrientNumber": "203",
          "unitName": "G",
          "derivationCode": "LCCS",
          "derivationDescription": "Calculated from value per serving size measure",
          "derivationId": 70,
          "value": 0,
          "foodNutrientSourceId": 9,
          "foodNutrientSourceCode": "12",
          "foodNutrientSourceDescription": "Manufacturer's analytical; partial documentation",
          "rank": 600,
          "indentLevel": 1,
          "foodNutrientId": 25592372
        },
        {
          "nutrientId": 1004,
          "nutrientName": "Total lipid (fat)",
          "nutrientNumber": "204",
          "unitName": "G",
          "derivationCode": "LCCD",
          "derivationDescription": "Calculated from a daily value percentage per serving size measure",
          "derivationId": 75,
          "value": 0,
          "foodNutrientSourceId": 9,
          "foodNutrientSourceCode": "12",
          "foodNutrientSourceDescription": "Manufacturer's analytical; partial documentation",
          "rank": 800,
          "indentLevel": 1,
          "foodNutrientId": 25592373,
          "percentDailyValue": 0
        },
        {
          "nutrientId": 1005,
          "nutrientName": "Carbohydrate, by difference",
          "nutrientNumber": "205",
          "unitName": "G",
          "derivationCode": "LCCS",
          "derivationDescription": "Calculated from value per serving size measure",
          "derivationId": 70,
          "value": 65,
          "foodNutrientSourceId": 9,
          "foodNutrientSourceCode": "12",
          "foodNutrientSourceDescription": "Manufacturer's analytical; partial documentation",
          "rank": 1110,
          "indentLevel": 2,
          "foodNutrientId": 25592374,
          "percentDailyValue": 4
        },
        {
          "nutrientId": 1008,
          "nutrientName": "Energy",
          "nutrientNumber": "208",
          "unitName": "KCAL",
          "derivationCode": "LCCS",
          "derivationDescription": "Calculated from value per serving size measure",
          "derivationId": 70,
          "value": 250,
          "foodNutrientSourceId": 9,
          "foodNutrientSourceCode": "12",
          "foodNutrientSourceDescription": "Manufacturer's analytical; partial documentation",
          "rank": 300,
          "indentLevel": 1,
          "foodNutrientId": 25592375
        },
        {
          "nutrientId": 2000,
          "nutrientName": "Total Sugars",
          "nutrientNumber": "269",
          "unitName": "G",
          "derivationCode": "LCCS",
          "derivationDescription": "Calculated from value per serving size measure",
          "derivationId": 70,
          "value": 60,
          "foodNutrientSourceId": 9,
          "foodNutrientSourceCode": "12",
          "foodNutrientSourceDescription": "Manufacturer's analytical; partial documentation",
          "rank": 1115,
          "indentLevel": 2,
          "foodNutrientId": 25592376
        }
      ]
    }
  ]
}
```

--------------------------------

### SleepSession Health Data Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/sync_api.md

An example of the JSON structure for submitting sleep session data, including detailed sleep stage information and timestamps.

```json
{
  "type": "SleepSession",
  "timestamp": "2024-01-15T23:00:00Z",
  "source": "HealthKit",
  "duration_in_seconds": 28800,
  "bedtime": "2024-01-15T23:00:00Z",
  "wake_time": "2024-01-16T07:00:00Z",
  "deep_sleep_seconds": 7200,
  "light_sleep_seconds": 14400,
  "rem_sleep_seconds": 5400,
  "awake_sleep_seconds": 1800,
  "stage_events": [...] 
}
```

--------------------------------

### Create New Migration File

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/4.database.md

Demonstrates the command to create a new SQL migration file with a timestamped naming convention.

```bash
cd SparkyFitnessServer/db/migrations/
touch 2024_03_15_14_20_add_meal_planning.sql
```

--------------------------------

### Install Expo Dependencies

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/development.md

Always use `npx expo install` to ensure compatibility with Expo and React Native. This command helps resolve dependency conflicts.

```bash
npx expo install
```

--------------------------------

### ExerciseSession Health Data Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/sync_api.md

An example of the JSON structure for submitting exercise session data, including activity type, duration, calories burned, and distance.

```json
{
    "type": "ExerciseSession",
    "source": "HealthKit",
    "date": "2026-01-08",
    "entry_date": "2026-01-08",
    "timestamp": "2026-01-08T22:43:00.000Z",
    "startTime": "2026-01-08T22:43:00.000Z",
    "endTime": "2026-01-08T23:43:00.000Z",
    "duration": 3600,
    "activityType": "Running",
    "title": "Running",
    "caloriesBurned": 500,
    "distance": 20,
    "notes": "Source: HealthKit",
    "raw_data": {
        "startTime": "2026-01-08T22:43:00.000Z",
        "endTime": "2026-01-08T23:43:00.000Z",
        "activityType": 37,
        "duration": {
            "unit": "s",
            "quantity": 3600
        },
        "totalEnergyBurned": 500,
        "totalDistance": 20
    }
}
```

--------------------------------

### Development and Build Commands

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/CLAUDE.md

Common commands for running the app in development, performing clean rebuilds, and running tests.

```bash
npx expo run:ios
```

```bash
npx expo run:ios --device
```

```bash
npx expo prebuild -c
```

```bash
pnpm test:watch
```

```bash
pnpm run test -- __tests__/path/to/test
```

```bash
tsc --noEmit
```

--------------------------------

### Install and Login to EAS CLI

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/MobileApp-Dev-commands.md

Installs the Expo Application Services (EAS) Command Line Interface globally and logs in to your EAS account. This is required for iOS builds.

```bash
npm install -g eas-cli
eas login
```

--------------------------------

### Build and Push Multi-Platform Docker Image (Backend)

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docker/Docker_deploy_manual_command.md

Builds a Docker image for the backend service, targeting multiple platforms (amd64 and arm64), tags it with a specific version, and pushes it to a registry. Ensure you are logged into the Docker registry.

```bash
docker buildx build --platform linux/amd64,linux/arm64 -t codewithcj/sparkyfitness_server:v0.15.0 -f docker/Dockerfile.backend SparkyFitnessServer --push
```

--------------------------------

### Build and Push Multi-Platform Docker Image

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docker/Docker_deploy_manual_command.md

Builds a Docker image for the frontend, targeting multiple platforms (amd64 and arm64), tags it with a specific version, and pushes it to a registry. Ensure you are logged into the Docker registry.

```bash
docker buildx build --platform linux/amd64,linux/arm64 -t codewithcj/sparkyfitness:v0.15.0 -f docker/Dockerfile.frontend . --push
```

--------------------------------

### Example SQL Migration Script

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/4.database.md

Provides a complete SQL script for a new migration, including table creation, RLS policies, indexing, and version tracking. Use transactions for atomic operations.

```sql
-- Migration: Add meal planning functionality
-- Version: 2024_03_15_14_20

BEGIN;

-- Create meal plans table
CREATE TABLE meal_plans (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  name VARCHAR(255) NOT NULL,
  planned_date DATE NOT NULL,
  total_calories DECIMAL(10,2),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Enable RLS
ALTER TABLE meal_plans ENABLE ROW LEVEL SECURITY;

-- Create RLS policy
CREATE POLICY meal_plans_user_policy ON meal_plans
  FOR ALL USING (user_id = auth.uid());

-- Create indexes
CREATE INDEX idx_meal_plans_user_date ON meal_plans(user_id, planned_date);

-- Update migration version
INSERT INTO migrations (version, applied_at) 
VALUES ('2024_03_15_14_20', NOW());

COMMIT;
```

--------------------------------

### Internal API Food Data Response Example

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessServer/docs/externalapis.md

This is an example of the JSON response structure received from the internal API when querying food data by barcode. It includes details about the food item and its default serving variant.

```json
{
  "source": "openfoodfacts",
  "food": {
    "name": "Cheddar Cheese",
    "brand": "Grafton Village",
    "barcode": "0094395000172",
    "provider_external_id": "0094395000172",
    "provider_type": "openfoodfacts",
    "is_custom": false,
    "default_variant": {
      "serving_size": 28,
      "serving_unit": "g",
      "calories": 110,
      "protein": 6,
      "carbs": 1,
      "fat": 8,
      "saturated_fat": 6,
      "sodium": 190,
      "dietary_fiber": 0,
      "sugars": 0,
      "polyunsaturated_fat": 0,
      "monounsaturated_fat": 0,
      "trans_fat": 0,
      "cholesterol": 25,
      "potassium": 0,
      "vitamin_a": 120,
      "vitamin_c": 0,
      "calcium": 200,
      "iron": 0,
      "is_default": true
    }
  }
}
```

--------------------------------

### log_fasting

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/10.mcp/3.checkin.md

Logs a fasting window, including start and end times, and its status.

```APIDOC
## log_fasting

### Description
Logs a fasting window.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **start_time** (string) - Required - Start timestamp of the fasting window (ISO 8601).
- **end_time** (string) - Optional - End timestamp of the fasting window (ISO 8601).
- **fasting_status** (enum: "ACTIVE", "COMPLETED", "CANCELLED") - Optional - Current status of the fast.
- **fasting_type** (string) - Optional - Type of fasting (e.g., "Intermittent").

### Request Example
```json
{
  "start_time": "2023-10-27T19:00:00Z",
  "end_time": "2023-10-28T07:00:00Z",
  "fasting_status": "COMPLETED",
  "fasting_type": "Intermittent"
}
```

### Response
#### Success Response (200)
(No specific response schema provided in source)

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/identity/profiles

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/CLAUDE.md

Retrieves the user profile information. This endpoint is managed by profileApi.

```APIDOC
## GET /api/identity/profiles

### Description
Retrieves the user profile.

### Method
GET

### Endpoint
/api/identity/profiles
```

--------------------------------

### GET /api/user-preferences

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/CLAUDE.md

Fetches the current user preferences. This endpoint is part of the preferencesApi.

```APIDOC
## GET /api/user-preferences

### Description
Retrieves user preferences.

### Method
GET

### Endpoint
/api/user-preferences
```

--------------------------------

### Get Workout Presets

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/10.mcp/2.exercise.md

Retrieves a list of available workout presets or routines.

```APIDOC
## get_workout_presets

### Description
Retrieves a list of available workout presets/routines.

### Parameters
None.
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/codewithcj/sparkyfitness/blob/main/AGENTS.md

Commands for running the frontend development server, validation, and tests.

```bash
pnpm dev
pnpm run validate
pnpm test
```

--------------------------------

### Docs Development Commands

Source: https://github.com/codewithcj/sparkyfitness/blob/main/AGENTS.md

Commands for running the documentation development server and building the documentation site.

```bash
pnpm dev
pnpm run build
```

--------------------------------

### GET /api/water-containers

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/CLAUDE.md

Retrieves a list of water container presets. This endpoint is managed by measurementsApi.

```APIDOC
## GET /api/water-containers

### Description
Retrieves water container presets.

### Method
GET

### Endpoint
/api/water-containers
```

--------------------------------

### Nginx Proxy Configuration for SparkyFitness

Source: https://github.com/codewithcj/sparkyfitness/wiki/Sample-Setup

Example Nginx configuration for proxying requests to the SparkyFitness frontend.

```nginx
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;

```

--------------------------------

### User Not Found Response

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/sync_api.md

Example of a not found response (404 Not Found) when the requested user cannot be identified.

```json
{
  "error": "User not found."
}
```

--------------------------------

### GET /api/measurements/check-in/:date

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/5.api-reference.md

Retrieves daily check-in measurements for a specific date for the authenticated user.

```APIDOC
## GET /api/measurements/check-in/:date

### Description
Retrieves daily check-in measurements for a specific date for the authenticated user.

### Method
GET

### Endpoint
/api/measurements/check-in/:date

### Parameters
#### Path Parameters
- **date** (string) - Required - The date of the check-in in `YYYY-MM-DD` format.

### Response
#### Success Response (200 OK)
- **id** (string) - Unique identifier for the check-in entry.
- **user_id** (string) - Identifier for the user.
- **entry_date** (string) - The date of the check-in.
- **weight** (number) - The weight measurement.
- **body_fat** (number) - The body fat percentage.

*Note: Returns an empty object `{}` if no entry is found for the specified date.*

#### Response Example (200 OK)
```json
{
  "id": "uuid",
  "user_id": "uuid",
  "entry_date": "2025-08-19",
  "weight": 70.5,
  "body_fat": 15.2
}
```

#### Error Response (400 Bad Request)
- **error** (string) - Error message indicating missing date.

#### Error Response Example (400 Bad Request)
```json
{
  "error": "Date is required."
}
```
```

--------------------------------

### Run Production Docker Compose

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Starts the production services defined in the docker-compose.prod.yml file in detached mode.

```bash
docker-compose -f docker/docker-compose.prod.yml up -d
```

--------------------------------

### Run Backend Quality Checks

Source: https://github.com/codewithcj/sparkyfitness/blob/main/CONTRIBUTING.md

Execute backend type checking, linting, and testing. This command should be run in the SparkyFitnessServer directory.

```bash
pnpm run typecheck && pnpm run lint && pnpm run test
```

--------------------------------

### GET /api/measurements/water-intake/{date}

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/CLAUDE.md

Fetches water intake data for a specific date. This endpoint belongs to the measurementsApi.

```APIDOC
## GET /api/measurements/water-intake/{date}

### Description
Retrieves water intake for a specific date.

### Method
GET

### Endpoint
/api/measurements/water-intake/{date}

### Parameters
#### Path Parameters
- **date** (string) - Required - The date for which to retrieve water intake.
```

--------------------------------

### Create New SparkyFitness Database

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/3.administration/3.manual_backup_restore.md

Creates a new, empty SparkyFitness database using a temporary PostgreSQL client container. This is typically done after dropping the old one.

```bash
# Example: Replace with your actual DB details
DB_HOST="sparkyfitness-db" # Or localhost if connecting directly to host DB
DB_PORT="5432"
DB_USER="sparkyfitness"
DB_PASSWORD="your_db_password"
DB_NAME="sparkyfitness"

# Create database
docker run --rm -e PGPASSWORD=${DB_PASSWORD} postgres:latest createdb -h ${DB_HOST} -p ${DB_PORT} -U ${DB_USER} ${DB_NAME}
```

--------------------------------

### Run iOS App in Release Configuration

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/MobileApp-Dev-commands.md

Installs a standalone, release-configured version of the iOS app on a connected device. This version works offline and has better performance but is valid for 7 days (free account) or 1 year (paid account).

```bash
npx expo run:ios --configuration Release --device
```

--------------------------------

### Docker Helper Script Commands

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/8.developer/1.getting-started.md

Manage your SparkyFitness development and production environments using the provided Docker helper script. It offers commands for starting, stopping, viewing logs, and cleaning up services.

```bash
./docker/docker-helper.sh help

./docker/docker-helper.sh dev up

./docker/docker-helper.sh prod up

./docker/docker-helper.sh logs

./docker/docker-helper.sh down

./docker/docker-helper.sh clean
```

--------------------------------

### Update Docker Compose for PUID/GUID

Source: https://github.com/codewithcj/sparkyfitness/blob/main/docs/content/1.install/8.postgres-upgrade.md

Ensure the PUID and GUID are set to 1000 for the relevant services in your `docker-compose.yml` file.

```yaml
PUID: 1000
GUID: 1000
```

--------------------------------

### User Authentication Success Response

Source: https://github.com/codewithcj/sparkyfitness/blob/main/SparkyFitnessMobile/docs/sync_api.md

Example of a successful response (200 OK) from the /auth/user endpoint, returning user details.

```json
{
  "userId": 123,
  "email": "user@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00.000Z"
}
```