Trusted Tech Leader/ Case studies

Case study · AI & automation

AI-assisted supplier catalog sync platform

Connects supplier APIs and feeds to one product and pricing format, with AI-drafted connector specs and field mappings, and CSV export.

Sector
Promotional products and apparel supply
Category
AI & automation
Maturity
In active development; deployable service with container and deploy config and an automated test suite covering the API, connector, script-runner and credential logic

At a glance

Who it's for
Operations and catalog staff who onboard suppliers and keep product data current.
Core stack
Node.js, TypeScript, PostgreSQL, OpenAI
What sets it apart
An onboarding workflow that turns supplier API documents into tested, repairable connectors feeding one normalized CSV export.
On this page

What it looks like in use

The vendor list a catalog team works from, and the guided steps for adding a new supplier.

Catalog console
VendorsConnected suppliers and the freshness of their catalog data.+ Add Vendor
Vendor list
Sample Caps Ltd
Australia, priority HighUp to date
Sample Apparel Co
USA, priority MediumNeeds Update
Sample Drinkware
UK, priority LowUp to date
Sample Bags Pty
New Zealand, priority MediumNeeds Update
Check for UpdatesGet Decoration DataGet Product Data
Add New Vendor
1 DocumentationDone
2 ConnectDone
3 Map fieldsIn progress
4 ReviewNext
Map vendor fields to the catalog format
skuSKU
item_titleProduct name
Illustrative screen sample data, not client data

Real screens from the working product (sample data)

Vendor list showing six sample suppliers with their region, priority, update status and last sync date.
Real screen, sample data Each supplier shows how fresh its catalog is, with one-click update checks.
Setup step matching a sample supplier's product fields to the standard catalog fields.
Real screen, sample data Setup step where a supplier's fields are matched to the standard format; this draft was pre-filled.

Adding a supplier, step by step

  1. Priya adds a new supplier

    She enters the supplier name and region in a short form.

  2. She uploads the supplier documents

    The supplier's own instructions go in as a PDF, so nobody has to retype them.

  3. AI drafts the setup, she checks it

    AI reads the supplier's documentation and proposes how its fields fit the standard format; for script-based suppliers, a coding agent writes the sync script from a written contract. Priya reviews it all.

  4. She tests it with real sample rows

    Before saving, she checks the connection and previews a few real products.

  5. Updates are checked, then downloaded

    She checks for updates and downloads product or decoration data as CSV; long downloads run as tracked background jobs she can watch.

The challenge

Businesses that resell decorated apparel and promotional goods pull catalogs from many suppliers. Each supplier exposes a different API, auth scheme and field vocabulary, with separate decoration price breaks.

Onboarding one supplier usually means a developer reading its documentation and hand-writing an integration. The project records the pain points explicitly: very large catalogs, OAuth refresh tokens that invalidate on use, APIs with no change detection, and silent failures when a script reads the wrong source field names.

The solution

A web console and Node API where an operator registers a supplier, uploads its API documentation as a PDF and lets AI read it to draft the connector spec and field mapping. For script-based suppliers, any AI coding agent writes the sync script from a written contract, and the platform's AI identifies the credential fields a script needs and repairs failing scripts. The operator tests the connection and previews sample rows.

Source fields are mapped onto a fixed destination schema, split into product and decoration outputs. Decoration output supports up to 25 price breaks, and mapped data is exported as CSV on demand. A retrying queue worker for scheduled syncs is built into the service; operator-triggered checks and exports currently run on demand. A written contract guide lets any external coding agent produce compatible supplier scripts.

For your technical teamhow it works under the hood

Mechanism: from supplier docs to an on-demand check and export

Supplier onboarding and sync runSequence diagram with five participants: operator console, REST API, AI analysis, connector engine and supplier API. Step 1: the operator registers a supplier and uploads its API documentation PDF. Step 2: the API has the AI layer parse the PDF and draft a spec and field mapping. Step 3: the draft returns for review. Step 4: the operator tests the connection and previews sample rows. Step 5: the API calls the connector engine directly to run an update check or export on demand. Step 6: the engine fetches the catalog data from the supplier API. Step 7: the mapped rows return to the API and reach the operator as a CSV file.Operator consoleREST APIAI analysisConnector engineSupplier APIRegister supplier,upload API docs PDF1Parse PDF; draft specand field mapping2Draft for review3Test connection,preview sample rows4Run update checkor export on demand5Fetch catalogdata6Mapped rows returnedas a CSV file7
Setup is human-reviewed: the AI drafts, the operator tests. Once approved, update checks and exports run on demand through the connector engine, and every operator action is logged to a per-supplier activity trail, so failures are visible instead of silent.

Key features

