Skip to content

roadmap.md

Latest commit

 

History

History
113 lines (88 loc) · 8.43 KB

roadmap.md

File metadata and controls

113 lines (88 loc) · 8.43 KB
Raw

Roadmap

Current phase: 1 — Schema + auth + sellers DoD: signup → session → GET /api/seller round-trip covered by tests. (Phase 0 code is done and CI is green; two founder to-dos remain from Phase 0: enable Docker Desktop WSL integration, and register the Shopify Partner account + protected-customer-data application.)

Agents: check the current phase above before starting work; update it (and tick checklists) when you complete items. Decisions that must not be relitigated go in docs/adr/.

Web surface status (Aug 2026): the "security paper" identity overhaul is complete (ADR-0006, log in docs/ux-cycles.md § Identity overhaul) — cool security-paper palette with a computed-AA token gate (web/scripts/check-tokens.mjs in make lint-web), IBM Plex Sans/Serif/Mono, guilloché engraving, one canonical seal, shared primitives in web/components/ui.tsx (the Phase 4 dashboard should build on these), and badge/OG unified onto web/lib/tokens.ts. Critic verdict: SHIP, no must-fixes. Demo prep unchanged: run make demo-data, set NEXT_PUBLIC_SITE_URL in production.

Connector status (Aug 2026): the connector framework plus Etsy, eBay, and TikTok Shop connectors are code-complete and fixture-tested (ADR-0007; api/internal/connectors, api/internal/ingest). Live sync for all three is blocked on the external app approvals in the founder track below; Shopify remains the first live integration (Phase 2). TikTok covers orders/refunds/cancellations only — its official seller API exposes no reviews.

Phase 0 — Reset + scaffolding + CI (2–3 days)

  • Archive Solana prototype to legacy-solana branch + legacy-solana-final tag; clean main
  • AGENTS.md (+ CLAUDE.md symlink), README, docs skeleton, ADR-0001
  • api/: Go module, passportd (serve | migrate | keys generate), chi /healthz, goose + sqlc wired with migration 0001
  • web/: Next.js (TS strict, Tailwind, App Router) with landing page
  • docker-compose (Postgres 17), Makefile, .env.example, .claude/settings.json
  • GitHub Actions CI (Go vet/lint/test + web tsc/eslint/build)
  • Non-code, founder: register Shopify Partner account + create dev store + apply for protected customer data access (longest external lead time — do this now)

Phase 1 — Schema + auth + sellers (1–1.5 wk)

  • Full core schema migrations: users, sellers, seller_members, seller_identifiers, storefront_connections, sync_runs, raw_documents, reputation_events, score_snapshots, signing_keys, attestations, api_consumers, api_keys, api_usage_daily, webhook_subscriptions
  • Clerk integration: web components + Go JWT middleware (JWKS)
  • Signup → seller + passport auto-created with slug; profile endpoints
  • RFC 7807 error envelope, slog request logging, request-id middleware
  • Integration tests vs Postgres (guarded by TEST_DATABASE_URL)
  • ADR-0002 data model, ADR-0005 Clerk auth

DoD: signup → session → GET /api/seller round-trip covered by tests.

Phase 2 — Connector framework + Shopify ingestion (1.5–2 wk)

  • Connector interface + shared ingest HTTP client (retry/backoff, rate-limit respect, PII stripping, token redaction) (pulled forward, Aug 2026 — ADR-0007; api/internal/connectors, api/internal/ingest)
  • Etsy, eBay, and TikTok Shop connectors: OAuth helpers, typed fetch, normalizers, synthetic fixtures (pulled forward, Aug 2026; go-vcr re-record + live wiring land when the founder-track approvals arrive; eBay account-deletion webhook handler ships unit-tested and mounts at Phase 6 deploy)
  • Shopify OAuth connect flow; AES-GCM encrypted token storage
  • River worker: backfill (orders, disputes) with pagination, rate limits, cursors in sync_state; raw responses verbatim into raw_documents (buyer PII stripped)
  • Idempotent normalizer: raw docs → reputation_events (re-run = no-op)
  • Incremental sync (periodic) + webhook stubs
  • Judge.me connector #2 for reviews (Shopify has no native reviews)
  • go-vcr fixture tests from a real dev store

