---
title: Habit Journal
emoji: 📓
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# Habit Journal API

Personal habit journal API designed for a Hugging Face Docker Space. The
backend uses signed cookie sessions and durable JSONL files under `DATA_ROOT`.

## Run locally

Set `APP_PASSWORD` and `APP_SECRET_KEY`, install `requirements.txt`, then run:

```text
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 7860
```

`ENV=dev` enables the OpenAPI endpoints for local development.

## Environment

- `APP_PASSWORD`: initial password used only when `config.json` is absent
- `APP_SECRET_KEY`: required session-signing key
- `DATA_ROOT`: storage directory (default `/data/loop_logger`)
- `ENV`: runtime environment (default `prod`)
- `APP_NAME`: displayed application name (default `Habit Journal`)
- `SESSION_MAX_AGE_SEC`: signed-session lifetime (default `604800`)
- `LOGIN_RATE_LIMIT` / `LOGIN_RATE_WINDOW_SEC`: login throttling
- `AGENT_TOKEN`: Bearer token for `GET /api/agent/context` and `PUT /api/agent/plan/{day}`
- `OPENROUTER_API_KEY` / `OPENROUTER_MODEL`: optional coach model (else Rules backup)
- `COACH_*`: temperature, max tokens, history, trace limit (see `app/config.py`)
- `SCHEDULE_*` / `RESCHEDULE_MIN_GAP_MIN`: plan window and reschedule cooldown
- `DEBUG_INCLUDE_FULL_BRIEF` / `MIN_STATS_N`: debug paste and stats floor

Coach and schedule details: `docs/BACKEND.md`, `docs/SCHEDULE.md`, `docs/ARCHITECTURE.md`.  
P1 finish checklist: `docs/FINISH_AUDIT.md`.

## Frontend

Nav: **Home | Plan | (+) Log | Daily | Settings** (History via Home “See all”).

```text
cd frontend
npm install
npm test
npm run build   # writes to ../static for FastAPI
npm run dev     # proxies /api to :7860
```

Docker builds the frontend in a Node stage and copies `static/` into the image.
Service worker **never caches** `/api/*`.

### Phone / Space verify

1. Open the Space URL, log in.
2. Confirm bottom nav includes **Plan**.
3. Daily → Movement & freeze → save → reload → fields persist.
4. After two indoors days (or set `stayed_indoors_all_day` twice), Home shows indoors banner → **Move now**.
5. Log intensity 9 + remedy “Labeling” → warning; coach/Rules should push interrupt/proof, not label-only.

## Deploy to Hugging Face

```text
git remote -v   # expect hf → https://huggingface.co/spaces/Mbonea/Fastwhisper
git push hf master:main
```

Set secrets in the Space settings UI. Do not commit `.env` or tokens.
After rebuild, hard-refresh the PWA once so the new `static/` + SW load.