local

Handoff — 2026-02-04

TL;DR

What changed today: Staging deployment on Render is now aligned with the “min fixed monthly cost” approach: Render for web/worker, Neon for Postgres, Upstash for Redis. Render-managed Postgres/Key Value were intentionally removed.
Current state: Web + worker deploy via render.yaml. All webhook routes referenced in shopify.app.toml exist. Worker DTS build issue was fixed (exported RevertResult type). Health endpoint was returning 200 after the latest deploy.
Biggest open risk / unknown: The app’s core product workflows still need a concentrated “does this actually work end-to-end?” pass (embedded UI → triggers → jobs → results → apply/revert) in a live environment. Billing polish is intentionally deprioritized until closer to launch.

What I did (high-signal)

Updated staging deployment docs to match reality:
- docs/deploy/render.md now documents external Neon/Upstash instead of provisioning Render Postgres/Redis.
- .env.example now calls out DATABASE_URL (Neon) and REDIS_URL (Upstash) as the preferred staging config.
Updated architecture/runbook to reflect staging setup:
- docs/ARCHITECTURE.md now explicitly references Render + Neon + Upstash.
- docs/RUNBOOK.md now links to the staging deploy doc and describes managed services expectations.
Logged the staging infra decision as an ADR:
- docs/decisions/ADR-0001-staging-infra-neon-upstash-render.md
Updated the docs handoff index:
- docs/HANDOFF.md now points to this file as the latest.

Where things stand

Deployment
- Render services: web + worker are defined in render.yaml.
- Data services:
  - Neon Postgres provides DATABASE_URL
  - Upstash Redis provides REDIS_URL (BullMQ backing store)
- We intentionally do not provision Render Postgres or Render Key Value to avoid fixed monthly costs.
Shopify config
- shopify.app.toml is configured for the current Render web URL:
  - application_url = "https://shopify-ai-product-optimizer-web-p446.onrender.com"
  - Redirects include:
    - /auth/callback
    - /auth/shopify/callback
    - /api/auth/callback
- Webhook routes in code exist for every shopify.app.toml webhook URI:
  - /webhooks/products
  - /webhooks/bulk-operations
  - /webhooks/app-uninstalled
  - /webhooks/app-subscriptions
  - Privacy compliance:
    - /webhooks/customers-data-request
    - /webhooks/customers-redact
    - /webhooks/shop-redact
Billing / usage-based billing (status)
- Plan definition + DB persistence exists (see prior handoff docs/handoff/2026-02-02.md).
- /webhooks/app-subscriptions now calls syncBillingForShop(shopDomain) to keep billing state fresh.
- Still pending: wiring metered usage events to Shopify usage records (and surfacing billing status in UI).

Next steps (do these next)

Tomorrow focus (minimize chores; prioritize app build + test)

Execution rule for tomorrow

Item 1 is the objective: get the app working end-to-end (build + live test + core workflows).
Items 2–3 are supporting spikes: do them only when they unblock Item 1 or materially improve the plan.
Timebox research spikes (e.g. 30–60 minutes). Capture findings + next actions, then return to implementation/testing.

Build & test the app end-to-end (primary objective)
- Install on a dev store → complete OAuth → confirm embedded UI loads reliably.
- Exercise the “happy path” for the core workflows:
  - Analyze a product (single + batch)
  - Generate suggestions
  - Apply changes
  - Confirm audit trail exists
  - Revert a change (and verify data consistency)
- Trigger webhook-driven automation (product create/update) and confirm:
  - webhook arrives (web logs)
  - job enqueued (web logs)
  - worker processes (worker logs)
  - results appear in app UI
Deep-dive OpenAI agent-building docs + recipes/templates (research → refine approach)
- Goal: decide whether we should implement a true multi-agent orchestrator (planner/researcher/writer/critic/apply) and what the “minimum viable” version looks like for this Shopify app.
- Start from official guides:
  - OpenAI Agents SDK overview: https://platform.openai.com/docs/guides/agents-sdk
  - Responses API overview (agent-like apps + built-in tools): https://platform.openai.com/docs/guides/migrate-to-responses#about-the-responses-api
  - Multi-agent workflow pattern with handoffs/guardrails/traces (Codex + Agents SDK): https://developers.openai.com/codex/guides/agents-sdk/#creating-multi-agent-workflows
- Add “recipes” from OpenAI Cookbook (practical, reusable patterns):
  - Cookbook home / index: https://cookbook.openai.com/
  - Self‑Evolving Agents (autonomous agent retraining): https://cookbook.openai.com/examples/partners/self_evolving_agents/autonomous_agent_retraining
    - Why it matters for us: we can treat “SEO suggestion quality” as a system that improves via an evaluation flywheel (human feedback + LLM-as-judge graders → prompt/toolchain revisions → promotion).
    - Concrete adaptation for this app (tomorrow deliverables):
      - Create a tiny eval dataset (10–30 products) with “expected” outcomes (or rubric-only grading if we don’t have gold labels yet).
      - Define graders that matter for SEO suggestions:
        
        factuality vs source product fields (no hallucinated attributes)
        
        policy/safety compliance (no disallowed claims)
        
        SEO constraints (length limits, keyword inclusion rules, tone)
        
        merchant intent alignment (suggest vs apply)
      - Decide where this loop lives: offline harness first (local script) → later optional automation (nightly eval / regression gate).
- Deliverable: a short “AI architecture plan” note (where orchestration lives, agent roles, tool boundaries, tracing/evals plan) PLUS a first-pass “eval plan” (dataset + graders + success thresholds).
Research “Cultui Pro” (use what we already paid for)
- Confirm what “Cultui Pro” provides (components/templates/workflows) and where it can accelerate us without fighting Shopify Polaris/App Bridge.
- If it’s primarily UI components (e.g., Cult/UI), decide whether to use it for:
  - Non-embedded surfaces (marketing, docs, landing pages), or
  - Internal tools/admin screens (if compatible), or
  - Skip (if Polaris conflicts / adds churn)

Explicitly deprioritized (only do if blocking)

Shopify Partners URL/redirect updates (do soon, but not required to start app-building tomorrow unless install flow breaks).
Billing polish / usage record wiring (resume later, closer to launch).

Notes / gotchas

Secrets: do not commit .env or secrets in shopify.app.toml. Use placeholders in docs; set real values in Render dashboard/env.
Prisma: staging currently uses db:push on web start for convenience; switch to migrations for production (prisma migrate deploy).
Redis TLS: Upstash often uses rediss:// (TLS). Prefer setting REDIS_URL rather than host/port flags.

Commands I ran (representative)

# local
npm run dev
npm run worker:dev
npm run db:generate
npm run db:push

# render blueprint-driven deploy
# (Render pulls repo + uses build/start commands from render.yaml)

Links / references

Deploy guide: docs/deploy/render.md
Runbook: docs/RUNBOOK.md
Architecture: docs/ARCHITECTURE.md
ADRs: docs/decisions/README.md
Prior handoff (billing focus): docs/handoff/2026-02-02.md