FitTrack_GarminSync/constitution.yaml

# .spec-kit/constitution.yaml
version: '1.0'
project_name: 'fitness-platform'
created_date: '2024-01-15'

# Core Development Principles
principles:
  - name: 'Python Modernization'
    description: 'Use modern Python features and maintain compatibility with 3.13+'
    rules:
      - 'All projects must use Python 3.13 or newer'
      - 'Use type hints throughout all code'
      - 'Prefer dataclasses over traditional classes for data structures'
      - 'Use pathlib for all file path operations'

  - name: 'Virtual Environment Isolation'
    description: 'Maintain clean, reproducible development environments'
    rules:
      - 'All projects must use Python virtual environments'
      - 'Virtual environments must be named `.venv` in project root'
      - 'Dependencies must be pinned in requirements.txt'
      - 'Development dependencies must be separate from production'

  - name: 'Test-Driven Development'
    description: 'Write tests first, maintain high test coverage'
    rules:
      - 'All new features must include tests before implementation'
      - 'Test coverage must be maintained at 80% minimum'
      - 'Use pytest as the primary testing framework'
      - 'Unit tests, integration tests, and API tests must be separated'

  - name: 'Containerization Standards'
    description: 'Consistent container deployment across all services'
    rules:
      - 'Use Docker Compose V3 syntax exclusively'
      - 'Command must be `docker compose` not `docker-compose`'
      - 'Multi-stage builds for production containers'
      - 'Health checks in all service definitions'

# Project Structure Standards
project_structure:
  root_requirements: true
  venv_location: '.venv'
  test_structure:
    unit_tests: 'tests/unit/'
    integration_tests: 'tests/integration/'
    api_tests: 'tests/api/'
    fixtures: 'tests/fixtures/'
  source_structure:
    main_module: 'src/'
    api_routes: 'src/api/'
    models: 'src/models/'
    services: 'src/services/'

# Service-Specific Standards
service_standards:
  centraldb_service:
    database: 'PostgreSQL 15+ or SQLite'
    orm: 'SQLAlchemy 2.0+'
    migrations: 'Alembic'
    api_framework: 'FastAPI'

  garminsync_service:
    async_processing: true
    file_handling: 'FIT/TCX/GPX parsing'
    oauth_flows: 'Garmin Connect, Fitbit'

  reportgenerator_service:
    cpu_intensive: true
    chart_generation: 'Matplotlib/Plotly'
    file_formats: 'PNG, PDF, HTML'

  llmcoach_service:
    llm_providers: 'OpenAI, Anthropic, Local'
    prompt_management: 'Structured templates'
    conversation_storage: 'CentralDB integration'

  web_interface:
    frontend_framework: 'React/Next.js'

  cli_interface:
    cli_framework: 'Click or Typer'
    configuration: 'YAML config files'
    output_formats: 'JSON, table, CSV'

# Development Workflow
development_workflow:
  pre_commit:
    - 'black --check .'
    - 'flake8'
    - 'mypy .'
    - 'pytest'
  
  testing:
    unit_tests: 'pytest tests/unit -v'
    integration_tests: 'pytest tests/integration -v'
    api_tests: 'pytest tests/api -v'
    coverage: 'pytest --cov=src --cov-report=html'

  container_commands:
    development: 'docker compose -f docker-compose.dev.yml up'
    production: 'docker compose -f docker-compose.prod.yml up -d'
    testing: 'docker compose -f docker-compose.test.yml up --abort-on-container-exit'

# Dependency Management
dependency_management:
  requirements_files:
    - 'requirements.txt'  # Production dependencies
    - 'requirements-dev.txt'  # Development dependencies
    - 'requirements-test.txt'  # Testing dependencies
  
  version_pinning: 'exact versions in production'
  security_scanning: 'safety check && bandit -r src/'

# API Standards
api_standards:
  framework: 'FastAPI'
  documentation: 'Auto-generated OpenAPI/Swagger'
  versioning: 'URL path versioning (/api/v1/)'
  error_handling: 'Structured error responses'
  rate_limiting: 'Redis-based rate limiting'

# Code Quality Standards
code_quality:
  formatting:
    tool: 'black'
    line_length: 88
    config_file: 'pyproject.toml'
  
  linting:
    tool: 'flake8'
    max_complexity: 10
  
  type_checking:
    tool: 'mypy'
    strict: true
  
  import_sorting:
    tool: 'isort'

# Git Standards
git_standards:
  branch_naming:
    feature: 'feature/description'
    bugfix: 'fix/description'
    hotfix: 'hotfix/description'
    release: 'release/version'
  
  commit_messages:
    format: 'conventional commits'
    types: ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']
  
  protected_branches: ['main', 'develop']

# Deployment Standards
deployment:
  environments:
    development: 'docker compose on local machine'
    production: 'hashicorp nomad'
  
  health_checks:
    liveness: '/health/live'
    readiness: '/health/ready'
    startup: '/health/start'

# Monitoring and Observability
monitoring:
  logging:
    format: 'JSON structured logs'
    level: 'INFO (DEBUG in development)'