# Development

> All changes MUST follow the vendor/tiara-gitflow-spec.git and no work MUST be
> started without a TODO issue.

## Prerequisites

- Python 3.9+
- [Pipenv](https://pipenv.pypa.io/)
- [tox](https://tox.wiki/) (installed via Pipenv dev dependencies)
- Node.js (for the `@byteb4rb1e/mime-todo` issue tracker CLI)

## Setup

Iniitialize Git submodules:

```bash
git submodule update --init --remote --recursive
```

Install dependencies (includes the package in editable mode):

```bash
pipenv install --dev


Copy and fill in credentials:

```bash
cp .env.example .env
```

### Fitbit credentials

1. Register a **Personal** app at
   [dev.fitbit.com/apps/new](https://dev.fitbit.com/apps/new)
   - OAuth 2.0 Application Type: **Personal**
   - Callback URL: must match `FITBIT_REDIRECT_URI` in `.env`
   - Default Access Type: **Read-Only**
2. Add `FITBIT_CLIENT_ID`, `FITBIT_CLIENT_SECRET`, and `FITBIT_REDIRECT_URI`
   to `.env`
3. Authorize to get tokens: `python3 -m byteb4rb1e.homeostat auth`

### fddb.info credentials

Add `FDDB_USERNAME` and `FDDB_PASSWORD` to `.env`.

## Tooling

### Package

The project is packaged as `byteb4rb1e.homeostat` under a namespace package
layout (`src/byteb4rb1e/homeostat/`). It is installed in editable mode via
Pipenv.

Build a distribution:

```bash
pipenv run dist
```

### Testing

Tests are managed by tox. Test environments are defined in `tox.ini`:

```bash
# run all test suites
tox

# run specific environments
tox -e unit-py313
tox -e lint
tox -e format
```

| Environment | Purpose |
|---|---|
| `unit-py3{9-13}` | Unit tests |
| `smoke-py3{9-13}` | Smoke tests |
| `integration-py3{9-13}` | Integration tests |
| `lint` | Type checking (mypy) |
| `format` | Code style (autopep8) |
| `audit` | Dependency audit (pip-audit) |

### Issue tracker

Issues are tracked in the `TODO` file using the
[MIME TODO](https://specs.code.tiararodney.com/mime-todo/) format. Use the
`@byteb4rb1e/mime-todo` CLI to interact with it:

```bash
# list issues
npx @byteb4rb1e/mime-todo list

# show a specific issue
npx @byteb4rb1e/mime-todo show 3

# create an issue
npx @byteb4rb1e/mime-todo create --type feature --title "Title" --plan "Description" --module homeostat
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full issue lifecycle.

## Architecture overview

The pipeline has four phases:

1. **Source adapters** — thin modules that fetch raw data from providers
   (Fitbit, fddb). Provider-specific logic only.
2. **Raw warehouse** — stores fetched data with minimal interpretation. JSONL
   partitions by date and source.
3. **Canonical warehouse** — translates source data into provider-agnostic
   domain entities. JSONL partitions by entity and day.
4. **Projections** — generates the JSON output files from canonical data via
   SQLite views. Decoupled from sync.

SQLite sits on top of the JSONL warehouse as a query layer. It is disposable
and can be rebuilt from partitions at any time.

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design, including storage
layout, domain model, and open design questions.

## Project layout

```
src/byteb4rb1e/homeostat/    # package source
tests/                       # test suites (unit/, smoke/, integration/)
data/                        # canonical warehouse (JSONL partitions)
build/projection/            # projection output (gitignored)
vendor/                      # vendored specs
ARCHITECTURE.md              # full pipeline design
TODO                         # issue tracker (MIME TODO format)
```
