# 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