Skip to content

Architecture ​

Repository map ​

text
shootgrow-crew/
├── apps/
│   ├── web/        TanStack Start app: role spaces, public pages, login
│   ├── server/     Hono Worker: auth, oRPC, queue consumer, cron handler
│   ├── docs/       This site (VitePress)
│   └── native/     ON HOLD. Not in the workspace, Nx or CI. See ADR 0001.
├── packages/
│   ├── domain/     Pure TypeScript: roles, statuses, event-type seeds, settings registry,
│   │               versioning primitives. No I/O. Safe to import anywhere.
│   ├── db/         Drizzle schema + append-only migrations (D1)
│   ├── auth/       Better Auth configuration (username, admin, organization, two-factor)
│   ├── api/        oRPC procedures, the access module, job envelope, integration seams
│   ├── ui/         beUI components (vendored) + design tokens
│   ├── infra/      Alchemy stack: D1, R2, Queues, Worker, cron, web site
│   └── config/     Shared tsconfig
├── scripts/        beui.ts (vendoring), check-migrations.ts
└── roadmap.md      New ideas land here, not in the change in hand

Dependency direction (never the reverse):

flowchart LR
  domain --> db --> auth --> api --> server
  domain --> api
  domain --> web
  api -. types only .-> web
  ui --> web

web imports only the types of api (the router type) and never its runtime code.

Request flow ​

sequenceDiagram
  participant B as Browser (web)
  participant S as Worker (server)
  participant A as Better Auth
  participant P as packages/api
  participant D as D1
  B->>S: POST /rpc (cookie)
  S->>A: getSession(headers)
  A->>D: session lookup
  S->>P: procedure(context: session, db, requestId)
  P->>P: getActor(session) / roleProcedure / access scope
  P->>D: scoped query
  P-->>B: result, or NOT_FOUND outside scope
  • The browser talks to the server at /rpc (oRPC, typed end to end) and /api/auth/* (Better Auth). An OpenAPI reference is served at /api-reference.
  • createContext builds { session, db, requestId }. Procedures get an Actor from getActor(session); they never read the raw session.
  • Every access decision is in packages/api/src/access.ts (Conventions).

Web app structure ​

PathPurpose
routes/login.tsxSign in with username or email. Dev-only role preview.
routes/_app/route.tsxAuth guard + app shell for everything signed in
routes/_app/$space/route.tsxValidates /owner, /sales, /crew, /client; sends you to your own space
routes/_app/$space/index.tsxEach space's home, driven by lib/spaces.ts
routes/_app/$space/$section.tsxGeneric planned screen for any section in lib/spaces.ts
routes/p/*Public token pages (form, booked, quote, contract, set-password)
routes/dev/ui.tsxDev-only component gallery

To build a section, add a dedicated route file next to the generic one (for example routes/_app/owner/leads.tsx); static routes win over $section. See ADR 0008.

What runs where ​

ConcernRuns inNotes
HTTP API, authWorker fetchMust stay within CPU limits
Scheduled sweepsWorker scheduled (cron every 15 min)Idempotent; registered in packages/api/src/jobs.ts
Background jobsWorker queue consumerVersioned envelopes; dead-letter queue
Large filesBrowser → R2 directlyWorker only signs and records
Research, video processingExternal service, called from a jobNever inside a request

Internal documentation. Not for clients.