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

The project is developed and run only in Docker: there is no local Python setup. Everything below runs inside the fastapi-app container (.env must have POSTGRES_DATABASE_HOST=postgres, see .env.example).

Docker Development

# Start the app + PostgreSQL (applies migrations on start, hot reload for app/)
docker compose up --build

# Apply migrations manually (Alembic; the app itself does NOT migrate on startup)
docker compose exec fastapi-app alembic upgrade head

# Create a migration after changing models in app/core/database/models/
# (-u keeps the generated file owned by you instead of root)
docker compose exec -u "$(id -u):$(id -g)" fastapi-app alembic revision --autogenerate -m "describe change"

# Import all Obsidian + Apple notes into the database
docker compose exec fastapi-app python -m app.cli import [--replace]

# Stop (keeps the data) / stop and drop the database volume
docker compose down
docker compose down -v

Rebuild (--build) is needed only after changing requirements*.txt, Dockerfile or pyproject.toml.

Testing

Tests that need a database use a separate <POSTGRES_DATABASE_DB>_test database (TEST_DATABASE_URL, created automatically). Without it they are skipped.

# Run all tests
docker compose exec fastapi-app pytest

# Run specific test file
docker compose exec fastapi-app pytest tests/test_core/test_obsidian_parser.py

# Without a running stack (starts postgres, runs once, removes the container)
docker compose run --rm fastapi-app pytest

Type Checking

docker compose exec fastapi-app 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 uses PostgreSQL through async SQLAlchemy (asyncpg). ORM models live in app/core/database/models/, TrainingRepository (app/core/database/repository.py) is the data access layer, and a session is injected into endpoints with Depends(get_session). Schema migrations are handled by Alembic (alembic.ini, migrations/); the URL is taken from app/config.py.

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 - Standalone uvicorn runner (unused: Docker starts uvicorn from compose.yaml)
migrations/ - Alembic environment and versions
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.

3.9 KiB Raw Blame History