Development
Development guide
Understand the monorepo, local development, tests, migrations, and contribution rules.
Repository structure
The structure below is derived from package manifests, Nuxt and Cloudflare entrypoints, Worker bindings, route imports, and test directories in the current repository. Contribution documents remain useful for policy, but they are not the source for this architecture map.
| Path | Role |
|---|---|
| package.json · pnpm-workspace.yaml | Monorepo scripts and the four workspace package groups |
| siliconbeest/app.vue · pages/ | Nuxt 4 application shell and filesystem route entrypoints |
| siliconbeest/src/ | Vue views, stores, composables, API clients, localization, and Deck/Aurora/classic UI surfaces |
| siliconbeest/server/index.ts | Unified request router for the Hono API, ActivityPub, Nuxt SSR, static assets, and crawler metadata |
| siliconbeest/server/worker/ | Hono endpoints, OAuth, authentication, Fedify dispatchers and inbox processors, services, repositories, middleware, and StreamingDO |
| siliconbeest/migrations/ · test/ | Sequential D1 migrations plus separate Vue and Worker test suites |
| siliconbeest-queue-consumer/ | Federation and internal queue consumers, DLQ parking, timeline fan-out, media, notifications, Web Push, and remote fetches |
| siliconbeest-email-sender/ | Email queue consumption and SMTP delivery |
| packages/shared/ | Cross-Worker ActivityPub, queue, database, serializer, permission, domain-block, and cryptographic contracts |
| scripts/ | Resource provisioning, config generation, migrations, backup, deployment, updates, and account administration |
| .github/workflows/ | Production deploy, trusted PR preview, and upstream release sync automation |
Local development
Start routine UI and API development with the main app. Run the supporting Workers only when changing queue or email paths.
pnpm install --frozen-lockfile
pnpm --filter siliconbeest-vue dev
# In separate terminals, only when needed
pnpm --filter siliconbeest-queue-consumer dev
pnpm --filter siliconbeest-email-sender devUnit tests and UI work do not require ./scripts/setup.sh. Prepare the full Cloudflare environment only when validating real D1, R2, KV, and Queue connections together.
Migrations and bindings
- Add new SQL to siliconbeest/migrations/ using the NNNN_short_description.sql format.
- Do not modify a migration that has already been deployed.
- Review rollout and rollback effects on instances with existing data first.
- When wrangler.jsonc bindings change, regenerate types for every affected Worker.
./scripts/migrate.sh --local
pnpm --filter siliconbeest-vue cf-typegen
pnpm --filter siliconbeest-queue-consumer cf-typegen
pnpm --filter siliconbeest-email-sender cf-typegenTesting and quality bar
pnpm lint
pnpm test
pnpm --filter siliconbeest-vue type-check
pnpm build- Test both allowed and denied cases for permission changes.
- For ActivityPub changes, verify visibility, signatures, audiences, duplicate handling, and the DLQ.
- Keep SSRF defenses and protocol, redirect, size, and timeout limits on external URL fetches.
- Check keyboard focus, light and dark modes, mobile layouts, and RTL languages for UI changes.
- Do not commit secrets, real user data, .env files, or personal Cloudflare resource IDs.
Changes and pull requests
- 1 Keep the scope focused
Each pull request should address one logical change without unrelated formatting edits.
- 2 Describe the impact
Document API and federation compatibility, migrations, new bindings, and deployment order in the pull request.
- 3 Provide evidence
List the tests you ran and attach before-and-after screenshots for UI changes.
- 4 Check AGPLv3 obligations
Source-sharing requirements also apply to modified versions offered as a network service.
Use the project contact channel listed in the contribution documents to request access to paid or Enterprise Workers testing and discuss federation test requirements.