FitTrack_GarminSync/.specify/memory/constitution.md

<!--
Version change: None → 1.0.0
List of modified principles:
  - Python Modernization (New)
  - Virtual Environment Isolation (New)
  - Test-Driven Development (New)
  - Containerization Standards (New)
Added sections:
  - Project Structure Standards
  - Service-Specific Standards
  - Development Workflow & Quality Gates
  - Dependency Management
  - API Standards
  - Code Quality Standards
  - Git Standards
  - Deployment Standards
  - Monitoring and Observability
Removed sections:
  - None (placeholders replaced or removed as per YAML content)
Templates requiring updates:
  - .specify/templates/plan-template.md ⚠ pending
  - .specify/templates/spec-template.md ⚠ pending
  - .specify/templates/tasks-template.md ⚠ pending
Follow-up TODOs:
  - Ensure all `MUST` and `SHOULD` statements are clear and testable.
-->
# 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