MTS BigCommerce AI Commerce Intelligence

Problems in the target environment

• Fragmented visibility. Sales live in the control panel, inventory in a separate grid, marketing ROI in ad tools; nobody holds the joined picture.
• Reactive operations. Stockouts and churn are discovered after the revenue is already lost.
• Manual reporting. Finance and operations rebuild the same exports every week, with no single source of truth and no audit trail.
• Opaque "AI". Generic AI tools cannot see store data, hallucinate numbers, and leak merchant context to third parties.
• No governance. Who changed a price, who exported customer data, who switched a plan — frequently unanswerable.

What the platform delivers instead

• One warehouse, one truth. Orders, customers, products, variants, inventory snapshots, campaigns and analytics in a normalised multi-tenant model.
• Explainable intelligence. A deterministic rule engine produces insights and recommendations with evidence, severity and priority — every statement traceable to a metric.
• Action, not dashboards alone. Threshold alerts with in-app notifications, prioritised restock queues, win-back lists and CSV exports for finance.
• Privacy-first AI. AI_PROVIDER=rule runs fully offline; external LLMs are optional, and any provider failure transparently falls back to the local engine.
• Enterprise governance. Seven roles, 25 permissions, tenant isolation on every query, bcrypt password hashing, hashed session tokens, encrypted integration secrets and a full audit log.

Request path

1. BrowserSends a credentialed request; the session travels in the mts_session cookie (HttpOnly, SameSite=Lax, Secure in production).
2. Next.js proxyThe app's 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 @RequirePermission keys.
4. Controller + serviceControllers stay thin: validate, delegate to the module service, shape the response. Business rules live in services and shared packages.
5. Tenant-scoped PrismaQueries run through the extended client; tenant models are filtered by tenantId at the client layer, and sensitive reads are additionally guarded in service code.

Background path

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

How enforcement works

• @RequirePermission('key') on a controller or handler; PermissionsGuard resolves the session user's role and compares against its permission set.
• @Public() marks the ten endpoints reachable without a session: health, auth login/register, the BigCommerce install entry point, 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, not hard-coded constants, so MageTech can extend a merchant's role model without a schema change.

Conventions

• Collection routes are plural nouns; list endpoints accept period (7/30/90 or a custom range) and pagination parameters.
• Mutations return the created or updated resource, or a compact acknowledgement for actions.
• List responses wrap records with pagination metadata where the dataset can grow unbounded.
• Errors use standard status codes: 400 validation, 401 unauthenticated, 403 forbidden, 404 missing, 409 conflict, 429 rate-limited (documented future control), 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 metrics@mts/analytics 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 are translated into 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 the question into a typed intent, maps it to a tool call over the same metrics, and returns a grounded answer with the supporting numbers. Examples of supported shapes:

• revenue and order questions for a period, with comparison to the previous window;
• top products and best-performing channels;
• inventory risk and low-stock questions;
• customer segment and lifetime-value questions;
• marketing campaign and ROAS questions;
• "what should we do" — answered with the 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 evidence JSON a user can read.
• Auditable. Provider, tokens and request counts are logged per tenant and user.
• Cost-aware. Monthly request budget and per-tenant metering make AI spend attributable.

Authentication

• OAuth 2.0 app install. Settings links to GET /api/bigcommerce/install, which returns the BigCommerce authorisation URL with the requested scopes; the callback exchanges the code, stores encrypted credentials, and registers webhook subscriptions.
• API account token. For stores without an app registration, the merchant pastes a store hash and access token; the connection is verified on save and a sync is queued.
• Credential storage. Access tokens and client secrets are encrypted with AES-256-GCM before persistence; only ciphertext and a key version are stored.
• Uninstall handling. BigCommerce control-panel uninstall and user-removal events are processed to disable the connection and stop future syncs.

Sync engine

• Seven sync entities: categories, brands, products, customers, orders, inventory, settings.
• Paged fetch (page/limit 250) through the shared client, so no request is issued without budget.
• Per-entity checkpoints on the sync run, so an interrupted sync resumes rather than restarts.
• Idempotent upserts keyed on external ids — a repeated run converges instead of duplicating.
• Run status, item counts, errors and duration are visible in Settings.

Client behaviour

Scopes

store_v3, catalog_v3, customers_v3, orders_v3, marketing_v3

Rate limit

Token bucket at 90 requests/minute (floor 20), concurrency 6

Retries

Up to 5 attempts, exponential backoff with jitter, honours Retry-After

Timeout

30 seconds per request

Auth proof

HS256 signed_payload_jwt for control-panel callbacks; HMAC-SHA256 for webhooks

