---
id: WF-PFM-TNL-001
title: Submit a request for a new workspace
trigger: Record a workspace construction request and its durable build before attempting execution.
product_area: platform
module: tenant-lifecycle
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§4.1 (approved 2026-10-09); services-platform:docs/hq/rhythm-hq-plan.md#§I
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
- CAP-PFM-TNL-001
- CAP-PFM-TNL-004
moves:
- STATE-PFM-TNL-001
- STATE-PFM-TNL-002
crosses:
- SVC-PFM-TNL-tenants
- SVC-PFM-SEC-tenants
- SVC-PFM-SEC-customers
idempotency: The recorded submission identity returns the original workspace and job. A different request cannot
  reuse a taken or retired workspace identity.
concurrency: Workspace identity and open-attempt database constraints arbitrate competing submissions.
hops:
- n: 1
  actor_or_service: Platform API (createTenant)
  action: Check staff authority and validate workspace, customer, sender and first-administrator inputs.
  anchor: services-platform:modules/tenants/aws/api/tenants.routes.ts:createTenant
  seam: sync
  on_failure: Reject invalid input before persistence.
  left_inconsistent: No records are created.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/aws/api/tenant-api-mapper.ts
- n: 2
  actor_or_service: Provisioning submission
  action: Return an existing submission result or reject a taken or retired workspace identity.
  anchor: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:submitTenantProvisioning
  seam: sync
  on_failure: Report the identity conflict and retiring decision where available.
  left_inconsistent: No new submission records are retained.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:tenantIdTaken
- n: 3
  actor_or_service: Provisioning submission
  action: Validate sender selection, deriving a domain from a hostname-shaped workspace identifier when appropriate.
  anchor: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:withTenantEmailDomain
  seam: sync
  on_failure: Return the validation refusal.
  left_inconsistent: No sender setting is written.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/communications/services/persistence/sender-identities.ts:validateSenderIdentity
- n: 4
  actor_or_service: Provisioning submission
  action: Commit the optional new customer, provisioning workspace, sender setting and build job in one transaction.
  anchor: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:submitTenantProvisioning
  seam: sync
  on_failure: Roll back the transaction and translate supported uniqueness conflicts.
  left_inconsistent: The transaction retains every record together or none.
  observer: Job progress and service logs.
  provenance: observed
  source: services-platform:modules/tenants/services/provisioning/submit-tenant-provisioning.ts:provisioningSubmissionRefusal
- n: 5
  actor_or_service: Provisioning submission
  action: Clear local availability facts and start the committed job execution.
  anchor: services-platform:modules/jobs (startJobOrLeaveToReconciler)
  seam: state_machine
  on_failure: Log a failed start and still return the committed submission.
  left_inconsistent: The pending job can lack execution until shared recovery settles it.
  observer: Job progress and service logs.
  provenance: documented
  source: services-platform:docs/jobs.md#§2 step 8
- n: 6
  actor_or_service: Platform API
  action: Return the workspace and job reference for progress inspection.
  anchor: services-platform:modules/tenants/aws/api/tenants.routes.ts:createTenant
  seam: sync
  on_failure: Response loss can cause the caller to repeat its submission.
  left_inconsistent: The recorded job remains available through the original submission identity.
  observer: Job progress and service logs.
  provenance: documented
  source: services-platform:docs/hq/rhythm-hq-plan.md#§D12
branches:
- Creating a customer permits its first-administrator invitation.
- Omitting sender strategy retains shared sending.
waits: []
evidence:
- 'services-platform at ad3f6a65: modules/tenants/aws/api/tenants.routes.ts; aws/api/tenant-api-mapper.ts; services/provisioning/submit-tenant-provisioning.ts;
  docs/tenants/console-contract.md.'
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Submit A Request For A New Workspace

## What It Does

Record a workspace construction request and its durable build before attempting execution. The recorded submission identity returns the original workspace and job. A different request cannot reuse a taken or retired workspace identity.

## The Flow

```mermaid
sequenceDiagram
  autonumber
  actor Staff as Rhythm staff
  participant API as Platform API
  participant Sub as Provisioning submission
  participant DB as Platform database
  participant Jobs as Job engine and Step Functions
  Staff->>API: provisioning request with submission identity
  API->>API: authorize and validate fields
  API->>Sub: submit
  Sub->>DB: same submission already recorded?
  alt repeat
    DB-->>Sub: original workspace and job
  else new
    Sub->>Sub: validate sender choice
    Sub->>DB: one transaction: customer, workspace (building), sender setting, job
    Sub->>Jobs: start execution after commit
  end
  Sub-->>Staff: workspace and job identifier
```

## When Something Fails

Return the validation refusal. No sender setting is written. Roll back the transaction and translate supported uniqueness conflicts. The transaction retains every record together or none. Log a failed start and still return the committed submission. The pending job can lack execution until shared recovery settles it. Response loss can cause the caller to repeat its submission. The recorded job remains available through the original submission identity.

## Open Design Questions

Console navigation after submission is a documented requirement outside the verified console scope.