​

Add a New Standalone App

⚠️ This is the INFRA-MECHANICS appendix, not the full process. The canonical onboarding SOP — infrastructure and citizenship (spine, registry, governance, staffing, Definition of Done) — is app-onboarding.md. Start there. Known-stale: several workflows referenced below (create-hyperdrive.yml, scaffold-*.yml, setup-*-secrets.yml) no longer exist; use the scripts in packages/deploy/scripts/ directly. Librarian #1975 owns the refresh.

​

Rate Limiter ID Registry

⚠️ Rate-limit bindings go under wrangler unsafe.bindings with type: "ratelimit" — the top-level rate_limiters key is silently dropped (“unexpected field”) and binds nothing (the-calling#43).

​

Prerequisites

• Neon project created for this app
• Connection string stored as a GitHub Secret in Latimer-Woods-Tech/factory: {APP_UPPER}_CONNECTION_STRING
  • Example: app xico-city → secret MEXXICO_CITY_CONNECTION_STRING
• CF_API_TOKEN set in Factory GitHub Secrets
• GH_PAT (classic PAT with repo + read:packages) set in Factory GitHub Secrets
• GitHub repo created: gh repo create Latimer-Woods-Tech/{app} --private

​

Step 1 — Add App to Factory Scripts

​

1a. create-hyperdrive.mjs

{ envKey: '{APP_UPPER}_ID', name: '{app}-db', conn: process.env.{APP_UPPER}_CONN },

​

1b. write-schema.mjs

​

1c. add-app-deps.mjs

'{app}': ['@latimer-woods-tech/stripe'],  // only extras needed

​

Step 2 — Update create-hyperdrive.yml

1. Env var in the Create Hyperdrive instances step:
   {APP_UPPER}_CONN: ${{ secrets.{APP_UPPER}_CONNECTION_STRING }}
   
2. Store step (even though it will fail with 403 — the log still captures the UUID):
   store HYPERDRIVE_{APP_UPPER} "${{ steps.hyperdrive.outputs.{APP_UPPER}_ID }}"
   

​

Step 3 — Create Standalone Workflow Files

​

scaffold-{app}.yml

• Set the correct rate limiter ID (from the registry above)
• Leave --hyperdrive-id as a placeholder ("REPLACE_AFTER_STEP_4") until Step 4

​

setup-{app}-secrets.yml

• The JWT secret references JWT_SECRET_{APP_UPPER} — add this to Factory GitHub Secrets before running
• The Sentry DSN references SENTRY_DSN_{APP_UPPER} — add this to Factory GitHub Secrets before running

​

Step 4 — Commit, Push, Create Hyperdrive

git add packages/deploy/scripts/create-hyperdrive.mjs \
        packages/deploy/scripts/write-schema.mjs \
        packages/deploy/scripts/add-app-deps.mjs \
        .github/workflows/create-hyperdrive.yml \
        .github/workflows/scaffold-{app}.yml \
        .github/workflows/setup-{app}-secrets.yml
git commit -m "feat(deploy): add {app} \u2014 hyperdrive, schema, workflows"

$token = gh auth token
$encoded = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("x-access-token:$token"))
git -c credential.helper="" -c "http.extraheader=Authorization: Basic $encoded" push origin main

gh workflow run create-hyperdrive.yml --repo Latimer-Woods-Tech/factory

​

Step 5 — Extract Hyperdrive UUID from Logs

RUN_ID=$(gh run list --repo Latimer-Woods-Tech/factory --workflow create-hyperdrive.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run view $RUN_ID --repo Latimer-Woods-Tech/factory --log | grep "{app}-db ->"
# Output: [created] {app}-db -> <UUID>

1. Hard-code the UUID in scaffold-{app}.yml
2. Store it as a Factory secret:
   echo "<UUID>" | gh secret set HYPERDRIVE_{APP_UPPER} --repo Latimer-Woods-Tech/factory
   
3. Commit and push the updated scaffold workflow

​

Step 6 — Add Required Secrets to Factory

openssl rand -base64 32 | gh secret set JWT_SECRET_{APP_UPPER} --repo Latimer-Woods-Tech/factory

​

Step 7 — Run Scaffold and Secrets Workflows

# 1. Scaffold the app repo
gh workflow run scaffold-{app}.yml --repo Latimer-Woods-Tech/factory

# Wait for completion
gh run watch $(gh run list --repo Latimer-Woods-Tech/factory --workflow scaffold-{app}.yml --limit 1 --json databaseId --jq '.[0].databaseId') --repo Latimer-Woods-Tech/factory --exit-status

# 2. Verify scaffold succeeded
gh api repos/Latimer-Woods-Tech/{app}/contents/src/index.ts --jq '.name'
# Expected: "index.ts"

# 3. Wire secrets to the app repo and Worker
gh workflow run setup-{app}-secrets.yml --repo Latimer-Woods-Tech/factory

​

Step 8 — Update This Registry

​

Checklist Summary

• Rate limiter ID reserved (next available: 1012+)
• Neon connection string in Factory Secrets as {APP_UPPER}_CONNECTION_STRING
• GitHub repo created: Latimer-Woods-Tech/{app}
• create-hyperdrive.mjs updated
• write-schema.mjs updated with canonical Drizzle schema
• add-app-deps.mjs updated with app-specific package deps
• create-hyperdrive.yml updated with new env var + store step
• scaffold-{app}.yml created
• setup-{app}-secrets.yml created
• All changes committed and pushed
• create-hyperdrive.yml workflow triggered; UUID extracted from logs
• UUID hard-coded in scaffold workflow + stored as HYPERDRIVE_{APP_UPPER} secret
• JWT_SECRET_{APP_UPPER} added to Factory Secrets
• SENTRY_DSN_{APP_UPPER} added to Factory Secrets
• scaffold-{app}.yml workflow run successfully
• setup-{app}-secrets.yml workflow run successfully
• Rate limiter registry table updated in this file
• Update github-secrets-and-tokens.md to include new app in the app list
• Create .github/repo-contexts/{app}/CLAUDE.md with the repo’s standing orders (stack, hard constraints, surfaces, commit format). The CI validate job will fail until this file exists — see coh or humandesign for examples.