set-app-backend

name

set-app-backend

description

Wire the backend (stage 3) of a web app whose foundation already exists (see set-project-structure). Turns every placeholder seam — auth, calendar/data + quota, object storage, AI gateway + token metering, Stripe payments — into a working, server-authoritative backend, with a schema delta + migration for anything the foundation left out (AI usage, entry attachments, webhook idempotency). Reads project specifics from PROJECT.md. Mounts the drop-in auth UI on /login so auth is testable, but builds NO bespoke UI — it exposes clean endpoint + server-helper contracts that the dashboard stage (set-dashboard) consumes. STOPS at one plan gate before building. Use after the landing stage, before the dashboard UI. The correctness half of the app: money and limits must be exactly right.

Set App Backend — wire the seams into a server-authoritative app

This skill builds only the backend (stage 3). It assumes the foundation skill (set-project-structure) already laid the seams: the neon_auth-referencing Drizzle schema, the placeholder lib/ clients, the 501 API routes, the auth handler + proxy.ts gate, a PROJECT.md brief, and .env.local keys. The dashboard UI is a separate later skill (set-dashboard) that reads the same brief and consumes this stage's contracts — adding it never edits this one.

Mental model: the foundation skill created seams; the landing skill was about taste. This skill is about correctness under money and limits — where a client-trusted quota check, an unverified webhook, a non-idempotent credit top-up, or a metered LLM call that spends before it checks are the failures that actually cost the user. Every rule that touches a quota, a credit, a token budget, or a dollar is enforced on our server, never on the client. This skill builds no dashboard; it builds the contracts the dashboard will stand on.

---

Step 0 — Load the brief & verify the foundation (required first)

1. Read ./PROJECT.md in the target repo. It is the single source of truth for identity, business model / plans, allowance model, entities, and which Neon services are enabled. Wherever this skill says "per the brief," read it from PROJECT.md — never invent it.
2. Verify the foundation contracts exist before wiring anything:
   • Drizzle schema with the brief's entities FK'd into neon_auth.user; drizzle-kit runs.
   • Placeholder lib/ clients (auth/server.ts, db/, data-api.ts, storage/, ai/gateway.ts, stripe.ts, avatar.ts) that import + type-check.
   • The auth handler (app/api/auth/[...path]/route.ts) and the gate file (proxy.ts / middleware.ts) protecting the brief's gated routes.
   • The 501 business/asset/webhook route placeholders and .env.local keys for every enabled service. If these are missing, stop and tell the user to run the foundation skill first. This skill wires seams; it does not lay foundation.
3. Resolve the brief's one likely gap — AI allowance per plan. The foundation's business model usually meters the primary entity (e.g. calendar entries), not AI tokens. If PROJECT.md does not state a per-plan AI token allowance, ask the user, propose sensible defaults (a small trial for Free, a generous cycle budget for paid, effectively-unlimited for the top tier), and write it into PROJECT.md before proceeding. Business numbers live in the brief, never hardcoded in this skill.

---

Operating principles (apply throughout)

1. Server-authoritative, always. Every mutation that touches a business rule — quota, credit, token budget, plan, dollar — runs in our own route handler / server action behind requireUser(). The client may request; it never decides. Reads that gate features (what plan am I, how much quota is left) are also server-resolved.
2. Enforce before you spend. Check the quota before the write; check the token budget before the LLM call; verify the webhook signature before you trust a cent. Never spend-then-check.
3. Make money idempotent. Webhooks retry and arrive out of order. Any handler that increments (credits, tokens) must dedupe on the provider event id; handlers that set absolute state (plan, subscription id) are naturally safe. Assume every event can arrive twice.
4. Guard against races. Two concurrent requests must not both pass the same last-unit quota check. Consume with an atomic conditional update (UPDATE … WHERE used < quota RETURNING) or a row lock inside a transaction — never read-then-write across an await boundary.
5. Verify, don't trust memory. Websearch the current Neon Auth / Auth-UI / Data API / AI provider / Stripe SDK APIs before wiring each one — they move. The Knowledge Appendix is last-known truth and a drift detector, not gospel. Report what you find.
6. Fail closed, surface honestly. When quota/budget is exhausted, return a typed 402 the UI can act on (upgrade / top-up) — never a silent success or a 500. Log server-side; leak no secrets.
7. No bespoke UI. Mount only the drop-in auth UI so flows are testable end-to-end. The dashboard, modals, chat surface, and all taste belong to set-dashboard. Stay in your lane.

