Skip to content

Multi-Client Onboarding Guide

This document describes how to onboard a new factory client onto the Foot Factory platform without any code changes or redeployment.

Overview

The platform is designed to be fully configurable per tenant. Every business rule that varies between clients is stored in MongoDB and managed through the admin dashboard. The following can be configured per tenant without touching code:

Configuration Where Default
Job workflow steps (names, order, paid/unpaid) TenantConfig —
Article attributes (custom master data fields) TenantConfig —
Shoe size range TenantConfig 6–12
Custom ledger entry types TenantConfig none (built-ins only)
Pagination defaults TenantConfig 50 / 200
Plan limits (users, workers, job steps, attributes) Plan per plan
API rate limits Plan 100 req/15min

Platform-level settings (apply to all tenants):

Configuration Where Default
Allowed CORS origins GlobalConfig (DB) hardcoded base list
Subdomain suffix display VITE_SUBDOMAIN_SUFFIX env var .dotevolve.net

Step-by-Step Onboarding

Step 1 — Choose or Create a Plan

Before provisioning a tenant, ensure an appropriate plan exists.

  1. Open the admin dashboard → Plans
  2. Review existing plans. If none fit, click Create Plan and set:
  3. Name and slug
  4. limits.maxUsers — max admin users (-1 for unlimited)
  5. limits.maxWorkers — max workers (-1 for unlimited)
  6. limits.maxJobSteps — max job workflow steps (-1 for unlimited)
  7. limits.maxArticleAttributes — max article attributes (-1 for unlimited)
  8. rateLimits.maxRequests — API requests per window
  9. rateLimits.windowMs — window duration in milliseconds

Step 2 — Provision the Tenant

  1. Open the admin dashboard → Tenants → Provision New Tenant
  2. Fill in:
  3. Company Name — display name for the tenant
  4. Subdomain Slug — URL-safe identifier (e.g. acme-corp)
  5. Plan — select from active plans
  6. Admin Email and Temporary Password — credentials for the tenant's first admin user
  7. Click Confirm Provision

This atomically creates the Tenant document and the initial admin User in a single MongoDB transaction.

Step 3 — Configure the Tenant

  1. In the tenant list, click Configure next to the new tenant
  2. The configuration panel opens pre-populated with defaults. Configure:

Job Workflow (Schema Builder)

  • Add job steps in order: name, order number, and whether the step is paid
  • Example: Cutting (1, paid), Upper (2, paid), Bottom (3, paid), Packing (4, unpaid)

Article Attributes (Schema Builder)

  • Add custom attributes for articles: name (camelCase key), label (display name), type, required
  • Example: colorCode / Color Code / string / required

Size Range

  • Set min and max shoe sizes for this factory
  • Example: { min: 6, max: 12 } for standard adult sizes

Custom Ledger Types (optional)

  • Add any non-standard financial entry types this factory needs
  • Example: advance, bonus, deduction

Pagination

  • Set defaultPageSize (how many records per page by default)

  • Set maxPageSize (maximum records a client can request per page)

  • Click Save Configuration

Step 4 — Share Credentials

Provide the tenant's admin with:

  • The client app URL (e.g. https://acme-corp.dotevolve.net or your configured domain)
  • Their admin email and temporary password
  • Instructions to change their password on first login

Step 5 — Add CORS Origin (if needed)

If the client is accessing the platform from a custom domain not already in the allowed list:

  1. Open the admin dashboard → Settings → CORS Origins
  2. Add the client's domain (e.g. https://app.acme-corp.com)
  3. The API will pick up the new origin within 60 seconds — no restart needed

Suspending and Reactivating Tenants

To temporarily block a client's access:

  1. In the tenant list, click Suspend next to the tenant
  2. Confirm the action
  3. All authentication attempts by that tenant's users will return 403 immediately

To restore access:

  1. In the tenant list, click Reactivate next to the suspended tenant
  2. The tenant's users can log in again immediately

Environment Variables

For white-label or custom-domain deployments of the admin dashboard, set:

VITE_SUBDOMAIN_SUFFIX=.your-domain.com

This changes the suffix displayed in the provisioning form's subdomain slug field. If not set, defaults to .dotevolve.net.

What Still Requires Code Changes

The following are intentionally not configurable at runtime and require a code change if they need to change:

  • Job step status transitions (Pending → In-Progress → Completed) — fixed state machine
  • Authentication mechanism (JWT + httpOnly cookie) — fixed
  • Database provider (MongoDB Atlas) — fixed
  • Deployment infrastructure (Vercel + Render) — fixed