Data Persistence & Schemas
Relevant source files
The following files were used as context for generating this wiki page:
Data persistence in OpenWork is split between local workspace configurations and a centralized cloud/enterprise identity and organization management system (Den). Local persistence focuses on file-based state within .opencode directories, while the Den system manages multi-tenant structures including organizations, teams, marketplaces, and cross-platform identity mapping.
The architecture emphasizes a "local-first, cloud-ready" approach where personal work resides on the user's machine, and collaborative features like shared marketplaces and SCIM identity management are persisted in a centralized MySQL-compatible database using Drizzle ORM.
Multi-Tenant Organization Schema (Den)
The enterprise layer (Den) utilizes a relational schema to manage high-level entities. This includes organizations, memberships, and the distribution of agentic tools via plugins and marketplaces.
Core Entity Relationships
The schema defines a hierarchy where users belong to organizations via a membership table, and organizations contain teams and marketplaces.
The diagram shows the relationship between core organization entities, memberships, and the plugin marketplace system. Sources: ee/apps/den-api/scripts/seed-demo-org.ts:15-30, prds/scim/scim-compatibility-layer-plan.md:110-120
Identity and SCIM Mapping
To support enterprise Single Sign-On (SSO) and System for Cross-domain Identity Management (SCIM), the project maintains a dedicated mapping layer. This ensures that a local user can be associated with different remote identities across multiple identity providers (IdPs).
| Table | Key Fields | Description |
|---|---|---|
scim_identity | remoteId, externalId, userId, organizationId | Maps local Better Auth users to external SCIM identities. |
scim_group | id, teamId, displayName | Maps SCIM groups to internal organization teams. |
member | userId, organizationId, role | Tracks user permissions (owner, admin, member) within an org. |
Sources: prds/scim/scim-compatibility-layer-plan.md:27-46, ee/apps/den-api/scripts/seed-demo-org.ts:333-345
Local Workspace Persistence
Local data is persisted primarily through structured files within a workspace's root and the .opencode subdirectory. This allows for portability and version control of agent behaviors and workspace settings.
File-Based Configuration
OpenWork initializes workspaces with standard configuration files that define the environment, default agents, and active plugins.
opencode.jsonc: The primary configuration file using JSON with comments. It defines the$schema,default_agent, and activepluginlist (e.g.,opencode-chrome-devtools)..opencode/openwork.json: Stores metadata specific to the OpenWork desktop app, including the workspace name, creation date, andauthorizedRoots..opencode/agents/openwork.md: Persists the instructions, behavior memory, and working style for the primary agent.
Sources: apps/server/src/workspace-init.ts:133-176, apps/server/src/workspace-init.ts:186-218
Artifact Guidance and State
The system persists "Artifact Guidance" within the agent's markdown instructions. This state defines how the agent should handle deliverable files like .md, .csv, and .xlsx in the workspace.
The local directory structure utilized for persisting workspace-level configurations and agent logic. Sources: apps/server/src/workspace-init.ts:121-131, apps/app/src/app/data/skill-creator.md:12-25
Plugin and Skill Data Structures
Skills and plugins are the primary units of extensibility. Their persistence format is designed to be human-readable and portable.
Skill Persistence Format
Skills are persisted as folders containing a SKILL.md file. This file uses YAML frontmatter to store metadata like name and description, while the body contains instructions.
---
name: my-skill
description: Triggers when user mentions specific phrases.
---
# Instructions
The body of the skill goes here.
Sources: apps/app/src/app/data/skill-creator.md:52-64, ee/packages/utils/src/skill-markdown.ts:133-150
Config Object Management
In the Den ecosystem, these local files are represented as ConfigObjects for synchronization and marketplace distribution.
| Component | Persistence Method | Role |
|---|---|---|
ConfigObject | MySQL Table | Tracks metadata, versioning, and access grants for a tool. |
ConfigObjectVersion | MySQL Table | Stores the rawSourceText and normalizedPayloadJson of a specific version. |
PluginConfigObject | Junction Table | Associates specific skills or commands with a marketplace plugin. |
Sources: ee/apps/den-api/scripts/seed-demo-org.ts:468-525, evals/cloud-marketplace-sync-flows.md:11-19
Data Flow: Workspace Import & Sync
OpenWork implements a preview-based persistence flow for importing data into a workspace. This ensures that changes to the local filesystem are audited and approved before being committed.
The sequence of events for persisting imported configurations into a local workspace. Sources: apps/server/src/workspace-import-preview.test.ts:103-149, apps/server/src/workspace-import-preview.test.ts:413-448
Summary
OpenWork's data persistence architecture is a hybrid model. It leverages local file systems for immediate agent execution and portability, while using a sophisticated relational schema (Den) to manage enterprise-grade requirements like SCIM identity mapping, multi-tenant organization structures, and marketplace synchronization. This ensures that while individual work is "ejectable" and local, team-wide collaboration is backed by a robust and auditable central database.