Webhooks

Order, product, customer and inventory events arrive at a raw-body endpoint. Each event is verified with a custom secret header or an HMAC signature, then recorded by event hash so retries are idempotent. Accepted events enqueue the corresponding sync entity.

Channel mapping

BigCommerce channels are normalised into a platform enum so channel mix is comparable across stores: 1 web, 2 point of sale, 3 phone, 4 marketplace, 5 offline, 6 store, 7 kiosk.

How generation works

• A report definition is created with type and date range; the request enqueues a reports job.
• The worker queries the warehouse through the shared analytics package and writes a CSV to storage/reports/<tenantId>/<reportId>.csv.
• The report record tracks status, parameters, file path and generation time, and is downloadable from the Reports module.
• Schedules repeat a definition daily; the 07:00 delivery job materialises them automatically.

Design notes

• Tenant partitioning at the filesystem level matches the database boundary — one tenant's export is never addressable from another's path.
• Historical correctness: item prices are snapshotted at order time, so a past sales export still reconciles after a catalogue price change.
• Exports are read-only by design; nothing in a report mutates the warehouse.
• Current limitation: the API generate endpoint records the request, while CSV materialisation is performed by the worker — the job is the source of the file.

Controls in place

• Password hashing. bcryptjs with a per-tenant-independent work factor; plaintext passwords are never stored or logged.
• Opaque session tokens. Random token in an HttpOnly, SameSite=Lax cookie (Secure in production); only a SHA-256 hash is stored, with expiry and last-seen tracking.
• Secret encryption. BigCommerce access tokens and client secrets encrypted with AES-256-GCM; key supplied via ENCRYPTION_KEY.
• Tenant isolation. Tenant context is derived from the session, injected by the Prisma client extension on all scoped models, and asserted in sensitive service paths.
• Permission enforcement. Server-side guard on every mutating and sensitive read endpoint; 51 endpoints carry explicit permission requirements.
• Signed webhooks. Raw-body verification with custom secret header or HMAC-SHA256, plus event-hash idempotency to prevent replay-driven duplication.
• Audit trail. Tenant-scoped log of actor, action, entity, metadata and IP for configuration and administrative changes.
• Callback JWT proof. BigCommerce control-panel callbacks verified with an HS256 signed_payload_jwt before any state change.
• Dependency hygiene. A single committed migration, one lockfile, CI on every push, and a strict TypeScript build gate.

Deliberate limits, stated honestly

Hardening path

1. Edge controlsRate limiting, security headers, request size limits at the reverse proxy.
2. Session defenceOAuth state + PKCE, rotation on privilege change, idle timeout, optional MFA.
3. Secret hygieneWire the pepper into password hashing, rotate the encryption key with versioned re-encryption.
4. OperationsDatabase backups, Redis persistence, log shipping, dependency scanning in CI.

Tokens and primitives

• Tailwind v4 @theme defines the palette; the neutral slate ramp is remapped to cool blue-greys so surfaces sit in the same family as the navy shell.
• Status ramps: emerald, rose, amber, orange, indigo, violet, sky — one set for success, error, warning, accent and AI states.
• Utility gradients: brand-gradient, cta-gradient, ai-gradient, hero-wash, ai-glow, accent-strip.
• Shell: navy sidebar and header, white logo chip, per-module active nav colour with shadow, indigo AI copilot CTA with cyan glow, orange unread badge.
• Primitives: Card with accent strip, tinted StatCard, PageHeader with module accent bar, branded Tabs, data tables and notification bell.
• Charts are hand-rolled SVG: brand series colours, light gridlines, responsive view boxes, no charting dependency.

Contribution rules — the same every time

1. Register the module colourAdd the module to the brand colour map; the nav, header bar and stat chip pick it up automatically.
2. Reuse primitivesCompose pages from Card, StatCard, PageHeader and the table pattern; do not invent one-off containers.
3. One accent, one CTAModule colour for identity; orange gradient reserved for primary conversion actions.
4. AI means indigo/cyanCopilot, generated content and AI states use the AI gradient, never the commerce orange.
5. Motion with restraintReveal transitions and chart animations use the shared timing and easing; respect reduced-motion.
6. Verify, don't eyeballCheck type, lint, route responses and computed styles before shipping a visual change.

Root scripts

npm install                # workspace install
npm run setup              # install + db:generate + db:deploy + db:seed
npm run dev                # turbo dev: web, api, worker
npm run build              # dependency-ordered production build
npm run lint               # eslint across workspaces
npm run typecheck          # tsc --noEmit across workspaces
npm run test:e2e           # Playwright, boots dev servers unless E2E_SKIP_SERVERS=1
npm run db:reset           # drop, re-migrate and re-seed

