Leon4gr45/builder

1# Multitenancy2 3OSW Studio server mode supports workspaces and multiple users on a single instance. Workspaces are the primary unit of organization and isolation. Users are granted access to workspaces with roles.4 5## Concepts6 7### Workspaces8 9A workspace is a self-contained environment with its own projects, deployments, templates, skills, and quotas. Each workspace maps to its own SQLite database at `data/workspaces/{id}/osws.sqlite`. Data in one workspace is completely isolated from other workspaces.10 11Workspaces are what you manage. Users are just accounts that get access to workspaces.12 13### Access Model14 15There are two levels of access:16 17- **Instance admin** -- can create and manage workspaces, users, and instance settings via `/admin/users` and `/admin/workspaces`18- **Workspace member** -- can use the AI, edit projects, publish sites, and manage deployments within workspaces they have access to19 20All workspace members have the same capabilities within a workspace.21 22### How it fits together23 24An agency running OSWS might set up:25- A workspace per client (e.g., "Sweet Candies", "Nordic Bikes")26- Agency devs as members of each workspace they manage27- The client invited to their workspace, so they can use the AI for daily updates (adding articles, changing hours)28- Quota limits per workspace (1 project, 1 deployment for basic clients; more for premium)29 30A team might set up:31- One shared workspace for the team, everyone as members32- The team lead as instance admin33 34## Architecture35 36```37data/38  system.sqlite                    # Users, workspaces, access grants39  workspaces/40    {workspaceId}/41      osws.sqlite                  # Projects, files, templates, skills42      projects/43        {projectId}/44          database.sqlite          # User-defined project databases45  deployments/46    {deploymentId}/47      runtime.sqlite               # Published deployment runtime48      analytics.sqlite             # Published deployment analytics49 50public/51  deployments/52    {deploymentId}/                # Published static files53```54 55**system.sqlite** is the only shared database. It stores user accounts, workspace definitions, access grants (who can access which workspace), and deployment routing.56 57**Per-workspace osws.sqlite** contains everything within a workspace. The schema is identical to single-user mode. Isolation is physical (separate files), not logical.58 59## URL Structure60 61All workspace pages use the `/w/{workspaceId}/` prefix:62```63/w/{workspaceId}/projects64/w/{workspaceId}/deployments65/w/{workspaceId}/dashboard66/w/{workspaceId}/settings67```68 69API routes follow the same pattern:70```71/api/w/{workspaceId}/sync/projects72/api/w/{workspaceId}/deployments73/api/w/{workspaceId}/shell/execute74```75 76System-wide admin pages (no workspace context):77```78/admin/users79/admin/workspaces80/admin/login81```82 83## Setup84 85### 1. Initial Setup86 87On a fresh install with `NEXT_PUBLIC_SERVER_MODE=true`:88 891. Visit `/admin` -- you'll be redirected to a registration page902. Create the admin account (email + password)913. You're in. The first user automatically becomes admin with an unlimited workspace.92 93No `ADMIN_PASSWORD` env var is needed for new installs. The legacy admin password only works as a bootstrap mechanism when no user accounts exist.94 95### 2. Configure Environment96 97Add to your `.env` alongside standard server mode variables:98 99| Variable | Default | Description |100|----------|---------|-------------|101| `REGISTRATION_MODE` | `closed` | `open` = users can self-register. `closed` = admin creates accounts |102| `NEXT_PUBLIC_REGISTRATION_MODE` | `closed` | Client-side mirror (controls register link visibility) |103| `INSTANCE_API_KEY` | *(none)* | Admin API accepts `x-instance-api-key` header for programmatic access |104 105See **[Server Mode](?doc=server-mode)** for the full variable list.106 107### 3. Choose How Users Join108 109**Open registration** (`REGISTRATION_MODE=open`): Users visit `/admin/register`, create an account, and get a default workspace automatically.110 111**Admin-managed** (default): Admin creates users and workspaces via `/admin/users` and `/admin/workspaces`, then grants access.112 113### 4. Create Workspaces114 115**Via admin UI** at `/admin/workspaces`:116- Click "New Workspace", set a name and assign an owner117- Expand a workspace row to see members, add or remove access118- Edit quotas (max projects, deployments, storage) per workspace119 120**Via admin API**:121```122POST /api/admin/workspaces123{ "name": "Sweet Candies", "ownerEmail": "dev@agency.com" }124```125 126### 5. Grant Access127 128**Via admin UI**: Expand a workspace, click "Add Member", enter email and role.129 130**Via admin API**:131```132POST /api/admin/workspaces/{id}/access133{ "email": "client@sweetcandies.com", "role": "editor" }134```135 136## Admin API Reference137 138All admin routes require an admin session or the `x-instance-api-key` header.139 140### Workspace Management141 142```143GET    /api/admin/workspaces              -- list all workspaces with stats144POST   /api/admin/workspaces              -- create workspace145GET    /api/admin/workspaces/{id}         -- workspace detail + members146PUT    /api/admin/workspaces/{id}         -- update (name, quotas)147DELETE /api/admin/workspaces/{id}         -- delete workspace148POST   /api/admin/workspaces/{id}/access  -- grant user access149DELETE /api/admin/workspaces/{id}/access  -- revoke user access150POST   /api/admin/workspaces/{id}/repair  -- detect and fix data issues151```152 153### User Management154 155```156GET    /api/admin/users              -- list all users with their workspaces157POST   /api/admin/users              -- create user account158GET    /api/admin/users/{id}         -- user detail + workspaces159PUT    /api/admin/users/{id}         -- update (display name, active)160DELETE /api/admin/users/{id}         -- deactivate user161```162 163### User's Own Workspaces164 165```166GET /api/workspaces -- list workspaces the current user has access to167```168 169## Quotas170 171Each workspace has configurable limits. Defaults:172- 3 projects173- 1 published deployment174- 100 MB storage175 176Enforced at:177- **Project creation** — rejects sync push when at project limit178- **Deployment publishing** — rejects publish when at deployment limit179- **File sync** — rejects file push when storage limit reached180 181A warning banner appears in the workspace UI when storage usage exceeds 80%.182 183Configurable per-workspace via the admin UI or API. An agency might give basic clients 1 project / 1 deployment and premium clients 10 / 5.184 185## Upgrading from Single-User Mode186 187Existing single-user instances automatically migrate when multitenancy is enabled:188 1891. On first login, a default workspace is created with unlimited quotas1902. Existing projects, deployments, templates, and skills are copied from `data/osws.sqlite` to the workspace1913. Project databases from `data/projects/` are copied to the workspace192 193If migration doesn't complete (e.g., already logged in when workspace was created), a "Workspace Setup Required" dialog offers to re-login and retry. Manual repair is available via:194 195```196POST /api/admin/workspaces/{id}/repair197```198 199## Security200 201- **Physical isolation**: Each workspace has its own SQLite file. No cross-workspace data leakage possible from missing query filters.202- **Role-based access**: Every workspace API request verifies the user has sufficient access via `verifyWorkspaceAccess()`.203- **Path validation**: Workspace IDs validated as UUIDs before file path construction.204- **Timing-safe auth**: API key and password comparisons use constant-time operations.205- **Statement blocking**: ATTACH, DETACH, PRAGMA, VACUUM blocked in user-facing SQL execution.206- **Session validation**: Deactivated users' sessions invalidated on next request.207 208## Browser Mode Compatibility209 210All multitenancy code is in server mode code paths, gated by `NEXT_PUBLIC_SERVER_MODE`. Browser mode (IndexedDB, client-side only) is completely unaffected.211