TimeTracker/docs/DEVELOPMENT.md

TimeTracker Development Guide

Quick reference for running the project locally, running tests, and contributing. For a single-page contributor overview (workflows, adding routes/services/templates), see Contributor Guide. For full guidelines, see Contributing and the developer documentation.

Running Locally

Option A: Python and virtual environment

1. Clone the repo and enter the directory:

   git clone https://github.com/drytrix/TimeTracker.git
   cd TimeTracker
   

2. Create and activate a virtual environment:

   python -m venv venv
   # Windows:
   venv\Scripts\activate
   # Linux/macOS:
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Copy the environment template and set required variables:

   cp env.example .env
   

   Edit .env: set SECRET_KEY (e.g. from python -c "import secrets; print(secrets.token_hex(32))"). For a local DB, you can use SQLite (see Local Testing with SQLite).

5. Initialize the database and run the app:

   flask db upgrade
   flask run
   

   By default the app is at http://127.0.0.1:5000.

Option B: Docker (SQLite, no PostgreSQL)

For a quick run without installing Python locally:

docker-compose -f docker/docker-compose.local-test.yml up --build

Then open http://localhost:8080. See Local Testing with SQLite for details.

Environment Setup

• Copy env.example to .env and adjust values.
• Key variables: SECRET_KEY, DATABASE_URL (or leave default for SQLite), TZ, CURRENCY.
• Full list and descriptions: Docker Compose Setup and env.example.

Dependencies

• Python: 3.11+
• Package list: requirements.txt
• Package install for tests: setup.py is used so the app can be installed as a package (e.g. pip install -e .) for testing; core dependencies remain in requirements.txt.

Folder Structure

TimeTracker/
├── app/              # Flask app: routes, models, services, templates, utils
├── desktop/          # Electron-style desktop app
├── mobile/           # Flutter mobile app
├── docker/           # Docker config and scripts
├── tests/            # Pytest tests
├── docs/             # Documentation
├── app.py            # Application entry point
├── env.example       # Environment template
└── requirements.txt # Python dependencies

For more detail, see ARCHITECTURE.md and Project Structure.

Coding Conventions

• Follow the Contributing guidelines: PEP 8, Black (line length 88), type hints and docstrings where appropriate.
• Use blueprints for routes; keep business logic in services.

Development Workflow

1. Create a branch for your change.
2. Run tests locally: pytest (or pytest --cov=app for coverage).
3. Lint/format: follow Contributing (e.g. Black, flake8).
4. For user-facing changes, add an entry under Unreleased in CHANGELOG.md.

Running Tests

# All tests
pytest

# With coverage
pytest --cov=app

# Single file
pytest tests/test_timer.py

# Single test class or test
pytest tests/test_routes/test_api_v1_projects_refactored.py -v

See Contributing – Testing for more options and conventions.

Build Steps

• Web app: No separate frontend build required; Tailwind and static assets are served as-is (or built via your pipeline if you use one). Run the app with flask run or python app.py.
• Docker image: docker build -t timetracker . from repo root. See Docker Compose Setup.
• Mobile/Desktop: See Build Guide and mobile-desktop-apps/README.md for Flutter and Electron build steps.

Contributing

1. Read CONTRIBUTING.md.
2. Follow the full Contributing guidelines (branching, PR process, changelog).
3. For user-facing changes, add an entry under Unreleased in CHANGELOG.md.

Releases

How versions and releases are managed is documented in Version Management. The application version is defined in setup.py as the single source of truth.