Cloud Backend Setup

The repository supports local-first operation plus optional cloud backend connections. The application model stays the same: projects own file artifacts, teams and accounts are assignment scopes, and document-artifact paths are generated under stable account/workspace and project prefixes.

AWS and Azure are backend adapters for the same product model, not forks of the product. Projects, file/document artifacts, teams, accounts, grants, metadata records, write events, and notification preferences keep the same shape on both providers. The coordinating node can register AWS, Azure, or both connections and sync provider-neutral project data across those surfaces.

This page is the shared backend orientation: what gets provisioned, how local state connects to provider backends, and how sync should flow. Use AWS Backend Setup and Azure Backend Setup for provider-specific resource names, services, permissions, and CLI steps. After provider setup, use Backend Parity Checklist to confirm that AWS and Azure still implement the same application contract.

Static frontend deployment is a separate concern covered in Frontend Deployment.

Setup Progression

  1. Run the local app first with npm run dev:local.
  2. Confirm local persistence in .wm-data/workspace.sqlite and .wm-data/objects/.
  3. Provision AWS, Azure, or both private data backends with the provider-specific setup pages.
  4. Run the backend parity checklist when both provider docs or scripts need to stay aligned.
  5. Add non-secret provider connection manifests to the local API.
  6. Push and pull sync items through the coordinating node.
  7. Deploy the static frontend only after deciding how users will reach the app and API.

Select Provider Defaults

Run one of these during repo initialization to set provider labels, default resource names, and deployment metadata:

npm run init:backend -- --provider aws --environment dev --prefix workspace-management --region us-east-1
npm run init:backend -- --provider azure --environment dev --prefix workspace-management --location eastus

The script writes src/config/backend.js. That file is intentionally non-secret and safe to commit when it only contains provider choice, region/location, and resource names. Cloud credentials, account keys, connection strings, and personal login material should stay in the local cloud CLI profile, managed identity, Key Vault, Secrets Manager, or deployment environment.

The selected provider is not the only backend the coordinating node can sync with. It is the active default for labels, generated names, and deployment context. Provider connections in .wm-data/connections.json can include AWS, Azure, and local backup targets at the same time.

Provisioning Scripts

After authenticating locally with the selected cloud CLI, run either or both setup scripts:

npm run setup:aws
npm run setup:azure

The setup scripts create only the baseline private data resources:

API compute, identity callbacks, email sender verification, custom domains, and production network controls are deployment-specific and should be added after the baseline data backend is selected.

Connection Checklist

  1. Keep provider credentials outside the repo.
  2. Run the matching setup script from an authenticated shell.
  3. Add a provider connection manifest through POST /api/connections.
  4. Use POST /api/sync/push/{connection_id} to send local state to a backend.
  5. Use POST /api/sync/pull/{connection_id} to merge backend state into the local workspace.
  6. Use the same artifact prefixes across providers:
accounts/{account_id}/projects/{project_id}/documents/{document_id}/raw/{filename}
workspaces/{workspace_id}/projects/{project_id}/documents/{document_id}/raw/{filename}

The provider may call this an S3 key or an Azure Blob name, but the application should treat it as the same project-owned storage path.

Connecting AWS And Azure Together

To connect both cloud providers to one local coordinating node:

  1. Run npm run setup:aws from a shell authenticated with the intended AWS profile or role.
  2. Run npm run setup:azure from a shell authenticated with the intended Azure account, subscription, and RBAC permissions.
  3. Add one AWS connection manifest with provider: "aws" and one Azure connection manifest with provider: "azure".
  4. Push the local workspace to each provider connection.
  5. Pull from each provider connection when another surface may have changed.
  6. Resolve any reported conflicts at the project/document level, then push the resolved state back out.

The coordinating node does not store browser secrets while doing this. It calls provider adapters from the server process, using AWS CLI credentials, Azure CLI credentials, managed identity, or deployment environment credentials.

Maintaining Both Providers

When a site feature changes storage, identity, database records, API contracts, or notification behavior, update the shared model first and then keep the AWS and Azure docs/scripts aligned. The active src/config/backend.js file selects default labels and deployment context, but src/lib/workspace-model.js should continue to describe both providers in backendProviderCatalog, and the coordinating-node adapters should continue to support multiple configured connections.

Do not store credentials in src/config/backend.js. Keep cloud credentials in local CLI profiles, managed identity, Key Vault, Secrets Manager, Parameter Store, or deployment environment variables.