PROTOCOL FOUR// field manual
FieldField Manual
SystemsSystems
AssetsAssets
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.

01

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
Read more
02

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
Read more
03

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
Read more
04

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
Read more
05

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
Read more
06

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
Read more

Tech Stack

Expo SDK 54
React Native
Convex
Clerk
NativeWind
Reanimated
Zod