Organizational Structure

Authorized Brands

ADAW LLC maintains authorized distribution agreements with 32+ brands across multiple product categories including health & household, beauty & personal care, grocery, and home & kitchen.

Brand Relationship Overview

How Brand Data Integrates with DistroTrack

When the scanner discovers eligible products, it automatically detects and tracks the brand associated with each listing. This data feeds into the Brands tab, which provides:

• Brand-level analytics: Total products, average margins, and revenue estimates per brand
• Ungated highlighting: Brands we are authorized to sell are visually highlighted for quick identification
• Product drill-down: Click any brand to see all eligible products from that brand with full competitive analysis
• Export capabilities: Export brand-level data for sourcing and purchasing decisions

Compliance Overview

ADAW LLC maintains comprehensive compliance across all operational jurisdictions, ensuring legal and regulatory adherence for all distribution and sales activities.

Compliance Practices

What Is ADAW Scanner?

ADAW Scanner is a fully automated Amazon FBA product-intelligence tool for wholesale and online-arbitrage sellers. A background worker continuously enriches a shared catalog of 500K+ Top Seller ASINs with Keepa data; when a tenant runs a scan, the system checks each ASIN for the seller's specific eligibility, pulls live SP-API pricing, fees, and offers, scores the result, and surfaces ranked Green-light winners.

Unlike manual product research (clicking through Amazon listings one by one), ADAW Scanner automates the entire pipeline. It has one scan mode — Top Sellers — backed by the shared catalog:

The end result is a ranked list of eligible products with margin, fees, competition, sales-velocity estimates, and investment recommendations — usually delivered overnight while you sleep.

Alerts & notifications: Discord webhooks fire for high-quality Green Light products (score 7.0+ with 100+ monthly sales). Browser notifications fire on scan completion and Green-light batch discoveries.

How Scanning Works

Top Sellers is the only scan mode (April 2026 pivot). Each scan runs against a shared, pre-enriched catalog of 500K+ ASINs that the enrichment worker maintains in PostgreSQL — the scanner itself never calls Keepa during a scan. The pipeline runs as four phases per tenant:

Phase 1 — Seed the queue

When a tenant clicks Scan, _populate_scan_from_shared_catalog() in finder.py copies a slice of the shared catalog into that tenant's scan_asins table. ASINs already checked recently are skipped. Zero Keepa tokens are spent here — everything the scanner needs (BSR, monthly_sold, drops, trends, prices) was already enriched in shared_catalog.

Phase 2 — Eligibility check (per-ASIN, serial)

_scan_phase_eligibility() pulls 100 ASINs at a time from scan_asins and runs Amazon's getListingsRestrictions for each one with a 0.2 second gap (the SP-API rate limit). Roughly 92% of ASINs come back ineligible (gated, restricted brands, excluded categories) and skip the rest of the pipeline. The remaining ~8% continue.

Phase 3 — Wave 1 (pricing + catalog, parallel)

For each eligible ASIN, two SP-API calls run in parallel via a 2-worker ThreadPoolExecutor:

Both endpoints are rate-limited at 0.5 req/sec, so wave 1 takes ~0.5 s per ASIN.

Phase 4 — Wave 2 (fees + offers, parallel)

Wave 2 fires the two most expensive SP-API endpoints in parallel:

These are limited to 0.5 req/sec each, so wave 2 takes ~2 s per ASIN. After wave 2, the result is scored and written to checked_asins.

Early skip-outs

Wave 2 is skipped for ASINs that clearly won't profit, saving ~50% of the SP-API call budget on bad listings:

Even early-skipped products still get basic data stored: estimated_monthly_sales, amazon_on_listing, fba_seller_count, buy_box_price, buy_box_seller. Realistic throughput is 30–55 ASINs/minute depending on the eligibility rate.

Sales estimation tiers

Monthly-sales estimates come from the shared_catalog data the enrichment worker already populated. Each estimate carries a confidence tier that's used as a multiplier on the Sales Velocity score component:

BSR Formula (NONE-tier fallback)

When neither badge nor drops are available, estimate_monthly_sales(bsr, category) uses a power-curve calibrated against SellerAmp SAS ground truth:

