Fire Tools — Engineering documentation

This section is for developers and operators who want to self-host the backend, build a custom client, or understand the internals. If you're a regular user, you probably want the user guide instead.

Pages in this section

Architecture at a glance

+----------------+        +----------------+        +----------------+
|  Web / Electron| <----> |  Node.js API   | <----> |     SQLite     |
|     client     |  HTTP  |   Express +    |  SQL   |  local file DB |
|  (React, Vite) |        |    OpenAPI     |        |  local/compose |
+----------------+        +----------------+        +----------------+

Why a local-first backend?

Most FIRE tools either run entirely client-side (data trapped in one browser) or fully cloud-hosted (third party sees your finances). Fire Tools' backend is meant to run on your own machine (Docker Desktop, your homelab, whatever) so your data stays on your hardware while still being reachable from multiple devices on your network.

Every domain table already carries user_id, but the default configuration boots a single user. The schema and user-scoping helpers leave room for a future authenticated multi-tenant deployment; they are not authentication.

Source map

Path Purpose
src/ React + TypeScript frontend (Vite)
src/i18n/ On-demand translation resources and language setup
src/routes/ Lazy route registry and navigation preloading
src/workers/ Monte Carlo and withdrawal-rate simulation execution
src/assets/fonts/ Bundled icon font; its license is distributed from public/
.github/skills/ Repository-local UI, performance and data-integrity workflows
server/ Node.js + Express + better-sqlite3 backend
electron/ Electron main + preload (desktop wrapper)
website/ Marketing landing page
docs/api/ OpenAPI contract + Redocly config
docs/database/ DDL + ERD notes
docs/deployment/ Docker Compose how-tos
docs/user/ End-user documentation (this site's /docs/user/)
docs/engineering/ Engineering documentation (this site's /docs/engineering/)

Agent-assisted changes

AGENTS.md is the contributor-wide agent entry point. The focused skills in .github/skills/ capture the interface, calculation-performance and data-retention safeguards for future changes. Read the relevant SKILL.md before working in that area. Each skill includes planning smoke-test prompts; those fixtures are not claims of completed model benchmarks.

npm run test:browser runs the committed Playwright regression suite with synthetic data and mocked external responses. Its CI job verifies navigation, plot and label bounds, usable chart height and local-only overflow across desktop/mobile routes.

Continuous integration

The Tests workflow runs on every pull request update, including drafts, and every push to main. A newer run cancels obsolete work for the same pull request. Each main push has its own concurrency group, so integration validation is not canceled by a later push. Deployment, version preparation and release concurrency are unchanged.

The existing path filters select page-specific tests unless shared inputs require the full renderer suite. Only changed pages enter the test matrix; docs-only and backend-only changes do not allocate empty page-test runners. The page matrix stops remaining siblings on failure. Every main push still runs the full renderer, backend, browser and uncached Docker health checks.

Node-based test jobs use locked installs with --ignore-scripts to avoid downloading Electron and rebuilding SQLite for the wrong runtime. The test commands still run their pretest hooks, which verify and, if needed, rebuild SQLite for plain Node. Jobs installing both dependency trees key the npm download cache from both lockfiles; installed dependencies are not cached.

Browser CI uses two Playwright workers across isolated spec files while tests within each file stay sequential. It still builds the backend and self-hosted frontend and runs every browser regression. Local runs keep the one-worker default; use npm run test:browser -- --workers=2 to reproduce CI concurrency.

Related links