### Frontend Setup (Local Development)

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Steps to set up the frontend application locally, including dependency installation and starting the development server.

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

# Install dependencies
npm install

# Start development server
npm run dev

```

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

### Backend Setup (Local Development)

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Steps to set up the backend server locally, including dependency installation, environment configuration, and starting the 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

```

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

### Production Environment Setup

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Starting the production stack using Docker, with details on the available service and features.

```bash
# Start production stack
./docker/docker-helper.sh prod up

# Service available:
# - Application: http://localhost:3004 (nginx proxy)

```

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

### Development Environment Setup

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Starting the development stack using Docker, with details on available services and features.

```bash
# Start development stack
./docker/docker-helper.sh dev up

# Services available:
# - Frontend: http://localhost:8080 (live reload)
# - Backend: http://localhost:3010 (direct access)
# - Database: localhost:5432 (direct access)

```

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

### Quick Start with Docker

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Cloning the repository, setting up the environment, and starting the development server using Docker.

```bash
# Clone the repository
git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness

# Copy environment template
cp docker/.env.example .env

# Start development environment (with live reloading)
./docker/docker-helper.sh dev up

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

```

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

### Quick Start Development Environment Setup

Source: https://codewithcj.github.io/SparkyFitness/developer/contributing

Commands to fork, clone, set up environment variables, and start the development environment.

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

cp docker/.env.example .env

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

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

### Database Setup (Local Development)

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

SQL commands to create the database and user for local development.

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

```

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

### Copy Environment Template

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Command to copy the example environment file for configuration.

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

```

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

### Start SparkyFitness Application

Source: https://codewithcj.github.io/SparkyFitness/install/docker-compose

Pulls the latest Docker images and starts the application services in detached mode.

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

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

### Download Docker Compose and Environment Files

Source: https://codewithcj.github.io/SparkyFitness/install/docker-compose

Creates a directory, navigates into it, and downloads the production Docker Compose file and an example environment file.

```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
```

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

### Environment Configuration Example

Source: https://codewithcj.github.io/SparkyFitness/install/external-database

Example of how to configure the .env file to point to an external PostgreSQL database.

```dotenv
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

```

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

### Manual Docker Compose Commands

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Commands for managing the Docker Compose environment, including production and development setups, stopping services, and viewing logs.

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

# Development with live reloading
docker-compose -f docker/docker-compose.dev.yml up

# Stop services
docker-compose down

# View logs
docker-compose logs -f [service_name]
```

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

### PostgreSQL Extensions Installation

Source: https://codewithcj.github.io/SparkyFitness/install/external-database

SQL commands to connect to the database and create required PostgreSQL extensions, along with granting execute permissions.

```sql
\c sparkyfitness_db

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

-- Performance monitoring
CREATE EXTENSION IF NOT EXISTS "pg_stat_statements";

-- Grant with grant to functions that extensions add as they are still owned by postgres
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO "sparky_admin" WITH GRANT OPTION;

```

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

### Example Translation JSON

Source: https://codewithcj.github.io/SparkyFitness/developer/translations

An example of a translation.json file structure, showing nested objects for organizing translations.

```json
{
  "nav": {
    "diary": "Diary",
    "checkin": "Check-In"
  },
  "settings": {
    "profileInformation": {
      "title": "Profile Information"
    }
  }
}
```

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

### Docker Helper Script Commands

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Common commands for managing the SparkyFitness development and production environments using the Docker helper script.

```bash
# Show all available commands and help
./docker/docker-helper.sh help

# Start development environment
./docker/docker-helper.sh dev up

# Start production environment  
./docker/docker-helper.sh prod up

# View logs
./docker/docker-helper.sh logs

# Stop services
./docker/docker-helper.sh down

# Clean up everything
./docker/docker-helper.sh clean

```

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

### Start SparkyFitness Services

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Command to start the SparkyFitness services using Docker Compose.

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

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

### Repository Pattern Example

Source: https://codewithcj.github.io/SparkyFitness/developer/contributing

Example demonstrating the repository pattern for database operations, including transaction management.

```javascript
// All database operations use repository pattern
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();
    }
  }
};

```

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

### Helm Installation Commands

Source: https://codewithcj.github.io/SparkyFitness/install/kubernetes

Commands to install SparkyFitness using Helm, either directly from OCI registry or from source, with an option for custom values.

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

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

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

# 3. Access the application in browser via Ingress or HTTPRoute you've specified in values

```

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

