← All documents

Vervoro — engineering handover

Vervoro — AI Operating System for e-commerce.

Vervoro is a multi-tenant operations platform for marketplace sellers: catalogue, stock, orders, warehouse work and channel integrations, sold as three plans (Core, Growth, Pro) plus a Vendor Central add-on. It is a clean rebuild, on Cloudflare's serverless platform, of the functionality proven in Seba Trade's in-house ERP (seba-erp). Seba Trade is the first tenant.

Status (2026-10-07): no application code yet. These documents are the complete handover to the build team; they were reviewed on 2026-10-07 and the findings fixed (reports in reviews/). Open owner questions are in Decisions.

Read in this order

Reading time: about two and a half hours.

The engineer NDA and IP assignment draft is in legal/; it must be signed before any of Seba's data is shared.

What is authoritative

1. Decisions: dated owner decisions. They override everything below.
2. docs/ defines what to build and the rules that cannot be broken.
3. seba-erp is the reference for how Seba works today: behaviour, edge cases, marketplace quirks. When a document says "seba-erp: lib/vendor-pricing.ts", read that file to understand the behaviour. Without access to the seba-erp repository, the same file is in reference/seba-erp/, a curated copy of 51 files including the full data model. A read-only login to the running seba-erp app shows the screens; reference/seba-erp/SCREENS.md maps every page to its Vervoro module and priority. Do not copy its architecture. It is single-tenant, keeps settings in one row, has no tests and runs as one long-lived Node process.

Who decides

• Engineers own every implementation choice that stays within these documents, including library choices marked "recommended". Record a change of a recommended choice in Decisions.
• The product owner decides scope, pricing, anything a customer would notice, and anything marked Fixed in the architecture.
• Product owner: Muhammet Surucu (owner of Seba Trade). Engineers: Yusuf Figanioglu and Tolga Sahin.

Maintaining these docs

Keep one fact in one place and link to it rather than copying. Update the docs in the same pull request as a behaviour change. Keep them short: if a document passes about four pages, split it or cut it.

← All documents

AGENTS.md — rules for AI coding agents on Vervoro

Copy this file into the application repository on day one and keep it current. It applies to code as well as to these docs.

Sources, in order of authority

1. docs/08-decisions.md: dated owner decisions. Only rows whose Status is Live (or Proposed and confirmed) apply; ignore superseded rows.
2. docs/ (01–13): what to build and the rules that cannot be broken. The data model is docs/12-data-model.md; permissions are docs/10-permissions.md; moving a customer's data in is docs/13-customer-migration.md.
3. seba-erp (read-only login to the app, and the copy in reference/seba-erp/): how Seba's business works today. Read it for behaviour and edge cases. Do not copy its architecture or patterns: singleton settings, globalThis caches, setInterval scheduler, plaintext secrets, unscoped queries, a hard-coded channel enum.

If two sources conflict, stop and ask. Do not quietly pick one.

Stack (see docs/04-architecture.md)

TypeScript only. Cloudflare Workers (web, jobs, mcp), Hono + Zod, React + Vite SPA, Drizzle with pg, Neon Postgres (London) through Hyperdrive with caching off, Better Auth (organization = tenant, own auth schema, twoFactor plugin), Queues, Workflows, Durable Objects, Workers KV (MCP OAuth grants), R2, Workers Logs + Issues, Logpush, Stripe. Don't add a server, VM, container or new infrastructure service without a decision entry.

• Worker config: compatibility_flags: ["nodejs_compat"] and a pinned compatibility_date in every wrangler.jsonc.
• Clients per request: create the pg client and the Better Auth instance per request or per job from the bindings, never at module scope; close the client with ctx.waitUntil(client.end()).
• Schedules: one dispatcher cron in the jobs Worker reads every module manifest's schedules. Never add a Cron Trigger per module.
• MCP: the mcp Worker serves /mcp* on the app host so consent can see the Better Auth session.

Commands

Fill these in on day 1 and keep them true; an agent without commands guesses.

Migrations

1. Change the Drizzle schema, run drizzle-kit generate, and read the SQL.
2. Add by hand, in the same migration: ALTER TABLE … FORCE ROW LEVEL SECURITY, the policy tenant_id = nullif(current_setting('app.tenant_id', true), '')::uuid for USING and WITH CHECK, and grants to the runtime role.
3. Only expand/contract changes: a migration must work with both the old and the new code.
4. Apply over Neon's direct URL as the owner role, never through Hyperdrive.
5. The CI catalogue check must pass: every table outside platform and auth has tenant_id, row security and forced row security.

Never

• Trust a tenant id from the client. The tenant comes from the session, a signed job message or an MCP token.
• Touch the database outside withTenant(tenantId, tx => …), or set the tenant with a session-level SET (Hyperdrive resets it; use set_config('app.tenant_id', …, true) inside the transaction).
• Do cross-tenant work any way except withPlatform(reason, …) and its named role. Never use the owner role or BYPASSRLS at runtime.
• Create a tenant table without tenant_id, forced RLS, composite tenant foreign keys and tenant-scoped unique constraints.
• Turn on Hyperdrive query caching, or write a tenant query without an explicit tenant_id = $1 filter.
• Run migrations through Hyperdrive, or create a preview database branch from anything except the masked seed.
• Let staging, or any connection in shadow mode, send anything to a real marketplace or customer. Shadow sends are stored as suppressed and never sent, not even when the connection later becomes active. A tenant with shadow connections sends no email or documents.
• Put a customer's unmasked import files, production query results, tokens or buyer personal data into an AI tool's context. Use the masked seed or synthetic data.
• Write stock tables from anywhere except the inventory service.
• Make a network call inside a database transaction.
• Send anything to a marketplace except through the outbox and an idempotent job.
• Blindly retry a non-idempotent external operation after a timeout. Read the native state first.
• Push physical stock to a channel, or push any quantity to an FBA (Amazon-fulfilled) listing. Push sellable stock, divided by the mapping's multiplier, to merchant-fulfilled listings only.
• Clamp a negative stock result to zero. Fail instead.
• Add money across currencies, or use floating point for money.
• Let AI or the ads engine change data without an approved proposal; return buyer personal data or unfiltered cost fields from an MCP tool.
• Store marketplace tokens unencrypted, or log tokens or buyer addresses.
• Serve an uploaded file inline from the app's origin.
• Check a plan name in code (if plan == "growth"). Check a module entitlement or a limit quantity instead; plans are data.
• Grant admin rights by default ("everyone is admin while no admin exists" is forbidden), let an Admin grant Owner, or let anyone change their own role.

Always

• Copy the shape of the reference module (modules/products, built first): manifest, routes, Zod schemas, requirePermission, audit entry, domain tests and isolation tests.
• Put a module behind its manifest: entitlement and enablement middleware on its mount point, and requirePermission(…) on every route.
• Write a test for each domain rule you implement (docs/05-domain-rules.md, using its rule ids in test names, e.g. S7 applies pack multiplier).
• Add every new route, job, export, file route and MCP tool to the tenant-isolation suite, and every warehouse-bound route to the warehouse-scope suite.
• Declare a new module's permissions in its manifest and add them to docs/10-permissions.md; until roles are decided, only Owner and Admin get them.
• Store idempotency keys per tenant and route with a body hash (docs/04-architecture.md API conventions).
• Record mutations in the audit log.
• Keep the docs current in the same pull request when behaviour or a decision changes.
• Before writing a connector, read seba-erp's version and the provider's current docs, and record anything learned in docs/06-integrations.md.

← All documents

1. Handover brief

What Vervoro is

Vervoro is a SaaS operations system for sellers on Amazon (Seller and Vendor), eBay, Shopify and TikTok Shop, starting in the UK and EU. It covers what a seller with their own warehouse does every day: keep the catalogue, receive stock, take orders from every channel, reserve and pick stock, dispatch, push sellable quantities back to the channels, ship to Amazon FBA, confirm Amazon Vendor POs, and later run Amazon advertising.

Each customer company is a tenant. A tenant subscribes to one of three plans (Core, Growth, Pro) that differ by features and by how many orders it ships from its own warehouse; Amazon Vendor Central is an add-on. Channels, users and the AI connector are unlimited in every plan. See Product and modules.

Seba's workload

• FBA orders (about 85% of the total) are imported for reporting and dashboards only. They never reserve or move own-warehouse stock (rule O6).
• The fulfilment path that touches stock handles about 150 orders a day per company. That is small for Postgres; size for bursts (e.g. Prime Day) and imports, not for steady load.
• Seba EU is a separate company and a separate tenant with one warehouse. It uses no system today and moves after Seba UK, through the same customer migration steps (D-026, D-027, D-034, D-035).

Why a rebuild

seba-erp works and holds months of hard-won marketplace knowledge. It was built for one company:

• Single-company design: settings are a single row (id: "singleton"), product SKUs are unique across the whole database, and none of its 306+ queries filter by tenant.
• Long-lived process: it needs one Node process (an in-memory scheduler and caches) and stores marketplace secrets in plain text.
• No tests.

Vervoro keeps the knowledge and replaces the foundations: multi-tenancy, RBAC, sellable modules and a serverless runtime from day one.

The first goal: Seba UK on Vervoro

Seba UK runs its daily operations on Vervoro, as tenant #1, on production infrastructure, with seba-erp switched off as a stock writer. The build is P0 in the delivery plan, estimated at about 36 engineer-days and tracked at regular progress checkpoints. Seba UK then moves with the standard customer migration (D-058): import once, a few days of shadow mode, then switch over. Expected cutover: January 2027 (D-065).

Seba must be able to:

• Do the warehouse and order work from a phone, scanning barcodes with the camera.
• Find any product, its batches, best-before dates and locations.
• Receive goods against a supplier PO into batches.
• See Amazon (FBM and FBA), eBay, Shopify and TikTok orders arrive, with stock reserved automatically.
• Create manual and B2B orders and their invoices.
• Print pick lists and picking slips, confirm dispatch, and see stock decrease.
• See correct sellable stock pushed to every connected channel.
• Approve and confirm Amazon Vendor POs at the right price, reserve and ship them (ASN and transport stay in Vendor Central and Carrier Central, as today).
• Build and ship an FBA replenishment step by step, with stock reserved and moved correctly.
• Raise supplier purchase orders and receive against them.
• Use Claude or ChatGPT through the MCP connector to look at products and stock and to propose listing changes and purchase orders, which a person approves (shortly after cutover, D-053).
• Manage users and what each user may do.

What stays in seba-erp after cutover:

• Accounting and the Amazon Ads engine (both later modules).
• All history before cutover (read-only).
• Any P1/P2 module not finished in time (see the delivery plan).

Definition of done (cutover)

• Seba's catalogue, SKU mappings, suppliers, customers, open orders, open POs and current batches are imported into Vervoro. Batch quantities match seba-erp at cutover.
• Every P0 item in the delivery plan works end to end against Seba's real accounts.
• The ready-to-cut-over checklist is complete.
• seba-erp is read-only for stock and its order import and stock push jobs are disabled. Vervoro is the only system writing stock to the channels.
• The tenant-isolation test suite passes: a second test tenant cannot read or change anything of Seba's, through the API, files, jobs (and MCP once it is built).
• Production has backups with a tested restore, error tracking and a jobs view.
• seba-erp stays available for at least two weeks after cutover, as the fallback (Customer migration, step 7).

Not in the first cutover

• Accounting and the Amazon Ads engine (later modules; both stay in seba-erp).
• AI features that run inside Vervoro (P1/P2). The MCP connector follows shortly after cutover (D-053).
• Self-serve sign-up and Stripe checkout. The data model for entitlements is built early in the build; the checkout UI follows Seba's cutover.
• External customers. These also depend on marketplace app approvals; see Integrations.
• The larger features from the earlier V1 design (central listing and price management, promotions, DE/GB stock pools, condition-graded book stock, formal stock counts). See Decisions.

Day-1 access checklist

The product owner provides these before day 1. Share secrets through a password manager, never in chat or email.

Working agreement

• Two engineers, AI-assisted. Copy AGENTS.md into the application repository on day one. AI agents follow it literally, so keep it current.
• Tests come with the code. Every domain rule in Domain rules gets at least one test. Tenant isolation has its own suite that runs in CI.
• When something is unclear: check seba-erp's behaviour first. If it is still unclear and a customer would notice the answer, ask the product owner and record the answer in Decisions.
• Demo to the product owner on Seba's real data every two to three days.

Biggest risks

← All documents

2. Product and modules

How it is sold

Three plans that differ by features, each with a ceiling on orders shipped from the tenant's own warehouse, plus one add-on. Full terms and prices: Commercial model.

Prices and order ceilings live only in Commercial model.

Unlimited in every plan: users, channels and channel accounts, warehouses, batch and best-before tracking, and the AI connector (MCP). New channels added later (Walmart, Target, Etsy…) are included in every plan too.

Module catalogue

key is the stable identifier used in code, permissions, Stripe metadata and URLs. Never rename one.

