ns-architecture — Mobile technical architecture

Critical framing: the stack is already decided (read CLAUDE.md / AGENTS.md). You are NOT choosing a database or a framework — you are designing how the PRD's features map onto Convex + Expo + Better Auth + Apple IAP/Stripe + R2 + TanStack Start. The valuable output is the data model, the Convex function surface, the screens, and the payment/auth/storage wiring — grounded in the real files, not invented.

Phase 2 — Design, challenging every decision

For each must-have feature in the PRD, decide:

• Data model — new Convex tables + the indexes each query needs (.withIndex, pagination — never unbounded .collect()/.filter(); counters for real counts). What hangs off the users row.
• Function surface — the public/internal Convex queries/mutations/actions, each built with the project builders and derived server-side identity (never a client userId). Name them and state args/returns at a high level.
• Screens — which Expo Router screens/route groups (mind the group-segment paths, e.g. /(flow)/paywall), what's a tab vs a stack screen, and what the web /app surface shows (if any).
• Entitlement & gating — what's behind the paywall; record the entitlement on the user level and apply derived grants idempotently (the auth-payments-storage rule: a validated purchase must never fail because a derived grant threw). IAP on iOS, Stripe on Android/web.
• Storage — any R2 uploads (Convex storage helpers, signed URLs) and where.
• Auth/admin — which surfaces are signed-in vs admin-only; allowlist in site-config.ts + Convex check.

Phase 3 — Write .agents/plan/ARCHITECTURE.md

Use the template. Keep it real: cite actual paths and builders, include an ADR for each non-obvious choice, and a build-order. Don't restate the whole stack — only the deltas this product adds.

Phase 4 — Next step

Point at /ns tasks to slice this into implementable work, then /ns setup if config values (products, admin emails) changed.

<output_template>

# Technical Architecture: [App Name]

## Overview
[2–3 sentences: how the PRD maps onto the stack. Link .agents/plan/PRD.md.]

## Data Model (Convex)
| Table | Fields (key) | Indexes | Notes |
|---|---|---|---|
| `xyz` | … | `by_user`, … | hangs off users / counters / pagination |
[Reference: extends `convex/schema.ts`. Indexes for every queried field.]

## Convex Function Surface
| Function | Type (builder) | Args → Returns | Auth |
|---|---|---|---|
| `xyz.list` | `authQuery` | … | user-scoped |
| `admin.…` | `adminQuery` | … | admin-only |
[Identity derived server-side. Validators on every arg.]

## Screens (Expo Router)
| Screen | Path (with group) | Type | Notes |
|---|---|---|---|
| … | `/(tabs)/…` / `/(flow)/…` | tab / stack / modal | |
[Web `/app` surface, if any.]

## Payments & Entitlements
- Gated: [features] · iOS: Apple IAP · Android/web: Stripe
- Entitlement recorded on: **user** · derived grants: [idempotent, try/catch]

## Storage / Auth
- R2: [what, where] · Signed-in surfaces: […] · Admin-only: […]

## Architecture Decision Records
### ADR-001: [decision] — context / choice / why / trade-offs
### ADR-002: …

## Build Order
1. **Foundation** — schema + indexes, core Convex functions
2. **Core features** — screens + wiring
3. **Monetization & polish** — paywall, entitlements, analytics

</output_template>