Mental model
Main rule
Section titled “Main rule”Browser workflows usually go through SvelteKit pages, loads, and form actions. Mobile and native clients talk to apps/api through Better Auth and tRPC. Shared business logic belongs in packages, not copied into apps.
Request paths
Section titled “Request paths”| Surface | Path | Notes |
|---|---|---|
| Web reads | SvelteKit loads or direct service calls | SSR-first where useful. |
| Web writes | SvelteKit form actions | Progressive enhancement and localized validation. |
| Mobile reads/writes | apps/api tRPC | Native apps use a hand-written tRPC-over-HTTP client (cookie auth, no Origin). |
| Auth | Better Auth mounted in web and API | Cookie sessions, no bearer-token app auth. |
| Async work | apps/worker BullMQ | Search sync, leads, alerts, AI jobs, and DLQ handling. |
| Notifications | Knock via @repo/notifications | Translation and email layout live in the shared package. |
Source-of-truth packages
Section titled “Source-of-truth packages”| Package | Why it matters |
|---|---|
@repo/database | Kysely client (pg) + SQL migrations + generated types. |
@repo/api | tRPC routers and service layer used by web/mobile. |
@repo/contract | Zod wire schemas used to generate Swift/Kotlin models. |
@repo/notifications | Knock workflow translations and email layout. |
@repo/redis-search | Property search/indexing behavior. |
High-blast-radius changes
Section titled “High-blast-radius changes”Treat changes to database schema, contract schemas, auth, API procedure shape, notification payloads, and search indexing as cross-app changes. Update docs and run the broader checks listed in First checks.