Skip to Content
Settlr

Architecture

How the monorepo is laid out, and how the web app, the Convex backend and the shared package fit together.

The monorepo

Settlr is a Turborepo monorepo with pnpm workspaces:

turbo.json
pnpm-workspace.yaml
WorkspacePackageDepends on
apps/webweb@settlr/backend, @settlr/shared
apps/mobilemobile@settlr/backend, @settlr/shared
apps/docsdocsnothing in the repo
packages/backend@settlr/backend@settlr/shared
packages/shared@settlr/sharedzod
  • @settlr/backend holds convex/, where all app data lives. The web app imports its generated API as @settlr/backend/convex/_generated/api (and .../dataModel for types). convex/_generated/ is written by convex dev and committed.
  • @settlr/shared is TypeScript source used on both sides: schemas (the currencies, categories and zod schemas for forms and search params, with the same limits the backend checks) and format (money and date formatting). The web app compiles it through transpilePackages; Convex bundles it with the functions.

Request flow

Browser ──(WebSocket: live queries, mutations)──────────────▶ Convex
   │                                                          ▲
   └─▶ Next.js (apps/web) ──(prefetch as the user, JWT)───────┘
            │
            └─ /api/auth/*  ──proxy──▶ Better Auth inside Convex (HTTP routes)
            └─ /api/mcp     ──token exchange, then api.mcp.handle──▶ Convex
  1. A server page (page.tsx) gets the user's Convex JWT from the Better Auth session and prefetches its queries with prefetchQuery.
  2. It renders a client view (view.tsx) inside <Prefetched>, which seeds those results into the browser's TanStack Query cache, so the first HTML is complete.
  3. In the browser, each useSuspenseQuery(convexQuery(...)) becomes a live Convex subscription. Mutations (useConvexMutation) update every open page and tab without refetching or router.refresh().

Backend modules

FileWhat it holds
schema.tsTables and indexes (see Data model)
friends.tsFriends, one-on-one expenses and payments, friend requests
groups.tsGroups, members, group expenses and payments
personal.tsPersonal expenses by month
budgets.tsBudgets and the month's spending across everything
notifications.tsNotifications, accepting and declining friend requests
receipts.tsReceipt uploads and viewing
assistant.tsThe chat assistant (an action calling OpenRouter)
mcp.tsThe same tools over MCP, and the connected apps
auth.ts, auth.config.ts, http.tsBetter Auth running inside Convex
convex.config.tsThe Better Auth component and the typed environment variables
lib/requireUser, value checks (input.ts), balance math (ledger.ts), receipts, the assistant's tools

Principles

The user comes from the token. Every query and mutation calls requireUser(ctx), which reads the identity from the Convex JWT, and scopes every read and write to that user. Functions never take a user id as an argument. Queries that take an id from the URL accept a string, normalise it and return null for missing or foreign rows; the page turns that into a 404.

Validation on both sides. Forms validate with the zod schemas in @settlr/shared/schemas. Convex functions check argument types with validators and values with convex/lib/input.ts, using the same limits, because clients can call public functions directly. Type checks in convex/lib/validators.ts fail the build if the Convex enums and the shared lists drift apart.

Money is integers. Every amount is stored as integer minor units (amountCents), never floats. All supported currencies have two decimals.

Precomputed totals. Balances and insight totals are stored on the friend or group document and updated in the same mutation as each expense or payment, so pages read one document instead of summing a ledger (see Balances).

On this page