Pearl

Pearl is a source-available product-data operating system for commerce teams.

It turns messy supplier inputs such as PDFs, CSVs, and spreadsheets into structured product drafts, routes them through human review, and prepares approved import to a commerce system of choice.

Take the example of a merchant who turns a supplier's weekly PDFs and spreadsheets into a repeatable catalog pipeline that detects changes, stages product updates, routes low-confidence fields for review, and prepares the approved work for Shopify import.

Architecture

TypeScript monorepo with four apps and shared packages:

apps/
  web/        → Next.js — operator dashboard, review workflows, auth
  api/        → Hono — ingestion endpoints, webhooks, external API
  worker/     → Inngest — OCR, extraction, reasoning, write-back workflows
  agent/      → Eve — future Pearl agent surface

packages/
  ai/         → Model adapters, prompt builders (Vercel AI SDK)
  core/       → Domain logic, product state machine, business rules
  db/         → Drizzle ORM schema, queries, migrations
  ingestion/  → Document parsing, OCR wrappers, file handling
  schemas/    → Zod contracts for events and API boundaries

Stack: Next.js, Hono, Inngest, Eve, Postgres, Drizzle ORM, Vercel AI SDK, Mistral OCR, S3-compatible storage.

System Shape

• End-to-end ingestion from supplier files into normalized product candidates
• A clean split between web UI, API, worker, domain logic, schemas, storage, and model adapters
• Durable workflow orchestration for OCR, reasoning, retries, and review handoff
• Fail-fast AI configuration instead of silent placeholder behavior
• Human-in-the-loop approval before write-back
• Source-grounded review data and confidence signals
• Package boundaries that keep the workflow understandable and extensible

Local Development

Prerequisites: Node.js 22+, pnpm 10+, Docker. The Eve agent workspace requires Node.js 24+.

# 1. Install dependencies
pnpm install

# 2. Configure environment
pnpm onboard

# 3. Start everything (infra + apps)
pnpm dev

pnpm dev automatically:

• Starts Postgres, MinIO, and Inngest via Docker Compose
• Starts Portless and maps stable HTTPS local URLs (web.localhost, api.localhost, worker.localhost)
• Waits for services to be ready
• Creates the database and pushes the schema
• Launches web (Next.js), api (Hono), and worker (Inngest) concurrently

Local services:

Service	URL
Web	http://web.localhost:1355
API	http://api.localhost:1355
Inngest DevUI	http://localhost:8288
MinIO Console	http://localhost:9001
Postgres	localhost:5433

The API exposes an OpenAPI 3.1 spec at http://api.localhost:1355/openapi.json.

Seeded local login:

Email: admin@pearl.test
Password: password
Workspace: /demo

Other commands

pnpm test           # Run tests (vitest)
pnpm build          # Build all packages
pnpm typecheck      # Type-check all packages
pnpm lint           # Lint
pnpm check          # Required local quality gate
pnpm agent:dev      # Run the Eve agent workspace
pnpm db:prune       # Clear all local database rows
pnpm db:push        # Push schema changes
pnpm infra:down     # Stop all Docker services

Deployment

Pearl deploys to AWS via SST.

# Set secrets
sst secret set DatabaseUrl "postgres://..."
sst secret set BetterAuthSecret "..."
sst secret set MistralApiKey "..."
sst secret set LlmApiKey "..."
sst secret set InngestEventKey "..."
sst secret set InngestSigningKey "..."

# Deploy
npx sst deploy --stage production

SST provisions:

• S3 bucket for file storage
• Lambda function for the API (Hono)
• Lambda function for the Worker (Inngest)
• Next.js deployment for the web app
• Postgres is provisioned externally (Neon, Supabase, RDS, etc.)

License

The source is available for personal, educational, evaluation, and internal use.

You may use and adapt it for your own workflows, but you may not offer Pearl, a hosted version, or a substantially similar product-data-operations service as a business without separate permission. See LICENSE.