Skip to content

Melvynx/saveit.now / .agents/skills/ns-architecture

ns-architecture

Verified

Design the technical architecture for a NowStack Mobile app from .agents/plan/PRD.md, mapping the product onto the FIXED boilerplate stack (Convex schema + functions, Expo Router screens, Better Auth, Apple IAP/Stripe, R2), then save .agents/plan/ARCHITECTURE.md. Use for "design the architecture", "ns architecture", "plan the schema and screens", or as the second planning step after ns-prd and before ns-tasks. Not a blank-slate stack design — the stack is set; this maps features onto it.

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>

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall