mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-26 00:51:44 +00:00
feat: Initial commit of FitTrack_GarminSync project
This commit is contained in:
@@ -1,50 +1,198 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
<!--
|
||||
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
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### 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.
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
### 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.
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
### 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.
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
### 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.
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
## Project Structure Standards
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
Root requirements file MUST be present.
|
||||
Virtual environment MUST be located at `.venv`.
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
### 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/`.
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
### 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/`.
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
## 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
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
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**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
**Version**: 1.0.0 | **Ratified**: 2024-01-15 | **Last Amended**: 2025-10-09
|
||||
Reference in New Issue
Block a user