---
status: draft
last_updated: 2026-04-19
---

# Table Schemas: Projects & Workspaces

Project and workspace tables. For cross-cutting reference (cascade behavior, index reference, status enums, relations), see [table-reference.md](./table-reference.md). For design decisions, see [../../../decisions/](../../../decisions/).

### `projects`

Git repositories / work contexts. A project may have multiple workspaces (branches). Projects belong to organizations.

| Column | Type | Notes |
|--------|------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| orgId | text | FK → organizations.id (nullable — personal projects have no org) |
| name | text NOT NULL | Project name |
| directory | text | Local filesystem path (primary workspace) |
| repoUrl | text | Git remote URL |
| vcs | text | Version control system (default: `git`) |
| iconUrl | text | Project icon URL |
| iconColor | text | Project icon color (opencode compat) |

**Indexes**: `idx_projects_org_id` on `(orgId)` — find projects for an org.

### `workspaces`

Project workspaces — branches, directories, and execution contexts. A project can have multiple workspaces (e.g., main branch workspace, feature branch workspace). This maps to opencode's `workspace` concept and our coordination `mappings`.

| Column | Type | Notes |
|--------|------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| projectId | text NOT NULL | FK → projects.id (cascade) |
| type | text NOT NULL | Workspace type: `local`, `remote`, `container` |
| branch | text | Git branch name |
| name | text | Human-readable workspace name |
| directory | text | Local filesystem path |
| extra | jsonb | Workspace-specific configuration |

**Indexes**: `idx_workspaces_project_id` on `(projectId)` — find workspaces for a project.