Factory Zero · VENTURE BACKEND TEMPLATE

---

The template

Every Factory Zero venture gets its own backend: its own Worker, its own database, its own secrets, its own domain. This repository is the starting point. Click Use this template, edit one file, and the rest is wiring.

One file to edit. src/harness.rs names the venture, lists the modules, and picks the adapters. Everything else in the repo is the same for every venture and is kept current by the harness.

Built on the Cratefield harness (Rust, workers-rs, axum).

What you get

Cargo.toml               depends on cratefield-core, the runtime, and the modules you want
src/harness.rs           Harness::builder() composition for this venture   ← edit this
src/lib.rs               #[event(fetch)] / #[event(scheduled)] delegating to the harness
tests/harness_builds.rs  asserts Harness::build() is Ok; a bad config fails `cargo test`
wrangler.toml            staging + production envs, D1, rate limit, custom domain, worker-build
migrations/              generated by `fz migrations collect`, committed, never renumbered
justfile                 dev · check · migrate-staging · migrate-prod
smoke.sh                 health, ready, and a signup against a deployed URL
.github/workflows/
  ci.yml                 fmt · clippy · test · fz doctor · worker-build --release
  deploy.yml             main → staging automatically; tag v* → production behind an approval gate
  health.yml             weekly canary against the latest harness crates

New venture checklist

1. Use this template. Name the repo <venture>-backend.
2. Edit src/harness.rs: venture name, domain, CORS origins, modules.
3. Databases. wrangler d1 create <venture>-api-staging and <venture>-api; paste the ids into wrangler.toml.
4. Migrations. just migrate-staging runs fz migrations collect and wrangler d1 migrations apply.
5. Secrets per environment. HARNESS_SECRET, RESEND_API_KEY, TURNSTILE_SECRET, ADMIN_TOKEN, set with wrangler secret put.
6. Mail domain. Verify send.<domain> in Resend. The subdomain, never the apex, which carries inbound mail.
7. Custom domain. api.<domain> in the production routes of wrangler.toml.
8. Ship. Push to main for staging. Tag v0.1.0 for production.

Steps 3, 5, 6 and 7 need a human with dashboard access. Everything else runs in CI.

Local development

just dev        # wrangler dev with a local D1
just check      # fmt, clippy -D warnings, test, fz doctor, worker-build

Requires stable Rust with the wasm32-unknown-unknown target, worker-build, and wrangler.

CI/CD

Two GitHub Actions workflows live in .github/workflows/:

• ci.yml — runs on every pull request. cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, cargo test, cargo run --bin fz -- doctor, then installs and runs worker-build --release to make sure the Worker actually builds for wasm32. It never runs on main or on tags — deploys are deploy.yml's job.
• deploy.yml — runs on push. A push to main deploys to staging automatically. Pushing a v* tag deploys to production, gated behind a required reviewer (see below). Both jobs apply pending D1 migrations with wrangler d1 migrations apply DB --env <env> --remote, deploy with wrangler deploy --env <env> --var HARNESS_BUILD:<git-sha>, then run smoke.sh against the deployed URL, which checks /__health, /__ready and a waitlist signup, and fails the job on any unexpected status.

Cloudflare API token. Create a scoped token (not your global API key) with exactly these permissions:

• Account → Workers Scripts → Edit
• Account → D1 → Edit
• Zone → Workers Routes → Edit

Repo configuration (one-time, by a human). In Settings → Environments, create a staging and a production environment. Add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID as secrets on each. On production, add a required reviewer so tagged deploys wait for approval — this protection rule can't be expressed in the workflow YAML, it's configured on the Environment itself.

Runtime secrets (HARNESS_SECRET, RESEND_API_KEY, TURNSTILE_SECRET, ADMIN_TOKEN, ...) are never set from Actions. Set them once by hand with wrangler secret put <NAME> --env production (and --env staging for the staging equivalents).

Status

Template scaffolding is tracked in the issues. It depends on the harness reaching milestone M2, when the crates are on crates.io.

License

MIT.