From 0da1f18d2985ecb66b43fd048fd9330ef2359d98 Mon Sep 17 00:00:00 2001
From: dimiro1 <dimiro1@gmail.com>
Date: Tue, 2 Jun 2026 22:45:57 +0200
Subject: [PATCH] docs: add architecture decision records

---
 docs/adr/0000-template.md                     | 22 +++++++
 .../adr/0001-record-architecture-decisions.md | 40 ++++++++++++
 ...configuration-via-environment-variables.md | 55 +++++++++++++++++
 docs/adr/0003-frontend-with-mithril.md        | 46 ++++++++++++++
 docs/adr/0004-no-nodejs-vendored-js.md        | 47 ++++++++++++++
 docs/adr/0005-mise-for-toolchain-and-tasks.md | 47 ++++++++++++++
 docs/adr/0006-dependency-injection-with-fx.md | 44 +++++++++++++
 .../0007-single-binary-embedded-frontend.md   | 41 +++++++++++++
 docs/adr/0008-sqlite-as-the-datastore.md      | 41 +++++++++++++
 docs/adr/0009-lua-as-the-function-language.md | 49 +++++++++++++++
 docs/adr/0010-in-house-i18n.md                | 54 ++++++++++++++++
 docs/adr/0011-testing-strategy.md             | 61 +++++++++++++++++++
 docs/adr/README.md                            | 31 ++++++++++
 13 files changed, 578 insertions(+)
 create mode 100644 docs/adr/0000-template.md
 create mode 100644 docs/adr/0001-record-architecture-decisions.md
 create mode 100644 docs/adr/0002-configuration-via-environment-variables.md
 create mode 100644 docs/adr/0003-frontend-with-mithril.md
 create mode 100644 docs/adr/0004-no-nodejs-vendored-js.md
 create mode 100644 docs/adr/0005-mise-for-toolchain-and-tasks.md
 create mode 100644 docs/adr/0006-dependency-injection-with-fx.md
 create mode 100644 docs/adr/0007-single-binary-embedded-frontend.md
 create mode 100644 docs/adr/0008-sqlite-as-the-datastore.md
 create mode 100644 docs/adr/0009-lua-as-the-function-language.md
 create mode 100644 docs/adr/0010-in-house-i18n.md
 create mode 100644 docs/adr/0011-testing-strategy.md
 create mode 100644 docs/adr/README.md

diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md
new file mode 100644
index 0000000..50d5c8a
--- /dev/null
+++ b/docs/adr/0000-template.md
@@ -0,0 +1,22 @@
+# NNNN. Title
+
+- Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNNN
+- Date: YYYY-MM-DD
+
+## Context
+
+What is the problem, force, or constraint that motivates a decision? Describe the
+situation as neutrally as possible — facts, requirements, and the options on the
+table. A reader should be able to understand the tension without already knowing
+the answer.
+
+## Decision
+
+The change we are making, stated in the active voice: "We will …". Be specific
+enough that someone can act on it.
+
+## Consequences
+
+What becomes easier and what becomes harder as a result. Include the trade-offs
+we accept, the things we explicitly rule out, and any follow-up work this
+implies.
diff --git a/docs/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md
new file mode 100644
index 0000000..176051c
--- /dev/null
+++ b/docs/adr/0001-record-architecture-decisions.md
@@ -0,0 +1,40 @@
+# 0001. Record architecture decisions
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar is a self-hosted FaaS platform with a number of deliberate, non-obvious
+architectural choices: configuration through the environment, a build-step-free
+Mithril frontend, no Node.js in the toolchain, `mise` for tasks, `uber/fx` for
+wiring, a single embedded binary, and pure-Go SQLite. These decisions are easy
+to misread as accidents when only the resulting code is visible. New
+contributors (and our future selves) repeatedly ask "why is it done this way?",
+and without a record the answer lives only in memory and scattered commit
+messages.
+
+We want a durable, low-ceremony way to capture the *reasoning* behind decisions
+that shape the codebase, separate from the code that implements them and from the
+user-facing README.
+
+## Decision
+
+We will keep Architecture Decision Records as Markdown files under `docs/adr/`,
+one decision per numbered file, following the lightweight format in
+[`0000-template.md`](0000-template.md) (Status, Context, Decision,
+Consequences).
+
+ADRs are append-only. Once a record is `Accepted` we do not edit its substance;
+a decision that changes is recorded as a new ADR that supersedes the old one,
+and the old one's status is updated to point at its replacement.
+
+## Consequences
+
+- The rationale behind a choice travels with the repository and is versioned
+  alongside the code, reviewable in the same pull requests.
+- There is a small, well-understood cost to writing a record when a decision is
+  made. We accept this as cheaper than re-litigating decisions later.
+- Reviewers gain a natural place to push back on direction before it is encoded
+  in the codebase.
+- The README stays focused on *using* Lunar; the ADRs explain *building* it.
diff --git a/docs/adr/0002-configuration-via-environment-variables.md b/docs/adr/0002-configuration-via-environment-variables.md
new file mode 100644
index 0000000..327bc8a
--- /dev/null
+++ b/docs/adr/0002-configuration-via-environment-variables.md
@@ -0,0 +1,55 @@
+# 0002. Configuration via environment variables
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar ships as a single self-hosted binary that people run on their own
+machines, in Docker, and on platforms like Railway. These environments differ in
+how they inject settings, but every one of them can set environment variables.
+We need a configuration mechanism that:
+
+- works identically across local, Docker, and PaaS deployments;
+- requires no config file to exist for a first run (good defaults);
+- keeps secrets such as the API key out of the source tree;
+- is straightforward to test without mutating global process state.
+
+The realistic alternatives were a config file format (YAML/TOML), command-line
+flags, or environment variables. Config files add a parsing layer and a "where
+does it live" question for a single-binary tool. Flags are awkward to thread
+through container platforms and don't compose well with secret managers.
+
+## Decision
+
+We will load all runtime configuration from the process environment, following
+the [12-factor](https://12factor.net/config) approach, and bind it to a typed
+`config.Config` struct using [`caarlos0/env`](https://github.com/caarlos0/env)
+struct tags (`env:"..."`, `envDefault:"..."`).
+
+Configuration lives in its own `internal/config` package (not in `cmd`) so that
+the per-feature `fx` modules can depend on it directly — see
+[ADR-0006](0006-dependency-injection-with-fx.md).
+
+Concerns that a struct tag can't express are handled in code right after parsing:
+a custom parser for `EXECUTION_TIMEOUT` (an integer count of seconds), a
+computed default for `BASE_URL` (`http://localhost:<PORT>`), creation of the data
+directory, and an API-key fallback chain of env var → on-disk file → freshly
+generated key.
+
+`config.parse` accepts an explicit environment map so loading can be unit-tested
+without touching `os.Environ`.
+
+## Consequences
+
+- The same binary configures itself the same way everywhere; deployment docs are
+  just a list of variables with defaults.
+- A fresh run works with zero configuration — sensible defaults plus a
+  self-generated, persisted API key.
+- Secrets are supplied at runtime and never committed.
+- Standardising on `caarlos0/env` keeps loading declarative; the few exceptions
+  are localised and documented in the package doc comment.
+- Trade-off: deeply nested or list-of-object configuration is clumsy as flat
+  environment variables. This is acceptable given Lunar's small, flat config
+  surface; if that changes we will revisit with a new ADR rather than bolt on a
+  file format ad hoc.
diff --git a/docs/adr/0003-frontend-with-mithril.md b/docs/adr/0003-frontend-with-mithril.md
new file mode 100644
index 0000000..cbf52cb
--- /dev/null
+++ b/docs/adr/0003-frontend-with-mithril.md
@@ -0,0 +1,46 @@
+# 0003. Frontend with Mithril.js
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar's dashboard is a genuine single-page application: a code editor (Monaco),
+routing across functions/versions/executions/logs, i18n, a command palette, and
+many reusable components. We need a client-side framework, but the project has
+two strong constraints that rule out the mainstream React/Vue/Svelte path:
+
+- **No Node.js toolchain** (see [ADR-0004](0004-no-nodejs-vendored-js.md)). That
+  removes JSX/TSX, bundlers, and the npm-based ecosystem those frameworks assume.
+- **Ship inside a single Go binary** (see
+  [ADR-0007](0007-single-binary-embedded-frontend.md)). The frontend has to be a
+  set of static files we can `go:embed`, with no build artifact pipeline.
+
+We need a framework that is small, works as a single `<script>` with no build
+step, has a built-in router and XHR layer, and renders via plain function calls
+rather than a compiler-dependent template syntax.
+
+## Decision
+
+We will build the dashboard with [Mithril.js](https://mithril.js.org/), vendored
+as a single minified file and loaded via a `<script>` tag in `index.html`.
+
+Views are authored as plain ES modules using Mithril's hyperscript (`m(...)`)
+API, organised under `frontend/js` into `components/`, `views/`, `routes.js`,
+`api.js`, and an `i18n/` layer. No JSX, no transpilation: the `.js` files we
+write are the `.js` files the browser runs.
+
+## Consequences
+
+- The frontend has zero build step. Editing a `.js` file and reloading is the
+  whole dev loop; the embedded files are exactly what we authored.
+- Mithril is tiny and batteries-included (routing + `m.request` for XHR), so we
+  avoid pulling a constellation of micro-dependencies to fill gaps.
+- Hyperscript instead of JSX means component code is a little more verbose and
+  there's no template-level type checking. We accept this; it's the cost of
+  having no compiler.
+- We pin the Mithril version in `mise.toml` and vendor it via the `vendor-js`
+  task, so upgrades are explicit and reproducible.
+- Trade-off: we step outside the dominant React ecosystem, so off-the-shelf
+  component libraries don't apply. In return we keep the whole frontend
+  inspectable, buildless, and embeddable.
diff --git a/docs/adr/0004-no-nodejs-vendored-js.md b/docs/adr/0004-no-nodejs-vendored-js.md
new file mode 100644
index 0000000..1034111
--- /dev/null
+++ b/docs/adr/0004-no-nodejs-vendored-js.md
@@ -0,0 +1,47 @@
+# 0004. No Node.js: vendored JS, Deno for tooling
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar is a Go project that happens to have a rich browser frontend. The default
+path for that frontend would drag in the Node.js world: a `package.json`, an
+`node_modules/` tree of transitive dependencies, a lockfile, and a bundler. For a
+small self-hosted tool that wants to stay auditable and ship as one Go binary,
+that ecosystem brings real costs — supply-chain surface area, churn, a second
+language runtime in every contributor's environment and in CI, and a build step
+between the source and what runs.
+
+At the same time we still want *some* JS tooling: a formatter for the frontend
+code, and a way to run the browser test suite.
+
+## Decision
+
+We will not use Node.js, npm, or a bundler anywhere in the project.
+
+Browser dependencies (Mithril, Monaco, highlight.js, Jasmine) are **vendored**
+into `frontend/vendor/` by the `vendor-js` `mise` task, which downloads pinned
+versions straight from CDNs/registries (`unpkg`, `cdnjs`, the npm registry
+tarball for Monaco) using `curl`/`tar`. Versions are pinned as variables in
+`mise.toml`, so vendoring is reproducible and upgrades are a deliberate diff.
+
+For tooling that genuinely needs a JS runtime we use [Deno](https://deno.com/)
+(itself installed via `mise`): `deno fmt` formats the frontend, excluding the
+vendored tree. The frontend test suite runs through a small Go `testserver`
+binary that serves Jasmine in a browser — no Node test runner involved.
+
+## Consequences
+
+- There is no `node_modules/`, no `package.json`, and no lockfile to manage or
+  audit; the vendored files in git *are* the dependency manifest.
+- Every dependency is a concrete, reviewable file at a pinned version. Upgrades
+  show up as explicit diffs from re-running `vendor-js`.
+- Contributors need only the tools `mise` installs (Go, Deno, etc.); there's no
+  separate Node version to match.
+- The vendored files are committed, which adds some weight to the repository. We
+  accept this in exchange for reproducibility and a buildless frontend.
+- Trade-off: we forgo npm's convenience and the framework ecosystems that assume
+  a bundler. This is the deliberate counterpart to
+  [ADR-0003](0003-frontend-with-mithril.md) and
+  [ADR-0007](0007-single-binary-embedded-frontend.md).
diff --git a/docs/adr/0005-mise-for-toolchain-and-tasks.md b/docs/adr/0005-mise-for-toolchain-and-tasks.md
new file mode 100644
index 0000000..abec45f
--- /dev/null
+++ b/docs/adr/0005-mise-for-toolchain-and-tasks.md
@@ -0,0 +1,47 @@
+# 0005. mise for toolchain and task management
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+The project depends on several pinned tools — Go, golangci-lint, Deno (see
+[ADR-0004](0004-no-nodejs-vendored-js.md)), GoReleaser, and Air — and on a
+collection of repeatable commands: build server/CLI, run tests at several levels,
+lint, format, vendor JS, run dev mode, tag releases. Previously this lived in a
+`Makefile` plus prose instructions for installing tools, which drifts: a
+contributor's locally-installed Go or linter rarely matches CI, and "how do I run
+X" lives outside version control.
+
+We want one declarative file that both **pins the toolchain** (so every machine
+and CI run uses identical versions) and **defines the tasks**, replacing the
+"install these tools yourself + Makefile" split.
+
+## Decision
+
+We will use [`mise`](https://mise.jdx.dev/) as the single entry point for both
+the toolchain and project tasks, configured in `mise.toml`.
+
+- `[tools]` pins exact versions of Go, golangci-lint, Deno, GoReleaser, and Air;
+  `mise install` provisions them and `mise up` bumps them.
+- `[env]` holds shared variables, including the pinned frontend dependency
+  versions consumed by the `vendor-js` task.
+- `[tasks.*]` defines every project command (`build`, `test`, `test-e2e`,
+  `lint`, `fmt-frontend`, `run`, `dev`, `vendor-js`, `tag`, …) with `depends`,
+  `sources`/`outputs` for incremental runs, and `usage` for arguments.
+
+CI and contributors invoke work through `mise run <task>` rather than ad-hoc
+commands or a Makefile.
+
+## Consequences
+
+- Local and CI environments use byte-identical tool versions; "works on my
+  machine" toolchain drift largely disappears.
+- Onboarding is `mise install` followed by `mise run <task>`; the task list is
+  self-documenting via each task's `description`.
+- Tasks and tool versions live in one version-controlled file, reviewed like any
+  other change.
+- `sources`/`outputs` give make-style incremental builds without a Makefile.
+- Trade-off: contributors must install `mise` first, and we depend on a
+  relatively young tool. We judge the reproducibility win worth it, and tasks
+  remain plain shell that could be lifted out if needed.
diff --git a/docs/adr/0006-dependency-injection-with-fx.md b/docs/adr/0006-dependency-injection-with-fx.md
new file mode 100644
index 0000000..04daae1
--- /dev/null
+++ b/docs/adr/0006-dependency-injection-with-fx.md
@@ -0,0 +1,44 @@
+# 0006. Dependency injection with uber/fx
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar is composed of many cooperating subsystems — the Lua runner, the engine,
+the API layer, housekeeping, and a set of built-in services (KV, logger, env,
+HTTP, AI, email). These have a non-trivial dependency graph and a real lifecycle:
+the database must open before services that use it, the HTTP server must start
+after handlers are registered, and everything must shut down in the right order.
+
+Wiring this by hand in `cmd` means a large, brittle constructor-call sequence
+where ordering is implicit and adding a dependency ripples through the call
+chain. We wanted construction and lifecycle to be declared locally by each
+subsystem rather than centralised and manually ordered.
+
+## Decision
+
+We will use [`uber/fx`](https://github.com/uber-go/fx) as the dependency
+injection and lifecycle framework. Each subsystem exposes an `fx.Module` (e.g.
+`internal/api/module.go`, `internal/runner/module.go`, the `internal/services/*`
+modules) that provides its own constructors and registers any
+`fx.Lifecycle` start/stop hooks. `cmd/app.go` assembles the application by
+composing these modules in `fx.New`.
+
+Configuration is provided into the graph as the `config.Config` value (see
+[ADR-0002](0002-configuration-via-environment-variables.md)), so modules depend
+on settings by type rather than reaching for globals.
+
+## Consequences
+
+- Each subsystem owns its construction and lifecycle locally; `cmd` just lists
+  the modules to include.
+- Start/stop ordering is derived from the dependency graph instead of maintained
+  by hand, which removes a common class of shutdown bugs.
+- Adding a dependency is "ask for it in a constructor signature" rather than
+  threading it through intermediate calls.
+- Trade-off: `fx` introduces runtime (rather than compile-time) wiring, a graph
+  that's resolved via reflection, and a learning curve for contributors new to
+  it. For an application of this size with real lifecycle needs we judge the
+  structure worth the indirection. This decision was implemented in commit
+  `fc1c3e8` ("build the dependency graph with uber/fx").
diff --git a/docs/adr/0007-single-binary-embedded-frontend.md b/docs/adr/0007-single-binary-embedded-frontend.md
new file mode 100644
index 0000000..702e9a2
--- /dev/null
+++ b/docs/adr/0007-single-binary-embedded-frontend.md
@@ -0,0 +1,41 @@
+# 0007. Single binary with embedded frontend
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar's value proposition includes being lightweight and self-hosted: "single
+binary, no external dependencies". A FaaS dashboard, though, is made of static
+assets — HTML, CSS, JS, the Monaco editor, vendored libraries. If those assets
+ship separately from the binary, operators must deploy and path-configure a web
+root, versions can skew between binary and assets, and "just run the binary"
+stops being true.
+
+We need the compiled server and its frontend to be one indivisible artifact.
+
+## Decision
+
+We will embed the entire frontend into the Go binary using `go:embed`. The
+`frontend` package embeds `css`, `js`, `vendor`, `index.html`, and `llms.txt`
+into an `embed.FS` and exposes a `Handler()` that serves them via
+`http.FileServer`.
+
+This is the constraint that drives the buildless, vendored frontend: because the
+embedded files must be the literal files we ship, there can be no bundler output
+step (see [ADR-0003](0003-frontend-with-mithril.md) and
+[ADR-0004](0004-no-nodejs-vendored-js.md)). Combined with pure-Go SQLite (see
+[ADR-0008](0008-sqlite-as-the-datastore.md)), the result is a CGo-free,
+dependency-free single binary, released via GoReleaser.
+
+## Consequences
+
+- Deployment is copying one binary; there is no asset directory to manage and no
+  binary/frontend version skew.
+- The frontend is served straight from memory with no filesystem layout
+  assumptions.
+- Builds are reproducible and the release artifact is self-contained.
+- Trade-off: changing a frontend file requires recompiling to embed it for a
+  production build (dev mode via Air rebuilds automatically, so the day-to-day
+  loop is unaffected). The binary also carries the weight of all assets,
+  including Monaco — acceptable for a self-hosted dashboard.
diff --git a/docs/adr/0008-sqlite-as-the-datastore.md b/docs/adr/0008-sqlite-as-the-datastore.md
new file mode 100644
index 0000000..c485879
--- /dev/null
+++ b/docs/adr/0008-sqlite-as-the-datastore.md
@@ -0,0 +1,41 @@
+# 0008. Pure-Go SQLite as the datastore
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar stores functions, versions, execution history, logs, KV data, and related
+state. As a self-hosted, single-binary tool (see
+[ADR-0007](0007-single-binary-embedded-frontend.md)), requiring operators to
+stand up and connect a separate database server (Postgres, MySQL) would
+contradict the "no external dependencies, just run the binary" promise. We need
+durable, transactional, SQL-capable storage that lives in the same process and on
+the local filesystem.
+
+The classic embedded choice is SQLite, but the most common Go driver
+(`mattn/go-sqlite3`) requires CGo. CGo complicates cross-compilation, slows
+builds, and undercuts the goal of a clean, portable single binary.
+
+## Decision
+
+We will use SQLite as the datastore, via the **pure-Go**
+[`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite) driver — no CGo.
+The database is a file under the configured `DATA_DIR`, and we run it in
+**WAL** mode for better read/write concurrency under the server's workload.
+
+## Consequences
+
+- Storage is embedded: no database server to provision, secure, or back up
+  separately — backups are file copies.
+- Staying CGo-free keeps cross-compilation simple and builds fast, preserving the
+  portable single-binary story end to end.
+- WAL mode lets readers proceed concurrently with a writer, which suits the
+  dashboard-plus-execution workload. (WAL behaviour was tightened in commit
+  `ba3e33a`.)
+- Trade-off: SQLite is single-writer and local to one host, so this design does
+  not target multi-node horizontal scaling. That is consistent with Lunar's
+  self-hosted, lightweight positioning; a different topology would warrant a new
+  ADR.
+- The pure-Go driver historically trails the C library slightly on raw
+  performance, which is an acceptable price for portability at this scale.
diff --git a/docs/adr/0009-lua-as-the-function-language.md b/docs/adr/0009-lua-as-the-function-language.md
new file mode 100644
index 0000000..29287dd
--- /dev/null
+++ b/docs/adr/0009-lua-as-the-function-language.md
@@ -0,0 +1,49 @@
+# 0009. Lua as the function language
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar is a Function-as-a-Service platform: users write functions that the server
+executes in response to HTTP triggers. The central design question is what
+language those functions are written in and how they run. Options ranged from
+executing arbitrary binaries/containers (heavy, hard to sandbox, slow cold
+starts) to embedding a scripting language in-process.
+
+For a lightweight, single-binary, self-hosted tool we wanted function execution
+to be in-process, fast to start, easy to sandbox (functions get capabilities only
+through APIs we expose — HTTP client, KV, env, logging, AI, email), and bounded
+by an execution timeout. We also wanted a small, approachable language that
+doesn't require users to manage dependencies.
+
+## Decision
+
+We will use **Lua** as the function authoring language, executed in-process via
+[`yuin/gopher-lua`](https://github.com/yuin/gopher-lua), a pure-Go Lua VM.
+
+Each invocation runs in its own Lua state with only the capabilities Lunar
+injects as built-in APIs, and is bounded by the configurable
+`EXECUTION_TIMEOUT` (see
+[ADR-0002](0002-configuration-via-environment-variables.md)). The function
+subsystems are wired as `fx` modules (see
+[ADR-0006](0006-dependency-injection-with-fx.md)).
+
+We commit to backward compatibility for the Lua APIs while the project is in
+beta, as stated in the README.
+
+## Consequences
+
+- Functions start instantly (no container/process spin-up) and run in the same
+  binary, keeping the platform lightweight.
+- A pure-Go VM preserves the CGo-free, single-binary build (see
+  [ADR-0007](0007-single-binary-embedded-frontend.md) and
+  [ADR-0008](0008-sqlite-as-the-datastore.md)).
+- Sandboxing is capability-based: a function can only do what our injected APIs
+  allow, which keeps the security model explicit.
+- The Lua API surface is a long-lived contract; changes must preserve backward
+  compatibility, which constrains how built-ins evolve.
+- Trade-off: users write Lua specifically rather than bringing an arbitrary
+  language or existing libraries. For Lunar's "simple serverless functions" niche
+  this is a feature, not a limitation; broader language support would be a
+  separate, larger decision.
diff --git a/docs/adr/0010-in-house-i18n.md b/docs/adr/0010-in-house-i18n.md
new file mode 100644
index 0000000..4506780
--- /dev/null
+++ b/docs/adr/0010-in-house-i18n.md
@@ -0,0 +1,54 @@
+# 0010. In-house i18n with locale modules
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+The dashboard ships in more than one language (currently English and Brazilian
+Portuguese) and needs to translate hundreds of UI strings, interpolate values
+("{{count}} functions total"), pick a sensible default from the browser, and
+remember the user's choice. The reflex solution is an off-the-shelf i18n
+library, but the project's constraints push back:
+
+- **No Node.js / no bundler** (see [ADR-0004](0004-no-nodejs-vendored-js.md)), so
+  any library would have to be vendored as a buildless `<script>`/ES module.
+- The need is genuinely small: a flat-ish dictionary, dot-keyed lookup, simple
+  `{{param}}` interpolation, locale persistence, and a fallback chain. A general
+  i18n framework brings pluralisation rules, ICU message syntax, async catalog
+  loading, and other machinery we don't need.
+
+## Decision
+
+We will implement i18n ourselves as a small module under `frontend/js/i18n/`.
+
+- Each locale is a plain ES module default-exporting a nested dictionary
+  (`locales/en.js`, `locales/pt-BR.js`). English is the source of truth.
+- `index.js` exposes an `i18n` object and a `t(key, params)` shorthand.
+  Translation uses **dot-notation keys** (`nav.logout`) resolved against the
+  nested object, with `{{param}}` interpolation.
+- Lookup has a defined fallback chain: current locale → `DEFAULT_LOCALE` (`en`)
+  → the key itself (with a `console.warn`), so a missing translation degrades
+  visibly but never crashes the UI.
+- The active locale is auto-detected from `navigator.language` (with a `pt*` →
+  `pt-BR` heuristic) on first run, persisted in `localStorage`, and triggers
+  `m.redraw()` on change so Mithril re-renders.
+
+Adding a language is: create a `locales/<code>.js`, register it in `index.js`,
+and add its display name to `localeNames`.
+
+## Consequences
+
+- Zero runtime dependency for translation; the i18n layer is a handful of files
+  we fully control and can read end to end.
+- Translations live in version control as plain data modules, reviewable in
+  normal diffs, and editable by translators without tooling.
+- The fallback chain makes missing keys safe and discoverable (warned in the
+  console) rather than fatal.
+- Trade-off: we don't get advanced features like CLDR pluralisation or gender
+  rules. If a future locale needs them we will revisit rather than retrofit them
+  awkwardly. There is also no automated check that locale files are *complete* —
+  the runtime fallback hides gaps — so completeness currently relies on review
+  (a candidate for a small lint task later).
+- The i18n module is covered by the frontend Jasmine suite (see
+  [ADR-0011](0011-testing-strategy.md)).
diff --git a/docs/adr/0011-testing-strategy.md b/docs/adr/0011-testing-strategy.md
new file mode 100644
index 0000000..e0e8938
--- /dev/null
+++ b/docs/adr/0011-testing-strategy.md
@@ -0,0 +1,61 @@
+# 0011. Layered testing strategy without a JS test runner
+
+- Status: Accepted
+- Date: 2026-06-02
+
+## Context
+
+Lunar spans a Go backend, a generated Go CLI (`lunar-cli`), and a buildless
+browser frontend. Each layer needs testing, but the project's constraints shape
+*how*:
+
+- **No Node.js / no bundler** (see [ADR-0004](0004-no-nodejs-vendored-js.md)),
+  so a Node-based frontend test runner (Jest, Vitest) is off the table.
+- The frontend is plain ES modules served as-is, so tests should run them the way
+  the browser does, with no transpile step.
+- Confidence requires more than units: we want to know the real HTTP API works
+  and that the dashboard actually drives that API in a browser.
+
+We need a coherent set of test layers, each runnable through a single `mise`
+task (see [ADR-0005](0005-mise-for-toolchain-and-tasks.md)) and CI-friendly.
+
+## Decision
+
+We will test at four layers, each with a dedicated task:
+
+1. **Go unit tests** (`mise run test`) — standard `go test` across the server and
+   CLI packages, excluding `e2e`. The fast inner loop.
+2. **Frontend tests** with **Jasmine** (`mise run test-frontend`) — specs under
+   `frontend/test/spec/` (per-component, plus `i18n`, `routes`, `utils`) run in a
+   real browser via `SpecRunner.html`. A tiny Go `cmd/testserver` serves the
+   `frontend/` directory on `:8888` and opens the runner; no Node runner is
+   involved. Jasmine itself is vendored (see ADR-0004).
+3. **CLI integration tests** (`mise run test-cli-integration`) — built-tagged
+   (`-tags integration`) tests in `lunar-cli/integration` that exercise the
+   generated client against a real running server.
+4. **End-to-end browser tests** (`mise run test-e2e`) — Go tests under `e2e/`
+   that boot the real API on an `httptest.Server` against a migrated SQLite
+   store and drive **headless Chrome via `chromedp`**, with a small fluent
+   `browserTest` helper. `mise run test-all` runs units + e2e together.
+
+The unifying principle: wherever a runtime is needed, prefer **Go** as the test
+harness (testserver, chromedp, httptest) rather than introducing a second
+language's tooling.
+
+## Consequences
+
+- Every layer runs through one `mise` task, so contributors and CI invoke tests
+  the same way, and the suite needs only the `mise`-managed toolchain (Go, Deno,
+  a Chrome for e2e) — no Node.
+- Frontend specs run the exact ES modules the browser ships, so there's no
+  transpile-vs-runtime skew.
+- e2e tests assemble the real `fx`-wired API and a real (migrated) SQLite
+  database, giving high-fidelity coverage of the API-plus-dashboard path.
+- Trade-offs:
+  - Jasmine specs are browser-driven, so they're not part of the headless
+    `go test ./...` run and are easy to forget in pure-CLI CI; running them
+    requires a browser context. This is the cost of staying Node-free.
+  - e2e tests depend on a Chrome/Chromium being available and use timing
+    (`chromedp.Sleep`) in places, which can be slower and flakier than unit
+    tests — hence they live behind their own task and the `e2e` package is
+    excluded from the default `test` run.
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 0000000..4e0eb1a
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,31 @@
+# Architecture Decision Records
+
+This directory records the significant architectural decisions made on Lunar,
+using lightweight [ADRs](https://adr.github.io/). Each record captures the
+context in force at the time, the decision taken, and its consequences — so a
+future reader can understand *why* the code looks the way it does without having
+to reverse-engineer it or interrupt the people who were there.
+
+## Conventions
+
+- One decision per file, named `NNNN-kebab-case-title.md`, numbered in order.
+- Records are immutable once `Accepted`. We don't rewrite history: to change a
+  past decision, add a new ADR and set the old one's status to `Superseded by
+  ADR-NNNN`.
+- Start from [`0000-template.md`](0000-template.md).
+
+## Index
+
+| ADR | Title | Status |
+| --- | --- | --- |
+| [0001](0001-record-architecture-decisions.md) | Record architecture decisions | Accepted |
+| [0002](0002-configuration-via-environment-variables.md) | Configuration via environment variables | Accepted |
+| [0003](0003-frontend-with-mithril.md) | Frontend with Mithril.js | Accepted |
+| [0004](0004-no-nodejs-vendored-js.md) | No Node.js: vendored JS, Deno for tooling | Accepted |
+| [0005](0005-mise-for-toolchain-and-tasks.md) | mise for toolchain and task management | Accepted |
+| [0006](0006-dependency-injection-with-fx.md) | Dependency injection with uber/fx | Accepted |
+| [0007](0007-single-binary-embedded-frontend.md) | Single binary with embedded frontend | Accepted |
+| [0008](0008-sqlite-as-the-datastore.md) | Pure-Go SQLite as the datastore | Accepted |
+| [0009](0009-lua-as-the-function-language.md) | Lua as the function language | Accepted |
+| [0010](0010-in-house-i18n.md) | In-house i18n with locale modules | Accepted |
+| [0011](0011-testing-strategy.md) | Layered testing strategy without a JS test runner | Accepted |