New Contributors

New Contributors

Use this guide for your first day in the repo.

Repo mental model

• apps/ — user-facing deployable entrypoints
• workers/ — backend/runtime Cloudflare Workers
• packages/ — reusable libraries and extracted feature slices
• scripts/ — repo automation and deploy helpers
• tests/ — cross-app and end-to-end verification
• docs/ — canonical architecture, runbooks, ADRs, onboarding

First 10 minutes

1. Install dependencies: pnpm install
2. Start the dashboard: pnpm dev:dashboard
3. Open http://localhost:5173
4. Read ../../apps/README.md
5. Read ../architecture/00-repo-map.md
6. Read ../architecture/01-code-placement.md

Common commands

Goal	Command
Start dashboard	pnpm dev:dashboard
Start marketing site	pnpm dev:marketing
Start docs site	pnpm dev:docs
Start ingestion workers	pnpm dev:ingestion
Start public API worker	pnpm dev:worker-consumer-api
Run architecture checks	pnpm ci:arch
Run repo validation	pnpm validate
Deploy dashboard	pnpm deploy:dashboard
Deploy marketing site	pnpm deploy:marketing

Use the canonical names above.

Quick repo map

Area	Purpose	Edit when…	Common command
apps/dashboard	Main product UI + server functions	you are changing dashboard routes, pages, auth, or server functions	pnpm dev:dashboard
apps/marketing	Public marketing site	you are changing public site content or marketing pages	pnpm dev:marketing
apps/docs	Public docs site	you are changing published docs content	pnpm dev:docs
workers/*	Cloudflare workers and operational services	you are changing queue consumers, public API, log processing, or rate limiting	pnpm dev:ingestion, pnpm dev:worker-consumer-api
packages/feature-*	Reusable dashboard feature data/UI slices	logic is reused across dashboard screens	pnpm ci:arch
packages/platform-*	Cross-feature infrastructure	multiple features or apps need shared platform support	pnpm ci:arch
packages/domain-* / packages/utils / packages/db	Shared domain and platform foundations	logic is framework-light or schema/data related	pnpm ci:arch
tests/	Cross-app/system verification	you are adding or adjusting end-to-end coverage	pnpm test:all

Choosing where new code goes

If you are adding…	Put it here
Dashboard page composition	apps/dashboard/src/features/{domain}/pages/
Dashboard route declaration	apps/dashboard/src/routes/{-$locale}/...
Reusable dashboard feature queries or mutations	packages/feature-{domain}/src/
Cross-feature platform logic	packages/platform-*
Shared business/domain rules	packages/domain-*, packages/utils, packages/db
Worker feature logic	workers/*/src/features/
Worker runtime adapters/binding access	workers/*/src/infra/
Canonical docs	docs/architecture/, docs/runbooks/, docs/adr/

If you are unsure, stop and check ../architecture/01-code-placement.md.

Fast decision tree

Are you adding a deployable entrypoint?
  YES -> Is it user-facing?
           YES -> apps/
           NO  -> workers/
  NO  -> Is it dashboard-only page or route composition?
           YES -> apps/dashboard/src/features or apps/dashboard/src/routes
           NO  -> Is it worker-runtime-specific (queues, D1 bindings, Durable Objects, wrangler-owned runtime)?
                    YES -> workers/*/src/features or workers/*/src/infra
                    NO  -> Is it reused across multiple screens or multiple owners today?
                             YES -> packages/feature-* or packages/platform-*
                             NO  -> Keep it with the current owning app/feature

How to work on a worker

1. Find the owning worker under workers/*
2. Keep runtime entrypoints thin
3. Put domain logic in src/features/
4. Put Cloudflare binding access and adapters in src/infra/
5. Use the root canonical dev/deploy commands instead of memorizing local package names

Common mistakes

• Putting dashboard page composition into packages/feature-*
• Putting Cloudflare runtime access into browser-safe layers
• Using generic folders like helpers/, common/, or broad utils/ without a narrow owner
• Assuming workers participate in the main Turbo app pipeline
• Adding new production code to deprecated workers/my-api/

Turbo vs Wrangler

• apps/dashboard, apps/marketing, and apps/docs are the main user-facing deployables and show up in the core Turbo workflow.
• workers/* are still deployables, but they are operated through Wrangler-oriented scripts and worker-specific flows.
• The repo is organized by deployable ownership, not by forcing every deployable into the same toolchain path.

Scaffold shortcuts

pnpm scaffold dashboard-feature my-feature --route my-feature
pnpm scaffold domain-module my-domain
pnpm scaffold worker-feature worker-ingestion-process linking

Expected output paths:

• pnpm scaffold dashboard-feature my-feature --route my-feature
  • apps/dashboard/src/features/my-feature/...
  • route files under apps/dashboard/src/routes/{-$locale}/(dashboard)/...
• pnpm scaffold domain-module my-domain
  • packages/domain-my-domain/src/...
• shared ingestion runtime modules
  • packages/platform-ingestion/src/features/notifications/...

Read next

• ../README.md
• ../architecture/16-contributing-and-templates.md
• ../architecture/03-dependency-rules.md