Timebox

Timebox combines a dual-lane daily planner with a task and project backlog. The React + Tailwind web app and native Kotlin + Compose Android app share a FastAPI + Postgres backend.

Plan and track planned vs actual time blocks on a 30-minute grid, pull Ready to Plan tasks onto the day, and manage projects, subtasks, deadlines, reminders, recurring work, archives, and trash. The backend uses a fixed app timezone (APP_TIMEZONE) so every device agrees on “today”.

There is also a native Kotlin + Compose Android client in android/, talking to the same API.

Prerequisites

• Node.js 20+
• Python 3.11+
• uv (recommended for the backend; manages .venv and uv.lock)
• Postgres 15+ (local or Docker)

Environment

.env.example documents all supported variables. Environment files are resolved relative to the process working directory:

• When starting the API from backend/, put backend values in backend/.env or export them in the shell.
• When starting Vite from frontend/, put VITE_* values in frontend/.env or export them in the shell.
• A repo-root .env is not loaded automatically by those commands.

The backend reads DATABASE_URL, APP_TIMEZONE, CORS_ORIGINS, optional CORS_ORIGIN_REGEX, and optional API_KEY. Vite uses VITE_API_BASE_URL for direct API requests, or proxies /api to VITE_API_PROXY_TARGET during development.

Frontend command (from frontend/)	UI port	Default /api proxy target
npm run dev	5174	http://127.0.0.1:8000
npm run dev:review	5176	http://127.0.0.1:8001

Set VITE_API_PROXY_TARGET in frontend/.env or the shell to override either default. Vite reads frontend/.env from the frontend working directory. Both commands stop if their UI port is already occupied.

Database

Create a database and user matching DATABASE_URL, then run migrations from backend/:

cd backend
uv sync --extra dev
alembic upgrade head

If you previously ran an older schema (with hour_entries), alembic upgrade head applies the follow-up migration that drops hour_entries and creates time_blocks. Later migrations add the global day window, hierarchical task types, linked planned/actual blocks, Battle Plan projects and tasks, Ready to Plan scheduling, recurring templates, and blocked-task state. Always back up production data before migrating.

Without uv: python -m pip install -e ".[dev]" (from backend/).

Run locally

On Windows, the review launcher verifies the registered ports, Postgres identity, database URL, Alembic revision, API readiness, Vite proxy, and Android foreground activity before reporting success:

.\scripts\launch-timebox.ps1

It writes logs and machine-readable status.json under %LOCALAPPDATA%\Temp\timebox-launch. Use .\scripts\stop-timebox.ps1 to stop only processes and containers whose Timebox identity is verified. Pass -KeepDatabase or -KeepAndroid when those surfaces should remain running.

Terminal 1 — API

cd backend
uv sync --extra dev
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8001

Set DATABASE_URL, APP_TIMEZONE, and CORS_ORIGINS=http://localhost:5176,http://127.0.0.1:5176 in backend/.env or the shell first. In PowerShell, temporary values use $env:NAME="value"; on macOS/Linux, use export NAME="value".

Terminal 2 — UI

cd frontend
npm install
npm run dev:review

The review command proxies /api to http://127.0.0.1:8001 by default. Open http://127.0.0.1:5176.

These commands use the workspace's registered Timebox ports. The Android emulator's debug build also defaults to API port 8001.

Tests

Keep tests for persisted behavior, validation, time calculations, offline recovery, concurrency, accessibility, and destructive actions. Prefer one representative browser/device journey over repeated integration tests of the same logic. Screenshot capture without baseline comparison, fixed palette/spacing assertions, and retired UI flows are excluded.

cd backend && uv run --extra dev --extra eval python -m pytest
cd frontend && npm test
cd frontend && npm run lint
cd frontend && npm run build
cd frontend && npm run e2e

The Windows launcher safety helpers have a focused Pester suite:

Invoke-Pester .\scripts\tests\Timebox.Launch.Tests.ps1