### Stop and Remove SparkyFitness Services and Volumes

Source: https://codewithcj.github.io/SparkyFitness/install/docker-compose

Stops and removes all services, networks, and volumes, including database data.

```bash
docker compose down -v
```

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

### Weight Data Example

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of submitting weight data.

```json
[
  {
    "value": 70.5,
    "type": "weight",
    "date": "2025-08-19"
  }
]
```

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

### Claude Desktop Example Configuration

Source: https://codewithcj.github.io/SparkyFitness/features/mcp-server

Example configuration for connecting Claude Desktop to the SparkyFitness MCP server, including server URL and authorization header.

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

```

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

### Bring Up All Containers

Source: https://codewithcj.github.io/SparkyFitness/install/postgres-upgrade

Starts the 'sparkyfitness-db' container in detached mode.

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

```

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

### Steps Data Example

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of submitting step count data.

```json
[
  {
    "value": 10000,
    "type": "step",
    "date": "2025-08-19"
  }
]
```

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

### Port Conflict Troubleshooting

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Commands to check which processes are using specific ports, useful for resolving port conflicts.

```bash
# Check port usage
lsof -i :8080  # Frontend
lsof -i :3010  # Backend  
lsof -i :5432  # Database
```

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

### Database and User Configuration

Source: https://codewithcj.github.io/SparkyFitness/install/external-database

SQL commands to create the database, the database owner user, and grant necessary ownership and privileges.

```sql
-- 1. Create the Database
CREATE DATABASE sparkyfitness_db;

-- 2. Create the DB Owner user (referenced in .env as SPARKY_FITNESS_DB_USER)
CREATE USER sparky_admin WITH PASSWORD 'your_secure_password';

-- 3. Grant database ownership
ALTER DATABASE sparkyfitness_db OWNER TO sparky_admin;

-- 4. Grant Role Creation privilege
-- This allows the DB Owner to automatically create the App User during setup
ALTER USER sparky_admin CREATEROLE;

-- 5. Special Note for PostgreSQL 15+
-- Since PG 15, the default 'public' schema permissions have changed.
-- You may need to explicitly grant create permissions to the owner:
GRANT ALL ON SCHEMA public TO sparky_admin;

```

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

### Execute commands in containers

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Examples of executing shell commands within different SparkyFitness Docker containers.

```bash
# Frontend container
docker exec -it sparkyfitness-frontend-1 sh

# Backend container
docker exec -it sparkyfitness-server-1 sh

# Database container
docker exec -it sparkyfitness-db-1 psql -U sparky -d sparkyfitness_db
```

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

### Adding User to Docker Group

Source: https://codewithcj.github.io/SparkyFitness/developer/getting-started

Command to add the current user to the Docker group to resolve potential permission issues.

```bash
sudo usermod -aG docker $USER
# Log out and back in
```

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

### Water Intake Data Example

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of submitting water intake data.

```json
[
  {
    "value": 500,
    "type": "water",
    "date": "2025-08-19"
  }
]
```

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

### Active Calories Data Example

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of submitting active calories data.

```json
[
  {
    "value": 500,
    "type": "Active Calories",
    "date": "2025-08-19"
  }
]
```

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

### Transaction Management in Migrations

Source: https://codewithcj.github.io/SparkyFitness/developer/database

Example of using BEGIN and COMMIT for atomic database migrations.

```sql
BEGIN;
-- All migration statements here
-- If any statement fails, entire migration rolls back
COMMIT;
```

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

### Example Migration SQL

Source: https://codewithcj.github.io/SparkyFitness/developer/database

SQL content for a new migration file, including table creation, RLS policy, and version tracking.

```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;
```

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

### Migration File Naming Convention

Source: https://codewithcj.github.io/SparkyFitness/developer/database

Example of the naming pattern for migration files.

```bash
YYYY_MM_DD_HH_MM_description.sql
```

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

### Check rate limit configuration

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Example of rate limiting configuration in nginx.conf.template.

```nginx
limit_req_zone $binary_remote_addr zone=login_signup_zone:10m rate=5r/s;
```

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

### Backend Zod Schema Validation Example

