Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (61 loc) · 2.31 KB

AGENTS.md

File metadata and controls

81 lines (61 loc) · 2.31 KB
Raw

AGENTS.md

Guidelines for AI agents and collaborators working on BackupForge.

BackupForge is a self-hosted monorepo for managing Convex backups with a Go backend, short-lived Docker runners, SQLite, S3/MinIO storage, and a TanStack Start frontend.

Repository Layout

apps/backend   Go API server, backup runner, migrations, Docker files, scripts
apps/frontend  TanStack Start app, React UI, API client, tests

Folder-specific rules live in:

  • apps/backend/AGENTS.md
  • apps/frontend/AGENTS.md

When editing inside an app, follow the local file first, then this root file.

Current Stack

  • Backend: Go, chi, GORM, SQLite, Docker SDK, S3-compatible storage, SSE.
  • Frontend: TanStack Start, React, TypeScript, TanStack Query, Tailwind CSS, Biome, Vitest.
  • JavaScript package manager: pnpm only.

Common Commands

From the repository root:

pnpm run frontend:dev
pnpm run frontend:build
pnpm run frontend:test
pnpm run frontend:check
pnpm run backend:dev
pnpm run backend:server
pnpm run backend:test
pnpm run backend:build

Backend helpers:

cd apps/backend
pnpm run minio
pnpm run compose
go test ./...

Frontend helpers:

cd apps/frontend
pnpm run dev
pnpm run build
pnpm run test
pnpm run check

Monorepo Rules

  • Keep one Node lockfile at the root: pnpm-lock.yaml.
  • Do not mix frontend code into apps/backend or Go code into apps/frontend.
  • Document new environment variables in the relevant app README or .env.example.
  • If an API contract changes, update backend and frontend code in the same change.
  • Do not commit node_modules, local SQLite databases, binaries, backup artifacts, build output, or secrets.
  • Prefer root scripts as wrappers; each app remains the source of truth for its own commands.

Product And Security Rules

  • Keep BackupForge self-hosted.
  • SQLite is the backend source of truth. Do not introduce PostgreSQL unless explicitly requested.
  • Do not use Convex as this app's backend.
  • Do not switch to Kubernetes unless explicitly requested.
  • Do not add endpoints that execute arbitrary shell commands.
  • Do not allow arbitrary Docker images from the UI.
  • Do not mount /var/run/docker.sock in runners.
  • Do not run privileged containers.
  • Do not log secrets or return complete secrets to the frontend.
  • Do not store permanent signed download URLs.