FitTrack_GarminSync/.specify/memory/constitution.md

FitTrack_GarminSync Constitution

Core Principles

I. Python Modernization

All projects MUST use Python 3.13 or newer. Type hints MUST be used throughout all code. Dataclasses SHOULD be preferred over traditional classes for data structures. Pathlib MUST be used for all file path operations.

II. Virtual Environment Isolation

All projects MUST use Python virtual environments. Virtual environments MUST be named .venv in the project root. Dependencies MUST be pinned in requirements.txt. Development dependencies MUST be separate from production dependencies.

III. Test-Driven Development

All new features MUST include tests before implementation. Test coverage MUST be maintained at 80% minimum. Pytest MUST be used as the primary testing framework. Unit tests, integration tests, and API tests MUST be separated.

IV. Containerization Standards

Docker Compose V3 syntax MUST be used exclusively. The command docker compose MUST be used, not docker-compose. Multi-stage builds MUST be used for production containers. Health checks MUST be included in all service definitions.

Project Structure Standards

Root requirements file MUST be present. Virtual environment MUST be located at .venv.

Test Structure

Unit tests MUST be located in tests/unit/. Integration tests MUST be located in tests/integration/. API tests MUST be located in tests/api/. Test fixtures MUST be located in tests/fixtures/.

Source Structure

Main module MUST be located in src/. API routes MUST be located in src/api/. Models MUST be located in src/models/. Services MUST be located in src/services/.

Service-Specific Standards

centraldb_service

Database MUST be PostgreSQL 15+ or SQLite. ORM MUST be SQLAlchemy 2.0+. Migrations MUST use Alembic. API framework MUST be FastAPI.

garminsync_service

Asynchronous processing SHOULD be implemented where appropriate. File handling MUST support FIT/TCX/GPX parsing. OAuth flows MUST support Garmin Connect and Fitbit.

reportgenerator_service

CPU intensive operations SHOULD be optimized. Chart generation MUST use Matplotlib/Plotly. Supported file formats MUST include PNG, PDF, HTML.

llmcoach_service

LLM providers SHOULD include OpenAI, Anthropic, and Local options. Prompt management MUST use structured templates. Conversation storage MUST integrate with CentralDB.

web_interface

Frontend framework MUST be React/Next.js.

cli_interface

CLI framework MUST be Click or Typer. Configuration MUST use YAML config files. Output formats MUST include JSON, table, CSV.

Development Workflow & Quality Gates

Pre-commit Hooks

Pre-commit hooks MUST include:

• black --check .
• flake8
• mypy .
• pytest

Testing

Unit tests MUST be run with pytest tests/unit -v. Integration tests MUST be run with pytest tests/integration -v. API tests MUST be run with pytest tests/api -v. Test coverage MUST be reported with pytest --cov=src --cov-report=html.

Container Commands

Development containers MUST be run with docker compose -f docker-compose.dev.yml up. Production containers MUST be run with docker compose -f docker-compose.prod.yml up -d. Testing containers MUST be run with docker compose -f docker-compose.test.yml up --abort-on-container-exit.

Dependency Management

Requirements Files

Dependency files MUST include:

• requirements.txt (Production dependencies)
• requirements-dev.txt (Development dependencies)
• requirements-test.txt (Testing dependencies)

Version pinning MUST specify exact versions in production. Security scanning MUST include safety check and bandit -r src/.

API Standards

API framework MUST be FastAPI. API documentation MUST be auto-generated OpenAPI/Swagger. API versioning MUST use URL path versioning (e.g., /api/v1/). Error handling MUST provide structured error responses. Rate limiting SHOULD be Redis-based.

Code Quality Standards

Formatting

Code formatting tool MUST be Black. Maximum line length MUST be 88 characters. Black configuration file MUST be pyproject.toml.

Linting

Linting tool MUST be Flake8. Maximum complexity SHOULD be 10.

Type Checking

Type checking tool MUST be Mypy. Mypy MUST be run in strict mode.

Import Sorting

Import sorting tool MUST be Isort.

Git Standards

Branch Naming

Feature branches MUST follow the pattern feature/description. Bugfix branches MUST follow the pattern fix/description. Hotfix branches MUST follow the pattern hotfix/description. Release branches MUST follow the pattern release/version.

Commit Messages

Commit messages MUST follow conventional commits format. Allowed commit types include: feat, fix, docs, style, refactor, test, chore.

Protected branches MUST include main and develop.

Deployment Standards

Environments

Development environment MUST use docker compose on the local machine. Production environment MUST use HashiCorp Nomad.

Health Checks

Liveness probes MUST be at /health/live. Readiness probes MUST be at /health/ready. Startup probes MUST be at /health/start.

Monitoring and Observability

Logging

Logging format MUST be JSON structured logs. Logging level MUST be INFO (DEBUG in development).

Governance

This Constitution supersedes all other practices. Amendments require documentation, approval, and a migration plan. All Pull Requests and code reviews MUST verify compliance with these principles. Any deviation from these principles or introduction of complexity MUST be justified with a clear rationale.

Version: 1.0.0 | Ratified: 2024-01-15 | Last Amended: 2025-10-09