Source: https://codewithcj.github.io/SparkyFitness/developer/contributing

Example demonstrating how to define Zod schemas for request validation in a Node.js/Express backend.

```typescript
import { z } from 'zod';

// Define schemas
const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
  password: z.string().min(8)
});

// Use in route
app.post('/api/users', async (req, res) => {
  const validated = createUserSchema.parse(req.body);
  // ... rest of handler
});
```

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

### Progress Summary Response Template

Source: https://codewithcj.github.io/SparkyFitness/developer/advanced/ai-command-patterns

A template for displaying a user's daily progress summary, including consumed amounts versus goals for key metrics.

```string
"Here's your progress for today:

**Calories:** [consumed]/[goal] ([percentage]%)
**Protein:** [consumed]g/[goal]g ([percentage]%)
**Carbs:** [consumed]g/[goal]g ([percentage]%)
**Fat:** [consumed]g/[goal]g ([percentage]%)

[motivational message based on progress]"
```

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

### Integration into React Application

Source: https://codewithcj.github.io/SparkyFitness/developer/translations

The main entry point (src/main.tsx) showing how to import the i18n configuration and wrap the application with Suspense for translation loading.

```typescript
import { createRoot } from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import { BrowserRouter } from 'react-router-dom';
import { AuthProvider } from './hooks/useAuth.tsx';
import './i18n'; // Import the i18n configuration
import { Suspense } from 'react';

createRoot(document.getElementById("root")!).render(
  <Suspense fallback="loading">
    <BrowserRouter>
      <AuthProvider>
        <App />
      </AuthProvider>
    </BrowserRouter>
  </Suspense>
);
```

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

### Troubleshooting Permission Denied

Source: https://codewithcj.github.io/SparkyFitness/install/postgres-upgrade

Command to resolve 'Permission Denied' errors if the PostgreSQL container fails to start after the upgrade, by re-applying ownership and permissions to the PostgreSQL data directory.

```bash
sudo chown -R 1000:1000 ./postgresql

```

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

### TanStack Query Integration Example

Source: https://codewithcj.github.io/SparkyFitness/developer/architecture

Compares traditional useEffect-based data fetching with the TanStack Query approach using custom hooks and API functions.

```typescript
// Component.tsx
useEffect(() => {
  const fetchData = async () => {
    const response = await fetch('/api/users');
    const data = await response.json();
    // ... set state
  };
  fetchData();
}, []);
```

```typescript
// src/api/userApi.ts
import { api } from '@/services/api';

const userKeys = {
  all: ['users'] as const,
  details: (id: string) => [...userKeys.all, id] as const,
};

const getUsers = () => {
  return api.get('/users');
};

// src/hooks/useUsers.ts
import { useQuery } from '@tanstack/react-query';
import { userKeys, getUsers } from '@/api/userApi';

export const useUsers = () => {
  return useQuery({
    queryKey: userKeys.all,
    queryFn: getUsers,
  });
};

// Component.tsx
import { useUsers } from '@/hooks/useUsers';

const UserList = () => {
  const { data: users, isLoading, isError } = useUsers();

  if (isLoading) return <div>Loading users...</div>;
  if (isError) return <div>Error fetching users</div>;

  return (
    // ... render users
  );
};
```

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

### i18next Configuration

Source: https://codewithcj.github.io/SparkyFitness/developer/translations

The i18next instance configuration file (src/i18n.ts), setting up supported languages, fallback, language detection, and translation loading.

```typescript
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import HttpApi from 'i18next-http-backend';

i18n
  .use(HttpApi)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    supportedLngs: ['en', 'ta'], // List of supported languages
    fallbackLng: 'en', // Fallback language if a translation is missing
    detection: {
      order: ['localStorage', 'querystring', 'cookie', 'sessionStorage', 'navigator', 'htmlTag'],
      caches: ['localStorage', 'cookie'],
    },
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json', // Path to load translation files
    },
    react: {
      useSuspense: false, // Set to true if you want to use React.Suspense for loading translations
    },
  });

export default i18n;
```

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

### Create Database

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Command to create a new SparkyFitness database using Docker.