---

Procedure

1. Load brief & verify foundation

Per Step 0, including resolving the AI-allowance gap into the brief.

2. Verify current service APIs (websearch — do before planning)

Confirm, for each enabled service, the current package + API surface, and note any drift from the Appendix:

• Neon Auth: the session-reading API for server code (e.g. auth.getSession() / auth.api.getSession()), the sign-in/sign-up components in @neondatabase/auth-ui, and the sign-out call. Confirm identity table shape (neon_auth.user: id, email, name fields).
• AI provider: whether @neondatabase/ai-sdk-provider is installable now (the foundation flagged it was blocked by an npm registry time-cap). If yes, use it (neon('<model>')). If still blocked, use the AI-SDK OpenAI-compatible provider (@ai-sdk/openai's createOpenAI) pointed at NEON_AI_GATEWAY_BASE_URL with NEON_AI_GATEWAY_TOKEN. Confirm the usage field names for the installed ai major (v5+: inputTokens/outputTokens; older: promptTokens/completionTokens).
• Stripe: the pinned SDK major and its default API version; Checkout Session + Billing Portal + webhooks.constructEvent signatures; how to read the raw request body in this Next major.
• Neon Data API / Storage: the @neondatabase/neon-js createClient({ auth, dataApi }) shape, and the S3 presigner call (getSignedUrl + PutObjectCommand).

3. Gate — STOP and wait (present the backend plan)

Present and wait for explicit approval. Wire nothing until approved. The plan must state:

1. Schema delta — the exact new tables/columns and the migration you'll generate (see §5.1).
2. Plan-limits map — the per-plan entry allowance and AI-token allowance (from the brief), expressed as the single code constant that both enforcement and billing read.
3. Endpoint inventory — every route/action, its method, its auth, and its enforcement rule.
4. AI provider resolution — which path you confirmed in §2, and the usage field names.
5. Webhook event map — each Stripe event → the exact state change, and the idempotency mechanism.
6. Cycle model — how the monthly quota + AI budget reset (lazy-on-access vs invoice.paid), and how the two interact.
7. Anything you're unsure about or assuming (esp. Neon Auth session/UI API names).

4. Schema delta + migration (highest coupling — do first)

Everything downstream depends on the schema. Extend the foundation's db/schema.ts additively (don't rewrite it), then generate one migration.

4.1 Add (adapt names to the brief):

• ai_usage — per-call metering: user_id (FK → neon_auth.user), tokens_in, tokens_out, model, optional kind/request_id, created_at.
• AI-budget columns on billing — ai_tokens_quota (from the plan-limits map), ai_tokens_used_cycle (resets with the entry cycle). Keep them beside the existing monthly_quota / used_this_cycle / cycle_resets_at so one cycle reset covers both.
• Attachment link on the primary entity — e.g. calendar_entries.asset_id (nullable FK → assets.id, on delete set null) per the storage decision in the brief.
• processed_stripe_events (or equivalent) — event_id primary key, type, created_at — the idempotency ledger for incrementing webhook handlers.

