Skip to content

Factory Workflows

Foot Factory orchestrates complex industrial workflows using a meta-driven approach via TenantConfig, rather than a one-size-fits-all model.

Core Workflows

1. Tenant Provisioning

Triggered by a Super Admin via the admin dashboard or POST /api/v1/tenant.

  1. Super Admin submits tenant name, slug, plan, and admin credentials.
  2. API validates the plan slug against the Plan collection.
  3. A MongoDB transaction atomically creates:
  4. The Tenant document (with settings copied from plan limits)
  5. The admin User document linked to the tenant
  6. Sets Tenant.owner to the new user
  7. On failure, the transaction is rolled back — no partial state.
  8. After the transaction commits, subdomain provisioning runs concurrently against Vercel and Cloudflare (see Tenant Subdomain Provisioning).
  9. If both services succeed → 201 Created, domainStatus: "active". If either fails → 207 Multi-Status, domainStatus: "pending".

2. Subdomain Provisioning

Triggered automatically after tenant creation, or manually via retry.

See Tenant Subdomain Provisioning for the full flow, retry sequence, architecture diagram, and environment variable reference.

3. Dynamic Schema Configuration

Triggered by a Super Admin via Configure Schema in the admin dashboard.

  1. Super Admin opens the Schema Builder for a tenant.
  2. Defines jobSteps (name, order, isPaid) and articleAttributes (name, label, type, isRequired).
  3. Admin dashboard calls POST /api/v1/tenant-config with the full config payload.
  4. API upserts the TenantConfig document for that tenant.
  5. The client app picks up the new schema on next login or context refresh.

See Dynamic Schema for full details.

4. Job Creation & Step Assignment

Triggered by a tenant admin in the client app.

sequenceDiagram
    participant Admin as Tenant Admin
    participant App as Client Dashboard
    participant API as Core API
    participant Ledger as Ledger DB

    Admin->>App: Submits New Job (Article, Quantities)
    App->>API: POST /job/create
    API->>API: Instantiate Steps from TenantConfig
    API->>API: Assign Workers to Steps (Status: Pending)
    API-->>App: 200 OK (Job Created)

    note over Admin,API: Later: Worker begins task
    Admin->>App: Updates Stage to 'In-Progress'
    App->>API: PATCH /job/:id (status: In-Progress)
    API-->>App: 200 OK

    note over Admin,Ledger: Later: Worker completes task
    Admin->>App: Updates Stage to 'Completed'
    App->>API: PATCH /job/:id (status: Completed)
    API->>API: Calculate Wages (Article.stepRates * quantity)
    API->>Ledger: Create Credit Entry for Worker
    API-->>App: 200 OK (Stage Completed)
  1. Admin creates a job, selecting an article and filling in dynamic attribute fields (driven by TenantConfig.articleAttributes).
  2. Job steps are instantiated from TenantConfig.jobSteps — each step starts with status: "Pending".
  3. Workers are assigned to each step.
  4. As workers complete steps, status transitions: Pending → In-Progress → Completed.
  5. On step completion, the system calculates wages: Article.stepRates[stepName] × totalQuantity and credits the worker's Ledger.

5. Wage & Ledger Calculation

Triggered automatically when a job step transitions to Completed.

  1. jobController reads Article.stepRates for the completed step.
  2. Multiplies the rate by the quantity produced in that step.
  3. Creates a Ledger entry (type: credit) for the assigned worker.
  4. The worker's ledger is queryable via POST /api/v1/ledger/worker/:workerId.

6. Tenant Isolation

An invisible workflow enforced on every API request.

  1. authController.protect validates the JWT and attaches req.user (including tenantId).
  2. tenantMiddleware injects { tenantId: req.user.tenantId } into all Mongoose queries via query hooks.
  3. Operations like "Get Workers" or "Delete Job" automatically filter to the caller's tenant.
  4. Super Admins bypass tenant scoping for management operations (tenant routes use restrictToSuperAdmin instead of tenantMiddleware).

7. Plan Limit Enforcement

Enforced at the API layer on write operations via the shared checkPlanLimit helper.

  • Adding a job step beyond Plan.limits.maxJobSteps → 403
  • Adding an article attribute beyond Plan.limits.maxArticleAttributes → 403
  • Creating a user beyond Plan.limits.maxUsers → 403
  • Creating a worker beyond Plan.limits.maxWorkers → 403
  • -1 in any limit field means unlimited — no enforcement applied.

8. Worker Payment Settlement

Triggered when a payment transaction is created for a worker.

See Worker Payment Lifecycle for full details.

  1. Before recording the payment ledger entry, a settlement pass runs.
  2. Any existing advance credit (negative worker balance) is applied against jobsPendingPayment entries in FIFO order.
  3. The new payment amount is then applied against remaining jobsPendingPayment entries in FIFO order.
  4. Jobs whose full earnedAmount is covered move from jobsPendingPayment to jobsPaid.
  5. Any surplus beyond all pending jobs makes the worker's balance go negative (advance credit for future jobs).

9. Multi-Client Onboarding

See Multi-Client Onboarding Guide for the full step-by-step process.

Summary:

  1. Create or select a Plan with appropriate limits and rate limits.
  2. Provision the tenant via the admin dashboard (atomic tenant + admin user creation).
  3. Configure the tenant: job steps, article attributes, size range, custom ledger types, pagination.
  4. Add CORS origin if the client uses a custom domain (takes effect within 60 seconds).
  5. Share credentials with the client's admin.