Category-specific (factor, exponent) pairs are defined for ~27 categories (e.g., Home & Kitchen: 114069 × BSR^-0.77; Electronics: 237841 × BSR^-0.75). The formula requires the root category BSR from Keepa — subcategory BSRs from SP-API produce wildly inaccurate numbers.

Scoring & Green Light System

Every eligible product is scored using the Green Light Score, a composite rating based on real-world arbitrage viability criteria derived from extensive SellerAmp SAS analysis.

Hard Rejects (Instant Red)

This condition immediately disqualifies a product with a score of 0 (Red), regardless of all other criteria:

Weighted Components (0-10 scale)

The total theoretical maximum is ~11.0 points, clamped to 10.0. Products without Keepa enrichment are rescaled from 0–9.5 to 0–10.0 so they aren't unfairly capped below the Green threshold while their Keepa data is still being fetched.

Sales Estimation Tiers

The confidence factor on Sales Velocity comes from where the monthly-sales number was sourced:

Penalties

Score Labels

Top Opportunities Quality Gates

Products must pass ALL of these filters to appear in Top Opportunities:

Opportunity Score Formula

Products that pass all quality gates are ranked by a composite opportunity score:

Keepa Multipliers

If Keepa data is available, the base score is multiplied by trend factors:

The top 10 products by opportunity score are displayed on the Overview tab. Scoring is continuous (0–10) plus the Green / Yellow / Red label — there is no letter-grade overlay; ranking is by raw opportunity score.

Category Intelligence

After running a Top Sellers scan, the Insights tab shows category-level analytics including hit rates, average margins, competition levels, and price sweet spots. Use this data to understand which product categories offer the best opportunities.

Prerequisites

Step 1: Amazon SP-API Setup

The scanner uses Amazon's Selling Partner API for all product data. You need 6 credentials:

