Skip to content

Structure

Where things live and where to put new code. For system shape, data flow, and invariants, see ARCHITECTURE.md. For per-app operational detail, see each apps/<name>/AGENTS.md and packages/cli/AGENTS.md.

├── apps/ Deployable units (one self-contained deploy each; apps/agent is provisioning-only, no deploy)
│ ├── keeweb/ KeeWeb static-site deploy (SSH/rsync to Mail-in-a-Box)
│ ├── cliproxy/ CLIProxyAPI Claude proxy (DigitalOcean + Docker Compose)
│ ├── gateway/ Fro Bot Discord gateway (DigitalOcean + Docker Compose)
│ ├── umami/ Umami analytics (DigitalOcean + Docker Compose)
│ ├── dashboard/ Fro Bot monitoring dashboard (DigitalOcean + Docker Compose)
│ ├── vpn/ WireGuard egress box (AWS Lightsail eu-west-1, native wg-quick@wg0)
│ ├── broker/ OIDC credential broker (DigitalOcean + Docker Compose)
│ └── agent/ Operator-run AWS provisioner for fro-bot/agent S3 durable storage (no deploy step)
├── packages/ Reusable libraries (never import from apps/)
│ ├── cli/ @marcusrbrown/infra goke CLI + MCP bridge + VPN peer model + repo-local workflow scripts
│ └── shared/ Cross-app SSH/SCP/provisioning helpers
├── docs/ Brainstorms → plans → solutions (compound learning)
├── .agents/skills/ Agent skill context packets (load before working in a domain)
├── .github/ Workflows, pinned host keys, Renovate, Copilot, repo settings
└── .opencode/commands/ OpenCode slash commands

One subdirectory per deployable. Each app owns its Compose/build config (or native systemd config for VPN), a TypeScript deploy script (src/deploy.ts; KeeWeb uses src/build.ts + deploy.sh), a provisioning script (except keeweb — server/provision-droplet.ts for the DigitalOcean Docker apps including dashboard and broker, server/provision.ts for the @aws-sdk/client-lightsail VPN box), a deploy-side host validator (src/host.ts where the deploy spawns SSH), and an AGENTS.md runbook. Apps never share code by importing each other — shared logic lives in packages/shared, and the VPN peer model is published from packages/cli. apps/agent is the non-deployable exception: a private: true operator-run AWS provisioner with no src/deploy.ts, no src/host.ts, and no deploy workflow — just server/provision.ts (IAM + S3 convergence) and src/key-layout.ts (S3 key layout the Action uses).

