Skip to content

0013: Go monorepo with a shared core and native shells

  • Status: accepted
  • Date: 2026-09-22

Context

Targets: macOS, Windows and Linux CLI/TUI/agent installed through brew, chocolatey, scoop, winget, apt, nix and npm; desktop GUIs; native iOS and Android apps that approve requests, hold hardware-backed keys and browse vaults; a hosted relay and sync service. run wraps every developer command, so startup latency matters.

Decision

  • Language: Go. One static binary per platform for cli, tui and agent; trivial cross-compilation; Bubble Tea for the TUI; gomobile produces an .xcframework and .aar from the core; the tailscaled LocalAPI is reachable without embedding a node.
  • Layout (single repository, Go workspace):
    • core/: crypto, format, events, fold, policy, storage interface and backends. No UI, no I/O beyond the storage interface. This is the module exported to mobile.
    • cmd/vaultfold/: CLI, TUI and agent daemon in one binary; MCP server; harness hooks.
    • desktop/: Wails application over the core.
    • ios/, android/: thin native shells (SwiftUI, Jetpack Compose) over the gomobile core; platform code limited to key stores, biometrics, QR, URL scheme and push.
    • cloud/: hosted service: relay, sync, share blob store, accounts and billing.
    • web/: marketing site and documentation (Astro + Starlight, static).
    • openspec/, docs/adr/, docs/threat-model.md: specifications and records.
  • Distribution: GoReleaser for brew, scoop, winget, apt/rpm, nix; an npm wrapper package with per-platform optionalDependencies (the esbuild pattern), no postinstall download.
  • Format independence: the on-disk format is specified in openspec/specs/ with test vectors, independently of the Go implementation, so that other implementations can exist.
  • Secrets are never accepted as command-line arguments; values are prompted for or read from stdin or the out-of-band form.

Consequences

  • Cryptography is written once and audited once.
  • Two mobile UI codebases, each small.
  • The npm package is a thin shim; Node is not a runtime dependency.

Alternatives considered

  • Rust with Tauri v2 (desktop and mobile) and UniFFI. Viable; rejected for build speed and the tailscaled and gomobile precedents (WireGuard, Tailscale apps).
  • TypeScript with Electron. Rejected: startup latency on every run, native crypto module friction on Windows, large desktop binaries.
  • Flutter or React Native for mobile. Rejected: the core still has to be linked, and Secure Enclave operations would depend on third-party plugins.