npm test runs Vitest unit/component tests. npm run e2e starts isolated API and web servers with a SQLite test database, then checks core routes, task lifecycle, planning placement, themes, and responsive layouts. Install its browser once with npx playwright install chromium. Recurrence rules and editing remain covered by backend and component tests. The backend command includes the optional eval dependencies required by its controlled optimizer tests; it makes no paid model calls.

E2E note: Playwright uses the dedicated ports declared in frontend/playwright.config.ts and may reuse listeners already occupying those exact ports outside CI. If a stale E2E server or schema causes failures, stop that listener or delete backend/e2e.sqlite so Playwright can start a fresh API using AUTO_CREATE_TABLES=1.

Android unit tests and builds are available after Android Studio has generated the Gradle wrapper. On Windows, use the repository launcher so Gradle automatically uses an installed JDK 17+ without changing the machine-wide Java configuration:

.\scripts\android-gradle.ps1 testDebugUnitTest assembleDebug

Android device tests use the shared emulator reservation helper:

python scripts/android-emulator.py test --owner "your-task-id"

It selects an isolated emulator and releases it after testing. For interactive work, review holds, and recovery, see Android emulator ownership.

On macOS or Linux, set JAVA_HOME to JDK 17+ and run cd android && ./gradlew testDebugUnitTest assembleDebug.

Design and behavior references

The visual source of truth is DESIGN.md. Native Android setup and behavior are documented in android/README.md. Current domain vocabulary and decisions live in CONTEXT.md and docs/adr/; implementation-specific design and verification notes are organized under docs/design/, docs/specs/, and docs/reports/.

Product surfaces

• Day: Planned and actual lanes, Ready to Plan scheduling, linked completions, notes, and overlap validation.
• Chronicle: Browse dates through Today with plans, recorded activity, or Task Completion.
• Battle Plan: Projects and admin tasks, subtasks, status and priority metadata, deadlines, reminders, manual ordering, archive, and trash.
• Recurring: Scheduled and quota-based templates with preview, pause, resume, end, and deletion workflows.
• Task types: Reusable hierarchical slash-path categories shared by blocks, tasks, and recurring templates.
• Settings: One page grouped the same way on web and Android: Day & time (day window and Reporting Time Zone, shared by all devices), then device-only Focus & check-ins, reminders and notifications, appearance, and (Android) server connection.

API assumptions

• Timezone: The backend owns APP_TIMEZONE; the UI uses meta from day responses for “today” and server time.
• Auth and readiness: The application is single-user. Setting API_KEY turns on a shared-secret X-API-Key check for every application route, including days, settings, task types, projects, tasks, reminders, and recurring templates. /health and /ready stay open. /ready returns HTTP 200 only when the database responds and its Alembic revision matches the repository head. The Android client sends the key; the web frontend does not, so leave it unset while relying on the browser UI.
• Day summary: GET /days/{date}/summary returns planned/actual totals plus per-task-type minutes without creating the day. The old Android Day Review UI was removed while reporting is reconsidered; this endpoint remains as a possible reporting primitive.
• Day preview: GET /days/{date}/preview returns renderable day data without creating a missing day. The Android client uses it for adjacent pages during an interactive swipe.
• Day and Chronicle reads: GET /days/{date} renders missing dates without saving a Day row. GET /days/chronicle?month=YYYY-MM returns qualifying dates for the requested month, defaulting to the current month in the Reporting Time Zone. Empty saved Day rows stay stored but do not appear in Chronicle.
• E2E / SQLite: Setting AUTO_CREATE_TABLES=1 lets the API create tables on startup (used by Playwright). Do not use this for production Postgres; use Alembic instead.
• Day window: Configure the visible hours under Settings (GET/PATCH /settings); changes apply to all days.
• Task types: Manage reusable path categories under Task types (GET/POST/PATCH/DELETE /task-types). Names are canonical lowercase slash paths (e.g. coding, coding/ai, exercise/cardio); creating a deep path materializes ancestors; renames cascade to descendants. Every stored Block references a Task Type. Planned Block creation may omit task_type_id: the backend uses a linked Task's type when available or atomically materializes unspecified. Planned Blocks may also include an optional 500-character Block Name and a separate optional . See the , especially .