Skip to content

development.md

Latest commit

 

History

History
64 lines (47 loc) · 2.22 KB

development.md

File metadata and controls

64 lines (47 loc) · 2.22 KB
Raw

Development

The repository is split into core, drivers and optimizer. See architecture.md before moving responsibilities between them.

Fast loop

make dev          # simulators + core, creates config.local.yaml when missing
make test         # Go and Python suites
make e2e          # explicit full-stack simulator test
npm test          # web tests
make verify       # fast pre-commit verification
make ci           # e2e, builds and browser smoke

make test runs independent Go and optimizer work concurrently and reuses the optimizer virtual environment. Prefer a narrow package or test while iterating, then run make verify. Use make ci for a complete local handoff pass.

Run core alone:

cd go
go run ./cmd/ftw -config ../config.local.yaml -web ../web

The UI listens on the configured API port, normally 8080.

Live-data UI work

FTW_PROXY_UPSTREAM forwards local /api/* requests to a live LAN instance while serving UI files from the worktree. Writes are blocked by default.

FTW_PROXY_UPSTREAM=http://192.168.1.20:8080 \
  go run ./go/cmd/ftw -config config.local.yaml -web web

Set FTW_PROXY_READONLY=0 only for an intentional live write session.

Containers

docker compose up -d mirrors the Linux production topology: core, optimizer, updater and MQTT broker. Use docker-compose.macos.yml on macOS. Local Compose overrides are machine-specific and untracked.

Generated files

bin/, dist/, artifacts/, local databases, caches, node_modules/ and optimizer/.venv/ are disposable and ignored. Do not treat generated output or agent plans as project documentation.

drivers/*.lua is ignored too: it is a snapshot of the commit pinned in drivers/BUNDLED_SOURCE.json, fetched, never authored here. A fresh clone or git worktree therefore starts without either it or the virtual environment, and the first make test builds both. There is no separate setup step. Later runs cost nothing.

The optimizer needs Python 3.11 or newer. make picks an interpreter that qualifies, overridable with PYTHON=, and falls back to uv — optional, used only when the machine has no suitable Python of its own.