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.
Directory Layout
Section titled “Directory Layout”├── 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 commandsDirectory Purposes
Section titled “Directory Purposes”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).
packages/
Section titled “packages/”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.
.github/
Section titled “.github/”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.
.agents/skills/
Section titled “.agents/skills/”Per-domain agent context packets (<name>/SKILL.md). Load the relevant skill before working in that domain.
.opencode/commands/
Section titled “.opencode/commands/”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.
Key File Locations
Section titled “Key File Locations”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 |
Naming Conventions
Section titled “Naming Conventions”- Scripts: TypeScript run via
bun run. Exactly two approved Bash scripts:apps/keeweb/deploy.shandapps/umami/retention.sh(allowlisted inpackages/cli/src/conventions.test.ts). - Tests: colocated
*.test.tsbeside source. Fixtures in__fixtures__/, snapshots in__snapshots__/. UseNO_COLOR=1for deterministic subprocess snapshots. - CLI command modules:
packages/cli/src/commands/<app>/<action>.ts(e.g.status.ts,deploy.ts) + a barrelindex.tsexportingregister<App>Commands. - Host validators:
host.ts(deploy-side underapps/<name>/src/, CLI-side underpackages/cli/src/commands/<app>/). - Workflows:
.yamlextension (not.yml); deploy workflowsdeploy-<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 frompackages/cli/package.jsonfilesandexportsand from the build entrypoint, and are invoked only by their owning workflow.
Where to Add New Code
Section titled “Where to Add New Code”Mechanical layout; for the integration rationale see ARCHITECTURE.md.
- New app →
apps/<name>/mirroringapps/cliproxy/(Docker Compose on DigitalOcean) orapps/vpn/(native systemd on AWS Lightsail): Compose config or deploy script,src/deploy.ts,server/provision.ts(new apps useprovision.ts; existing DigitalOcean apps keepprovision-droplet.ts),src/host.ts,AGENTS.md. Add topackage.jsonworkspaces+provision:<name>/deploy:<name>scripts; runbun installto refreshbun.lock. - New operator-only tool (no deploy) → mirror
apps/agent/:private: true,server/provision.tsonly — nosrc/deploy.ts,src/host.ts, deploy workflow, or GitHub Environment. Addprovision:<name>to rootpackage.jsonscripts. - New repo-local workflow script →
packages/cli/scripts/<name>.ts+ colocated test; keep it out ofpackages/cli/package.jsonfiles/exportsand 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’sindex.tsbarrel. - New shared helper →
packages/shared/server/droplet-helpers.ts+ colocated test (orpackages/shared/cliproxy/management.tsfor CLIProxyAPI management-API helpers). - New test → colocate
*.test.tsbeside the source; fixtures/snapshots in__fixtures__//__snapshots__/. - New workflow →
.github/workflows/<name>.yaml, SHA-pinned actions with# vX.Y.Z; for a deploy, copy adeploy-<app>.yamland wire it intodeploy.yaml’s paths-filter. - New docs page →
docs/<brainstorms|plans|solutions>/; solutions carry YAML frontmatter.