Field Manual / Systems

Under the hood

The plumbing under the agent OS. Auth, database, reactivity, the mineral economy, the social graph, and push delivery. How each piece works and why we put it where we did.

Authentication

Clerk + Convex, one identity

Clerk handles every sign-in surface — Apple, Google, email OTP. Convex receives a verified JWT and uses ctx.auth.getUserIdentity() to gate every query and mutation. There's a single users table indexed by clerkId that maps the auth identity to an internal user doc.

ClerkJWTConvex Auth

Database

Convex tables, typed end-to-end

Convex serves as the single source of truth. Every table is typed in schema.ts and reachable from any query, mutation, or action with type inference end-to-end. Reactive queries push updates to the client without polling.

ConvexReactiveTypeScript

Reactivity

No refresh button anywhere

Every screen subscribes to Convex queries that push updates as the underlying data changes. When a friend reacts to your goal, your notifications bell badge increments without polling. When your goals refetch on date change, the mission cards re-height-equalize automatically.

ConvexuseQueryLive

Mineral Economy

Olivium, Ruby, Emerald, Sapphire

An in-app economy with four minerals. Olivium spends; the other three accumulate as identity signals. Grants come from goal and mission completion. Decay debits a small amount nightly unless the agent is on a paid break.

EconomyLedgerDecay

Social Graph

Friends, supporters, activity

Three layers of social: friends (bidirectional, gates feed visibility), mission supporters (lightweight 'I'm on this with you' relationship), and an activity feed with reactions. Notifications fan out across all three.

SocialActivityReactions

Push Notifications

Expo push, Convex actions

Every notification-worthy event (friend request, friend acceptance, reaction, mineral change) writes a notifications row and enqueues a push via Convex actions. Tokens are device-scoped and revoke on sign-out.

ExpoPushActions

Tech Stack

Expo SDK 54

React Native

Convex

Clerk

NativeWind

Reanimated

Zod