Local Setup And Sync

The local coordinating node is the API process that sits behind the static frontend during local development. It lets the app function as a real local file and workflow manager before any cloud backend is connected. It owns local persistence, object writes, connection manifests, and sync metadata. The browser never receives cloud credentials.

Run the local API and Observable preview together:

npm install
npm run dev:local

The default endpoints are:

• Frontend: http://127.0.0.1:3000/ or the next available Observable preview port.
• Local API: http://127.0.0.1:8788.
• SQLite metadata store: .wm-data/workspace.sqlite.
• Workspace envelope table: workspace_envelopes.
• Canonical sync items table: sync_items.
• Raw uploaded objects: .wm-data/objects/.
• Object manifest table: objects.
• Connection manifest: .wm-data/connections.json.

Existing .wm-data/workspace.json, .wm-data/sync-items.json, and .wm-data/objects-manifest.json files are imported into SQLite on first run. After that, SQLite is the source of truth for workspace state, sync metadata, and object manifests.

In local-only mode, the application is not connected to AWS or Azure. Records are read from and written to the local API, the SQLite database, and the local object directory. Cloud resources are used only after provider connections are added and sync operations are run.

API Surface

The frontend uses:

• GET /api/workspace
• PUT /api/workspace
• PUT /api/objects/{provider-neutral-storage-key}

The coordinating node also exposes:

• GET /api/providers
• GET /api/connections
• POST /api/connections
• GET /api/connections/{connection_id}/health
• GET /api/sync/items
• PUT /api/sync/items
• POST /api/sync/push/{connection_id}
• POST /api/sync/pull/{connection_id}
• PUT /api/connections/{connection_id}/objects/{provider-neutral-storage-key}

Provider Connections

Connections are non-secret manifests. They identify a provider, resource names, and a credential reference. Do not store keys, tokens, connection strings, or passwords in the manifest.

The coordinating node can keep multiple provider surfaces aligned. A local workspace can have a local backup connection, an AWS connection, an Azure connection, or both cloud connections. The sync API converts workspace state into provider-neutral sync items, pushes those items to connected providers, pulls remote items back, and merges them through the same conflict rules.

Current provider roles:

• local: another local filesystem/object directory, useful for backups and migration testing.
• aws: S3 for object bytes and workspace envelopes, DynamoDB for provider-neutral sync indexes.
• azure: Azure Blob Storage for object bytes and workspace envelopes, Cosmos DB for provider-neutral sync indexes.

Local connection:

{
  "connection_id": "local_backup",
  "provider": "local",
  "credential_mode": "none",
  "settings": {
    "rootDir": ".wm-data-backup"
  }
}

AWS connection:

{
  "connection_id": "aws_dev",
  "provider": "aws",
  "credential_mode": "aws_profile",
  "credential_ref": "profile:workspace-dev",
  "settings": {
    "region": "us-east-1",
    "bucket": "workspace-management-dev-documents",
    "table": "workspace-management-dev"
  }
}

Azure connection:

{
  "connection_id": "azure_dev",
  "provider": "azure",
  "credential_mode": "azure_cli",
  "credential_ref": "az-login",
  "settings": {
    "resourceGroup": "wm-dev-rg",
    "location": "eastus",
    "storageAccount": "workspacemanagedevdocs",
    "container": "workspace-documents",
    "cosmosAccount": "workspace-management-dev-cosmos",
    "database": "workspace",
    "itemContainer": "workspace_items"
  }
}

Sync Contract

Workspace objects are converted to provider-neutral sync items:

• sync_id: {collection}:{entity_id}
• collection: projects, documents, accounts, teams, grants, metadata records, write events, and preferences. The documents collection stores the file/document artifact records shown as files in the UI.
• version
• checksum
• origin_node_id
• updated_at
• deleted_at
• value

Merges use deterministic checksums and last-writer-wins conflict records. Deleted records travel as tombstones through deleted_at.

This means connected surfaces should converge on the same canonical accounts, projects, document artifacts, grants, metadata records, and write events even when AWS and Azure are both connected. Provider-specific storage services differ, but the application sync payload does not.

Adapter Status

The local filesystem adapter is implemented with SQLite metadata and a local object directory. AWS and Azure adapters are implemented server-side through the local CLI tools:

• AWS object bytes and full workspace envelopes are written to S3. DynamoDB stores workspace pointers and provider-neutral sync-item indexes.
• Azure object bytes and full workspace envelopes are written to Azure Blob Storage. Cosmos DB stores workspace pointers and provider-neutral sync-item indexes.

The adapters use server-side credentials from AWS profiles, instance roles, Azure CLI, managed identity, or deployment environment variables. The browser only calls the coordinating-node API and never receives provider credentials.

AWS requires the aws CLI and a connection with region, bucket, and table.

Azure requires the az CLI and a connection with resourceGroup, location, storageAccount, container, cosmosAccount, database, and itemContainer. The Cosmos item upsert path uses the Azure CLI cosmosdb sql item upsert command; install or enable the relevant Azure CLI support if your local az distribution does not include that command group.