4.2 Generate + verify: drizzle-kit generate produces a clean migration; drizzle-kit migrate (or push per the project's convention) applies it without error. Do not hand-edit generated SQL.

5. Wire the backend (only after approval)

5.1 Auth flows.

• Login: replace the /login stub with the Neon Auth-UI sign-in/sign-up component. This is the only UI this skill ships; keep it a thin mount, no bespoke styling beyond the wired tokens.
• Session helpers (lib/auth/*): requireUser() (resolve the current Neon Auth user or redirect/401), and getOrCreateProfile(user) — a provisioner that, on first authenticated request, inserts the profiles row (email, plan=free, generated unique referral_code, referred_by from a ?ref= cookie) and the billing row (entry + AI quotas from the plan-limits map, used=0, extra_credits=0). Make it idempotent (upsert / on conflict do nothing).
• Referral grant: when referred_by is set on first provision, create the referrals row and grant the referrer the bonus credit — once (guard on credit_granted), and reject self-referral. Grant sits behind the same server rules as every other credit mutation.
• Logout: a server action that calls Neon Auth sign-out and clears the session (consumed by the dashboard dropup later).

5.2 Primary-entity CRUD + quota (the core enforcement).

• Routes/actions for the brief's primary entity (e.g. app/api/entries — create / edit / delete), every one scoped by user_id from requireUser() (never a client-supplied id).
• Create runs the allowance gate, atomically (principle 4):
  1. Lazy cycle reset — if cycle_resets_at is null or past, reset used_this_cycle and ai_tokens_used_cycle to 0 and set the next cycle_resets_at.
  2. Consume — quota first, then credits: if plan==='max' allow (unlimited, no decrement); else if used_this_cycle < monthly_quota increment used; else if extra_credits > 0 decrement credits; else fail closed with 402 ({ reason: 'quota_exhausted', canTopUp, canUpgrade }).
  3. Only on success insert the entry — in the same transaction as the consume.
• Edit/Delete: ownership-checked; deletes do not refund quota (allowance is consumption, not a live count) unless the brief says otherwise — state the choice.
• Expose a getBillingState() read helper returning { plan, entriesUsed, entriesLimit, creditsRemaining, cycleResetsAt, aiTokensUsed, aiTokensLimit } — the shape the dashboard renders.

5.3 Object storage (per the brief's storage decision).

• app/api/assets (POST): behind requireUser(), validate contentType against an allowlist, return a presigned PUT (getSignedUrl(s3, new PutObjectCommand({ Bucket: S3_BUCKET, Key, ContentType }), { expiresIn })) with a scoped key (e.g. users/${userId}/entries/${id}/${uuid}), and insert the assets metadata row linked to the entity (asset_id).
• Size can't be enforced on a presigned PUT — either use a presigned POST with a content-length-range policy, or verify size via a HeadObject after upload and reject/delete oversize objects. Pick one and say which. Never serve user objects from a public bucket if the brief implies privacy — presign reads too.

5.4 AI gateway + token metering.

• Wire lib/ai/gateway.ts with the provider path confirmed in §2. Keep the model id in NEON_AI_GATEWAY_MODEL so it's swappable.
• app/api/chat (POST, streaming): behind requireUser().
  1. Budget gate before the call — if ai_tokens_used_cycle >= ai_tokens_quota (and not the unlimited tier) → 402 (reason: 'ai_budget_exhausted'). Set a maxOutputTokens cap so a single call's overage is bounded.
  2. Inject calendar context — fetch this user's entries for a bounded window and format them into the system prompt (scoped to the user only; keep the context within a token budget).
  3. Stream via the AI SDK (streamText), and in onFinish read usage, insert an ai_usage row, and increment ai_tokens_used_cycle (tokens_in + tokens_out). Metering happens on finish, not before — record actuals.
• Note: Neon AI Gateway also tracks tokens/cost server-side for observability, but in-app enforcement is ours — the gateway dashboard is not the quota.

5.5 Payments (Stripe).

• app/api/stripe/checkout (POST, requireUser()): create a Checkout Session — mode: 'subscription' for plan prices (STRIPE_PRICE_PRO/MAX), mode: 'payment' for the one-time top-up (STRIPE_PRICE_TOPUP). Attach/create the Stripe customer, store stripe_customer_id, and put { userId, kind } in metadata. Return the URL.
• app/api/stripe/portal (POST, requireUser()): billingPortal.sessions.create({ customer, return_url }) — where the user manages / cancels the subscription.
• app/api/stripe/webhook (POST, no auth, raw body): constructEvent(rawBody, sig, STRIPE_WEBHOOK_SECRET); reject bad signatures with 400. Dedupe on event.id via processed_stripe_events before any increment. Handle:

  Event	State change
  checkout.session.completed	subscription → set plan, store subscription_id, set entry + AI quotas from the plan-limits map. payment (top-up) → extra_credits += N (idempotent).
  customer.subscription.updated	reconcile plan/quotas from the price; honor cancel_at_period_end.
  customer.subscription.deleted	downgrade to free, reset quotas to the free tier.
  invoice.paid / payment_succeeded	renew the cycle: reset used_this_cycle + ai_tokens_used_cycle, advance cycle_resets_at.

  • Keep the plan → (entry quota, AI quota) map as one code constant; map Stripe price ids → plan from env. Never derive plan from client input.

5.6 Data API (optional). Prefer server routes/actions (Drizzle + requireUser()) for authoritative reads too, for one consistent enforcement path. If the brief wants direct authenticated client reads, wire createDataApiClient() with the Neon Auth adapter — but that requires RLS policies (auth.user_id() = row owner) on the exposed tables; note that as a Neon console/SQL step and keep all mutations in our routes regardless.

6. Verify end-to-end & commit

• npm run build succeeds; tsc --noEmit clean; drizzle-kit generate yields no pending diff.
• Auth: sign up → a profiles + billing row is provisioned exactly once; sign out works.
• Quota: creating past the allowance returns the typed 402; a top-up/upgrade path restores it; concurrent creates never over-consume (race check).
• Storage: presign → client PUT → object lands under the scoped key → assets row links it.
• AI: chat streams with calendar context; ai_usage rows accrue; exceeding the budget 402s.
• Stripe: drive the webhook with the Stripe CLI (stripe listen / trigger) — signature verifies, a replayed event is a no-op (idempotency), plan/credits/cycle update correctly.
• Commit as its own clean change on top of the landing baseline. Touch no dashboard UI.

---

Definition of Done

1. npm run build + tsc --noEmit pass; the migration generates cleanly and applies.
2. Auth works end-to-end: Auth-UI login mounts; provisioning creates profiles+billing idempotently; referral grants once and rejects self-referral; logout works.
3. All enforcement is server-side and atomic: quota consume (quota→credits→402) can't be raced; AI budget gates before the call; both reset on one cycle.
4. Storage issues scoped presigned uploads, records assets, links attachments, and has a stated size-enforcement strategy.
5. AI chat streams with per-user calendar context, caps output, and meters real usage into ai_usage + billing on finish.
6. Stripe checkout (sub + top-up), portal, and a signature-verified, idempotent webhook all work against the Stripe CLI; plan/credits/cycle transitions (including cancel) are correct.
7. Contract seam is stable and documented (see below) so set-dashboard can build against it.
8. No secrets on the client; failures return typed, actionable responses; nothing silently succeeds.
9. No bespoke UI beyond the login mount was built.

Contract seam — what this stage exposes for set-dashboard

The dashboard depends only on these; never on internals:

• Server helpers: requireUser(), getOrCreateProfile(), getBillingState().
• Endpoints/actions: primary-entity CRUD (/api/entries …), /api/assets (presign), /api/chat (stream), /api/stripe/checkout, /api/stripe/portal, logout action.
• Data shapes: the entity row; getBillingState()'s { plan, entriesUsed, entriesLimit, creditsRemaining, cycleResetsAt, aiTokensUsed, aiTokensLimit }; the typed 402 bodies (quota_exhausted / ai_budget_exhausted with canTopUp / canUpgrade).

Keep these stable. If a shape must change, it's a deliberate contract change — say so.

Out of scope — do NOT build in this stage

The dashboard/app shell, calendar UI, glassmorphic settings/billing modal, AI chat surface, dropup — all of it belongs to set-dashboard. Also out: deployment/hosting config (a later stage), multi-tenant/team features, and any schema the brief marks a non-goal. Mount the auth UI; build no other screen.

---

Knowledge Appendix — current wiring patterns

A starting point, not gospel — re-verify at runtime (Step 2). Confirm versions match the set the foundation pinned; don't introduce a conflicting major of ai, the Neon SDKs, or Stripe.

• Neon Auth (server session). Read the user in route handlers / server components via the auth instance's session API (verify the exact name, e.g. auth.getSession() / auth.api.getSession()); return/redirect on absence in requireUser(). Server components that read auth need export const dynamic = 'force-dynamic'. Identity is neon_auth.user — FK into it; never mirror it.
• Neon Auth UI. @neondatabase/auth-ui ships prebuilt sign-in/sign-up components — mount them on /login; confirm the component + props names at runtime. It talks to app/api/auth/[...path].
• Provisioning pattern. First-request getOrCreateProfile() (upsert profiles + billing) is simpler and race-safe than a signup webhook; make it idempotent so concurrent first requests can't double-insert (on conflict (user_id) do nothing, then select).
• Atomic quota consume. One statement, no read-then-write gap:

  UPDATE billing
     SET used_this_cycle = used_this_cycle + 1
   WHERE profile_id = $1 AND used_this_cycle < monthly_quota
  RETURNING id;               -- 0 rows → quota full; then try extra_credits similarly, else 402
  

• AI provider resolution. Preferred: @neondatabase/ai-sdk-provider → neon(NEON_AI_GATEWAY_MODEL). Fallback (provider not yet installable): AI-SDK OpenAI-compatible provider against the gateway:

  // verify field names for the installed `ai` major
  const res = streamText({
    model,                                   // neon(MODEL) or openai-compatible(MODEL)
    system: calendarContext,                 // this user's entries, bounded
    messages, maxOutputTokens: CAP,
    onFinish: async ({ usage }) => {         // v5+: usage.inputTokens / usage.outputTokens
      await recordAiUsage(userId, usage);    // insert ai_usage + bump ai_tokens_used_cycle
    },
  });
  

• Stripe webhook (raw body + idempotency). Read the raw body (await req.text()), then:

  const event = stripe.webhooks.constructEvent(rawBody, sig, WEBHOOK_SECRET); // throws → 400
  if (await alreadyProcessed(event.id)) return ok();      // dedupe before any increment
  // …handle by type; setting absolute state is safe, increments must be behind the dedupe…
  await markProcessed(event.id);
  

  Checkout: mode:'subscription' for plans, mode:'payment' for top-ups; carry { userId, kind } in metadata and always store stripe_customer_id. Portal handles cancel/manage — don't rebuild it.
• Storage presign. getSignedUrl(s3, new PutObjectCommand({ Bucket: S3_BUCKET, Key, ContentType }), { expiresIn }). The SDK auto-reads AWS_ENDPOINT_URL_S3 / AWS_*. Scope keys per user; size limits need presigned-POST policy or a post-upload HeadObject check.
• Cycle model. Lazy reset (compare now vs cycle_resets_at on access) covers Free/idle users with no cron; invoice.paid renews paid subscribers on billing. Reset entry and AI counters together so the two allowances share one cycle.

Sources (re-fetch for current truth):

• Neon Auth + Next.js: https://neon.com/guides/neon-auth-nextjs
• Neon Data API: https://neon.com/docs/data-api/get-started
• Neon AI Gateway: https://neon.com/docs/ai-gateway/get-started
• Vercel AI SDK (streamText / usage / providers): https://ai-sdk.dev/docs
• Neon S3-compatible storage: https://neon.com/docs/guides/aws-s3
• Stripe Checkout: https://stripe.com/docs/checkout · Billing Portal: https://stripe.com/docs/customer-management · Webhooks: https://stripe.com/docs/webhooks