DoD: real dev store → events in Postgres; re-run backfill is a no-op; tokens never appear in logs.

Phase 3 — Scoring + attestations (1 wk)

  • Score engine v1: Bayesian rating mean, Wilson dispute bound, volume/recency/diversity/tenure; confidence separate; golden tests (pulled forward during the July 2026 UX cycles — api/internal/score)
  • score_snapshots after sync; skip when inputs_hash unchanged
  • Ed25519 attestations (JCS canonical payloads, domain-separated), hash-chain + JWKS primitives, JWKS endpoint on passportd (pulled forward — api/internal/attest; the persisted append-only log, POST /v1/verify, and revocation still land here)
  • ADR-0003 scoring, ADR-0004 attestation format (write from the shipped code + /docs/verification copy)

DoD: sync → snapshot → attestation verifiable with only the published public key.

Phase 4 — Public passport + badge + dashboard (1.5 wk)

  • /p/[slug] public page: ISR + on-demand revalidation, renders without client JS, JSON-LD AggregateRating, per-platform provenance (design + copy shipped as the static /p/demo sample during the UX cycles; this item becomes "wire it to real data")
  • Badge: public/embed.js → iframe + backlink; static SVG route (SVG badge route + embed snippet shipped for the sample; embed.js iframe variant still to do)
  • Dashboard: connections/sync status, score chart, embed snippet, publish toggle
  • DNS TXT domain verification for seller_identifiers
  • GDPR SellerDeletionJob + dashboard delete flow

DoD: connect store → shareable page + badge pasted into a random HTML file renders live score.

Phase 5 — Platform API + monetization surface (1 wk)

  • /v1/passports/{id}, /v1/passports/lookup, /v1/.../score (+ inline attestation), /v1/.../attestations
  • API keys (rp_live_/rp_test_, hashed), token-bucket rate limits, api_usage_daily metering
  • Sandbox sellers seeded for rp_test_ keys
  • docs/api/openapi.yaml complete + Fumadocs rendering + reference verifiers (TS/Go)
  • CSV import fallback (csv_self_reported trust level)

DoD: a stranger with a test key can query and verify a sandbox passport from public docs alone.

Phase 6 — Launch prep (1–1.5 wk)

  • Deploy: passportd on Fly.io/Render, Postgres on Neon (→ RDS later), web on Vercel
  • Mount + deploy the eBay marketplace-account-deletion webhook on the production HTTPS origin (/webhooks/ebay/account-deletion; handler is built and unit-tested — this is the prerequisite for the eBay production keyset)
  • Secrets in platform secret store; signing key generated in prod, never in git
  • Backups, Sentry, uptime check, docs/ops/ runbook
  • Landing page + waitlist; privacy policy + ToS
  • Onboard 3–5 design-partner sellers + 1–2 API-consumer prospects

Non-code founder track (run alongside phases)

  • Shopify Partner + protected-customer-data application — Phase 0, now
  • Etsy developer application — now (2–4+ week manual review, no sandbox). Personal App "Reputation Passport"; description: imports a seller's OWN shop history (receipts + reviews) read-only via OAuth with explicit consent, read scopes only, buyer PII stripped before storage, no data resale; include privacy-policy + OAuth callback URLs. The provisional key works against your own shop immediately — use it to record real fixtures before approval.
  • eBay developer account + keysets — now (sandbox keyset immediate; production gated). Create the sandbox keyset for fixture recording. Decide the webhook URL (e.g. https://api.<domain>/webhooks/ebay/account-deletion) and generate + store EBAY_WEBHOOK_VERIFICATION_TOKEN; the production keyset can only be enabled after the Phase 6 deploy.
  • TikTok Shop Partner Center — now (business verification + app review, region-scoped). Register on partner.us.tiktokshop.com; verify the legal entity (check sole-proprietor eligibility first); start with a custom app (named sellers) for the design-partner pilot, public app before GA; US region first.
  • Paste docs/ops/connector-env.example into .env.example (agent tooling is denied write access to .env*).
  • Design-partner seller outreach list — start Phase 3, don't wait for polish
  • Pricing hypothesis doc (per-query vs monthly tiers) — validate with API design partners in Phase 5
  • Name/domain/trademark check
  • GDPR-lite legal review before launch