Plans are bundles of these modules. Entitlements stay per module in code, so a plan can be re-cut without code changes. Seba UK and Seba EU are internal tenants with every module granted.

Purchasing for Seba: Seba receives stock through POs, so Purchasing is P0 for cutover even though it sits in Growth. Every tenant can always receive stock through Inventory ("goods in" without a PO, with a required reason, audited and listed in the reconciliation report); Purchasing adds the supplier and PO workflow on top.

Core plan (all plans)

Warehouse tasks are listed here with customers for reading convenience but belong to Growth.

Products (products)

• Product record: SKU, name, EAN/GTIN (check digit validated), brand, weight, dimensions, cost, status.
• Product kinds:
  • Simple product.
  • Bundle / kit: sold as one item, picked from component stock; it has no stock of its own.
  • Physical pack: has its own stock, made by a repack job (REPACKED_IN/REPACKED_OUT) or received from the supplier.
• Box/pack configurations ("Box × 12, Pallet × 480"). Picking documents express quantities in cases as well as units.
• Categories, tags, and a per-product activity log.
• Bulk edit by CSV. SKU is the match key and is never written back. A blank cell means "leave alone", not "clear". (seba-erp: lib/product-csv.ts)
• Catalogue onboarding: pull drafts from a connected channel into a workbook to correct, then import. SKUs already matched are skipped. (lib/product-draft.ts, lib/product-workbook.ts)
• Barcode comparison normalises formatting: hyphens, a dropped leading zero (EAN-13 vs UPC-A), whitespace. (lib/barcode.ts)

Inventory (inventory)

• Batches carry: lot number, best-before, production date, supplier batch, units per box and landed unit cost (provisional until all charges arrive). A batch's stock sits in balance rows by location and status (Data model). Batches received without a lot get YYYYMMDD-NN references.
• Warehouses and locations / bins. A tenant can have several warehouses from the first version (Seba EU has its own). Locations belong to a warehouse; each channel account has a default warehouse (rule O9). seba-erp has no warehouse entity: only a flat list of locations (WarehouseLocation), with no warehouse on orders, so this is new in Vervoro.
• Movements ledger: received, transferred, dispatched, adjusted, repacked in/out, returned, written off. Every movement has a reason, an actor and a source. Reservations are allocations, not movements (rule S2).
• Transfers between locations. Adjustments need a reason.
• FEFO: allocation picks the earliest best-before first, with manual override.
• Batch traceability page: where a batch came from and where it went.
• Returns: received into quarantine, then inspected as saleable, damaged or written off.
• Low-stock alerts per product.

Orders (orders)

• One order list across channels, filterable by channel account, status and stock status.
• Imports from every connected channel account. FBA orders are recorded for reporting but never reserve own stock.
• Manual orders: direct, telephone and B2B. They use the same reservation and dispatch rules as channel orders.
• Reservation on import:
  • Partial reservation when stock is short; the missing quantity is visible.
  • Unmapped SKUs are flagged and reserve nothing.
• Picking and dispatch documents: pick list, packing list, and a 15 × 10 cm picking slip modelled on the Vendor PO sheet (SKU, EAN, cases and units, FEFO lots).
• Dispatch:
  • Confirming dispatch is what decreases physical stock.
  • Tracking is recorded on dispatch.
  • The channel is notified of dispatch where the connector supports it.
• Cancellation and returns follow Domain rules.
• Statuses: order status and stock status are tracked separately; both flows are in Data model: Status flows.

Warehouse (warehouse), Customers (customers)

• Warehouse tasks: title, notes, assignee, priority, due date; status TODO → IN_PROGRESS → DONE.
  • Some tasks are created automatically, e.g. "pick order X" when it is fully reserved.
  • Completing a task never moves stock; dispatch is still its own step.
• Customers:
  • Marketplace buyers are linked to a customer record only when the name plus email, or the name plus postcode, match.
  • A postcode alone is never enough; it would merge whole households and office blocks.

Invoicing (invoicing)

• Sales invoices for B2B and direct orders: printable PDF, payments recorded against them, collection notes for couriers.
• No accounting here. Bank feeds, VAT returns and bookkeeping belong to Accounting (later).

Reports (reports)

• Dashboard: what sold today by channel, against the same day last week, plus month to date. Totals are what the customer paid, before marketplace fees.
• Basic reports: stock value, low stock, product sales report.
• Basic profit per SKU from Amazon payouts. The detailed version (full payout profitability with landed cost, Buy Box, rank tracking) is in Growth. Both need the Amazon settlement import (P1). Ad spend joins the profit figures only once the Ads module exists.

Channels (channels)

• Connections:
  • Several accounts per connector, each with its own identity, token, status and sync progress.
  • Reconnecting the same account keeps its history.
• SKU mapping:
  • Channel SKU → product, per connection.
  • An "unmatched SKUs" list fills from incoming orders.
  • Listings are grouped by the channel's own reference (ASIN, eBay item id, Shopify variant id), so FBA and FBM SKUs of one ASIN fold together.
• Stock push: sellable quantity only, only the SKUs that changed. See Domain rules.
• Jobs view: what each sync did, when, and what failed, per connection.

Growth, Pro and add-on modules

FBA, purchasing, detailed reporting and attendance come with Growth and Pro. Vendor Central is an add-on on Growth or Pro. AI & MCP is in every plan.

Amazon Vendor Central (vendor): add-on

• POs: synced from Vendor Central, with changes and cancellations.
• Review and confirmation:
  • A user reviews each PO line: accept a quantity, reject the rest.
  • The confirmed price must be at or below the price ceiling defined in rule V2.
  • A "check prices" step compares against Vendor Central.
• Approval creates a real order on the Vendor channel and reserves stock. From there it uses the normal dispatch flow. (lib/vendor-stock.ts)
• Shipping: barcode matching (as in seba-erp). Carton and pallet labels and the ASN come later (P1); seba-erp doesn't have them, and Seba does them in Vendor Central and Carrier Central today.
• Multiple Vendor accounts per tenant (e.g. Vendor UK, Vendor Germany).

FBA shipments (fba): Growth

• Inbound plans built step by step on Amazon's Inbound API (v2024-03-20), showing placement and transport options with destination and carrier names. Prep and labelling come from Amazon's per-SKU rule; see lib/fba-test.ts for why the one-click builder failed.
• Box labels: a "heavy package / team lift" warning is added to boxes over 15 kg. Labels are fetched one per page in thermal format, then laid out on A4. (lib/fba-labels.ts)
• Stock: shipping to FBA is a transfer, not a sale (rule S10). Stock is reserved once the shipment is ready to pack and deducted at handover, with the pack multiplier applied; no order is created. (lib/fba-stock.ts)
• Status: shipment status is synced; ship-from addresses come from Seller Central.

Purchasing (purchasing): Growth

• Suppliers: each supplier's own product codes are learned once and remembered. An unknown code stops the order until a person maps it; nothing is guessed.
• Purchase orders: statuses as in Data model: Status flows. Orders can be emailed to the supplier, and documents can be attached.
• Receiving creates batches with landed cost.
• Landed cost allocation:
  • A discount or charge printed on the supplier document is shared by value.
  • Freight, duty and clearance arriving on later invoices are shared per unit by default, with value or weight as options. (lib/purchasing/allocate.ts)
• Supplier document → PO:
  • Lines are read from an invoice, proforma or delivery note.
  • The reading is accepted only if every line reproduces its printed amount and the lines reach the document total exactly; otherwise nothing is offered. (lib/purchasing/document-lines.ts)
• Reorder suggestions combine stock cover in days, recent sales, stock on order and supplier lead time. (lib/purchasing.ts)
• Warnings for likely mapping mistakes before an order is approved. (lib/purchasing/checks.ts)

Amazon Ads engine (ads): later, lowest priority

Not in the first version. Seba keeps using seba-erp's Ads engine (its ads-* jobs stay switched on after cutover) until this module is built. Ads never touches stock, so running it in seba-erp alongside Vervoro is safe. The description below records what the module must eventually do.

• Sync and spend:
  • Ads profiles per marketplace.
  • A local mirror of the Sponsored Products structure (campaigns, ad groups, keywords, targets).
  • Daily spend per SKU from asynchronous reports. A first report can take 20 minutes.
• Goals and strategies:
  • Bid engine: a target TACoS per ASIN is turned into keyword bids and budgets through the ASIN's ad share of sales. (lib/ads-engine.ts)
  • Strategies: named settings of six levers, scored against the product's real numbers. (lib/ads-strategies.ts, lib/ads-strategy-build.ts)
  • New campaigns: an auto campaign plus an exact campaign. Opening bid = price × target ACoS × assumed conversion rate, shown and editable.
• Ongoing optimisation:
  • Harvesting: search terms proven over 30 days are promoted to exact and negated where they were found.
  • Pacing: detects campaigns that run out of budget and at what time of day.
  • Scope: the engine only acts on ad groups that advertise this one ASIN; shared ad groups are reported, not touched. (lib/ads-scope.ts)
• Change control and history:
  • Every bid, budget and harvest change is a proposal a person approves.
  • seba-erp prefixes the campaigns it creates ERP-. Vervoro prefixes the campaigns it creates VRV- (configurable per tenant) and treats Seba's existing ERP- campaigns as legacy (D-048).
  • Campaign history merges Amazon's change history (90-day limit) with Vervoro's own proposals and approvals.

Detailed reporting (reports-advanced): Growth

• Payout profitability: per Amazon settlement, product by product. Amazon's fees and payments, plus cost of goods from batch landed cost, minus VAT; plus ad spend per SKU once the Ads module exists. (lib/settlement-profit.ts)
• Pricing and Buy Box research per product.
• Sales rank check and rank scan.

AI & MCP (ai): every plan

Priority: the MCP connector, with its read tools, propose tools and the approval screen, comes shortly after Seba UK's cutover (P1, D-053). AI features that run inside Vervoro itself, and so spend Vervoro's tokens, come later (P1/P2).

• MCP connector lets Claude, ChatGPT and other assistants work with the tenant's data:
  • Users sign in through OAuth, using public clients with PKCE only.
  • Tokens are revocable, act for that user, and never carry a marketplace credential. (lib/oauth.ts)
• MCP tools:
  • Read tools: products, Amazon listing, variation family, stock and sales, open POs, A+ content.
  • Propose tools: listing change, variation, purchase order, A+ content, new listing. (lib/mcp/tools.ts)
  • First release (P1, after cutover): the read tools, plus the listing-change and purchase-order proposals with their approval screens. The other propose tools follow.
  • With the Ads module (later): ads for a product, search terms, ads change proposals.
• Proposals never apply themselves:
  • A person reviews and approves each one.
  • Applying re-checks that the target has not changed since the proposal was written. (lib/amazon/listing-edit.ts)
• Images attached to proposals are copied into storage. They are fetched only from public https addresses, never internal ones. (lib/ai-images.ts)
• Usage: AI usage is metered per tenant.

Attendance (attendance): Growth

• Clocking: staff clock in and out by scanning an entrance code with their own phone; records are keyed to the signed-in person.
• Leave: annual leave requests, allowances and bank holidays.
• Dates are calendar days in the tenant's timezone, so clock changes can't move them. (lib/attendance-calc.ts)
• Access: staff see only their own records; managers see the team, correct records and approve leave.

Later: Accounting

seba-erp's accounting is large (about 12k lines) and specific to UK bookkeeping (Xero/Dext, HMRC VAT, Amazon settlements, bank coding, Vendor remittances). It stays in seba-erp for Seba UK and will become Vervoro modules later.

Accounting differs by region, so plan it as one shared core plus regional packs:

• Integrate with the customer's accounting software rather than replacing it. Vervoro prepares and exports the figures and documents, and Xero, DATEV or QuickBooks keeps the statutory books. Building full statutory accounting for every country is a different product.
• Each regional pack is its own sellable module, offered to tenants in that region.

Don't design anything now that blocks this. From the first version:

• keep landed cost on batches;
• keep each tenant's Amazon settlement data;
• store money with its currency;
• on order lines, store tax amount, rate and country exactly as the channel reports them;
• give each tenant a country, a base currency and a list of its tax registrations.

← All documents

3. Commercial model

Prices and terms below were chosen by the product owner on 2026-10-07 from the pricing debate. Keep every number in configuration, not code, so it can change without a release.

Plans and add-ons

• Add-on: Amazon Vendor Central (vendor) on Growth or Pro: £199 · €229 · $249 per month.
• Above 15,000 own-warehouse orders: priced on request.
• Unlimited in every plan: users, channels and channel accounts, warehouses, batch and best-before tracking, AI connector.
• Optional onboarding: guided setup £595 (about 8 hours); full migration £1,950 (one source system, up to 2,000 SKUs and 4 channel accounts); extra work £75/hour, quoted first. Credited against the first year if the customer pays annually.

How the order ceiling works

• Count orders shipped from the tenant's own warehouses per calendar month: dispatched orders, each counted once however many parcels it ships in, in the month it is dispatched (there is no partial dispatch in V1). Manual and B2B orders count like channel orders. Each Vendor PO shipment counts as one order. FBA orders never count. Orders cancelled before dispatch, replacements and returns count zero.
• Use the average of the last 3 months, so one busy December does not change the plan.
• Warn at 80% of the ceiling. When the 3-month average is over the ceiling, offer the next plan and move the tenant up at the next renewal. No overage charges, ever.
• Never stop importing or shipping orders because of a limit.

Founder rate (first 25 paying customers)

• 25% off the plan for 24 months, then 15% off for as long as the customer stays subscribed. Written into the contract, with a price lock and the right to export all data at any time.
• Not applied to the Vendor add-on; not combined with the annual 2-months-free.
• The first 10 founders who pay annually get the migration package credited.
• Founders agree to a case study or two reference calls a year.

Promises to every customer

• Prices rise at most once a year, by no more than 10%, with 90 days' notice.
• If Amazon reintroduces developer API fees, they may be passed on at cost in proportion to each customer's usage, with 60 days' notice.

Commercial defaults

These fill gaps the pricing decision left open; the owner confirmed them (D-055).

• Founder lock vs the 10% cap: a founder's price is fixed for the first 24 months (no rises at all). After that it is always the current list price minus 15%, and list prices follow the 10%-a-year cap. In Stripe: founder Prices fixed for 24 months, then a 15% coupon on list Prices.
• Trial ends without a card: the tenant becomes read-only for 14 days with a banner. Order import, reservation and dispatch keep running, so channels never sell stock nobody tracks. Then stock push is switched off after the user confirms "set channel stock to 0", and the tenant is cancelled.
• Payment fails: 14 days grace with full access, then suspended for up to 30 days (see Tenant lifecycle), then cancelled. Before cancellation the owner is asked to set channel stock to 0; Vervoro never leaves a channel selling stock it no longer tracks.
• Vendor add-on ends: confirmed Vendor POs that are already reserved can still be dispatched and closed; no new POs are confirmed.
• A seller with a UK and an EU company: two tenants, two subscriptions; each company is billed separately.

Other rules

• Plan changes: upgrades apply immediately, prorated; downgrades apply at the end of the billing period.
• AI: the MCP connector runs on the customer's own Claude or ChatGPT, so it costs Vervoro no tokens and is in every plan. AI features that run inside Vervoro (later) may come with a usage allowance, metered per tenant through AI Gateway.
• Internal tenants (Seba UK, Seba EU, demo tenants) get every module granted manually, with no Stripe subscription.
• Payments: prices are shown ex VAT. Offer Bacs Direct Debit (UK) and SEPA (EU) alongside cards, especially for annual plans. Register for UK VAT from day one, validate EU VAT numbers for reverse charge, and keep a EUR balance in Stripe. Offer USD only to customers with a UK or EU company until US channels launch.
• Service credits for outages are capped at one month's fee and are the only remedy; consequential losses are excluded. A lawyer must check the wording.

Stripe

• Products and prices: one Stripe Product per plan (Core, Growth, Pro) and one for the Vendor add-on, each with GBP, EUR and USD prices, monthly and annual. Onboarding packages are one-off Prices. Each Price carries metadata.vervoro_key (core, growth, pro, vendor) and metadata.kind (plan or addon). Vervoro maps a plan to its module entitlements in configuration.
• Founder rate: founder Prices fixed for 24 months, then a 15% coupon on list Prices (see Commercial defaults), so the lock survives plan upgrades.
• Purchase and management: Checkout for the first purchase, plan upgrades and adding Vendor. The Customer Portal handles plan changes, payment methods and invoices.
• Tax: Stripe Tax handles UK VAT and EU VAT. Collect a VAT ID for B2B reverse charge.
• Webhooks go to /api/webhooks/stripe:
  • Verify the signature.
  • Store the event by id before processing; processing is idempotent.
  • Handle at least: checkout.session.completed, customer.subscription.created|updated|deleted, invoice.paid, invoice.payment_failed.
• Stripe is the source of truth for what was bought. Vervoro derives tenant_entitlement rows from the subscription after every relevant event. Never read Stripe live on a user request.

Three gates on every request

A request to a module succeeds only if all three are true:

1. Entitled: the tenant has an active entitlement for the module, from Stripe, a trial or a manual grant.
2. Enabled: the tenant's admin has the module switched on. An admin can hide a paid module from the team without cancelling it.
3. Permitted: the user's role grants the permission the action needs. See Architecture: RBAC.

The API enforces all three. The UI only hides what the API would refuse.

tenant_entitlement(tenant_id, key, quantity, source: stripe|trial|manual,
                   status: active|grace|ended, valid_until, stripe_subscription_item_id)
tenant_module_setting(tenant_id, key, enabled, settings jsonb)

Plans are configuration, modules are the product

Everything is built as an add-on; a plan is only a named bundle. That way, who gets what can change without code: move a module between plans, sell one on its own, or add a new plan.

• The unit of sale is the module (key from the module catalogue). Code only ever checks "is module X entitled for this tenant?", never "is this tenant on Growth?". Checking a plan name in code is forbidden.
• Limits are entitlements too, with a quantity: limit.own_warehouse_orders = 5,000, and later, if wanted, limit.channel_accounts or limit.warehouses. Code reads the quantity, never a plan.
• The plan catalogue is data, versioned, in the platform schema:
  • plan: key, version, name, order ceiling, the modules and limits it grants, its Stripe prices.
  • addon: key, the module or limit it grants, which plans it can be added to, its Stripe prices.
• Entitlements are derived from the tenant's subscription: (plan version → modules + limits) + add-ons + manual grants (internal tenants, goodwill) + trial. Recompute after every Stripe event or catalogue change.
• Changing who gets what: publish a new catalogue version. Existing subscribers keep their current version (grandfathered) until they change plan, or until a migration you choose with the price-rise notice in "Promises to every customer".
• Selling a module separately (e.g. detailed reporting as its own add-on): add an addon row and its Stripe price. No code change.
• Design rule: anything that might one day be sold on its own must be its own module key, with its own routes, jobs, permissions and navigation behind the manifest. If unsure, split it.

When an entitlement ends

Downgrades must never corrupt stock or leave a channel showing quantities nobody maintains.

Sign-up and onboarding (self-serve)

1. Account and company: sign up with email or Google. Turnstile protects the form. Create the company (tenant), pick a country and currency, and the user becomes Owner.
2. Trial: 14 days on Growth, extended to 30 days once the tenant has imported its catalogue. No card is needed during the founding phase (revisit when self-serve and the Shopify App Store open). One trial per company, matched on Amazon seller ID and VAT number. While the unlisted Amazon app is limited to 25 sellers, Amazon is connected with someone from Vervoro; a demo tenant with sample Amazon, FBA and Vendor data lets prospects explore first.
3. Onboarding wizard:
   • Warehouse and locations.
   • Connect the first channel.
   • Import the catalogue from that channel (workbook flow).
   • Opening stock.
   • Invite users.
   • Each step can be skipped and resumed.
4. Go live: connections start in shadow (reading, sending nothing). Switching one to active turns on stock push and is a separate, explicit step after the unmanaged-listings check (rule C6), because it overwrites channel quantities. A seller moving from another system follows Customer migration.

Tenant lifecycle

GDPR: tenants can export all their data at any time (CSV and JSON per module, plus one full export for leaving) and request deletion. A data processing agreement covers the buyer personal data from marketplace orders. Buyer addresses must be deleted or anonymised after the period each marketplace's data policy requires (Amazon is strict; see Integrations).

Platform admin (internal)

A separate, internal-only area for the Vervoro team:

• Tenants: list tenants with their state, plan, entitlements and usage.
• Entitlements: grant or revoke manually (internal tenants, goodwill credits).
• Support access: time-limited, read-only by default, visible to the tenant and fully audited.
• Jobs: inspect each tenant's jobs and errors.

Platform-admin access uses a separate role. It never acts through a tenant role.

← All documents

4. Architecture

Fixed vs recommended

Fixed decisions are the product owner's; changing one needs a new entry in Decisions. Recommended choices belong to the engineers: replace one if you have a better reason, and record why.

Why a single-page app rather than Next.js: an ERP behind a login has no SEO or server-rendering needs. seba-erp already works this way in practice: 76 of 88 pages are client components and the UI makes 364 fetch('/api/…') calls. Plain React + Vite avoids running Next.js through an adapter on Workers.

System overview

flowchart LR
  B[Browser SPA] -->|same origin /api| W[web Worker: Hono API + static assets]
  AI[Claude / ChatGPT] -->|MCP + OAuth| M[mcp Worker: Agents SDK]
  MP[Marketplace and Stripe webhooks] --> W
  W --> H[Hyperdrive] --> PG[(Neon Postgres, RLS)]
  M --> H
  W --> R2[(R2: tenant files)]
  W -->|outbox relay| Q[Queues]
  C[Cron Triggers] --> J[jobs Worker]
  Q --> J
  J --> WF[Workflows: long multi-step syncs]
  J --> DO[Durable Objects: API rate limiters]
  WF --> DO
  DO --> X[Amazon SP-API / Ads / Vendor, eBay, Shopify, TikTok]
  J --> H
  W --> AIG[AI Gateway] --> LLM[Anthropic API]

Three Workers deploy from one repository and share packages:

Suggested layout: apps/web, apps/jobs, apps/mcp, packages/db (schema, migrations, withTenant), packages/platform (auth, tenancy, RBAC, entitlements, audit, module registry), modules/<key> (one folder per module, with server and UI).

Tenancy

1. Tenant comes only from the server. It is the session's active organization, a job message signed by our own code, or an MCP token. A tenant_id in a request body, query or header is never trusted.
2. Every tenant table has tenant_id uuid not null. Uniqueness includes it: unique (tenant_id, sku), unique (tenant_id, connection_id, native_order_id). Foreign keys between tenant tables include tenant_id (composite foreign keys), so a row can never point at another tenant's row.
3. RLS is enabled and forced on every tenant table, with policy tenant_id = nullif(current_setting('app.tenant_id', true), '')::uuid for both USING and WITH CHECK. Written this way, a missing or empty tenant setting matches no rows instead of raising an error (rule T2).
   • A CI catalogue check fails the build if any table outside the platform and auth schemas lacks tenant_id, row security, or forced row security. Drizzle can declare policies; the FORCE ROW LEVEL SECURITY, policies and grants are written as reviewed SQL in the migration.
   • The runtime database role does not own the tables and has neither BYPASSRLS nor superuser.
   • Migrations run as a separate owner role.
4. Set the tenant context inside every transaction: select set_config('app.tenant_id', $1, true). Hyperdrive pools connections per transaction and resets SET when a connection returns to the pool, so a session-level SET does not survive. All database access goes through one helper, withTenant(tenantId, tx => …); code outside packages/db never gets a raw connection.
   • The same helper sets lock_timeout 5 s and statement_timeout 30 s with set_config(…, true).
   • The runtime role has an idle_in_transaction_session_timeout.
   • A lint rule forbids session SET outside packages/db.
5. Hyperdrive query caching is off on every configuration (--caching-disabled). The RLS filter lives inside the policy, not in the SQL text, so every tenant sends identical queries. A cached result could be served to the wrong tenant.
   • Belt and braces: every query also filters tenant_id = $1 explicitly.
   • The isolation suite runs the same SELECT as two tenants back to back.
6. Lock discipline for stock: lock all needed batch rows in one statement, ordered by id, then write in one batch. Keep a stock transaction to a few round trips, and log transaction time and lock waits from day one.
7. Platform tables (tenants, plans, Stripe events, platform admins) live in a separate platform schema without tenant RLS. Only platform code can reach them.
   • Cross-tenant work has exactly one door: a named database role (vervoro_platform) used only through one helper, withPlatform(reason, tx => …), which writes an audit row for every use. It reads the platform and auth schemas and the minimum needed to fan out work (which tenants and connections exist, which tenant a webhook belongs to). It is used by: the cron dispatcher, webhook routing, the health cron, the retention job and platform-admin screens. No code uses the owner role or BYPASSRLS at runtime. Tenant work always continues inside withTenant.
