Application Overview

Workspace Management is designed first as a fully local file and workflow management utility. A single user should be able to run the app on localhost, organize projects for different accounts such as clients, businesses, firms, departments, or personal workspaces, attach external files to those projects, and preserve the project record without depending on a cloud account.

The local mode is intentionally useful on its own. The frontend talks to a local coordinating-node API, metadata is persisted in .wm-data/workspace.sqlite, and uploaded file bytes are stored in .wm-data/objects/. This makes localhost a real workspace surface rather than a disposable browser-only mock.

The app reaches its full potential when it is connected to cloud backend infrastructure. Cloud connections allow multiple users to work against the same project model, which enables teams, account-level administration, shared document access, collaborative editing workflows, invitations, notifications, and durable cloud storage. Users should be able to bring their preferred backend. The current provider adapters target AWS and Azure, and the same local coordinating node can connect to AWS, Azure, or both.

Design Principles

• Local-first operation: the app remains useful as a local project, file, and workflow manager.
• Cloud-extendable operation: AWS and Azure connections add shared persistence, multi-user access, and cloud object storage.
• Provider-neutral data: projects, accounts, teams, document artifacts, grants, metadata records, and sync items keep the same logical shape on every backend.
• Account separation: application accounts separate client, business, or workspace contexts independently from cloud accounts or subscriptions.
• Project-owned documents: uploaded files resolve through projects for permissions, storage paths, audit history, billing scope, and sync.
• Server-side credentials: browsers never store cloud secrets. Provider credentials live in local CLI profiles, managed identity, cloud secrets stores, or deployment environments.
• Sync by contract: stable IDs, versions, checksums, timestamps, tombstones, and conflict records allow the coordinating node to keep connected storage surfaces aligned.

Recommended Reading Path

1. Start with Local Setup And Sync to run the app locally with persistent SQLite metadata and local object storage.
2. Read Accounts And Data Model to understand users, accounts, teams, projects, grants, and file artifact ownership.
3. Read Document Artifacts to understand how uploaded files are stored as document* artifact records under account and project prefixes.
4. Use Cloud Backend Setup to understand the shared cloud connection flow before choosing a provider.
5. Follow AWS Backend Setup or Azure Backend Setup for provider-specific private storage and database resources.
6. Use Backend Parity Checklist after provider setup, or whenever changing provider mappings, persistence behavior, or shared model fields.
7. Use Frontend Deployment when publishing the static site separately from private project data. AWS and Azure frontend commands, approval notes, and command-separation audits all live there.

Workspace Shape

The application is organized around a project relationship model. A project is a user-defined workspace entity that relates external files, source-code pages, requirements, decisions, teams, accounts, and audit history. Uploaded files can seed a project, but the project remains the durable object that owns work context, access grants, external file artifacts, tags, extracted metadata, derived outputs, and audit trail.

Accounts and teams are organization and access scopes:

• Personal workspace projects stay local or private until assigned or shared.
• Account projects belong to a client, business, department, consulting firm, or other application account.
• Account-scoped teams let account members collaborate without collapsing account boundaries.
• Personal-workspace teams group private workspace projects before they are moved into a client or business account.
• Legacy standalone team records remain in the model for import and compatibility, but the current UI creates new teams inside either an account or a personal workspace account.

Files belong to projects by default and are represented internally as document artifact records. The file repository can list and filter files across visible projects, teams, accounts, and private workspaces, but it does not bypass project permissions.

Local To Cloud Progression

The intended operating progression is:

1. Run locally with npm run dev:local.
2. Create accounts that represent clients, businesses, firms, departments, or personal workspaces.
3. Create projects under the appropriate account, team, or private workspace.
4. Upload or register files under project-owned storage keys.
5. Add provider connections for AWS, Azure, or both.
6. Push and pull provider-neutral sync items through the coordinating node.
7. Deploy the static frontend when users need browser access beyond a single local machine.

The same canonical model travels through every stage. Moving from local-only to cloud-backed operation changes where records and file bytes are persisted, not what a project, account, document, team, or grant means.

API Boundaries

The UI prototype maps to these backend contracts:

• GET /api/session-context
• GET/PATCH /api/me/workspace
• GET/POST /api/accounts
• GET/POST /api/accounts/{account_id}/teams
• GET/POST /api/teams
• GET/POST /api/projects
• GET/PUT /api/projects/{project_id}/grants
• PATCH /api/projects/{project_id}/assignment
• POST /api/uploads/presign
• GET/POST /api/artifacts
• GET /api/documents/workspace
• GET /api/documents/links
• GET/POST /api/artifacts/{artifact_id}/metadata-records
• PATCH /api/artifacts/{artifact_id}/metadata
• POST /api/artifacts/{artifact_id}/write-events
• GET/PUT /api/me/notifications

The executable shared model lives in src/lib/workspace-model.js, and the executable tests live in tests/workspace-model.test.mjs.