f1tness_parser/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

F1tness Parser is a FastAPI-based web application that parses fitness training data from two note formats:

• Obsidian Notes: Markdown tables with # DD.MM.YYYY (trainer-session) headers
• Apple Notes: Bold markdown tables with **DD.MM.YYYY (trainer-session)** headers

The application uses a layered architecture with parsers, models, services, and API endpoints.

Development Commands

Local Development

# Start development server
python run.py

# Start with Docker Compose (includes PostgreSQL)
docker compose up --build

# Run migrations manually
python -c "from migrations.runner import MigrationRunner; from app.config import settings; import asyncio; asyncio.run(MigrationRunner(settings.get_postgres_database_url()).run_migrations())"

Testing

# Run tests
pytest

# Run specific test file
pytest tests/test_core/test_obsidian_parser.py

# Run tests with coverage
pytest --cov=app

Type Checking

# Run type checking
mypy app/

Architecture

Core Components

Parser Architecture: The system uses a base parser class (app/core/parsers/base.py) with format-specific implementations:

• ObsidianNotesParser - handles Obsidian markdown format
• AppleNotesParser - handles Apple notes format
• Each parser includes exercise name mapping for normalization

Data Models: Located in app/core/dto/training.py:

• Training - represents a workout session
• Exercise - individual exercise with multiple approaches
• Approach - single set with weight and reps

API Structure:

• /api/v1/ - REST API endpoints
• /app/ - Web interface endpoints
• Static files served from app/static/
• Templates in app/templates/

Database

The application supports both SQLite (default) and PostgreSQL. Database migrations are handled by a custom migration runner in migrations/runner.py that reads SQL files from migrations/sql/.

Configuration is managed through app/config.py using Pydantic settings with .env file support.

Key Files

• app/main.py - FastAPI application setup with lifespan management
• app/config.py - Application configuration and database settings
• run.py - Development server entry point
• migrations/runner.py - Custom database migration system
• compose.yaml - Docker Compose setup with PostgreSQL

Environment Setup

Copy .env.example to .env and configure:

• PostgreSQL connection settings
• Debug mode
• PYTHONPATH (for Docker)

The application will run database migrations automatically on startup through the FastAPI lifespan event.