MTS BigCommerce AI
Commerce Intelligence

What that means in practice

• We build products, not just features. A complete, working, supported application — which is why this platform exists and runs today.
• We own outcomes. We are measured on whether the platform answers your questions, whether the data is right, and whether your team can use it without us.
• We hand over properly. Source code, documentation, environment definition, CI pipeline, training and support handover. No lock-in, no proprietary black boxes.
• We stay after go-live. Maintenance, monitoring, upgrades and a roadmap you can influence as the business changes.
• We are technology specialists. TypeScript, modern web frameworks, API architecture, data platforms, cloud delivery and AI engineering are our craft, not a subcontracted skill.

How this document is organised

• Sections 1–5 — the product: what it is, who uses it, and how it differs.
• Sections 6–22 — the engineering: stack, architecture, data, API, AI, integration, jobs, security, delivery, testing, configuration, demo data.
• Sections 23–29 — the relationship: how we demo, what we deliver, what we develop, maintain and build from scratch, our services, expertise, pricing and engagement models.
• Sections 30–32 — outcomes, quality commitments, roadmap, next steps and reference appendix.

The platform as our proof

We could describe our capability. It is faster to show it. This application is the reference implementation of how we work: structured, opinionated, complete and running.

The request path

1. BrowserCredentialed request; the session travels in the mts_session cookie — HttpOnly, SameSite=Lax, Secure in production.
2. Next.js proxyThe typed client routes /api/* to the Nest API. Server components fetch without a base URL; client components resolve it from the environment.
3. GuardsSessionGuard resolves the hashed token to a live session and attaches tenant, user and role; PermissionsGuard enforces declared permission keys.
4. Controller and serviceControllers validate and delegate; business rules live in services and shared packages. Nothing heavy runs inline.
5. Tenant-scoped PrismaQueries run through the extended client; tenant models are filtered by tenantId at the client layer, with additional assertions in sensitive service paths.

The background path

1. SchedulerFive repeatable jobs register on boot: sync dispatch, nightly full sync, daily insights, alert sweep and report delivery.
2. QueueJobs land on dedicated BullMQ queues with a stable job id per entity, so repeated triggers collapse instead of duplicating work.
3. ProcessorThe worker executes sync (paged fetch, upsert, checkpoint), insights (metrics, detectors, persistence), alerts (rules, notifications) and reports (CSV materialisation).
4. Result surfaceOutputs land in the database and on disk: insights, recommendations, notifications, sync-run records and storage/reports/<tenant>/<report>.csv.

How enforcement works

• @RequirePermission('key') on a controller or handler; PermissionsGuard resolves the session user's role and compares it against the permission set.
• @Public() marks the ten endpoints reachable without a session: health, authentication, the BigCommerce install entry point, the plan catalogue and the documented webhooks.
• 54 endpoints require a session; 51 additionally require a permission — a deliberate split so "logged in" and "allowed to act" stay distinguishable in the audit log.
• Guards attach tenant, user and role to the request context, so controllers never accept a tenant id from the client.

Permission key families

Keys are seeded data rather than hard-coded constants, so a merchant's role model can be extended without a schema change.

Conventions

• Collection routes are plural nouns; list endpoints accept a period (7, 30, 90 days or a custom range) plus pagination.
• Mutations return the created or updated resource, or a compact acknowledgement for actions.
• List responses wrap records with pagination metadata where a dataset can grow without bound.
• Errors use standard status codes: 400 validation, 401 unauthenticated, 403 forbidden, 404 missing, 409 conflict, 501 not yet implemented.

Example: session lifecycle

POST /api/auth/login
{ "email": "admin@magetech.demo", "password": "MTS-demo-2026!" }
→ 200 { "user": {…}, "tenant": {…}, "expiresAt": "…" }
   Set-Cookie: mts_session=<opaque token>; HttpOnly; SameSite=Lax

GET /api/auth/me
Cookie: mts_session=<opaque token>
→ 200 { "user": {…}, "tenant": {…}, "role": { "key": "owner" } }

Only a SHA-256 hash of the token is stored. The raw token exists in the browser cookie and in transit — never in the database.

Rule engine pipeline

1. Gather metricsThe analytics package computes revenue, orders, AOV, growth, channel mix, stock cover and customer aggregates for the requested window.
2. Run detectorsRevenue, product, inventory, customer, segment, order and marketing detectors evaluate configured thresholds and return findings with type, severity, title, message and evidence.
3. Build recommendationsFindings become concrete actions — reorder, win-back, promotion review, stock review — deduplicated by category plus action and ranked high, medium or low.
4. PersistInsights and recommendations are written with status and impact, feeding the dashboard, the insight feed and the alert engine.

Default thresholds

Copilot

The copilot classifies a question into a typed intent, maps it to a tool call over the same metrics, and returns a grounded answer with supporting numbers.

• Revenue and order questions for a period, compared to the previous window
• Top products and best-performing channels
• Inventory risk and low-stock questions
• Customer segment and lifetime-value questions
• Campaign and ROAS questions
• "What should we do?" — answered with current recommendations, not a new invention

Quality properties

• No hallucinated numbers. Figures come from the metrics service, not from the model.
• Explainable. Every insight carries readable evidence.
• Auditable. Provider, tokens and request counts are logged per tenant and user.
• Cost-aware. A monthly budget and per-tenant metering make AI spend attributable.

Connection paths

What is synced

Client behaviour

• Rate limiting. Requests are paced against the store's limits rather than optimistically fired.
• Retries. Transient failures back off exponentially instead of failing a run.
• Paging. Large collections are fetched page by page with a checkpoint after each page, so an interrupted run resumes instead of restarting.
• Upserts. Records are matched on external id and updated in place, making repeat syncs idempotent.
• Auth signing. BigCommerce login JWT payloads are signed correctly rather than hand-built, which is a frequent cause of silent 401s in custom integrations.

Webhooks

Order, product and customer events are accepted on a raw-body route, signature-verified, de-duplicated by event hash, and then applied as a targeted partial sync of the affected entity — so a new order appears without a full nightly refresh.

Report types

Lifecycle

1. RequestType, date range and optional filters are validated, then a report record is created with status pending.
2. GenerateThe worker materialises the CSV to storage/reports/<tenant>/<report>.csv — tenant-partitioned from the first line.
3. DownloadGET /api/reports/:id/download streams the file after a permission and ownership check.
4. ScheduleA schedule repeats the request on a cadence and delivers the file automatically.
5. RetainGeneration history is preserved, so a number quoted last quarter can be traced to the report that produced it.

Export conventions

• Columns are explicit and documented, not positional — a column reorder cannot silently corrupt a downstream import.
• Currency and date formats are normalised on export, so a spreadsheet in another locale reads correctly.
• Empty and null values are written explicitly rather than left ambiguous.
• Filenames carry tenant, report type and generation timestamp for auditability.
• Large datasets stream rather than buffer, so memory stays flat as the store grows.

Data dictionary (extract)

order_date        Date      Local store date of the order
status            Enum      Order status at export time
channel           Enum      web | pos | phone | marketplace | …
gross_revenue     Decimal   Order total before discounts
net_revenue       Decimal   After discounts and shipping
aov               Decimal   net_revenue ÷ orders
units             Integer   Sum of item quantities
discount_rate     Decimal   1 − (net ÷ gross)
customer_segment  Enum      vip | high_value | at_risk | inactive
stock_on_hand     Integer   Current level by variant and location
days_of_cover     Decimal   stock_on_hand ÷ average_daily_units

Type, spacing and shape

• Inter-led system sans stack for UI and marketing; a monospace stack for identifiers, SKUs, endpoints, tokens and code.
• One spacing scale, one radius scale, one elevation scale — defined as tokens, never ad-hoc values.
• Navy headings on light surfaces, white headings on navy and gradient surfaces; body copy in a muted ink for comfortable long reading.
• Tables use uppercase micro-headers on a navy band; dense data is a first-class layout, not an afterthought.
• Empty, loading, error and stale states are designed for every data view, not improvised later.

Charts without a chart library

The visualisation layer is hand-built SVG — area and bar charts, donut segments, sparklines and stat tiles. No charting dependency means no bundle bloat, full control of the brand gradient, and charts that render identically in the app, on the marketing site and in a printed report.

Motion

• Motion is purposeful: it explains hierarchy, direction and change — never it decorates.
• Reveals, card lifts, gradient sweeps and count-ups run on a shared easing curve so the interface feels like one system.
• Staggered delays give a group a reading order instead of a single noisy entrance.
• Looping background animation is low-contrast and slow; it never competes with content.
• prefers-reduced-motion is honoured everywhere — animation is a preference, not a requirement.

Local infrastructure

Two services and an optional tool, defined in infrastructure/docker-compose.yml and started with one command:

npm run infra:up     # postgres:16-alpine + redis:7-alpine
npm run infra:down

Commands

CI pipeline

Two jobs on every push and pull request to main, with concurrency cancellation so superseded runs do not consume capacity.

1. verifyNode 20 with npm caching, npm ci, then the dependency-ordered build, lint and typecheck across all workspaces.
2. e2eRuns only after verify passes. Starts PostgreSQL 16 and Redis 7 as managed services with health checks, exports the environment with AI_PROVIDER=rule, AI_PRIVACY_MODE=strict and MTS_DEMO=1.
3. Database lifecyclePrisma client generation, migrations deployed, demo data seeded — so the test run exercises a real schema and realistic data, not mocks.
4. Browser testsChromium installed with dependencies, then npm run test:e2e with the GitHub reporter, HTML report, trace and failure screenshots retained.

Deployment shape

• Three deployables — web (Next.js), api (NestJS), worker (BullMQ) — scaled independently.
• Stateless application tier: the only durable state is PostgreSQL, Redis and the report volume.
• Container-ready: each app has a production start script and no build-time coupling to the others.
• Environment-driven throughout, so promotion from staging to production is a configuration change, not a rebuild.
• LOG_LEVEL and an optional SENTRY_DSN are already wired for production observability.

Test configuration

• 60-second per-test timeout, 15-second assertion timeout.
• Serial execution with one worker — no flakes from shared-database contention.
• Existing dev servers reused locally; CI starts its own API and web, with a 120s and 180s readiness allowance.
• Trace retained on failure and screenshots on failure, uploaded as artefacts.
• One retry in CI, none locally, so a flake is visible in the pipeline rather than hidden.
• E2E_SKIP_SERVERS=1 runs the suite against already-running services.

Sign in

Workspace

NovaCart Commerce

URL

https://novacart.demo.mts

Email

admin@magetech.demo

Password

MTS-demo-2026!

Role

Owner

Plan

Growth

What is in it

Why the data is designed

• Seasonality, not a straight line. Weekly and monthly variation means trend comparisons are meaningful and the "versus previous period" logic is visible.
• Deliberate problems. Some variants are close to stockout, some campaigns underperform, some customer cohorts have gone quiet — so the insight engine has genuine findings to report.
• Volume with a point. 8,420 orders with 21,160 line items is enough to make pagination, filtering and export real work rather than decoration.
• Deterministic. The seed is idempotent and reproducible, so a demo, a screenshot and a test all show the same numbers.
• Safe by default. AI_PROVIDER=rule and AI_PRIVACY_MODE=strict: the full intelligence layer runs with no external call and no data leaving the machine.

Run it yourself

1. Start infrastructurenpm run infra:up brings up PostgreSQL 16 and Redis 7.
2. Prepare the databasenpm run db:generate, then npm run db:deploy to apply migrations.
3. Seed the workspacenpm run db:seed creates the tenant, roles, permissions, users and a year of commerce data.
4. Start the applicationsnpm run dev runs web, API and worker together.
5. Sign inOpen http://localhost:3000 and use the credentials above.

The thirty minutes

• 0–3 minTheir situation, in their words"What do you currently not know about your store that you wish you did?" We write the answers on the screen and use them as the agenda.
• 3–7 minSign in as two rolesOwner and operations manager. The identical screen, different data and different actions. Access control is proven, not claimed.
• 7–12 minDashboard in sixty secondsRevenue, orders, AOV, customers, low-stock and open alerts — with the previous-period comparison that makes a number meaningful.
• 12–18 minDrill to the answerFrom the dashboard into Sales, then Customers, then the specific cohort or product that explains the movement.
• 18–23 minThe insight, and its evidenceOpen one real insight: severity, the evidence behind it, the recommended action — and ask them to judge whether it is useful.
• 23–26 minAsk the copilotThey phrase the question. It returns grounded numbers. The credibility of the whole platform usually settles in this moment.
• 26–28 minThe alert that arrives at 02:00Show a rule, show the alert, show the notification. This is when "tool" becomes "system".
• 28–30 minThe handover question"What would you want to see on day one of your own instance?" Then we show the deliverables, not a brochure.

How we run it

• Their data if they have it. A read-only sandbox store turns the demo into their own business; the seeded workspace is the fallback.
• No slides after minute three. The system is the presentation material.
• One question at a time. We pause at the insight screen and let them interrogate it.
• Silence is useful. If a screen is confusing we stop and fix the explanation, not the screen.
• Recorded follow-up. The questions we could not answer become the roadmap conversation, in writing.

How the first four weeks run

• Week 0Discovery and accessGoals, constraints, stakeholders, data sources, environments and access. A written outcome definition we both agree on before any code.
• Week 1Architecture and first sliceData model and boundaries decided; a thin end-to-end path running against real data and demonstrable.
• Weeks 2–3IterationShort cycles against feedback. Weekly demonstration, visible backlog, reprioritised deliberately rather than accidentally.
• Final weeksHardening and handoverSecurity, performance, accessibility and error-state pass; documentation, training, CI and environment definition delivered; support agreement started.

Communication and governance

• One written source of truth for scope, decisions and open questions, so requirements are not remembered differently by different people.
• Weekly working session and demonstration — progress shown, not described.
• Decision log including the reasoning, so a later team understands why, not just what.
• Escalation path agreed before it is needed, with named contacts and response targets.
• Change control for scope changes, with the trade-off stated in writing rather than absorbed silently.

Outcomes we target

• A working version early. A demonstrable end-to-end path in the first weeks, not a design document in a quarter.
• Decisions without spreadsheet archaeology. The question that took an afternoon of exports answered from a screen in seconds.
• Problems caught before they cost money. Stockout risk, churn risk and revenue anomalies surfaced while there is still time to act.
• Reporting that reproduces. Every exported figure traceable to a generated report with a timestamp.
• Hours returned. Manual weekly reporting replaced by generated, scheduled exports.
• Ownership transferred. The client's team can deploy, extend and support the system without us.

Quality commitments

Roadmap

• DeliveredFoundation and productMonorepo, 32-model schema, 64-endpoint API, 10 modules, 7 roles, BigCommerce sync with resume and webhooks, insight engine, copilot, alerts, reports, worker with 5 queues and 5 schedules, CI and 10 browser tests.
• DeliveredBrand and experienceDesign tokens, module accents, SVG chart library, responsive layouts, marketing and application surfaces, accessibility pass.
• NextTest depth for the intelligence layerA dedicated unit and integration suite for the rule engine and metrics package, pinning thresholds and detector behaviour.
• NextRicher provider contextSerialising assembled business facts into external provider payloads, so narrative answers can cite the same computed evidence locally.
• PlannedScale and operationsConnection pooling and query budgets for larger tenants, job-level observability, retention policies for generated reports.
• Client-ledWhatever the roadmap prioritises nextFor retained engagements, the client's priorities are the roadmap. This list is the starting point, not the boundary.

What we need from you to start

• The decision-maker and the person who will use the system daily — ideally the same meeting.
• Read-only access to a store, or agreement to use the seeded workspace.
• The three questions your team cannot answer quickly today.
• Any constraint we should design around: hosting, data residency, timeline, budget shape.

A short readiness checklist

• Product runs todayAll ten modules, live on the seeded workspace.
• Documentation existsArchitecture, API, development, configuration and this document.
• Handover artefacts readySource, infrastructure, CI, seed, brand assets, training plan.
• Store connectionOAuth app or read-only API account, and a publicly reachable callback URL.
• EnvironmentDeployment target, domain, database and Redis provisioning.