Reusable libraries. packages/cli is the operator surface (goke command groups, unified status, MCP bridge) and also owns the VPN peer model (packages/cli/src/commands/vpn/peers.ts, published as @marcusrbrown/infra/vpn/peers and imported by apps/vpn). packages/shared is the provisioning helper library consumed by every app’s provision script, plus packages/shared/cliproxy/management.ts — CLIProxyAPI management-API primitives (managementHeaders, requestJson, parseManagementKeyList, OAuth model-alias helpers) consumed directly by apps/cliproxy/src/deploy.ts, apps/broker/src/mint.ts, and packages/cli/src/commands/cliproxy/*.ts. packages/ never imports from apps/; the published @marcusrbrown/infra (cli) stays self-contained and must not depend on the private packages/shared. packages/cli/scripts/ holds the package build entry (build.ts, run by bun run build / prepack) plus repo-local operational workflow scripts that are never part of the published package — reconcile-autoheal-reports.ts, invoked only by the daily-equivalent branch of .github/workflows/fro-bot.yaml, prune-untagged-packages.ts, invoked only by the manual dispatch of .github/workflows/prune-packages.yaml, and deploy-gate-notify.ts, invoked only by the notify jobs of .github/workflows/deploy-<app>.yaml.

CI/CD and automation: workflows/*.yaml (deploy router + per-app deploys, CI, release + release-alert, Fro Bot, Renovate + renovate-changesets, CodeQL, Scorecard, settings sync, manual GHCR pruning), known_hosts (pinned SSH host keys), renovate.json5, settings.yml, copilot-instructions.md.

Compound-learning chain: brainstorms/ (requirements), plans/ (implementation plans), solutions/ (documented fixes/best-practices with YAML frontmatter). Plan-taxonomy lives here and only here — never in shipped source or public docs.

Per-domain agent context packets (<name>/SKILL.md). Load the relevant skill before working in that domain.

OpenCode slash commands (Markdown). The generating-project-docs skill (.agents/skills/generating-project-docs/SKILL.md) owns all generated docs — ARCHITECTURE.md, STRUCTURE.md, the root README.md, and per-package READMEs. Slash commands here are for other OpenCode workflows.

Entry Points

File Role
packages/cli/src/cli.ts goke CLI entry; registers all command groups
apps/<name>/src/deploy.ts App deploy script (main/deploy)
apps/keeweb/src/build.ts KeeWeb build (download + SHA-256 verify + config inject)
apps/keeweb/deploy.sh SSH/rsync deploy (Bash)
apps/umami/retention.sh Host-native systemd retention runner (Bash)

Per-App Deploy / Provision

File Role
apps/<name>/server/provision-droplet.ts DigitalOcean droplet provisioning (cliproxy, gateway, umami, dashboard, broker)
apps/vpn/server/provision.ts Lightsail provisioning (@aws-sdk/client-lightsail)
apps/agent/server/provision.ts Operator-run AWS IAM + S3 convergence for fro-bot/agent durable storage; no deploy step
apps/agent/src/key-layout.ts S3 session/coordination-lock key layout the Action uses, independent of the Action version
apps/<name>/src/host.ts Deploy-side host validator (rejects --prefixed / invalid hosts)
apps/gateway/upstream.json Pinned fro-bot/agent daemon ref
apps/dashboard/docker-compose.yaml Digest-pinned ghcr.io/fro-bot/dashboard image (tag@sha256 in the image: line; Renovate tracks bumps)
packages/cli/src/commands/vpn/peers.ts VPN peer model: readPeers, writePeers, parsePeersJson, renderServerConfig, Peer (exported as @marcusrbrown/infra/vpn/peers)
packages/shared/cliproxy/management.ts CLIProxyAPI management-API helpers (managementHeaders, requestJson, HTTP_TIMEOUT_MS, parseManagementKeyList, OAuth model-alias helpers); shared by apps/cliproxy, apps/broker, and packages/cli cliproxy commands

CLI Commands

File Role
packages/cli/src/commands/<app>/<action>.ts Per-app subcommand (status, deploy, …)
packages/cli/src/commands/<app>/index.ts Command-group barrel (register<App>Commands)
packages/cli/src/commands/status.ts Unified cross-app status dashboard
packages/cli/src/commands/mcp.ts MCP stdio bridge + MCP_ALLOWLIST
packages/cli/src/lib/action-ctx.ts ActionCtx — MCP-capturable action context
packages/shared/server/droplet-helpers.ts Shared SSH/SCP/DigitalOcean helpers (also used by VPN deploy)

Config

File Role
package.json Workspaces, root provision:* / deploy:* / test / lint scripts
eslint.config.ts ESLint via @bfra.me/eslint-config
tsconfig.json TypeScript via @bfra.me/tsconfig
.github/renovate.json5 Renovate config (incl. apps/*/upstream.json custom manager)

Workflow Scripts