1. Register as SP-API Developer: Go to sellercentral.amazon.com → Apps & Services → Develop Apps → Register as developer. Choose "Self-authorization" (you're accessing your own seller account).
2. Create an IAM User: In the AWS Console, create an IAM user with sts:AssumeRole permission. Save the Access Key ID and Secret Access Key.
3. Create an IAM Role: Create an IAM role with a policy that allows execute-api:Invoke on arn:aws:execute-api:*:*:*. Set the trust policy to allow your IAM user to assume the role. Copy the Role ARN.
4. Create an LWA App: In Seller Central → Develop Apps, create a new app. After approval, note the LWA Client ID and LWA Client Secret.
5. Self-Authorize: Authorize the app on your own seller account. This generates a Refresh Token.
6. Get your Seller ID: In Seller Central → Account Info → Your Merchant Token (also called Seller ID).

You now have these 6 values:

Also set your marketplace and seller:

Step 2: Supabase Auth Setup

Supabase provides user authentication (login/logout, JWT tokens, password reset). It's free for small projects.

1. Go to supabase.com and create a free account.
2. Create a new project. Choose a name and set a database password (you won't use the DB directly).
3. Go to Settings → API and copy:
   • Project URL → this is your SUPABASE_URL
   • anon / public key → this is your SUPABASE_ANON_KEY
   • JWT Secret (under "JWT Settings") → this is your SUPABASE_JWT_SECRET
4. Go to Authentication → Providers and ensure Email is enabled.
5. Go to Authentication → Users and create a user with email + password. This will be your login credential.

Step 3: Keepa API Setup (Optional)

Keepa provides 90-day historical data (price trends, sales rank, competition changes). Without it, the scanner still works but scores max at 8/10 instead of 10/10 (the Keepa Trends component adds up to 2.0 points).

1. Go to keepa.com and create an account.
2. Subscribe to the API Starter Plan (€49/mo). This gives you 20 tokens/minute.
3. Go to your API settings and copy your API key.

Token budget: Each product query costs 1 token. At 20 tokens/min you can enrich ~1,200 products/hour.

Step 4: Clone & Install

The requirements.txt includes: flask, python-amazon-sp-api, gunicorn, PyJWT, keepa, numpy, python-dotenv, psutil.

Step 5: Configure Environment Variables

Create a .env file in the project root with all your credentials:

Step 6: Run Locally

Open http://localhost:5000 in your browser. If SUPABASE_JWT_SECRET is empty, you'll be logged in automatically.

The SQLite database (checked_asins.db) is auto-created on first run with all required tables and schema migrations.

Step 7: Deploy to Railway

1. Push your code to a GitHub repository.
2. Go to railway.app and create a new project. Choose "Deploy from GitHub repo" and select your repository.
3. Add a persistent volume: In your Railway service, go to Settings → Volumes → Add Volume. Mount it at a path like /data. Set DB_PATH=/data/scanner.db so the database survives redeploys.
4. Set environment variables: In Settings → Variables, add all the env vars from Step 5 (with real values this time, including SUPABASE_JWT_SECRET).
5. Add a custom domain (optional): In Settings → Networking → Custom Domain, point your domain to Railway.
6. Railway auto-deploys on every push to main. The Procfile tells Railway how to start:
   web: gunicorn dashboard:app --bind 0.0.0.0:$PORT --workers 2 --timeout 120

Step 8: Verify Everything Works

Complete Environment Variables Reference

Project File Structure

How It Works

Top Sellers is the only scan mode (April 2026 pivot). It runs against the global shared_catalog — a pre-enriched pool of 500K+ Amazon best-selling ASINs that the enrichment worker keeps fresh independently of any tenant's scan. When you click Scan, the system seeds a per-tenant queue from the shared pool and runs SP-API eligibility checks. The scanner itself spends zero Keepa tokens.

Process Flow

1. Seed — _populate_scan_from_shared_catalog() copies a slice of shared_catalog into your tenant's scan_asins queue. Already-checked ASINs are skipped. Zero Keepa cost.
2. Eligibility — SP-API getListingsRestrictions runs serially per ASIN (0.2s gap, 100 ASINs per batch). Roughly 92% are filtered out as ineligible.
3. Wave 1 — For eligible ASINs: getCompetitivePricing + getCatalogItem in parallel (2-worker thread pool).
4. Wave 2 — getMyFeesEstimate + listOffersByASIN in parallel. Skipped for sale price < $12 or seller count > 15.
5. Score & persist — Compute Green Light Score 0–10, write to checked_asins, fire Discord webhook for new Greens.

Token Cost

Why This Design?

• One Keepa refresh covers every tenant. Adding the 100th tenant adds zero Keepa cost — only their own SP-API eligibility calls.
• Deterministic scan time. No more waiting on Keepa's bestseller endpoint mid-scan; the catalog is always pre-warmed.
• Lower failure surface. Keepa rate limits / outages don't block scans — the enrichment worker absorbs them.

Safeguards

• Stacking prevention — Won't start if >100K unchecked ASINs are already queued for your tenant.
• Resume support — Stop and Scan again resumes from where you left off; Restart wipes scan data and starts fresh while preserving session history.
• Tenant isolation — Each tenant's queue and results are filtered by tenant_id on every query.
• Legacy fallback — If shared_catalog is empty (rare; happens on first SQLite/dev boot), the scanner falls back to the live-Keepa bestseller path. This is dev-only; production always has a populated catalog.

Technology Stack

ADAW Scanner is built with a modern, lightweight stack designed for reliability and speed:

Architecture Overview

The system consists of several core files:

Data Flow

The web service spawns finder.py as a subprocess when a scan starts. The scanner reads pre-enriched data from shared_catalog, runs SP-API eligibility per ASIN, and writes results back to PostgreSQL. The dashboard polls the DB on an adaptive interval. The enrichment worker is a separate Railway service running the same image with ENRICHMENT_MODE=1; it owns every Keepa API call and writes to shared_catalog independently.

Key Processes

Shared Catalog & Enrichment Service

A background enrichment service (enrichment.py) runs as a separate Railway worker, maintaining a global shared_catalog table with Keepa sales data for 500K+ ASINs. All tenants share this data — ADAW absorbs the Keepa API cost so customers don't need their own Keepa subscription. The service refreshes on a configurable interval (default 1 hour, ENRICHMENT_INTERVAL_HOURS) at 1 token/ASIN with a default 80,000-token daily budget.

• Web service — dashboard.py via Gunicorn (serves UI + API + scanner subprocess)
• Enrichment service — enrichment.py (background Keepa loop, sole token spender)
• PostgreSQL — shared database between both services

Frontend Build Pipeline

Production serves two minified bundles built by node build.js: app.min.js (~200 KB raw, ~55 KB gzipped) and app.min.css (~234 KB raw, ~41 KB gzipped). Development serves the unminified modules separately so source-mapped debugging works. Both modes append ?v=<mtime> for cache-busting; production also serves them with Cache-Control: immutable for one-year browser caching.

System Diagram

Two Railway services share one PostgreSQL database. The web service runs the dashboard and scanner. The enrichment service is the sole Keepa consumer and refreshes the shared catalog independently.

Scan Pipeline (Top Sellers, post-2026-04 pivot)

Top Sellers is now the only scan mode. When a tenant starts a scan, the system progresses through these phases:

Data Enrichment Cycle

The enrichment service runs independently on a 4-hour cycle, fetching fresh Keepa data for products in the shared catalog:

Sales Estimation Hierarchy

When displaying estimated monthly sales, the system uses verified Keepa data in priority order:

External Integrations

API Rate Limits & Performance

Amazon's SP-API enforces strict rate limits per endpoint. The scanner is designed to operate at maximum efficiency within these constraints:

Throughput Estimates

• Category discovery: ~4 pages/second (limited by Catalog Search rate)
• Eligibility checking: ~30-55 ASINs/minute (depends on how many pass the $12 threshold)
• Top Sellers scan: ~2 minutes for discovery (500K+ ASINs), then eligibility pipeline runs
• Keepa enrichment: ~1,200 products/hour (1 token/product, 20 tokens/min on Starter plan)

Dashboard API Endpoints

The Flask backend exposes 50+ authenticated API endpoints. All require a valid JWT token via the Authorization: Bearer header (except the public waitlist POST and /health endpoint).

Stats & Analysis

Products & Details

Insights & Analytics

Scan Control

Scan History & Sessions

Keepa & Enrichment

Export & Brands

Waitlist (Public)

Database & Data Model

Production runs PostgreSQL on Railway; the test suite uses SQLite (in-memory or on-disk file). All SQL is written in native PostgreSQL syntax (%s placeholders, ON CONFLICT, ILIKE, ::int casts). db.py contains a small SQLite shim that maps these PG-isms to SQLite equivalents in test mode only; production paths go straight to psycopg2 unchanged. All tables include a tenant_id column for multi-tenant isolation. The keepa_cache table is the exception — it is global (shared across all tenants) to avoid re-fetching the same ASIN data per user. Schema migrations run automatically on startup.

Table: checked_asins (Products)

The main products table. Every ASIN that has been evaluated is stored here, regardless of eligibility.

Table: scan_categories (Browse Tree)

Table: scan_asins (Discovery Queue)

Table: scan_sessions (History)

Table: scan_meta (Key-Value Store)

Table: waitlist (SaaS Signups)

Table: shared_catalog (Global Sales Data)

Table: watchlist (User Favorites)

Indexes

• idx_session on checked_asins(scan_session_id) — fast session-based product filtering
• idx_scan_categories_status on scan_categories(is_leaf, scan_status) — fast pending-category lookups
• idx_scan_asins_unchecked on scan_asins(eligibility_checked) — fast unchecked-ASIN batch fetching

Keepa Integration

Keepa provides 90-day historical data for every product, enriching the scanner's real-time data with trends and context:

• Price history: Track price stability via coefficient of variation (CV). CV < 0.15 = stable pricing, CV > 0.25 = volatile
• Sales rank trends: Identify products with improving (growing demand) or declining (shrinking demand) sales rank over 90 days
• Competition changes: Monitor seller count fluctuations — increasing seller count triggers a -1 scoring penalty
• Monthly sold estimate: Keepa's proprietary "bought in past month" badge data, often more accurate than BSR-based calculations
• Sales rank drops: Count of 30-day rank drops (BSR dips that indicate sales events)

How It Works

Keepa data is maintained by the Shared Catalog enrichment service (enrichment.py), which runs as a background Railway worker refreshing sales and price history continuously. Each product lookup costs approximately 1 Keepa token. ADAW absorbs the Keepa API cost, so users don't need their own Keepa subscription. The dashboard reads from the shared_catalog table first, falling back to per-tenant Keepa columns if unavailable. The Data Enrichment card on the Overview tab shows live coverage and freshness.

Token Budget & Rate Limits

The Keepa enrichment service is the sole owner of all Keepa API calls in production — no other code path calls Keepa. It runs as a separate Railway worker process (ENRICHMENT_MODE=1) and pulls from a per-tenant daily token budget that's synced with the tenant's plan.

Monthly Sold: 3-Tier Priority

The scanner extracts monthly sales data from Keepa using a 3-tier priority to get the freshest value:

Each tier is validated: value must be non-null and > 0 before use. If all three are missing, the scanner falls back to BSR-based estimation.

Live Refresh (update=1)

When the product modal requests live Keepa data, the enrichment worker processes the request via the enrichment queue. The Keepa API default is update=1, which refreshes data if it's older than 1 hour — matching SellerAmp SAS freshness.

Monkey-Patch for Keepa Library Bug #221

The official keepa Python library has a known bug (#221) where update_status() overwrites self.status from a proper Status dataclass to a raw Python dict, causing 'dict' object has no attribute 'refillRate' errors.

The scanner patches this in keepa_client.py with a replacement _safe_update_status() that detects dict corruption and reconstructs a proper Status dataclass with all attributes.

Numpy Type Safety (_safe_scalar())

Keepa returns numpy types (arrays, scalars) that fail Python boolean comparisons (if val and val > 0 raises "ambiguous truth value" errors). The _safe_scalar() utility converts numpy types to plain Python scalars before comparison. It handles: numpy integers/floats (.item()), single-element arrays, multi-element arrays (returns None), and passes through regular Python values unchanged.

Price & Rank Data Handling

• Prices stored in cents: Keepa stores all prices as integers in cents — divided by 100 for dollar values
• Price priority: Amazon price first, falls back to New (marketplace) price if unavailable
• Buy Box price: Extracted from stats index 17 (BUY_BOX_SHIPPING) in the current array
• Invalid values: -1 = out of stock/unavailable, NaN = no data. Both filtered before analysis
• Keepa epoch: Times stored as integer minutes since 2011-01-01 00:00:00 UTC

Deployment & Infrastructure

Railway Platform

The application is hosted on Railway, a modern cloud platform:

• Auto-deploy: Every push to the main branch on GitHub triggers an automatic deployment
• Build time: ~1-2 minutes for Docker image build
• Container creation: ~3-5 minutes for new container startup
• Total deploy time: ~5-7 minutes end to end
• Zero-downtime: Railway performs rolling deploys (new container starts before old one stops)
• Persistent volume: SQLite database stored on mounted volume (web-volume) that persists across deploys

Procfile & Gunicorn

The Procfile branches on ENRICHMENT_MODE so the same image powers two Railway services:

• Web service (default): Gunicorn with 2 workers, 120s timeout, graceful restart every 50 requests with ±10 jitter (prevents long-tail memory creep)
• Enrichment worker (ENRICHMENT_MODE=1): runs python enrichment.py, the sole owner of Keepa API calls
• $PORT is set automatically by Railway

Both services deploy from the same GitHub repo on every push to main; they're differentiated only by the ENRICHMENT_MODE env var on the worker service.

Environment Variables

All sensitive configuration is stored as Railway environment variables (never in code). See the From-Scratch Setup page for the complete reference table. Key groups:

Orphan Session Cleanup

When Railway redeploys, any running scan processes are killed. On startup, the application automatically calls _cleanup_orphaned_sessions() which:

1. Queries all sessions with status = 'running'
2. Updates each to status = 'stopped' with stopped_at = current timestamp
3. Logs the count and IDs of orphaned sessions found

This prevents stale "Running" indicators on the dashboard after a redeploy.

Database Persistence

The SQLite database (checked_asins.db) is stored on a Railway persistent volume. The DB_PATH environment variable points to the volume mount location. If DB_PATH is not set, the database is created in the script's working directory. The database is auto-created with all tables and indexes on first run via init_db().

Enrichment Service

The enrichment service runs as a separate Railway worker using the same GitHub repo but with ENRICHMENT_MODE=1 environment variable. The Procfile conditional routes to python enrichment.py instead of Gunicorn.

Required variables: DATABASE_URL, KEEPA_API_KEY, ENRICHMENT_DAILY_BUDGET, ENRICHMENT_INTERVAL_HOURS, ENRICHMENT_MODE=1

Discord Webhook Alerts

Set DISCORD_WEBHOOK_URL on the web service to receive Discord notifications for high-quality Green Light products (score 7.0+ with 100+ monthly sales). The webhook is non-blocking and fires from the /api/analysis endpoint during dashboard polling.

Authentication & Security

The dashboard uses Supabase Authentication (an open-source Firebase alternative) for user management.

Supabase Setup

To set up authentication from scratch:

1. Create a free project at supabase.com
2. Enable Email/Password auth in Authentication → Providers
3. Copy three values from Project Settings → API:
   • SUPABASE_URL — Project URL (e.g., https://xxxxx.supabase.co)
   • SUPABASE_ANON_KEY — Public anon key (safe to embed in frontend)
   • SUPABASE_JWT_SECRET — JWT signing secret (under Settings → API → JWT Secret)
4. Create your user account in Authentication → Users → Invite User

How Authentication Works

Email Allowlist

The ALLOWED_EMAILS environment variable restricts dashboard access to specific email addresses:

Comma-separated list. If empty or not set, all authenticated Supabase users can access the dashboard. If set, users whose email is not in the list receive a 403 "Access denied" response even with a valid JWT.

Local Development Mode

When SUPABASE_JWT_SECRET is empty or not set, the @require_auth decorator allows all requests through without authentication. This lets you develop and test locally without setting up Supabase:

authFetch() Flow

Every API call from the frontend JavaScript uses authFetch() instead of plain fetch():

Dashboard Tabs Explained

Overview Tab

Your command center. Surfaces live scan state and aggregate metrics:

• Scan Progress: Status pill (idle / running / stopped), pool size from shared_catalog, your tenant's checked count, eligible vs. ineligible split.
• Eligibility bar: Live progress bar tracking your tenant's queue burn-down. Throughput in ASINs/min plus an ETA.
• Last 5 Greens: A live feed of Green-light products discovered in the current session.
• Product Intelligence: Average profit per unit, average fee margin, Amazon presence, average competition, and the Green / Yellow / Red distribution.
• Data Enrichment: Coverage % of the shared catalog with fresh Keepa data, plus an ETA to full coverage at the current throughput.
• Top 10 Opportunities: Ranked by composite opportunity score (sales velocity × margin / competition factor) among products that pass all quality gates.

Products Tab

Sortable, searchable table of eligible products plus instant single-ASIN lookup:

• Lookup bar: Paste any ASIN or Amazon URL for a SellerAmp-style report in 3–6 seconds. Spends at most 1 Keepa token; zero if the catalog already has fresh data for the ASIN.
• Quick filter chips: Green Only, Hide Amazon Buy Box, Watchlist (starred), category, price range. Mobile-friendly tap targets.
• Search: Filter by product name, ASIN, brand, or category in real-time.
• Column sorting: Click any column header to sort ascending / descending. Default sort is score DESC.
• Product Modal: Click any row for the full report — per-seller forecast, competition analysis, Keepa history, fee breakdown, max-buy-cost calculator.
• SAS Export: ASIN-only or full CSV for SellerAmp / SAS workflows.
• Watchlist: Star products to save them across sessions; toggle the watchlist filter to show stars only.
• Keyboard shortcuts: / focus search, j/k row nav, Enter open modal, s toggle star, ? shortcut help.
• Mobile cards: Below 768 px the table converts to vertically-stacked cards.

Categories Tab

Aggregated category-level breakdown of the products you've checked. Each row shows the number of products checked in that category, how many are eligible, the hit rate, average score, and average margin — useful for spotting which categories yield the best opportunities for your seller account.

Brands Tab

Brand-level intelligence across all your scan data, using a two-pass detection algorithm:

• Pass 1 — Known Brands: Matches product names against a curated dictionary of brand keywords. Matched brands are labeled Ungated.
• Pass 2 — Auto-detected: For unmatched products, extracts the first meaningful word of the product name (filtering articles, colors, numbers). Labeled as auto-detected.
• Minimum 3 products: Brands with fewer than 3 listings are filtered out as noise.
• Deduplication: Case-insensitive merging (e.g., "CLOROX" and "Clorox" become one brand).

Each brand card shows product count, ungated status, parent company, categories, and all listings with prices, margins, sales, and scores. CSV export available.

Insights Tab

Strategic analytics across your scan results:

• Category Intelligence: Composite category score (0–100) blending hit rate, margin, sales volume, and competition.
• Price Sweet Spots: Distribution and green-rate across price bands ($10–15, $15–25, etc.).
• Competition Landscape: Average seller count by category, Amazon presence rates.
• Keepa Trend Analysis: Aggregated rank-trend and price-stability signals.

History Tab

Complete record of every scan session run by your tenant:

• Session cards: Timestamp, status (running / completed / stopped), duration, and result counts.
• Type badges: All scans now run in Top Sellers mode (the only scan mode after the April 2026 pivot). Older sessions may show legacy badges (FULL / TARGETED / SMART) for historical reference.
• Quality breakdown: Green / Yellow / Red counts per session.
• Drill-down: Click any session card to see its products.

Top Opportunities (on Overview)

The Overview tab features a Top 10 Opportunities section — the highest-ranked products that pass all quality gates: no Amazon on listing, no Amazon Buy Box, ≥5 sellers, ≥1 FBA seller, non-Red score, ≥$3 profit per unit. Each card shows the opportunity score and key metrics. Ranking is by raw opportunity score (sales velocity × margin ÷ competition factor) — there is no letter-grade overlay.

Help & Account & Docs

Help is the user-facing reference for filters, modal fields, scoring, and keyboard shortcuts. Account shows plan tier, usage, billing portal, Discord webhook setup, and tenant settings. Docs (admin only) is this comprehensive technical documentation hub.

FAQ & Troubleshooting

v3.0 — April 2026 (Current)

Architecture

• Shared Catalog: global shared_catalog table (550K+ ASINs) replaces per-tenant Keepa enrichment
• Enrichment Service: background worker (enrichment.py) on separate Railway instance
• Frontend: 14 JS modules + 5 CSS files, minified to 2 production bundles
• Hash Routing: deep-linkable URLs (#/overview, #/products, etc.)
• HTML Templates: product rows, history cards, opportunity items use <template> cloning
• Adaptive Polling: 2s during scan, 10s when idle (was fixed 5s)
• PWA: manifest.json + service worker for installable app experience

Features

• Watchlist/Favorites: star products, filter by watchlist, persisted per tenant
• Product Comparison: side-by-side view of 2-3 products
• Keyboard Shortcuts: /, j/k, Enter, s, %s for power users
• Interactive Charts: click quality/category/price bars to filter Products tab
• Browser Notifications: scan complete + Green Light batch alerts
• Discord Webhook: real-time alerts for Green products (score 7.0+, sales 100+)
• Mobile Card Layout: products table converts to cards on phones
• Loading Skeletons: shimmer placeholders during data loads

Accuracy

• Private Label Detection: -0.5 score penalty when avg sellers < 2.0
• Stale Badge Detection: CHECK 3 drops-vs-badge divergence (5x ratio)
• BSR Fallback: Keepa rank used when SP-API returns no BSR
• Keepa Price Validation: hide misleading prices that diverge >3x from sale price
• Top Opportunities: minimum 100 sales/mo gate added

Infrastructure

• Health Endpoint: /health for Railway monitoring
• Diagnostic Endpoint: /api/diagnostic/shared-catalog for catalog health
• Python Logging: structured logging module (replacing 444 print statements)
• Test Suite: 10 pytest tests (scoring, health, security)
• Security: removed hardcoded Discord webhook, env-var only
• Font Consistency: global font-family: inherit fix for all buttons/inputs

v2.0 — March 2026

Complete system overhaul: new scan modes, redesigned UI, cost optimizations, performance improvements, and 30+ bug fixes.

New Features

UI/UX Improvements

Performance Optimizations

Cost Architecture

The scanner uses two external APIs with usage-based costs. Our optimization strategy reduces total API calls by ~80% without sacrificing data quality.

SP-API Call Reduction

Keepa Token Optimization

The Shared Catalog architecture further reduces costs by 90%: one Keepa plan (~$100/mo) serves all tenants via the shared_catalog table, vs $500+/mo for per-tenant enrichment.

Per-Product API Cost Breakdown

Critical Fixes

UI/UX Fixes