descrybe/docs/getting-started.md

Getting started — operator checklist

Concise path for a local or staging operator: login → create/map feed → process → export.
Aligned with current web routes and API mounts (apps/api/internal/httpapi/server.go, v1.go).

First-time machine setup (Docker / Node / Go / migrate / ports / /readyz): README.md — Local setup (any OS).

Web	http://localhost:28472
API	http://localhost:28471
Postgres	localhost:5433 (docker compose → postgres:16-alpine)
Health	GET /healthz (liveness), GET /readyz (DB + worker heartbeat ≤60s)
OpenAPI	http://localhost:28471/api/v1/openapi.yaml · UI: /docs

Credentials and counts: demo-user.md. Do not use demo accounts in production. Never commit real .env secrets.

---

0. Bring the stack up

Canonical any-OS steps live in the README. Short path (Windows / macOS / Linux):

npm run setup                 # .env + Docker Postgres :5433 + goose migrate
npm install && npm run dev    # API :28471 + web :28472 + worker
npm run seed                  # optional demo login
npm run health                # /healthz + /readyz

Compose runs Postgres only. npm run dev / npm run dev:app include the worker (needed for process jobs and /readyz 200). npm run dev:backend is api+worker without web. npm run dev:api alone → /readyz 503.

/readyz 503 without a worker is expected (checks.worker=missing / stale, plus JSON reason). /healthz stays 200. Details: README troubleshooting.

After login (company admin): configure AI at /integrations/ai, marketing email at /integrations/email, stores at /stores. Do not rely on env copies or tmp placeholders for those secrets.

Seed demo login (after migrate; lands on Platform Demo — not A1):

npm run seed
# or: node scripts/seed-local.mjs
# or: pwsh -File .\scripts\seed-local.ps1

Optional password bootstrap for an existing user:

cd apps/api
go run ./cmd/migrator -postgres $env:DATABASE_URL -set-password "you@example.com:YourPassword"

---

1. First login

• Open /login → sign in → land on /dashboard
• Demo (seeded): demo@descrybe.local / DemoPass123! (alias demo@descrybe.test also works)
• Or /register for a fresh company (empty catalog)
• Confirm company in the shell (demo default: Platform Demo; A1 via a1-primary@descrybe.local)
• Optional: start the in-app tutorial from the dashboard (tutorial.md)

Session API: POST /api/auth/login, GET /api/auth/me, POST /api/auth/select-company.
CSRF: browser session uses cookie + X-CSRF-Token (Vite proxies /api → API).

---

2. Create (or open) a feed

UI:

Step	Where
Stores hub	/stores (Feed URL / CSV cards)
Add URL feed	/feeds?add=1&source=url
Add CSV file	/feeds?add=1&source=file
List / open	/feeds → Map → /feeds/{feedId}/mapping
Standard fields (recommended first)	/standard-fields → enable recommended

Checklist:

• Enable recommended standard fields on /standard-fields
• Create feed (name + public http(s) URL or CSV upload) — FTP/FTPS sync is not supported yet
• On mapping: Auto-map → Save mappings
• Sync (or Sync + Process sample on the mapping page)

Session API:

Action	Method
Create	POST /api/feeds (JSON or multipart with file)
Sync	POST /api/feeds/{id}/sync
Mappings	GET / PUT /api/feeds/{id}/mappings
Extract schema	POST /api/feeds/{id}/extract-schema
Sync + process sample	POST /api/feeds/{id}/sync-process-sample

Same shapes under /api/v1/... with Authorization: Bearer <api_key> (demo key in demo-user.md).

---

3. Process products

• Keep the worker running (npm run dev includes it; or npm run dev:worker / go run ./cmd/worker). Without it, jobs stall and /readyz stays 503.
• Open /products — use Unprocessed / raw if Processed looks empty
• Select raw products → process, or use mapping Sync + Process sample
• Watch jobs on /processing

Surface	Endpoint
Dashboard	POST /api/processing/jobs · GET /api/processing/jobs · GET /api/processing/jobs/{id}
Public API (legacy clients)	POST /api/v1/products/process (items[].ean or raw_product_ids) → 200 { data: { process_id, … } } · poll GET /api/v1/products/process/{id} until COMPLETED + items
Public API (flat jobs)	POST /api/v1/process → 202 flat ProcessingJob · GET /api/v1/process/{id} — not the same envelope as legacy

On legacy COMPLETED poll items[]: id is processed_products.id (legacy). Also returned additively: processed_product_id (same as id) and raw_product_id (raw_products.id) so dual-mode clients can correlate with raw_product_ids without guessing.

Cancel / retry: POST .../cancel or .../retry on dashboard /api/processing/jobs/{id} or flat /api/v1/process/{id} paths (legacy products/process is start+status only).

---

4. Export

• Open /export-feeds → create or open a template (Google Shopping / Meta / custom CSV|XML)
• Generate / Refresh the feed
• Copy the public poll URL into Merchant Center / partner importer
• Optional: export selected rows from /products (export dialog)

Surface	Endpoint
Create / list	POST / GET /api/export-feeds (also /api/v1/export-feeds)
Generate	POST /api/export-feeds/{id}/generate
Selected IDs	POST /api/export-feeds/{id}/export-products
Public download	GET /api/public/export-feeds/{token}.xml or .csv (no auth)

---

Minimal API smoke (after seed)

$H = @{ Authorization = "Bearer dk_demo_local_descrybe_test_key_v1" }
Invoke-RestMethod "http://localhost:28471/api/v1/feeds?limit=5" -Headers $H
Invoke-RestMethod "http://localhost:28471/api/v1/products?limit=1" -Headers $H

---

Related

Doc	Use when
README Local setup	First-time Docker/Node/Go/migrate; /readyz 503 without worker
demo-user.md	Demo email, API key, company IDs
tutorial.md	In-app guided tour steps
store-connectors.md	Woo / Shopify / feed URL / CSV / export
e2e-feeds-process-export.md	Historical API E2E notes (prefer Platform Demo + safe-test-fixtures.md)
process-and-sell-summary.md	Deeper process / EPREL / sell path
safe-test-fixtures.md	Demo vs A1 isolation (canonical)
qa-local-demo.md	Historical Local Demo Co QA (outdated naming)
ops-runtime.md	SMTP, sessions, encryption keys