Amazon SFR Analytics

Weekly Amazon Search Frequency Rank (SFR) analytics. Admin uploads CSV reports from Seller Central; users analyze keyword trends.

Status

Phase 0 (Foundation) — rubric upload and schema approval.

Architecture

See docs/superpowers/specs/2026-04-15-amazon-sfr-analytics-design.md.

Local development

Prereqs: Node 20+, pnpm, Neon account, Clerk account, Cloudflare R2 bucket.

1. cp .env.example .env.local and fill values
2. pnpm install
3. pnpm db:migrate
4. pnpm db:seed
5. Terminal A: pnpm dev
6. Terminal B: pnpm inngest:dev
7. Sign up at http://localhost:3000/sign-up
8. Promote yourself to admin: pnpm admin:promote (requires INITIAL_ADMIN_EMAIL in .env.local)

Commands

Command	Purpose
pnpm dev	Next.js dev server
pnpm inngest:dev	Inngest local dev server
pnpm test	Unit tests
pnpm test:integration	Integration tests (requires DB)
pnpm typecheck	TypeScript
pnpm db:generate	Generate migrations from schema changes
pnpm db:migrate	Apply pending migrations
pnpm db:seed	Seed app_settings
pnpm db:studio	Drizzle Studio
pnpm admin:promote	Promote INITIAL_ADMIN_EMAIL to admin

Ingestion (Plan 2)

Admin uploads weekly Amazon SFR CSVs through:

• /admin/upload — bulk upload (select multiple files, one batch)
• /admin/upload/single — single weekly file
• /admin/batches — upload history
• /admin/batches/[id] — batch health (view per-file status, import valid files)
• /admin/batches/[id]/files/[fileId] — per-file detail with validation errors

Files are uploaded directly to Cloudflare R2 via presigned URLs (browser → R2, bypassing the web server). Inngest validates each file as it arrives. Admin reviews the batch and clicks "Import valid files" to run the import pipeline, which streams each CSV from R2 into keyword_weekly_metrics.

Deployment

Vercel (auto-deploys on push to main). Env vars must be configured in Vercel dashboard. Clerk webhook URL must point at the deployed /api/webhooks/clerk.