TimeTracker/docs/development/CONTRIBUTOR_GUIDE.md

Contributor Guide

Single-page overview for contributors: architecture, local dev, testing, how to add routes/services/templates, and versioning. For full guidelines see CONTRIBUTING.md; for structure see Project Structure.

---

Repo architecture

• Stack: Flask app (server-rendered HTML + REST API), optional SocketIO/scheduler, Docker + Nginx + PostgreSQL.
• Layers: Routes (app/routes/) → Services (app/services/) → Repositories (app/repositories/) / Models (app/models/). API under /api/v1/.
• Blueprint registration: All route blueprints are registered in app/blueprint_registry.py (single place). Use the main registration list for required modules; optional feature blueprints go in _register_optional_blueprints—failures are logged with a full traceback, and the process re-raises in development only so optional routes are not silently missing locally.

flowchart LR
  Routes[routes/] --> Services[services/]
  Services --> Repos[repositories/]
  Repos --> Models[models/]
  Models --> DB[(DB)]

More: ARCHITECTURE.md · Project Structure

---

Local dev workflow

1. Clone the repo and cd TimeTracker.
2. Venv: python -m venv venv then activate (venv\Scripts\activate on Windows, source venv/bin/activate on Linux/macOS).
3. Deps: pip install -r requirements.txt; for tests also pip install -r requirements-test.txt.
4. Env: cp env.example .env and set at least SECRET_KEY (e.g. python -c "import secrets; print(secrets.token_hex(32))").
5. DB: flask db upgrade.
6. Run: flask run → http://127.0.0.1:5000.

Docker (no local Python):

• SQLite (quick test): docker-compose -f docker/docker-compose.local-test.yml up --build → http://localhost:8080.
• Default (HTTPS): docker-compose up -d → https://localhost (self-signed cert).
• HTTP 8080: docker-compose -f docker-compose.example.yml up -d → http://localhost:8080.

More: Local Testing with SQLite · DEVELOPMENT.md

---

Testing workflow

• Full suite: pytest or make test.
• Coverage (required for CI): make test-coverage or pytest --cov=app --cov-report=html --cov-fail-under=50.
• By type: make test-routes, make test-models, make test-api, make test-unit, make test-integration, make test-smoke.
• Markers: pytest -m routes, pytest -m api, etc.

Run the full test suite before opening a PR. Add tests for new behavior (e.g. in tests/test_routes/, tests/test_services/, tests/test_api_*).

More: Testing Quick Reference · Testing Coverage Guide

---

How to add a route

1. Add or extend a blueprint in app/routes/ (e.g. new file or existing api_v1_*.py).
2. Register the blueprint in app/blueprint_registry.py (import and app.register_blueprint(...) in register_all_blueprints, or add an optional (module_path, bp_attr) tuple if the module may be absent in some installs).
3. Prefer calling a service for business logic; keep the route thin.
4. Add tests in tests/test_routes/ or tests/test_api_* as appropriate.

More: Service Layer and Base CRUD · CONTRIBUTING.md

---

How to add a service or repository

1. Service: Add a class in app/services/ (e.g. app/services/my_domain_service.py). Put business logic and orchestration here.
2. Repository (optional): Add a class in app/repositories/ for data access and shared queries; use it from the service or route.
3. Follow existing patterns (see Service Layer and Base CRUD); use BaseCRUDService only when the domain is simple CRUD with an existing repository.
4. Call the service from routes; add tests in tests/test_services/ or tests/test_repositories/.

More: SERVICE_LAYER_AND_BASE_CRUD.md · ARCHITECTURE.md

---

How to add a template

1. Create a template that extends app/templates/base.html and overrides blocks (content, title, etc.).
2. Use components from app/templates/components/ui.html (e.g. page_header, empty_state, modal, confirm_dialog, form macros). Prefer these over legacy _components.html.
3. Follow UI Guidelines and FRONTEND.md for layout, buttons, and accessibility.
4. Styles: Tailwind; edit app/static/src/input.css and build to app/static/dist/output.css if needed.

---

Versioning

• Application version: Defined only in setup.py. Do not duplicate it in README or other docs.
• Desktop / mobile: Desktop and mobile builds may use their own version numbers; see Build Guide and repo scripts. Align with app version when releasing together.
• Releases and Docker images: Tagging, GitHub releases, and image publishing are in VERSION_MANAGEMENT.md and RELEASE_PROCESS.md.

For contributors: When updating the app version, change only setup.py. Do not add the version number to README, FEATURES_COMPLETE, or PROJECT_STRUCTURE.