8. Jobs: every queue message and Workflow input carries tenant_id; the consumer opens withTenant with it.
9. Files: R2 keys start tenants/{tenant_id}/. Files are served only through an authorized API route or a short-lived signed URL. Nothing is public.
10. Caches: Workers isolates are many and short-lived, so in-process caches (like seba-erp's globalThis access cache) are unreliable. Use KV or the database, and always include tenant_id in a cache key.
11. Isolation test suite in CI. Two tenants with overlapping SKUs and order numbers. Every API route, export, file route, MCP tool and job is called as tenant B against tenant A's ids, and must return nothing or 404. It also runs the same query twice in a row as two tenants, and checks idempotency keys and invitations (below) can't cross tenants.

Modules

Each module exports a manifest. The platform reads it to mount routes, build the navigation, register jobs, list permissions and enforce entitlements. This replaces seba-erp's path-prefix list (lib/modules.ts).

export default defineModule({
  key: "ads",                         // stable; matches Stripe metadata and permissions
  kind: "addon",                      // core | addon | connector
  requires: ["amazon-seller"],
  permissions: {
    "ads.read": "View campaigns and performance",
    "ads.proposals.approve": "Approve bid, budget and harvest changes",
    "ads.campaigns.create": "Create campaigns",
  },
  api: adsRoutes,                     // Hono sub-app, mounted at /api/ads
  ui: { routes: adsUiRoutes, nav: [{ label: "Advertising", path: "/ads", permission: "ads.read" }] },
  jobs: { "ads.sync-structure": syncStructure, "ads.daily-spend": dailySpendWorkflow },
  schedules: [{ job: "ads.daily-spend", cron: "15 4 * * *" }],
  settings: AdsSettingsPage,
});

Rules:

• Entitlement and enablement are checked by middleware on the module's mount point, so a route cannot forget them. Checks are always by module key or limit, never by plan name. Plans and add-ons are data in the plan catalogue (Commercial model), so moving a module between plans or selling it on its own needs no code change. Scheduled jobs check the same gates before they run per tenant.
• Own tables only. A module writes only its own tables (prefix them, e.g. ads_campaign). It reads other modules through their exported service functions, not their tables.
  • Stock changes only through the inventory service (inventory.receive, reserve, release, dispatch, adjust, transfer). No other module writes stock tables.
• Cross-module reactions use domain events. Inside a transaction, write a row to the outbox (e.g. order.dispatched); subscribers run from the queue afterwards.
• Connectors implement one interface: importOrders, pushStock, listListings, notifyDispatch, verifyWebhook, refreshToken. Capabilities a channel lacks are declared, not faked.
• Every connection has a mode: shadow or active. In shadow it reads (orders, listings, Vendor POs, FBA shipments) but never sends:
  • Each would-be stock push, dispatch notification or Vendor confirmation is written to the outbox with status suppressed, a final status the relay never sends, kept for inspection.
  • Switching a connection to active sends nothing from its past; a test proves it. The switch is an audited action that requires the unmanaged-listings check (rule C6) and starts with a full push computed fresh.
  • New connections start in shadow, for every tenant's onboarding and migration (Customer migration).
• A tenant with any connection in shadow sends no email and no documents (POs to suppliers, invoices, alerts to outside addresses); they are stored as suppressed too.
• Training: staff practise in staging or the demo tenant, never on real stock in production.

Adding a new sales channel

New platforms (Walmart, Target Plus and others for the US; Etsy, Kaufland, OTTO and others in Europe) must be addable without changing core code:

• A channel is a connector module. It is a folder under modules/ with a manifest, its own settings screen, jobs and rate-limit settings. Channels are included in every plan (D-037), so a connector has no Stripe price of its own. Channel keys are strings registered by connector modules, never a hard-coded enum. seba-erp's OrderChannel enum is the pattern to avoid.
• Canonical models in core: order, order line, listing, SKU mapping, stock target, shipment notification, buyer address. Connectors translate to and from these; core never sees a channel's raw format, except as a stored original payload for support.
• Capabilities are declared: e.g. orders.import, stock.push, dispatch.notify, listings.read, cancellation.read, returns.read. The UI and jobs read them, so a channel without a feature shows that clearly.
• Per-channel facts are data: currency, marketplaces, address format, tax fields, rate limits, polling interval.
• Conformance test kit: every connector must pass the same shared tests (idempotent import, unmapped SKUs, multipliers, merchant-fulfilled-only push, stock push only on change, dispatch notification retries, token refresh) against recorded fixtures before it is enabled. Before cutover, record 5–10 real orders per channel from Seba's accounts (masked) as the first fixtures.
• Template: keep modules/connector-template up to date, so a new channel starts from a working skeleton.

RBAC

• Permissions are strings, module.resource.action, declared by modules. A user's permissions come from their role in the tenant. The full catalogue, the role matrix, warehouse scoping and the data model are in Permissions and roles.
• Built-in roles (Owner, Admin, Manager, Warehouse, Accountant, Staff) and what each gets are defined only in Permissions and roles. A custom role editor comes later; the data model already supports it.
• Sensitive data has its own permissions: cost prices and margins (finance.costs.read), buyer personal data (orders.buyer_pii.read) and exports (data.export).
• Warehouse scope: a user can be limited to some warehouses; see Permissions and roles.
• Checked on the server for every request, with requirePermission("orders.dispatch"). The UI hides what a user can't do; it is never the security boundary.
• First-user rule: the user who creates a tenant is its Owner. There is never an "everyone is admin while no admin exists" fallback; seba-erp has one in lib/access.ts, and with many tenants it would be an escalation bug.
• Audit log: every mutation records tenant, actor, action, entity, a before/after summary, and the request or job id.

Jobs and integrations

• Cron Triggers decide what is due. They enqueue one message per tenant connection and job (e.g. {tenant, connection, job: "amazon.orders"}) and never do the work themselves.
• Queue consumers do short work: import a page of orders, push changed SKUs.
• Workflows do multi-step or waiting work: an FBA inbound plan, requesting an Ads report then polling until it is ready, reading a settlement. Each step retries on its own.
• Schedules: module manifests declare schedules, but Cron Triggers are fixed in the Worker's config. So the jobs Worker has one dispatcher cron (every minute) that reads every module's schedules and enqueues what is due. Never add a Cron Trigger per module.
• Rate limits: one Durable Object per (connector, account, operation) acts as a token bucket, set to that operation's published rate and burst. Every call to a marketplace asks it first. On HTTP 429, wait the provider's Retry-After if it sends one, otherwise the operation's restore time (Integrations: Amazon). While seba-erp still runs amazon-settlements on the same Amazon app and seller account, it uses part of the same quota; leave headroom for it.
• Amazon call counting: every SP-API GET is counted per tenant (Analytics Engine), as required by Integrations.
• One writer per channel account: a ChannelAccountWriter Durable Object per connection holds the sync leases. Only one job at a time can push stock or import orders for that account (rule E6).
• Worker placement: placement hints apply only to HTTP (fetch) handlers, not to queue, cron or Workflow handlers. Keep stock transactions to a few round trips. Only if traces show distant job consumers holding locks, move the inventory service into a small Worker placed near the database and call it through a service binding.
• Outbound changes (stock push, dispatch notification, Vendor confirmation) follow the outbox pattern. The domain change and the outbox row commit in one transaction; the relay sends the row to a queue; the consumer is idempotent.
• Sync state: each connection keeps a watermark per sync. Overlapping time windows are safe because imports are idempotent.
• Visible to users: jobs view per connection, with what ran, results, errors and next run.

API conventions

• Routes: REST-style JSON under /api/<module>/…. The OpenAPI spec is generated from the Zod schemas and used to generate the typed UI client.
• Errors: one shape everywhere, { "error": { "code": "STOCK_INSUFFICIENT", "message": "…", "details": {…} } }. Codes are stable strings the UI can map to translated messages; HTTP status follows meaning (400, 401, 403, 404, 409 conflict/stale version, 422 rule violation).
• Lists: cursor pagination (?cursor=…&limit=50, maximum 200), server-side filtering and sorting. Never return a whole table.
• Writes that must not happen twice (create order, dispatch, receive, confirm Vendor PO, apply proposal) accept an Idempotency-Key header. Keys are stored per tenant and route with a hash of the request body and the first response, and expire after 24 hours. A repeat with the same body returns the first response; the same key with a different body returns 422.
• Concurrency: edits send the record's version; a stale version returns 409.
• Money and quantities travel as strings for money ("12.3400") with a currency code, and integers for quantities.

UI conventions

• No design system yet: use shadcn/ui defaults with one accent colour, and keep it consistent. Branding can come later.
• Mobile-first where practical; every screen works on a phone (D-063). Seba runs much of its day from phones.
  • Designed for the phone first: scan, receiving, picking, packing, dispatch, tasks, returns, attendance, the order list and order page, Vendor PO review and approval, and the product page.
  • Usable on a phone, richer on a desktop: large tables, reports, imports, settings. On a phone they show fewer columns or a card list. They must work there, not be perfect.
  • Dense, sortable, filterable tables and keyboard shortcuts on desktop.
• Barcode scanning works two ways everywhere a code is entered: a hardware scanner (it types like a keyboard) and the phone camera. The camera scanner reads EAN, UPC, Code 128 and QR, prefers the rear camera and ignores the same code repeated within 3 seconds. seba-erp: components/BarcodeScanner.tsx (ZXing).
• Screens rebuild seba-erp's behaviour, not its layout. SCREENS.md lists every seba-erp page with its module and priority.
• English only in V1, with all text in message files so translations can be added later.
• Clear states: loading, empty, error and "saved" on every screen. A stale-version conflict tells the user who changed what.

Data conventions

• IDs: UUID v7.
• Time: timestamptz in UTC. Business dates (best-before, leave days) are date, interpreted in the tenant's timezone.
• Money: numeric(14,4) plus a currency code on the same row. Never add amounts across currencies; never convert silently.
• Quantities: integers in base units. Packs and boxes are multipliers on top of base units, never a separate count.
• Rows: every row has created_at, updated_at and created_by. Edits use optimistic concurrency (version column) wherever two people could change the same record.

Security

• Marketplace credentials:
  • Our marketplace application credentials (SP-API client secret, eBay app keys, Shopify app secret, Ads client) are Worker secrets.
  • They are never stored per tenant. seba-erp kept them in its settings row next to tenant tokens.
• Tenant tokens: refresh and access tokens are encrypted with AES-GCM via WebCrypto. The key comes from Secrets Store and carries a key version, so keys can be rotated.
• Sessions: HttpOnly, Secure, SameSite=Lax cookies on the app domain. State-changing requests require a CSRF token or an Origin check.
• Sign-in: multi-factor authentication (Better Auth twoFactor plugin) is required for every user of a tenant that has an Amazon connection (Amazon's data-protection rules), and offered to everyone else.
• Invitations: an invitation or a Google sign-in joins a tenant only for a verified email that exactly matches the invited address.
• Browser hardening: frame-ancestors 'none' on the app and the MCP consent page; a strict Content-Security-Policy.
• Abuse protection: Turnstile on sign-up and password reset; rate limiting on authentication routes.
• Webhooks: every inbound webhook is signature-verified and stored before it is processed.
• Server-side fetches of user-supplied URLs (e.g. AI images) allow only public https and block private addresses.
• Logs include tenant_id and the request id, and never tokens or buyer addresses.

AI and MCP

• Who pays for tokens: MCP tool calls are driven by the customer's own assistant (Claude, ChatGPT), which pays for the tokens. Vervoro pays only for model calls made inside Vervoro.
• Gateway: every model call Vervoro makes goes through AI Gateway, which gives per-tenant logging, cost tracking and rate limits. The default provider is Anthropic. Usage is metered per tenant (Analytics Engine) for billing.
• MCP server:
  • Built with the Agents SDK plus workers-oauth-provider, which stores its grants in Workers KV.
  • Served at /mcp* on the app's own host, so the OAuth consent step can see the user's Better Auth session. The consent screen names the client (e.g. Claude) and the tenant being connected; if the user belongs to several tenants they choose one.
  • A token belongs to one user in one tenant, expires (access 1 hour, refresh 30 days), and can be revoked.
  • Each tool checks that user's permissions and the ai entitlement on every call.
  • Tool output passes the same field filter as the API: no cost fields without finance.costs.read, and never buyer personal data through MCP. Bulk reads need data.export. A test runs every tool with a Warehouse-role token.
• Tool kinds: read tools return data; propose tools create a proposal record. Proposals apply only after a person approves them, with the target re-checked first. See Domain rules.

Files, PDFs, email

• Files: R2, EU jurisdiction. Uploaded files are served as downloads (Content-Disposition: attachment, X-Content-Type-Options: nosniff, a sandbox CSP), never rendered inline from the app's origin, so an uploaded SVG or HTML file can't run script in a user's session. File types are checked by content, not by name or declared type.
• PDFs: generated with pdf-lib (pure JavaScript; seba-erp's pdfkit needs file-system fonts). Barcode drawing comes from seba-erp's own Code 128 encoder (lib/barcode128.ts). Label sizes 15 × 10 cm and A4. Browser Rendering can do HTML→PDF if a template is easier in HTML.
• Reading PDFs (supplier documents): unpdf instead of pdf-parse.
• Excel: test exceljs under nodejs_compat. For large workbooks, stream them, or write CSV, which is often enough.
• Email: Cloudflare Email Service for sending (POs to suppliers, invitations, alerts). Inbound email (for a future accounting inbox) uses Email Routing plus an Email Worker, not IMAP polling.

Workers limits and how we design for them

Checked against Cloudflare's docs on 2026-10-06, Workers Paid plan. Re-check before relying on a number.

Environments and delivery

• Environments:
  • Local: wrangler dev with a local Postgres or a personal Neon branch.
  • Preview: one per pull request, on its own Neon branch.
    • Branched only from the masked seed: import templates with personal columns replaced by fake but consistent values, or synthetic data; no marketplace tokens. CI refuses any other parent branch.
    • The branch expires and is deleted when the PR closes.
    • Preview Workers connect directly to their branch with pg, not through Hyperdrive. Hyperdrive allows 25 configurations per account, and previews need no pooling.
    • Same db(env, region) code path, a fresh client per request or job, and the runtime role (never the owner).
  • Staging: always through Hyperdrive (caching off), on an unmasked copy of the data. This is where pooling behaviour is proven: CI runs the isolation suite and a concurrent reserve/dispatch test here before every production deploy.
    • Staging must never reach a real marketplace or customer. It has its own token-encryption key (so production tokens can't be decrypted there), the copy is made with all marketplace tokens removed, and its outbox relay runs in dry-run: it logs what it would send and sends nothing. Outbound email goes to a test inbox. The buyer-data anonymiser runs on staging too, so its copy follows the same 30-day rule as production.
  • Production.
• Pipeline:
  • CI runs typecheck, lint, unit, integration (real Postgres with RLS) and the isolation suite.
  • Migrations run before deploy, over Neon's direct connection as the owner role, never through Hyperdrive. A migration must work with both the old and the new code.
• Backups:
  • Neon point-in-time restore: 7 days on Launch, 30 on Scale.
  • A nightly pg_dump -Fc from a scheduled GitHub Action to R2 (EU). It is provider-independent, so it is our way off Neon if ever needed. The dump runs as a read-only database role, is encrypted before it leaves the runner (e.g. age with a key held only by the owner and engineers), and is kept for 14 days, so buyer data in backups doesn't outlive Amazon's limit by much. GitHub is therefore a sub-processor (Operations).
  • The restore rehearsal before cutover restores that dump; write down how long it took.

Regions (US later)

US customers get their own database cell, not a shared global database.

• Day 1 (EU only):
  • tenant.region column.
  • A db(env, region) factory that picks the region's Hyperdrive binding.
  • Better Auth tables in their own auth schema.
  • A global directory that needs only email_hash → region.
• When a signed contract needs it:
  • A second Neon project in a US region (a Neon project's region can't be changed later), plus a second Hyperdrive configuration.
  • R2 and Durable Objects in their us jurisdictions.
  • Each tenant is pinned to one region.
• Residency wording for contracts and the DPA:
  • Business data, including orders and buyer personal data, stays in the tenant's region.
  • Account identity (email, name), the tenant directory and billing data are global, held in the EU cell. Stripe processes billing data in the US anyway.
• Queues, Workflows and logs carry ids, never personal data. Cloudflare documents no jurisdiction control for them.
• EU customers: London is acceptable, because the EU's UK adequacy decision is renewed until 27 Dec 2031 (verify with counsel). Add Frankfurt only if a contract requires storage inside the EU.

Observability

• Workers Logs (7-day retention) for structured logs. Every line carries tenant_id and the request or job id, never tokens or buyer data. Sample high-volume logs.

• Security logs kept 12 months (Amazon requires at least 12 months): sign-ins, permission changes, support access, token use and audit events are shipped with Logpush to R2 (EU) and kept for 12 months, without buyer data.

• Workers Issues (open beta) groups exceptions, failed invocations and 5xx responses. Its automations post to chat, an incident tool or a webhook.

• Browser errors: the SPA sends window.onerror and unhandledrejection to /api/client-errors, which logs them as errors so Issues picks them up.

• Health cron every 5 minutes. The failures that hurt are silent, so it checks:

  • order-import watermark age per connection;
  • age of the oldest outbox row;
  • failed jobs;
  • drift between the stock ledger and stock balances (rule S1).

  Anything wrong is logged as a tagged error that an Issues automation turns into a page.

• Fallback: Sentry Team, if Issues misses things in the first weeks after cutover.

← All documents

5. Domain rules

These rules cannot be broken. Each one needs at least one automated test, named with the rule id (e.g. S7 applies pack multiplier). Purchasing rules are PU, so they can't be confused with the P0/P1/P2 priorities. Where seba-erp learned a rule the hard way, its file is named so you can see the original bug.

Tenancy

• T1. The tenant comes from the server (session, signed job message, MCP token), never from the client.
• T2. Every tenant row has tenant_id, and RLS enforces it. A missing tenant context returns no rows; it never returns all rows.
• T3. Identifiers that are unique in the real world are unique per tenant: SKU, batch number, native order id per connection.
• T4. Jobs, files, caches, exports and MCP tools are tenant-scoped the same way API routes are.

Stock

• S1. Ledger first. Every physical stock change is an immutable movement (received, transferred, dispatched, adjusted, repacked_in/out, returned, written_off) with quantity, batch, location, status, reason, actor and source document. Stock balances are updated in the same transaction and must always equal the sum of movements. Reserving and releasing are allocations (S2), not movements. A nightly job checks this and alerts on any difference.
• S2. One reservation implementation. Reserving and releasing stock is one function in the inventory service, used by every channel, manual orders, Vendor and FBA. A reservation is an allocation row linking an order line to a batch and quantity, not just a counter. seba-erp: lib/order-stock.ts, where per-channel copies drifted and left reserved quantities stranded.
• S3. Physical ≠ sellable. Channels always receive sellable, never physical. seba-erp: lib/stock-availability.ts, where Shopify was pushed physical stock and oversold.
  • Product sellable = physical saleable stock in the warehouses serving that channel account − reserved − safety buffer, counting only batches that are not expired (and meet any minimum shelf life set for the channel).
  • Kit sellable = the minimum over its components of ⌊component sellable ÷ component quantity per kit⌋.
  • Listing quantity pushed = ⌊sellable ÷ the mapping's multiplier⌋ (a 6-pack listing on a product with 20 sellable pushes 3).
• S4. Never negative, never clamped. A movement that would take a balance below zero fails with an error. Never hide it by clamping to zero.
• S5. Physical stock leaves only at dispatch confirmation. Labels, pick lists, packing lists, tasks and channel "shipped" messages do not move stock.
• S6. FEFO by default. Allocation takes eligible batches with the earliest best-before date first. A manual override is allowed and audited. Expired batches are not allocated.
• S7. Base units everywhere. Packs and boxes are multipliers that are always applied. seba-erp: lib/fba-stock.ts, where shipping five 10-packs deducted 5 instead of 50.
• S8. Kits vs packs. A bundle/kit has no stock of its own; it reserves and dispatches its components. A physical pack has its own stock; dispatching it does not consume components again. A repack job converts components into packs with paired movements.
• S9. Returns go to quarantine. Returned goods are not sellable until a person inspects them as saleable, damaged or written off. A refund never restocks anything, and a restock never refunds anything.
• S10. Moving stock to FBA is a transfer, not a sale. It creates no order and is never "confirmed" as a sale. Stock is reserved against the FBA shipment once it is ready to pack (so it stops being pushed to channels) and deducted at handover. Each FBA shipment is recorded once, keyed on Amazon's shipmentId. A shipment created outside Vervoro (Seller Central's Send to Amazon) is recorded in Vervoro the same way, and a daily check lists Amazon shipments with no Vervoro record.
• S11. Receiving creates a batch with landed cost (provisional until all charges arrive). Batches without a supplier lot get YYYYMMDD-NN references.

Orders

• O1. One canonical order per native order. The key is (tenant, connection, native_order_id). Re-importing updates the order; it never duplicates it. Two accounts that use the same order number are two different orders.
• O2. An order line whose SKU is unmapped is imported and flagged, reserves nothing and appears in "unmatched SKUs". Mapping it later triggers reservation.
• O3. Shortage: reserve what is available and show what is missing. Never cancel automatically and never assume stock will arrive.
• O4. Pre-dispatch edits: a native quantity decrease releases stock; an increase tries to reserve more.
• O5. Cancellation: a cancellation request is not a cancellation. Reservations stay until cancellation is confirmed, then are released once.
• O6. FBA orders (Amazon-fulfilled) are recorded for reporting and dashboards and never reserve own-warehouse stock. Every imported order stores its fulfilment channel (merchant or Amazon) from the marketplace data. Both values are matched positively (Amazon: AFN = Amazon, MFN = merchant); a missing or unknown value is not reserved until it is known. seba-erp: lib/amazon/order-import.ts.
• O7. An order total is the sum of its lines, in the order's currency. Marketplace fees are not part of a sale.
• O8. Dispatch is recorded once. Retries, tracking updates or channel messages never create a second dispatch.
• O9. One warehouse per order. An order reserves and ships from one warehouse: its channel account's default warehouse, which an authorised user can change before picking (reservations move with it). The stock pushed to a channel account is the sellable stock of the warehouses that serve it. Splitting one order across warehouses and automatic routing rules are later scope.

External systems

• E1. No network calls inside a database transaction, and never while holding stock locks.
• E2. Outbox. Anything that must reach a marketplace (stock push, dispatch notification, Vendor confirmation, ads change) is written to the outbox in the same transaction as the change. It is sent afterwards by an idempotent job with a stable operation id.
• E3. A timeout is "unknown", not "failed". For anything that is not naturally idempotent, read the native state back before retrying. Never blindly resend a confirmation, a cancellation or a campaign creation.
• E4. Stock push sends the latest absolute quantity, coalescing multiple changes, and only for SKUs whose sellable quantity changed since the last confirmed push. seba-erp: lib/stock-push.ts. Pushing every SKU every run cost 3 calls and 700 ms per SKU on Amazon and drained Shopify's rate limit.
• E5. Every marketplace call goes through the rate limiter for its account and operation. HTTP 429 means wait (for Retry-After if sent, otherwise the operation's restore time), then retry; it does not mean the SKU is broken. seba-erp: lib/amazon/spapi.ts.
• E6. One stock writer per channel account. Only one system, and one job, may push stock to a given account at any time. While a customer migrates, the old system is the writer and Vervoro's connections stay in shadow mode; at cutover the roles swap.
• E7. A queued request or an HTTP 200 is not proof that the channel applied the change. Reconcile periodically by reading native quantities and orders back.

Channels and accounts

• C1. A tenant can connect several accounts of the same connector. Identity is the native seller, shop or store id; reconnecting the same account keeps its history, mappings and watermarks.
• C2. Mapping is per connection: (connection, channel SKU) → product × multiplier, fulfilment type. The multiplier is how many base units one channel unit contains (a 6-pack listing = 6); order quantities are converted with it when the order is imported, in one place for every channel. Fulfilment type is merchant or Amazon (FBA). The channel's product reference (ASIN, eBay item id, Shopify variant id) groups several SKUs of one listing.
• C3. Only active listings are offered for mapping. seba-erp: lib/listing-sources.ts.
• C4. A tenant only sees channels it actually uses; don't show empty rows for connectors it never connected. seba-erp: lib/selling-channels.ts.
• C5. Stock is pushed only to merchant-fulfilled listings. Never push a quantity to an FBA SKU: on Amazon this can switch the listing to merchant-fulfilled. seba-erp: lib/stock-push.ts.
• C6. Unmanaged listings are not left selling. Before stock push is switched on for a connection, every active merchant-fulfilled listing is read back. Any listing with quantity above zero that Vervoro doesn't push must be mapped, or set to zero, or explicitly signed off.

Vendor Central

• V1. Every PO confirmation needs explicit user approval, even when stock covers it. The approved quantities and prices are what get sent; a later stock change never silently alters them.
• V2. Confirmed unit cost ≤ PO cost × (1 + tolerance), rounded down to the penny. Tolerance is a tenant setting, defaulting to 2%. seba-erp: lib/vendor-pricing.ts.
• V3. Rejected quantities create no reservation and no backorder. The accepted quantity ships from one warehouse, in one shipment.
• V4. Approval creates a Vendor-channel order that reserves through the normal inventory service (S2). seba-erp: lib/vendor-stock.ts.

FBA, purchasing, ads

• F1. Inbound plans follow Amazon's per-SKU prep and label rules, never a blanket default. Boxes over 15 kg get the team-lift warning.
• PU1. A supplier document is accepted only if its lines reproduce its printed totals exactly. Otherwise a person keys it in.
• PU2. An unknown supplier product code stops the PO until a person maps it; the mapping is remembered per supplier.
• A1. The ads engine acts only on ad groups that advertise a single ASIN, and only after a person approves the proposal.

AI

• AI1. AI never changes data directly. It creates a proposal with the exact content and the state of the target it was based on.
• AI2. Applying a proposal re-checks that the target still matches that state. If someone changed it in the meantime, the proposal is refused and the user is told why. seba-erp: lib/amazon/listing-edit.ts.
• AI3. An MCP token acts as one user in one tenant, with that user's permissions. It can be revoked at any time and never exposes marketplace credentials.
• AI4. MCP never returns buyer personal data, and its output goes through the same field filter as the API (no costs without finance.costs.read). Bulk reads need data.export.

Glossary

← All documents

6. Integrations

Every connector implements the connector interface in Architecture: Modules and follows Domain rules: External systems. seba-erp shows what works today against Seba's real accounts; read it before writing a connector.

Statements marked verify come from seba-erp's notes or from memory. Check them against the provider's current documentation before you depend on them.

Approvals to start now

These take weeks and are outside the engineers' control. They don't block Seba: until Vervoro's apps are approved, Seba connects through its own existing Amazon and eBay apps, plus a Shopify custom-distribution app and a TikTok self-developed app made for Vervoro (see below and the Day-1 checklist). They do block every external customer.

Running alongside the old system: separate authorisations

While a customer migrates, the old system and Vervoro (in shadow mode) read the same accounts at the same time; for Seba that is seba-erp. Each system holds its own tokens, so a token refresh in one can't invalidate the other and a rollback never needs a re-login. Where both use the same app, its app-level credentials are still shared; that is noted below.

Both systems use the same Amazon seller account and app, so they share its rate limits: Vervoro polls less often in shadow mode, imports FBA orders by report, and backs off automatically when the shared quota is under pressure.

Amazon Seller (amazon-seller): SP-API

• Auth: Login with Amazon OAuth (website authorization workflow); one refresh token per seller account and region. seba-erp has app/api/amazon/login and callback built but never run against a public app.

• App type and authorisation limits (Amazon's authorisation-limits page, checked 2026-10-06):

  App type	Who can authorise it	Limit
  Private	Only your own organisation, by self-authorisation	10 self-authorisations
  Public, unlisted	Other sellers and vendors through OAuth	25 sellers (vendors unlimited), plus 10 self-authorisations
  Public, listed on the Appstore	Anyone through OAuth	Unlimited

  • A private ("developer mode") app cannot serve other companies. It is for your own organisation only. Vervoro's customers are other companies, so customers need a public app from the start.
  • Public, unlisted covers the plan of 10–20 customers. Register Vervoro as a public developer, keep the app unlisted, and onboard up to 25 sellers through OAuth. List on the Appstore before seller number 25.
  • The review is the long-lead item. Public developer registration (and restricted roles for buyer PII) goes through Amazon's review whether the app is listed or not, so start it now.
  • Bridge for Seba: until Vervoro's public app is approved, Seba UK's tenant can connect through Seba's existing private app by self-authorisation (Seba's own accounts). Store that app's credentials encrypted on the connection, as with Shopify custom apps. Switch the connection to Vervoro's app once it is approved.

• Used by Seba:

  • Orders, FBM and FBA, on separate schedules.
  • Listings Items API for FBM stock push.
  • Catalog and listing text edits.
  • A+ content (read and submit; the AI module).
  • Product pricing (advanced reports).
  • Finances API (payout profitability; accounting later).

• FBA orders at volume: Seba UK alone has about 850 FBA orders a day. Fetching items order by order costs one GET call per order. Import FBA orders in bulk from Amazon's order reports instead (e.g. every few hours), and keep per-order API calls for FBM orders, which must arrive quickly.

• Buyer data: without restricted roles and a Restricted Data Token, an order carries only city, postcode and country, with no name or street. Plan for both states. Amazon's Data Protection Policy limits how long buyer data may be kept; implement the retention it requires.

• Fulfilment channel (AFN / MFN): each order's FulfillmentChannel is AFN (Amazon-fulfilled, FBA) or MFN (merchant-fulfilled). Test both positively: treating "not AFN" as merchant-fulfilled would reserve warehouse stock for orders Amazon ships itself. An order with a missing or unknown value waits until Amazon reports it (rule O6). seba-erp: lib/amazon/order-import.ts.

• Rate limits:

  • Limits apply per selling partner and application, so tenants don't share a quota. seba-erp relies on this; only the Amazon Ads API is shared enough to need staggering (lib/scheduler.ts).
  • Amazon rarely sends Retry-After on a 429. Wait for the operation's restore time instead. From seba-erp (lib/amazon/spapi.ts and callers): getOrders restores about one request a minute, so its retries wait 65 seconds; Finances calls retry after 3–5 seconds; 10 seconds suits most other operations.
  • Check each operation's published rate and burst in Amazon's docs and set the Durable Object limiter to them.

• Polling intervals Seba runs today (seba-erp lib/scheduler.ts; a starting point, not a rule):

  Job	Every
  Amazon FBM orders; eBay and TikTok orders	30 min
  Amazon, eBay, Shopify and TikTok stock push; Shopify orders	60 min
  Amazon FBA orders, FBA shipment status, Vendor POs	4 hours
  Amazon settlements	daily

  FBM orders use a watermark ("changed since the last run"), so a routine run fetches only the few orders that moved.

• Cost of stock push: about 3 calls and 700 ms per SKU, so only push changed SKUs (rule E4).

• Marketplaces (UK, DE, …) are destinations under one seller account, not separate accounts.

• API fees (watch this):

  • In November 2025 Amazon announced fees for third-party developers: a $1,400 annual fee, plus monthly tiers on GET calls only. Basic: 2.5M calls free. Pro: $1,000/mo for 25M. Plus: $10,000/mo for 250M. Overage: $0.40 per 1,000 calls.
  • On 12 May 2026 Amazon withdrew them "at this time", so today SP-API is free. They may come back, so design to keep GET calls low.
  • How to keep GET calls low:
    • Use the Notifications API (e.g. order-change notifications) instead of polling where possible. Amazon delivers notifications only to an AWS SQS queue or EventBridge, so this needs a small AWS account and a bridge into Cloudflare Queues. For the first version, polling is fine at Seba's volume; add notifications later.
    • Use reports instead of many single-item GETs.
    • Only re-read what changed.
  • Measure GET calls per tenant from day one (Analytics Engine), so a fee change can be priced into plans.
  • Don't split tenants across several developer accounts or apps to stay under a free tier. Each app needs its own Amazon review and its own seller authorisations. It would probably breach Amazon's developer policies, and each account would pay the annual fee anyway.

Amazon Vendor (vendor): SP-API vendor roles

• Account: a separate authorisation and refresh token per Vendor account (e.g. Vendor UK, Vendor DE), identified by its vendor code (party id, usually 5 characters).
• Connecting a Vendor account differs from Seller (seba-erp: app/(dashboard)/settings/amazon-vendor, summarised here):
  • It is often a separate LWA app from the seller one, with its own client id and secret. A refresh token belongs to one app; exchanging it with another app's credentials fails with invalid_grant. Store the app credentials with the connection.
  • Authorise from Vendor Central, not Seller Central. A seller account holds no vendor entity, so Seller Central's app list refuses. The consent link is https://vendorcentral.amazon.co.uk/apps/authorize/consent?application_id=<amzn1.sp.solution…>&version=beta, opened while signed in to Vendor Central.
  • Amazon returns an spapi_oauth_code to the app's OAuth redirect URI. It expires within minutes, so the callback must exchange it at once. Set both the OAuth login URI and the redirect URI on the app in Developer Central.
  • Fallback: paste a refresh token. Validate it: a refresh token starts with Atzr; amzn1.oa2-cs.… is a client secret and amzn1.application-oa2-client.… a client id, both commonly pasted by mistake.
• APIs: vendor orders (POs, acknowledgements); later, shipments (ASN).
• Labels and transport: shipping labels come through the API only for Direct Fulfillment vendors. Retail vendors such as Seba book transport in Carrier Central and send the ASN in Vendor Central; seba-erp does neither through the API today.
• Price ceiling: see rule V2; lib/vendor-pricing.ts records the real PO where Amazon accepted a small rise.
• Not in scope: supplier invoices and credit notes stay in Vendor Central; Vendor remittances belong to the future Accounting module.

Amazon Ads (ads)

• Separate registration: a third Amazon application, separate from SP-API, with its own LWA scope (advertising::campaign_management), hostnames and refresh token. A seller token cannot call the Ads API, and an Ads token cannot call SP-API. (lib/amazon/ads.ts)
• Profiles: every call is scoped to a profile, one advertising account in one marketplace.
• Reports are asynchronous; a first report can take 20 minutes. Run the request → poll → collect sequence as a Workflow.
• History: Amazon returns change history for 90 days only.
• Daily rhythm: structure sync, daily spend, nightly engine proposals. Stagger tenants so they don't all hit the API at the same minute (seba-erp staggers Ads jobs).

eBay (ebay)

• Auth: our own eBay application with OAuth consent. The seller registers nothing with eBay. (lib/ebay.ts)
• Token lifetime: refresh tokens expire after about 18 months (verify); show reconnect warnings before then.
• APIs: Sell APIs (Fulfillment for orders; Inventory, or Trading for legacy listings, for stock). Check which listing model Seba's listings use; older listings may not be visible through the Inventory API.
• Buyer data: full name, email, phone and address are available, so retention rules apply.

Shopify (shopify)

• Distribution and billing (verify with Shopify before building):
  • The rule: an app listed in the Shopify App Store must charge through Shopify's own billing (App Pricing / Billing API). A merchant who installs from the App Store must not be able to reach a Stripe checkout. Shopify keeps 0% of an app's first $1M of lifetime revenue and 15% above that (since June 2025).
  • Start: use custom distribution (an install link per merchant from the Partner Dashboard). There is no App Store review, and Vervoro bills the tenant through Stripe as usual. This is how Seba and other sales-led tenants connect.
    • A custom-distribution app installs on one store (or one Shopify Plus organisation), so each merchant gets its own app with its own credentials. Store those credentials encrypted per connection, like tokens. This is the one exception to "app credentials are Worker secrets".
    • Fine for a handful of sales-led tenants; it does not scale to self-serve.
  • Later, for App Store growth: list the app. Tenants who arrive through the App Store are billed through Shopify App Pricing and their entitlements come from Shopify's billing events, alongside Stripe. Keep the two billing paths fully separate.
• Connections: OAuth per store. Several stores per tenant are allowed.
• API choice (verify the current rules): seba-erp uses the REST Admin API. Shopify treats REST as legacy and requires new public apps to use the GraphQL Admin API, so build Vervoro's Shopify connector on GraphQL.
• Rate limits: GraphQL uses a calculated query cost. On a throttle, honour the provider's wait time; don't mark the SKU as failed. seba-erp: lib/shopify.ts.
• Webhooks: orders create/update, plus the mandatory privacy webhooks (customer data request, customer redact, shop redact).

TikTok Shop (tiktok)

• Request signing: HMAC-SHA256 over path + sorted query parameters (excluding sign and access_token) + body, wrapped in the app secret. (lib/tiktok.ts)
• APIs: order import and stock sync.
• Partner app approval is required for other sellers.

Future channels (not in the first version)

• US: Walmart Marketplace, Target Plus, Amazon US, eBay US, Shopify (US stores).
• Europe: Etsy, Kaufland, OTTO, bol.com.

Each is a new connector module (see Adding a new sales channel). Check each one's partner programme, approval rules and API fees before committing to a date. US channels also bring USD and US sales tax, which the data model already supports (money with currency, tax per order line).

Stripe

• See Commercial model. Webhooks are verified, stored by event id and processed idempotently.

Connector checklist (definition of done)

• Connect, reconnect (same identity, history kept) and disconnect (stock push stops first).
• Order import is idempotent across overlapping windows, handles unmapped SKUs and runs per account.
• Stock push sends sellable quantities, only changed SKUs, coalesced, through the rate limiter, and is reconciled periodically.
• Dispatch notification goes through the outbox, retries safely, and its failure is visible without undoing the local dispatch.
• Tokens are encrypted and refresh automatically; a reconnect is requested before expiry.
• Fixture-based tests from recorded real responses, with buyer data removed.
• Shows up in the jobs view with clear errors.

← All documents

7. Delivery plan

Goal: Seba UK runs its daily operations on Vervoro.

How: build P0, estimated at about 36 engineer-days (Work packages). Then move Seba UK with the standard customer migration (D-058): import once, run the channels in shadow mode for a few days, then switch over. The expected cutover is January 2027, after the go-live freeze; progress checkpoints turn the estimate into a measured forecast as the build runs (D-065).

Priorities decide what moves if time runs short, never the domain rules.

Fixed points

• No go-lives from 15 November to 31 December, including Seba's own tenants (Operations). Connections already in shadow may keep running.
• Seba EU follows Seba UK, through the same migration steps.
• The first external customer comes after the legal checklist, the marketplace approvals and P2.

Priorities

P0: needed to move Seba UK. Anything that writes stock or that Seba needs to fulfil orders moves together, because seba-erp and Vervoro must never both write stock.

• Platform:
  • Identity and access: tenants and auth with multi-factor sign-in, RBAC and warehouse scope, manual entitlements, module registry, audit log.
  • Background work: jobs and the dispatcher cron, outbox (with the suppressed status), rate limiter, token encryption, the cross-tenant role.
  • Safety nets: the CI RLS check, staging in dry-run, connection modes (shadow and active), no email or documents from a shadow tenant, the isolation suite, error tracking and backups with a rehearsed restore.
• Stock and orders: products, inventory (warehouses, locations, ledger, allocations), orders including manual and B2B, minimal customers (needed by B2B orders and invoices), dispatch documents, invoicing, basic warehouse tasks, returns quarantine.
• Phone use: every P0 screen works on a phone, the warehouse and order screens designed phone-first; camera barcode scanning (D-063, Architecture: UI).
• Channels: SKU mapping with multiplier and fulfilment type, unmatched SKUs, jobs view, the unmanaged-listings check (rule C6).
• Connectors: Amazon Seller (FBM orders by API, FBA orders by report), eBay, Shopify and TikTok Shop.
• Vendor Central: PO import, review and confirmation, price ceiling, reservation, barcode matching, dispatch. ASN and labels stay in Vendor Central and Carrier Central, as they do with seba-erp today.
• FBA: the inbound wizard on Amazon's step-by-step Inbound API, as seba-erp does today, plus recording shipments created in Seller Central (rule S10) (D-064).
• Purchasing: suppliers, POs, receiving into batches, landed cost.
• Migration: the template importers and the cutover steps in Customer migration.
• Amazon data protection (from the first shadow connection):
  • the buyer-data anonymiser job;
  • multi-factor sign-in;
  • security logs to R2 for 12 months;
  • the incident procedure with Amazon's 24-hour notice (Operations).
• Monthly cost-of-goods export for seba-erp's accounting (D-047), before the first month-end after cutover.

P1: in the weeks after cutover. These don't write stock, so seba-erp keeps running them until they are ready.

• MCP connector (D-053): OAuth, read tools, listing-change and PO proposals with approval screens; then the remaining propose tools. seba-erp's assistant stays available read-only until then.
• Vendor ASN and carton/pallet labels. New compared with seba-erp; needed before the first external Vendor customer who wants them.
• Catalogue-from-listings importer (D-035), for sellers with no system such as Seba EU. Opening stock uses the P0 template importer.
• Reporting and admin:
  • Dashboard and basic reports; customers' buyer matching.
  • Amazon settlement import (Finances API), which feeds Core's basic profit per SKU and Growth's payout profitability. Ad spend joins the profit report only when the Ads module exists.
  • Detailed reporting.
• Purchasing extras: document → PO, reorder suggestions, mapping warnings.
• Metering: Amazon API call counting per tenant; support-time logging per tenant.
• In-app AI features, if any are chosen.
• Attendance, built last: small, and seba-erp keeps running it until then.

P2: before the first external customer

• Billing:
  • Plan catalogue as data (plans, add-ons, limits).
  • Stripe Checkout, Customer Portal, webhooks → entitlements, founder prices.
  • Order counting against plan ceilings, with the 80% warning and plan-change prompts.
• Sign-up and onboarding:
  • Self-serve sign-up, trial and onboarding wizard.
  • Template downloads and the customer migration checklist in the wizard.
  • Tenant lifecycle: grace, suspension, export and deletion.
• Operations:
  • Platform admin console.
  • Status page.
  • A demo tenant with synthetic sample data, never Seba's.
• The legal checklist (Operations).

Later: lowest priority

• Amazon Ads engine. Seba keeps running it in seba-erp; it never touches stock.
• Accounting.

Work packages

P0 split into packages with a first estimate in engineer-days. Two engineers work with AI coding tools, roughly one lane each. The estimates are a starting point; the progress checkpoints replace them with measured speed.

Not estimated yet: the monthly export for seba-erp's accounting (D-047), until its contents are agreed.

Each connector can be connected to Seba's account in shadow mode as soon as it is built, once the data processing agreement is signed and the data-protection items are live.

Progress checkpoints

Instead of a fixed date, measure the build as it runs and forecast from real speed.

• When: every two to three working days, with the demo to the product owner.
• Who: an AI agent (e.g. Claude Code, run by hand or on a schedule) with read access to the application repository and this document.
• What it reads: the work packages table; merged pull requests, open issues and branches since the last checkpoint; which domain-rule tests exist by rule id; the isolation suite's status; the previous checkpoint.
• What it writes: a short report in the application repository, progress/YYYY-MM-DD.md:
  • each package: done, in progress (with a rough share done) or not started; done means merged, its rule tests present and the isolation suite green;
  • speed: estimated engineer-days completed ÷ engineer-days actually spent so far;
  • forecast: remaining P0 estimate ÷ speed, as working days and a date, then the same for P1 and P2;
  • packages that grew, new work found, and risks to the cutover.
• What the owner does with it: move scope between P0 and P1, or move the cutover. Decisions go into Decisions.

Moving Seba UK

Seba UK follows Customer migration step by step.

Before anything moves:

• The engineers' NDAs are signed before they receive any of Seba's data, masked or not.
• The Seba ↔︎ Vervoro data processing agreement is signed before the first shadow connection (D-054).

Ready to cut over when:

• the shadow check in the migration steps is done (orders arrive correctly, no unmatched SKUs);
• a restore from the nightly backup has been done and timed;
• the isolation and warehouse-scope suites are green against production;
• multi-factor sign-in, the anonymiser and security logs are live;
• staff have tried their daily screens in staging or the demo tenant;
• a test shows that switching a connection to active sends nothing that was suppressed during shadow.

← All documents

8. Decisions

Add new decisions at the bottom with the next number. To change one, add a new decision, mark the old one superseded and cut it to one line. Only decisions marked Live (or Proposed, once confirmed) apply. AI agents must ignore superseded rows.

Decision log

What the earlier design said, and what happened to it

Superseded:

Carried forward (in condensed form in Domain rules):

• Tenant authority from the server, RLS, and isolation tests (ADR 0002).
• Separating physical stock, reservations and demand, with an immutable ledger (ADR 0003).
• Durable outbound operations; "unknown" outcomes are reconciled, not blindly retried (ADR 0004).
• Dispatch as a physical event; cancellation, returns and refunds kept separate (ADR 0009).
• Multiple accounts per connector (BIZ-004).
• Vendor PO confirmations always need user approval (BIZ-002).
• No refunds initiated from Vervoro; refunds happen in the channel's own tools (BIZ-031).
• English UI with translatable messages (BIZ-050).

Moved to the backlog

These were V1 scope in the earlier VM-era design. seba-erp does not have them, and they are not in the first build:

• Central listing management: create listings, central prices with schedules, content, promotions across Amazon, eBay and Shopify; listing drift review.
• Separate DE/GB stock pools and warehouse reassignment rules. Multi-warehouse is in the data model, but routing rules are not.
• Condition-graded book stock (ISBN × condition).
• Formal stock counts with a pause and reservation repair. V1 has adjustments with reasons.
• Amazon Vendor Direct Fulfillment; full FBA inbound automation beyond what seba-erp already does; Etsy.
• Mandatory two-person approval; a custom role editor (the permission model supports it later).

Open questions

Add new ones with the next free id.

← All documents

9. Running costs

Today's list prices (checked 2026-10-06), excluding VAT. Cloudflare and Neon bill in USD; Stripe in GBP. These are infrastructure costs only, not salaries or tools for the engineers.

What we pay for

Everything else is $0 today:

Monthly cost by stage

The database is almost the whole bill. Its size per tenant is an estimate; the real figure depends on query efficiency and how often jobs run. Workers costs stay at the $5 base until the tenant count is large.

Stripe fees (only when a customer pays)

Seba UK and Seba EU are internal tenants and pay nothing through Stripe. For a paying UK customer on a £100/month plan, Stripe charges on the amount collected, £120 including 20% VAT:

• Many of our customers are businesses paying by business card, so plan for about 4–5%.
• Offer Bacs Direct Debit as the default for UK customers, especially on annual plans, where its £4 cap makes it far cheaper than cards.
• EEA cards cost 2.5% + 20p, plus 2% if Stripe converts the currency; take EUR payments into a EUR balance to avoid the conversion fee.

Not yet included

Costs Operations and launch needs before the first external customer, to be quoted:

• Status page service (or a self-hosted page on Workers).
• Help centre and support inbox tool.
• External penetration test (one-off).
• Solicitor: customer terms, data processing agreements, privacy policy, NDAs (one-off).
• ICO data protection fee (yearly) and company formation for Vervoro (one-off).

Compared with the earlier VM plan

The VM design (Hetzner + UpCloud, Keycloak, RabbitMQ) was budgeted at about €135/month for one customer, plus server administration. The serverless design costs about $36/month for Seba UK, with no servers to run.

Sources

Workers pricing · Queues · Workflows · Hyperdrive · R2 · Email Service · Neon pricing · Stripe UK

← All documents

10. Permissions and roles

A user can act only when all three are true: the tenant has the module (entitled and enabled; see Commercial model), the user's role grants the permission, and, for warehouse work, the record is in a warehouse the user may access. This document lists every first-version permission, which built-in role gets it, and how warehouse scoping and future custom roles work.

How it works

• A permission is a string, module.resource.action (e.g. orders.dispatch). Each module declares its permissions in its manifest (Architecture: Modules). The tables below are the first-version catalogue and the seed for the built-in roles.
• A role is a named set of permissions. A membership (Better Auth's member row) links a user to a tenant with one or more roles and a warehouse scope. In the first version the UI assigns one role per user; the data model allows several, and a user's permissions are the union.
• Effective permissions = the role's permissions, minus anything belonging to a module the tenant doesn't have. A role can never unlock a module the tenant hasn't bought.
• Checked on the server on every request with requirePermission("…"), evaluated fresh for each request (no long-lived permission cache). A role change or removal takes effect on the user's next request, including requests from their MCP connections.
• The UI hides what a user can't do, but it is never the security boundary.
• Platform admins (the Vervoro team) are not tenant roles; see Commercial model: Platform admin.

Built-in roles

Built-in roles are defined in code, versioned, and cannot be edited by a tenant. Every role includes attendance.self and tasks.self, so everyone can clock in and work their own tasks.

Who can change whose access

• Only an Owner grants or removes the Owner role (tenant.owners.manage). Admins manage everyone else.
• Nobody can change their own role or warehouse scope.
• The last remaining Owner can't be removed or demoted; transfer ownership first.
• Every role or scope change is audit-logged and shows in the security log.

Permission catalogue

Permission prefixes are resource names, not always the module key. Each module declares these prefixes in its manifest:

✓ = granted to that built-in role. O Owner · A Admin · M Manager · W Warehouse · Acc Accountant · S Staff.

Account and platform

Sensitive data (cross-module)

Without finance.costs.read, cost and margin fields are removed by the API, not just hidden. Without orders.buyer_pii.read, buyer fields come back masked; a Warehouse user needs it to pack and label, which is why it is granted to that role.

Products, inventory and warehouses

Orders, customers and invoicing

Channels and reports

Growth modules and add-ons

AI & MCP

Warehouse scope

Each membership has a warehouse scope: all warehouses (the default) or a list of warehouses.

• Scoped: stock, batches, movements, receiving, transfers, returns, repacks, and orders, FBA shipments, Vendor POs, PO receipts and tasks assigned to a warehouse in scope. Out-of-scope records are invisible, as if they don't exist (404, not 403).
• Not scoped: the shared catalogue, channel settings and anything tenant-wide. Reports and dashboards for a scoped user include only their warehouses.
• Enforced in the inventory and order services through one helper (scopeWarehouses(ctx)) that every warehouse-bound query uses, with a scope test suite: a user scoped to warehouse A calls every warehouse-bound route with warehouse B's ids and must get nothing.
• Owner and Admin are unscoped by definition, so making someone Admin widens their access; only Owners and Admins can do that, and only an Owner can make someone Owner. For every other role, changing the role never changes the warehouse scope.
• Seba UK and Seba EU have one warehouse each today, so scope is "all" for everyone; the feature exists for tenants with several sites.

Data model

permission catalogue    in code: module manifests (key, module, description)
role                    (id, tenant_id NULL = built-in, key, name, built_in, version)
role_permission         (role_id, permission_key)
member                  Better Auth organization plugin table (organization = tenant, user)
                        + warehouse_scope: 'all' | warehouse_id[]   (added column)
membership_role         (member_id, role_id)

• One membership table: Better Auth's organization plugin already keeps member (which user belongs to which tenant). Vervoro uses that table as the membership, adds warehouse_scope to it, and keeps roles in its own role, role_permission and membership_role tables. Better Auth's own member.role field is not used for authorization; Vervoro's tables are the only source of truth.

• Built-in roles have tenant_id NULL and are seeded from code. Changing a built-in role's permissions is a code change with a new version, recorded in the decision log.

• Custom roles (later): a tenant creates a role row with its own tenant_id and picks permissions from the catalogue; built-in roles can be cloned as a starting point. No schema change is needed.

• Tests: CI checks that every API route calls requirePermission, that every permission key used in code exists in a manifest, and that every key in a manifest appears in this document.

Adding a module

A new module ships with its permissions in its manifest, a row for each in this document, and a decision on which built-in roles get them. Until that decision is made, only Owner and Admin get the new permissions.

← All documents

11. Operations and launch

What has to exist, besides the product, before Vervoro takes money from an outside customer: support, incident handling, data retention, legal paperwork and the numbers to watch. Some of it is needed before Seba UK's first shadow connection, because Vervoro then holds Seba's data from Amazon and other channels: the Amazon data-protection rules, the incident procedure, backups, and the legal items marked before the first shadow connection. The rest must be ready before the first external tenant.

Support

• One support inbox (e.g. support@ on the Vervoro domain), with every conversation tagged by tenant.
• Log support time per tenant from the first external tenant (P1). The pricing review at founding customer 10 depends on it (Commercial model).
• Support access to a tenant's data uses the platform admin's time-limited, audited access; never a shared login.
• Help centre first: write an article every time the same question comes in twice. Core customers are self-serve; the support load decides whether Core stays profitable at its price.
• Working hours: UK business days. Outside them, only incidents (below) are handled.

Status page and incidents

• Public status page (on its own domain or a hosted status service) showing app, API, and each channel's sync (Amazon, eBay, Shopify, TikTok). The health cron's checks (Architecture: Observability) feed it.

• Severity:

  Level	Example	Response
  Critical	Stock push or order import stopped for any tenant; data exposed across tenants; app down	Page an engineer immediately, any time; status page within 30 minutes; update every hour
  Major	One channel or one module failing for several tenants	Next working hour; status page update
  Minor	A single tenant's problem with a workaround	Normal support queue

• Overselling risk first: if stock push is wrong or stale, pause stock push for affected accounts (or set channel quantities to a safe value) before investigating.

• After every critical incident: a short written review within 5 working days (what happened, impact, fix, prevention) shared with affected customers.

• Service credits: capped at one month's fee and the only remedy, as in the customer terms.

• Peak season: no go-lives between 15 November and 31 December, for customers and for Seba's own tenants alike; an engineer on call each day of that period, weekends included. Connections already in shadow mode may keep running.

• Security incidents involving personal data (cross-tenant exposure, leaked tokens or exports, unauthorised access) are always Critical:

  • Amazon within 24 hours (security@amazon.com) whenever Amazon data could be involved, as Amazon's Data Protection Policy requires;
  • the ICO within 72 hours where the law requires;
  • the affected tenants (and Seba, as controller of its buyers' data) without delay.

Amazon data protection (from the first shadow connection)

Amazon's Data Protection Policy applies to every tenant with an Amazon connection, Seba included, from the first day Vervoro holds Amazon data, which is the first shadow connection:

• Buyer personal data is kept no longer than 30 days after delivery, then anonymised by the nightly job (P0). This covers orders, stored raw marketplace payloads, webhook and inbox rows, and links from orders to customer records.
• Multi-factor sign-in for every user of such tenants (P0).
• Encryption at rest for personal data and tokens; never stored on personal devices. A customer's unmasked import files are handled only on a company-managed, encrypted machine and deleted after the import.
• Security logs kept at least 12 months, without buyer data (Logpush to R2, P0).
• Incident notice to Amazon within 24 hours (above).
• Least access: only the people who need it see buyer data (orders.buyer_pii.read), and MCP never returns it.
• As little buyer data as possible in shadow mode: a connection in shadow requests no Amazon Restricted Data Token, so Amazon orders carry no buyer name or address, and screens show buyers masked. The shadow check needs none of it. eBay, Shopify and TikTok send addresses anyway, so the anonymiser runs from the first shadow day.

Data retention

A nightly job applies these rules and reports what it anonymised or deleted.

Legal and compliance checklist

The product owner owns these; most need a solicitor.

Before engineers receive any of Seba's data, masked or not (the masked copy still holds real costs and supplier prices):

• Engineer NDA and IP assignment signed (draft).

Before the first shadow connection (about build day 4–5):

• Data processing agreement between Seba Trade (controller) and the company running Vervoro (processor), naming the sub-processors. The product owner arranges which company that is until Vervoro is registered (D-054).

Before the first external tenant:

• Vervoro company registered (being opened, D-046); it owns the marketplace developer accounts, Stripe and the code.
• Customer terms of service, including the founder rate and price lock, the 10%-a-year price-rise cap, the Amazon API fee pass-through, service credits and liability limits, data export rights, and termination.
• Data processing agreement for customers (Vervoro processes their buyers' personal data), with the list of sub-processors: Cloudflare, Neon, GitHub (runs the encrypted nightly backup), Stripe, Anthropic (only if in-app AI is used), the email provider.
• Privacy policy and cookie notice for the website and app.
• ICO registration (UK data protection fee) for Vervoro.
• UK VAT registration, EU VAT reverse-charge handling, and Stripe Tax set up.
• Marketplace approvals (Integrations), including each marketplace's data-protection requirements.
• Security review before the first external tenant: the isolation and warehouse-scope suites green on production, dependency audit, secrets rotation tested, and an external penetration test once there are paying customers.

Website and sales assets

• Public website with the pricing page (Commercial model), terms, privacy policy and status page link.
• Demo tenant with synthetic sample data (generated products, suppliers, costs, orders, Amazon, FBA, Vendor, batches with best-before dates), never Seba's data even masked, so prospects can explore without connecting their own Amazon account.
• Seba as the reference customer: a short case study with real volumes, once Seba UK has run on Vervoro for a month.

Numbers to watch (per tenant, from day one)

• Own-warehouse orders per month against the plan ceiling (3-month average).
• Support hours per month.
• Amazon API calls (GET) per month.
• Stock-push delays and sync failures.
• Infrastructure cost per tenant (database time, storage).

Review them at founding customer 10 against the triggers in the pricing report.

← All documents

12. Data model

The core tables and status flows, so every engineer and every AI session builds the same schema. Column lists are the minimum; add columns freely, but don't rename these concepts or change their keys without a decision entry. Rules referenced (S1, C2 …) are in Domain rules.

Conventions

• Every tenant table has id (UUID v7), tenant_id, created_at, updated_at, created_by, forced RLS, and composite foreign keys that include tenant_id (Architecture: Tenancy). Editable records also have version (optimistic concurrency).
• Quantities are integers in base units. Money is numeric(14,4) with a currency code on the same row.
• Natural keys are unique per tenant (or per connection), never globally.

Schemas

Core tables

Platform services

Catalogue

Warehouses and stock

Quarantine is a status, not a location. A return is received into a returns location with status quarantine; inspection moves it to saleable (normally into a storage location), damaged, or writes it off. Sellable stock counts only saleable balance rows of non-expired batches (S3).

Channels

Orders, customers, invoicing

Purchasing, Vendor, FBA

Other

Status flows

Order (merchant-fulfilled)

Amazon-fulfilled orders follow the channel's status and never reserve stock. While a connection is in shadow, an order the channel reports as shipped is closed as dispatched_elsewhere (Customer migration); once the connection is active, only Vervoro's own dispatch closes an order.

Purchase order: draft → approved → sent → partially_received → received; draft or approved → cancelled.

Vendor PO: new → in_review → approved (accepted quantities and prices fixed) → acknowledged (sent through the outbox) → reserved → dispatched → closed. An all-rejected PO is acknowledged and closed with no reservation. An Amazon cancellation releases its reservations.

FBA shipment: draft → ready_to_pack (stock reserved) → handed_over (stock deducted, stock_deducted = true) → in_transit → receiving → closed; draft or ready_to_pack → cancelled (reservations released).

Return: expected → received (quarantine) → inspected (each line saleable, damaged or written off) → closed.

Proposal: pending → approved → applied, or stale if the target changed since the proposal (AI2); pending → rejected.

What V1 does not have

• Partial dispatch of an order (one order, one dispatch).
• Nested kits.
• Splitting a batch (location changes move balance rows; the batch keeps its identity).
• Splitting one order across warehouses (O9).

← All documents

13. Customer migration

One standard way to move a seller onto Vervoro from whatever they use today: an off-the-shelf system (Linnworks, Veeqo, Helm, Cin7, StoreFeeder, Mintsoft, Zoho Inventory), custom in-house software, spreadsheets, or nothing at all. Keep it simple (D-058): move the current state once, check it in shadow mode, then switch over.

Principles

• Current state, not history. Products, stock, suppliers, open orders and open POs move. Order and invoice history stays in the old system or the customer's own exports.
• The channels are the source of truth for listings and marketplace orders. Vervoro reads them itself; marketplace orders are never imported from the old system.
• One stock writer. The old system's stock sync is switched off before Vervoro's is switched on (rule E6).
• The customer's data is handled under the data processing agreement. Their files never go into AI tools, and are deleted after import.

Steps

1. Discovery call (30–60 minutes):

   • channels and accounts;
   • warehouses and locations;
   • number of SKUs; kits, bundles and packs;
   • whether they track batches and best-before dates;
   • open POs; Vendor and FBA use;
   • anything the old system does that must keep working.

2. Get the data into Vervoro's templates. Vervoro has importers only; it never reads another system's format. The data reaches the templates in one of three ways:

   • by hand, from the old system's own CSV or Excel exports (most customers);
   • for custom in-house software, an approach still to be designed (see Source systems);
   • later, by a direct API importer (below).

   Record the exact steps for each source in the Source systems table the first time a customer comes from it.

3. Import the master data into Vervoro with the onboarding importers, against Vervoro's own templates (below): locations, products, kits and packs, packaging levels, suppliers, B2B customers. Create the warehouses in settings first. No stock yet.

   • Every import shows a preview with errors per row, and writes nothing until confirmed. Each run is kept as an import_run record (Data model).
   • Imports can be re-run safely: records match by SKU (and supplier code, customer reference) and are updated, not duplicated.
   • Each import needs the permission of what it writes: products.import, customers.write, purchasing.write, orders.create, warehouses.manage, channels.mapping.write, and inventory.receive for opening stock (Permissions).

4. Connect channels in shadow mode. Each channel gets Vervoro's own authorisation (Integrations) and starts in shadow.

   • Vervoro reads the listings and auto-maps them by SKU, then by the channel's own reference (ASIN, item id, variant id). Packs and SKUs that differ come from the SKU mappings template (it needs the connection, so it is imported now). The customer resolves the rest in the unmatched-SKU list.
   • New orders arrive. With no stock in Vervoro yet they reserve nothing; nothing is sent to the channel. Low-stock alerts stay off until cutover.
   • An order the channel reports as shipped (by the old system) is closed as dispatched_elsewhere: no stock effect.

5. Shadow check (a few days, as long as the customer needs). Done when:

   • every new marketplace order appears with the right lines and quantities;
   • the unmatched-SKU list is empty.

6. Cutover (about an hour, at a quiet time):

   1. In the old system, switch off stock sync and order import, and stop using it for stock.
   2. Import stock, once: a fresh stock export from the old system, or a physical count. Open marketplace orders already in Vervoro reserve against it.
   3. Import or enter the open direct and B2B orders and the open POs.
   4. Clear the unmanaged-listings list (rule C6). Switch each connection to active, one at a time, with a full first push, and spot-check each channel.
   5. Staff work in Vervoro from now on.

7. If something goes badly wrong in the first days:

   1. Switch the connections back to shadow.
   2. Switch the old system's sync back on.
   3. Re-enter any stock changes made in Vervoro into the old system by hand.

   Keep the old system available for at least two weeks after cutover.

Vervoro import templates

One CSV file per template, UTF-8, with a header row. The column list below is the contract every source writes to, so keep it versioned and change it only by adding columns.

Not imported:

• Marketplace orders, Vendor POs and FBA shipments are read from the channels in shadow mode. An FBA shipment still waiting to be handed over at cutover is recorded in Vervoro as usual (rule S10).
• Invoices already issued stay in the old system until paid; Vervoro issues the new ones. At cutover, set the next invoice, PO and collection-note numbers in Vervoro's settings so no VAT invoice number is reused.
• Users are invited, not imported.

Source systems

Fill this in the first time a customer comes from each source: how to get the data into the templates, what is missing, and any mapping quirks.

What to build, and when

• P0 (first migration):
  • the template importers above, with preview and row errors;
  • shadow mode, the unmatched-SKU flow, closing orders as dispatched_elsewhere, and the cutover steps.
• For external customers (P2, with the onboarding wizard): template downloads, and this checklist inside the wizard. The importers are the ones built in P0. The paid onboarding packages (guided setup, full migration) are delivered by the Vervoro team with the same tooling.
• The first investment after the first version: direct API importers, so customers move from competing systems without effort. A connector that reads the old system's API (Linnworks first, then whichever source customers come from most) and fills the same templates, so the customer only signs in to their old system. It feeds the same importers, so nothing else changes. Check each system's API terms before building.