What the system does, as built in the codebase.

  • 01

    Vendor registry

    One record per supplier with region, priority, status, spec, mapping and last-update markers.

  • 02

    AI documentation analysis

    Uploaded PDF documentation is parsed and read by AI to draft the connector spec (endpoints, auth) and field mapping.

  • 03

    Script-based connectors

    Python sync scripts, written by any AI coding agent from a written contract, are analyzed and tested in a child process with a timeout; the platform's AI identifies the credential fields a script needs and repairs scripts that fail.

  • 04

    Fixed destination schema

    Each source field is routed to a product or decoration output, with separate decoration mappings.

  • 05

    Connection test and live sample fetch

    Verify credentials and preview real records before saving.

  • 06

    Change detection

    A per-supplier update check tells the operator whether a catalog changed since the last download, and flags APIs that cannot report changes.

  • 07

    Credential rotation persistence

    Scripts can report refreshed tokens, which are stored for the next run.

  • 08

    CSV export and setup wizard

    A guided setup wizard in the browser console, a searchable, filterable and sortable suppliers table, a per-supplier activity trail with Slack alerts on failed checks, and CSV export of mapped rows.

How it fits together

From a supplier's documentation to a normalized CSV export.

  1. Operator consolevanilla JS wizard
  2. REST APIExpress and Helmet
  3. AI analysisLLM and PDF parsing
  4. Connector engineAPI fetch and Python scripts
  5. Normalized CSV exportmapped on demand, not stored
  6. Queue workerbuilt, not yet wired to the console
The operator console calls a REST API to set up and test suppliers. The API asks an AI layer to draft the spec. The API calls the connector engine directly, which fetches from the supplier and returns mapped rows as a CSV export; they are not stored. PostgreSQL holds suppliers, specs, field mappings, credentials, the job ledger and the activity log. A retrying queue worker for scheduled syncs is built but not yet driven from the console.
  • The console talks to the API for setup and testing; the API calls AI for spec drafting.
  • The API runs the connector engine directly for update checks and exports; long downloads run as in-process tracked jobs the console polls.
  • The queue worker (BullMQ with retries and per-run records) is built but not yet wired to the console.

Implementation notes

Engineering decisions worth knowing about.

  1. Retrying queue worker (not yet wired)

    A Redis-backed BullMQ queue with 3 attempts, exponential backoff and per-run records is built, with a worker started alongside the API process. Nothing enqueues from the console yet: update checks run synchronously in the request, and product, decoration and CSV exports run as in-process tracked jobs polled by the client.

  2. Flexible schema

    PostgreSQL with JSONB for specs and mappings, versioned connector specs marked as preset, AI or manual, and a sync job ledger.

  3. Incremental SQL migrations applied at start-up

    Incremental SQL migrations are applied in order when the service starts.

  4. Credential handling

    Credentials are kept in a dedicated column, never returned to the console list view, and only obfuscated rather than strongly encrypted; moving to a managed key store (KMS or vault) is flagged in the code before production.

  5. Large-catalog handling

    The script timeout is configurable for very large catalogs.

  6. Operational basics

    Helmet security headers, Winston logging, a per-supplier activity log and Slack alerts on failed checks. A Vitest suite (about 130 cases) covers controllers, services, the script runner and credential handling.

  7. Containerized setup

    Docker Compose for local Postgres and Redis, and a Railway build config.

Technology stack

Taken from the project's dependency and config files.

Backend
  • Node.js
  • TypeScript
  • Express
  • Helmet
  • Winston
  • Multer (PDF upload)
  • Vitest
Queue
  • BullMQ
  • Redis (ioredis)
Data
  • PostgreSQL
  • JSONB mappings
AI
  • OpenAI SDK
  • pdf-parse
Connector scripts
  • Python
Frontend
  • Vanilla JavaScript SPA served by the API
Infrastructure
  • Docker
  • Docker Compose
  • Railway
For your technical teamtechnology layers

Technology stack by layer

Supplier sync platform technology stack by layerLayered stack diagram. Frontend: a vanilla JavaScript single-page app served by the API. Backend: Node.js, TypeScript, Express, Helmet and Winston. AI and connectors: OpenAI SDK, pdf-parse and Python scripts. Queue: BullMQ and Redis. Data: PostgreSQL with JSONB mappings. Infrastructure: Docker, Docker Compose and Railway.FrontendVanilla JavaScript SPA served by the APIBackendNode.jsTypeScriptExpressHelmetWinstonAI andconnectorsOpenAI SDKpdf-parsePythonQueueBullMQRedis (ioredis)DataPostgreSQLJSONB mappingsInfrastructureDockerDocker ComposeRailway
The console and API are one Node.js service. Update checks and exports run in-process; the BullMQ and Redis queue and worker are built for scheduled syncs but not yet wired. PostgreSQL holds specs, mappings and run history.

Business value

What the system enables. No numbers are claimed.

  • Drafts the connector and mapping from the supplier's documentation, so a developer starts from a reviewable draft.
  • Gives one consistent product and decoration-pricing format regardless of supplier quirks.
  • Every operator action is logged to a per-vendor activity trail.
  • Lets operators use a guided setup, and lets external coding agents build compatible scripts through a documented contract.

Need a system like this built?

Tell us what it needs to do and we will scope it with you on a call.

Discuss a build