```bash
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"

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

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

### Stop SparkyFitness Services

Source: https://codewithcj.github.io/SparkyFitness/install/docker-compose

Stops the running Docker Compose services without removing their data volumes.

```bash
docker compose stop
```

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

### Prepare the Backup File

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Copy your chosen sparkyfitness_full_backup_YYYYMMDD_HHMMSS.tar.gz file into the backup volume's data directory on your host.

```bash
cp /path/to/your/backup/sparkyfitness_full_backup_YYYYMMDD_HHMMSS.tar.gz /var/lib/docker/volumes/sparkyfitness_server_backup_data/_data/

```

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

### Extract the Backup Archive (Option A: Using host tar)

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Extract the combined archive to get the database dump and uploads archive using the host's tar utility.

```bash
cd /var/lib/docker/volumes/sparkyfitness_server_backup_data/_data/
tar -xzf sparkyfitness_full_backup_YYYYMMDD_HHMMSS.tar.gz

```

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

### Connect to PostgreSQL

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Command to connect to the PostgreSQL database container.

```bash
docker exec -it sparkyfitness-db-1 psql -U sparky -d sparkyfitness_db

```

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

### Extract the Backup Archive (Option B: Using a temporary Docker container)

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Extract the combined archive to get the database dump and uploads archive using a temporary Docker container.

```bash
docker run --rm -v sparkyfitness_server_backup_data:/backup_volume ubuntu:latest tar -xzf /backup_volume/sparkyfitness_full_backup_YYYYMMDD_HHMMSS.tar.gz -C /backup_volume

```

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

### Custom Measurement Data Example

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of submitting a custom measurement like 'Blood Pressure Systolic'.

```json
[
  {
    "value": 120,
    "type": "Blood Pressure Systolic",
    "date": "2025-08-19",
    "timestamp": "2025-08-19T08:30:00Z"
  }
]
```

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

### Restore Database from Dump

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Command to restore the SparkyFitness database from a compressed SQL dump file using Docker and psql.

```bash
# Example: Replace with your actual DB details and backup file name
DB_HOST="sparkyfitness-db"
DB_PORT="5432"
DB_USER="sparkyfitness"
DB_PASSWORD="your_db_password"
DB_NAME="sparkyfitness"
DB_DUMP_FILE="/var/lib/docker/volumes/sparkyfitness_server_backup_data/_data/sparkyfitness_db_backup_YYYYMMDD_HHMMSS.sql.gz"

gunzip -c ${DB_DUMP_FILE} | docker run --rm -i -e PGPASSWORD=${DB_PASSWORD} postgres:latest psql -h ${DB_HOST} -p ${DB_PORT} -U ${DB_USER} -d ${DB_NAME}
```

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

### Get Check-in Measurements GET Response (400 Bad Request)

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Error response when the date parameter is missing.

```json
{
  "error": "Date is required."
}
```

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

### List running containers

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Command to list all currently running Docker containers for SparkyFitness.

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

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

### Get Check-in Measurements GET Response (200 OK)

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Successful response for retrieving check-in measurements for a specific date.

```json
{
  "id": "uuid",
  "user_id": "uuid",
  "entry_date": "2025-08-19",
  "weight": 70.5,
  "body_fat": 15.2
}
```

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

### Revoking CREATEROLE Privilege

Source: https://codewithcj.github.io/SparkyFitness/install/external-database

SQL command to revoke the CREATEROLE privilege from the database user after initial setup for security hardening.

```sql
ALTER USER sparky_admin NOCREATEROLE;

```

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

### Cloning Your Forked Repository

Source: https://codewithcj.github.io/SparkyFitness/developer/contributing

Instructions to clone the forked SparkyFitness repository locally.

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

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

### Update docker-compose.yml for PUID and GUID

Source: https://codewithcj.github.io/SparkyFitness/install/postgres-upgrade

Updates the 'sparkyfitness-db', 'server', 'frontend', and 'garmin' (if used) services in the 'docker-compose.yml' file to include PUID and GUID values of 1000.

```yaml
## Update postgres, server, frontend and garmin(if using garmin) section in your compose file to include 1000 for PUID and GUID PUID: 1000 GUID: 1000

```

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

### Row Level Security (RLS) Policy Example

Source: https://codewithcj.github.io/SparkyFitness/developer/database

An example of enabling Row Level Security for the 'food_diary' table and creating a policy to ensure users can only access their own data.

```sql
ALTER TABLE food_diary ENABLE ROW LEVEL SECURITY;
CREATE POLICY food_diary_user_policy ON food_diary
  FOR ALL USING (user_id = auth.uid());

