Contributing to SparkyFitness: Code, Docs, and PRs

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodeWithCJ/SparkyFitness/llms.txt

Use this file to discover all available pages before exploring further.

​

Ways to Contribute

​

Development Setup

git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness
cp docker/.env.example .env
# Generate encryption key
sed "s/SPARKY_FITNESS_API_ENCRYPTION_KEY=changeme_replace_with_a_64_character_hex_string/SPARKY_FITNESS_API_ENCRYPTION_KEY=$(openssl rand -hex 32)/" \
  .env > .env.tmp && mv .env.tmp .env
./docker/docker-helper.sh dev up

​

Development Workflow

git clone https://github.com/YOUR_USERNAME/SparkyFitness.git
cd SparkyFitness
git remote add upstream https://github.com/CodeWithCJ/SparkyFitness.git

git checkout main
git pull upstream main
git checkout -b feature/your-feature-name
# or: fix/login-validation, docs/update-setup-guide

# Frontend
cd SparkyFitnessFrontend && pnpm run validate

# Backend
cd SparkyFitnessServer && pnpm run typecheck && pnpm run lint && pnpm run test

# Mobile (if applicable)
cd SparkyFitnessMobile && pnpm run lint && pnpm run test:run -- --watchman=false --runInBand

git add .
git commit -m "feat: add exercise tracking functionality"

​

Coding Standards

​

General principles

• Clean, readable code — prefer self-documenting names; add comments for non-obvious logic.
• DRY — avoid duplication; extract shared logic into utilities or helpers.
• Separation of concerns — keep routing, business logic, and data access in their respective layers.
• No any — use TypeScript strictly; define interfaces and types explicitly.

​

Frontend (React + TypeScript)

// Use functional components with hooks
const ExampleComponent: React.FC<ExampleProps> = ({ prop1, prop2 }) => {
  // 1. Hooks at the top
  const [state, setState] = useState<StateType>('');
  const { data, isLoading } = useExampleData();

  // 2. Event handlers
  const handleSubmit = useCallback((e: React.FormEvent) => {
    e.preventDefault();
    // handle submission
  }, []);

  // 3. Early returns for loading/error states
  if (isLoading) return <LoadingSpinner />;

  return (
    <div className="component-container">
      {/* JSX */}
    </div>
  );
};

// src/api/exampleApi.ts
export const exampleKeys = {
  all: ['examples'] as const,
  detail: (id: string) => [...exampleKeys.all, id] as const,
};

export const getExamples = () => api.get('/examples');

// src/hooks/useExamples.ts
export const useExamples = () =>
  useQuery({ queryKey: exampleKeys.all, queryFn: getExamples });

​

Backend (Node.js + Express)

import { z } from 'zod';

const createFoodEntrySchema = z.object({
  foodItemId: z.string().uuid(),
  quantity:   z.number().positive(),
  unit:       z.string().min(1),
  mealType:   z.enum(['breakfast', 'lunch', 'dinner', 'snack']),
  consumedAt: z.string().datetime(),
});

router.post('/food-entries', async (req, res) => {
  const validated = createFoodEntrySchema.parse(req.body);
  // ...
});

const foodEntryRepository = {
  async create(data: CreateFoodEntryInput) {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      // parameterised queries only — never string interpolation
      const result = await client.query(
        'INSERT INTO food_entries(user_id, food_item_id, quantity) VALUES($1,$2,$3) RETURNING *',
        [data.userId, data.foodItemId, data.quantity]
      );
      await client.query('COMMIT');
      return result.rows[0];
    } catch (error) {
      await client.query('ROLLBACK');
      throw error;
    } finally {
      client.release();
    }
  },
};

​

Database standards

• All schema changes must go through a migration file in SparkyFitnessServer/db/migrations/.
• Every new user-specific table must have RLS policies added to SparkyFitnessServer/db/rls_policies.sql.
• Classify new tables into Tier 1, Tier 2, or Tier 3 in the database security documentation.
• Wrap all migrations in a BEGIN / COMMIT transaction.
• Use DECIMAL(10,2) for nutritional values; UUID for all primary keys.

​

Project Structure

​

Adding a New Integration

mkdir SparkyFitnessServer/integrations/myprovider

​

Translations

1. Add the key and English string to public/locales/en/translation.json.
2. Use the useTranslation hook in your component:
   import { useTranslation } from 'react-i18next';
   
   const MyComponent = () => {
     const { t } = useTranslation();
     return <h1>{t('myFeature.title', { defaultValue: 'My Feature' })}</h1>;
   };
   
3. Add a hardcoded fallback value directly in the code so the UI remains usable even if the translation file hasn’t loaded.

1. Create public/locales/es/translation.json.
2. Add 'es' to supportedLngs in SparkyFitnessFrontend/src/i18n.ts.
3. Add a <SelectItem> for Spanish in the language switcher in Settings.tsx.

​

Pull Request Checklist

• Branch is up to date with the latest main
• Changes have been tested thoroughly
• Code follows project conventions and standards
• No new console errors or warnings
• Mobile responsiveness verified for any UI changes
• Database migrations included if schema changed
• New tables added to RLS policies and classified in security docs
• English translation keys updated if new UI strings added
• Before/after screenshots attached for UI changes
• Frontend: pnpm run validate passes in SparkyFitnessFrontend/
• Backend: pnpm run typecheck && pnpm run lint && pnpm run test passes in SparkyFitnessServer/
• Backend new files: Written in TypeScript with Zod schemas and tests

​

Automated PR validation

1. Detects which packages changed (frontend, backend, mobile, UI).
2. Validates that the appropriate checkboxes in the PR template are checked.
3. Posts a comment with validation results and guidance.
4. Fails the PR check if required checkboxes are missing or unchecked.

​

Getting Help