Appearance
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 handDependency 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. createContextbuilds{ session, db, requestId }. Procedures get anActorfromgetActor(session); they never read the raw session.- Every access decision is in
packages/api/src/access.ts(Conventions).
Web app structure
| Path | Purpose |
|---|---|
routes/login.tsx | Sign in with username or email. Dev-only role preview. |
routes/_app/route.tsx | Auth guard + app shell for everything signed in |
routes/_app/$space/route.tsx | Validates /owner, /sales, /crew, /client; sends you to your own space |
routes/_app/$space/index.tsx | Each space's home, driven by lib/spaces.ts |
routes/_app/$space/$section.tsx | Generic planned screen for any section in lib/spaces.ts |
routes/p/* | Public token pages (form, booked, quote, contract, set-password) |
routes/dev/ui.tsx | Dev-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
| Concern | Runs in | Notes |
|---|---|---|
| HTTP API, auth | Worker fetch | Must stay within CPU limits |
| Scheduled sweeps | Worker scheduled (cron every 15 min) | Idempotent; registered in packages/api/src/jobs.ts |
| Background jobs | Worker queue consumer | Versioned envelopes; dead-letter queue |
| Large files | Browser → R2 directly | Worker only signs and records |
| Research, video processing | External service, called from a job | Never inside a request |