File Role
packages/cli/scripts/reconcile-autoheal-reports.ts Repo-local daily report reconciler; invoked only by the fro-bot-storage job, never published
packages/cli/scripts/reconcile-autoheal-reports.test.ts Colocated behavior tests (fake fetch boundary, pagination, readback, fail-closed paths)
packages/cli/scripts/prune-untagged-packages.ts Repo-local GHCR untagged-version pruner; dry-run unless --apply, invoked only by prune-packages.yaml, never published
packages/cli/scripts/prune-untagged-packages.test.ts Colocated behavior tests (fake fetch boundary, pagination, manifest-child gates, abort codes)
packages/cli/scripts/deploy-gate-notify.ts Repo-local deploy-gate Discord notifier; zero-dependency, always exits 0, invoked only by the notify job of each deploy-<app>.yaml, never published
packages/cli/scripts/deploy-gate-notify.test.ts Colocated behavior tests (fake fetch boundary, message rendering, retry and failure paths)
packages/cli/scripts/build.ts CLI bundle build (public deps external, @marcusrbrown/infra-shared inlined, known_hosts asset)

Tests / CI

File Role
**/*.test.ts Colocated tests (mock at boundaries: fetch, Bun.spawn)
packages/cli/src/conventions.test.ts Executable convention enforcement
.github/workflows/deploy.yaml Deploy router (paths-filter → per-app deploy)
.github/workflows/deploy-<app>.yaml Gated per-app deploy
  • Scripts: TypeScript run via bun run. Exactly two approved Bash scripts: apps/keeweb/deploy.sh and apps/umami/retention.sh (allowlisted in packages/cli/src/conventions.test.ts).
  • Tests: colocated *.test.ts beside source. Fixtures in __fixtures__/, snapshots in __snapshots__/. Use NO_COLOR=1 for deterministic subprocess snapshots.
  • CLI command modules: packages/cli/src/commands/<app>/<action>.ts (e.g. status.ts, deploy.ts) + a barrel index.ts exporting register<App>Commands.
  • Host validators: host.ts (deploy-side under apps/<name>/src/, CLI-side under packages/cli/src/commands/<app>/).
  • Workflows: .yaml extension (not .yml); deploy workflows deploy-<app>.yaml.
  • Bun script guards: scripts exporting functions for tests gate top-level execution with if (import.meta.main).
  • Repo-local workflow scripts: live under packages/cli/scripts/ beside a colocated *.test.ts (e.g. reconcile-autoheal-reports.ts, deploy-gate-notify.ts); they are excluded from packages/cli/package.json files and exports and from the build entrypoint, and are invoked only by their owning workflow.

Mechanical layout; for the integration rationale see ARCHITECTURE.md.

  • New app → apps/<name>/ mirroring apps/cliproxy/ (Docker Compose on DigitalOcean) or apps/vpn/ (native systemd on AWS Lightsail): Compose config or deploy script, src/deploy.ts, server/provision.ts (new apps use provision.ts; existing DigitalOcean apps keep provision-droplet.ts), src/host.ts, AGENTS.md. Add to package.json workspaces + provision:<name>/deploy:<name> scripts; run bun install to refresh bun.lock.
  • New operator-only tool (no deploy) → mirror apps/agent/: private: true, server/provision.ts only — no src/deploy.ts, src/host.ts, deploy workflow, or GitHub Environment. Add provision:<name> to root package.json scripts.
  • New repo-local workflow script → packages/cli/scripts/<name>.ts + colocated test; keep it out of packages/cli/package.json files/exports and the CLI registration, and invoke it only from its owning workflow.
  • New CLI command → packages/cli/src/commands/<app>/<action>.ts + colocated test; export it from the group’s index.ts barrel.
  • New shared helper → packages/shared/server/droplet-helpers.ts + colocated test (or packages/shared/cliproxy/management.ts for CLIProxyAPI management-API helpers).
  • New test → colocate *.test.ts beside the source; fixtures/snapshots in __fixtures__//__snapshots__/.
  • New workflow → .github/workflows/<name>.yaml, SHA-pinned actions with # vX.Y.Z; for a deploy, copy a deploy-<app>.yaml and wire it into deploy.yaml’s paths-filter.
  • New docs page → docs/<brainstorms|plans|solutions>/; solutions carry YAML frontmatter.