Developer experience note: with dev servers already running, skip builds and extra dev instances — shared build directories and Windows file locks (Prisma engine DLLs) are the usual failure causes. The E2E suite supports E2E_SKIP_SERVERS=1 to reuse a live stack.

Continuous integration

GitHub Actions runs on every push with two jobs:

1. verifyInstall, generate Prisma, then build, lint and typecheck every workspace.
2. e2ePostgreSQL 16 and Redis 7 services, database deploy and seed, Chromium install, full Playwright run.

Deployment model

• Web is stateless and server-render capable — suitable for container or serverless deployment.
• API and worker are stateless Node services; the worker scales horizontally because BullMQ coordinates work through Redis.
• Database changes ship as reviewed SQL migrations applied before application rollout.
• Report storage is a mounted volume; swap to object storage for multi-node deployments.
• Environment configuration is entirely environment-driven — 43 documented variables, no secrets in the repository.

Configuration principles

• Every variable is documented in .env.example with purpose and default behaviour.
• Secrets live only in a gitignored .env; the repository contains no credentials.
• Missing or malformed values fail validation at process start.
• Provider toggles are explicit: the system runs end to end with only database and Redis configured.

Plan catalogue

Billing provider defaults to in-memory for local development; Stripe checkout and webhook-driven subscription state are phase-2 work.

Access

Workspace

NovaCart Commerce (demo tenant)

Email

admin@magetech.demo

Password

MTS-demo-2026!

Mode

MTS_DEMO=1 · AI provider rule

Seeded volumes

What the seed makes visible

• A full revenue and order history with seasonality, so trends and period comparisons are meaningful.
• Realistic customer distribution across VIP, high-value, at-risk and inactive segments.
• Low-stock and overstock situations that trigger coverage maths and recommendations.
• Campaigns with varied efficiency, producing genuine ROAS comparisons.
• Pre-generated insights, recommendations and alerts so the Intelligence and Alerts modules are populated on first login.
• A completed sync run record, so the integration lifecycle can be demonstrated end to end.

Resetting the demo

npm run db:reset          # drop, migrate and re-seed
# or re-seed without dropping
npm run seed -w @mts/database

The seed is idempotent by external id, so re-running it converges to the same workspace state instead of creating duplicates.

Delivered

• LiveFull platform foundationMonorepo, API, worker, web app, warehouse, 64 endpoints, 10 modules.
• LiveBigCommerce integrationOAuth install, API-account connect, paged resumable sync, signed webhooks, channel mapping.
• LiveExplainable intelligenceRule engine with seven detectors, recommendations, alert rules and in-app notifications.
• LiveCopilot & brand systemGrounded Q&A with usage metering; complete brand palette, module colour contract and design primitives.
• LiveQuality gatesStrict types, ESLint, 10 Playwright tests, GitHub Actions verify and E2E jobs.

Next

• Phase 2Hardening for internet exposureInbound rate limiting, security headers, global validation pipe, OAuth state and PKCE, session rotation.
• Phase 2Billing and emailStripe checkout and webhook-driven subscriptions; SMTP delivery for alerts and scheduled reports.
• Phase 2AI payload completionSerialise assembled business facts into external provider payloads, with redaction enforced per privacy mode.
• Phase 2Account lifecyclePassword reset, email verification, MFA, and a complete report-schedule management surface.
• Phase 3Scale and intelligenceMulti-store tenants, forecasting, BigCommerce marketing sync, more provider tool calls, mobile or PWA views.
• Phase 3White-label programmePer-tenant theming, custom domains and agency distribution packages.

Command reference

# first run
npm install
cp .env.example .env          # set DATABASE_URL and REDIS_URL
npm run setup                 # generate, migrate, seed

# daily development
npm run dev                   # web + api + worker
npm run typecheck
npm run lint
npm run test:e2e              # add E2E_SKIP_SERVERS=1 to reuse a running stack

# database work
npm run db:generate
npm run db:deploy
npm run db:seed
npm run db:reset

# operations
docker compose up -d postgres redis
docker compose --profile tools up -d adminer

Ports and URLs

Where to look in the codebase

About this document

• Generated from the running codebase of mts-bigcommerce-intelligence; figures reflect the implemented system, not aspirations.
• Self-contained HTML: no external scripts, styles, fonts or network calls.
• Print to PDF for an offline review copy; the layout and colours are print-aware.
• Maintained by MageTech Solutions alongside the product.