```

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

### Database migration issues

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Commands to check and manage database migrations.

```bash
# Check migration status
docker exec -it sparkyfitness-server-1 npm run migrate:status

# Force migration reset (DANGEROUS)
docker exec -it sparkyfitness-server-1 npm run migrate:reset

```

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

### View all service logs

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Command to view all logs from running SparkyFitness services.

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

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

### Example Error Response

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

A general structure for error responses from the API.

```json
{
  "error": "Error message describing the issue."
}
```

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

### Data Migration

Source: https://codewithcj.github.io/SparkyFitness/developer/database

Example of migrating data to a new structure using a transaction.

```sql
-- Example: Migrating data to new structure
BEGIN;

-- Create new table
CREATE TABLE new_nutrition_data (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  food_item_id UUID NOT NULL REFERENCES food_items(id),
  calories_per_100g DECIMAL(10,2),
  -- other columns
);

-- Migrate existing data
INSERT INTO new_nutrition_data (food_item_id, calories_per_100g)
SELECT food_item_id, calories * 100 / serving_size
FROM old_nutrition_data
WHERE serving_size > 0;

-- Drop old table (after verifying migration)
-- DROP TABLE old_nutrition_data;

COMMIT;

```

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

### View database logs

Source: https://codewithcj.github.io/SparkyFitness/developer/troubleshooting

Command to view the logs of the SparkyFitness database container.

```bash
./docker/docker-helper.sh dev logs sparkyfitness-db
```

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

### Run Full Test Suite Command

Source: https://codewithcj.github.io/SparkyFitness/developer/contributing

Commands to run the development environment and test the application thoroughly.

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

```

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

### Successful Response (200 OK)

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of a successful response after processing health data.

```json
{
  "message": "All health data successfully processed.",
  "processed": [
    {
      "type": "weight",
      "status": "success",
      "data": { "id": "uuid", "user_id": "uuid", "entry_date": "2025-08-19", "weight": 70.5 }
    }
  ]
}
```

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

### Clear Existing Uploads Directory

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Clear the uploads directory using a temporary Docker container.

```bash
# Example: Assuming uploads volume is sparkyfitness_server_uploads_data
docker run --rm -v sparkyfitness_server_uploads_data:/uploads_volume ubuntu:latest rm -rf /uploads_volume/*

```

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

### Drop Database

Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore

Command to drop the existing SparkyFitness database using Docker.

```bash
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"

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

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

### Frontend Test Mock Pattern

Source: https://codewithcj.github.io/SparkyFitness/developer/testing

Example of mocking strategies used in frontend component tests.

```typescript
// 1. Mock i18n — return fallback string or key
jest.mock('react-i18next', () => ({
  useTranslation: () => ({
    t: (key: string, defaultValueOrOpts?: string | Record<string, unknown>) => {
      if (typeof defaultValueOrOpts === 'string') return defaultValueOrOpts;
      if (defaultValueOrOpts && typeof defaultValueOrOpts === 'object' && 'defaultValue' in defaultValueOrOpts) {
        return defaultValueOrOpts.defaultValue as string;
      }
      return key;
    },
  }),
}));

// 2. Mock contexts
jest.mock('@/contexts/ActiveUserContext', () => ({
  useActiveUser: () => ({ activeUserId: 'test-user-id' }),
}));
jest.mock('@/contexts/PreferencesContext', () => ({
  usePreferences: () => ({ loggingLevel: 'debug', foodDisplayLimit: 100 }),
}));

// 3. Mock toast
jest.mock('@/hooks/use-toast', () => ({ toast: jest.fn() }));

// 4. Mock logging
jest.mock('@/utils/logging', () => ({
  debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
}));

// 5. Mock services with trackable fns
const mockGetMeals = jest.fn();
jest.mock('@/services/mealService', () => ({
  getMeals: (...args: unknown[]) => mockGetMeals(...args),
}));


```

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

### Forbidden Response (403 Forbidden)

Source: https://codewithcj.github.io/SparkyFitness/developer/api-reference

Example of a 403 Forbidden response when the API Key lacks the required permission.

```json
{
  "error": "Forbidden: API Key does not have health_data_write permission"
}
```