Data Model

Tenancy Hierarchy

Organization
├── OrganizationMember (-> User, role)
├── Team
│   ├── TeamMembership (-> User, role)
│   └── Workspace
│       └── Project
│           ├── Task
│           └── WorkflowInstance
├── Skill (org-scoped)
├── Config (org-scoped)
└── Secret (org/team/workspace-scoped)

Base Model

All business models inherit from BaseCoreModel:

Field	Type	Notes
guid	UUID	Unique, external identifier (used in APIs)
slug	string	Auto-generated, unique within scope
name	string	Display name
description	text	Optional description
version	integer	Optimistic locking
created_at	datetime	Auto-set
updated_at	datetime	Auto-updated
deleted_at	datetime	Soft deletes -- never hard delete business objects
created_by	FK(User)	Audit trail
updated_by	FK(User)	Audit trail
deleted_by	FK(User)	Audit trail

Core Models

Tenancy

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Organization   │     │      Team        │     │    Workspace     │
│──────────────────│     │──────────────────│     │──────────────────│
│ name             │<----│ organization_id  │<----│ team_id          │
│ website          │     │ name, slug       │     │ name, slug       │
│ groups M2M       │     │                  │     │ is_active        │
└──────────────────┘     └──────────────────┘     └────────┬─────────┘
                                                           │
                                                  ┌────────v─────────┐
                                                  │     Project      │
                                                  │──────────────────│
                                                  │ workspace_id     │
                                                  │ name, slug       │
                                                  │ settings JSON    │
                                                  └──────────────────┘

Tasks and Workflows

Project
  │
  ├── Task
  │   ├── project_id
  │   ├── agent_image
  │   ├── status
  │   ├── brief_key
  │   ├── dispatcher_id
  │   ├── callback_url
  │   ├── skills M2M
  │   ├── configs M2M
  │   └── tools M2M
  │
  └── WorkflowInstance
      ├── project_id
      ├── template_id
      ├── status
      ├── temporal_wf_id
      ├── input_context
      └── stage_results

Skills and Configs

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│      Skill       │     │   SkillVersion   │     │     ToolDef      │
│──────────────────│     │──────────────────│     │──────────────────│
│ organization_id  │<----│ skill_id         │     │ name, slug       │
│ category         │     │ version_number   │     │ input_schema     │
│ content_hash     │     │ content_hash     │     │ handler_ref      │
│ storage_ref      │     │ storage_ref      │     │ adapter_ref      │
│ instructions     │     │ created_by       │     └──────────────────┘
│ current_version  │     └──────────────────┘
└──────────────────┘

┌──────────────────┐     ┌──────────────────┐
│     Config       │     │  ConfigVersion   │
│──────────────────│     │──────────────────│
│ organization_id  │<----│ config_id        │
│ category         │     │ version_number   │
│ content          │     │ content          │
│ content_hash     │     │ content_hash     │
└──────────────────┘     └──────────────────┘

Workflow Engine

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│WorkflowTemplate  │     │  WorkflowStage   │     │WorkflowStageExecution│
│──────────────────│     │──────────────────│     │──────────────────────│
│ category         │<----│ template_id      │<----│ workflow_instance_id │
│ is_published     │     │ order            │     │ stage_id             │
│ default_config   │     │ stage_type       │     │ task_id (nullable)   │
└──────────────────┘     │ agent_definition │     │ status               │
                         │ skills M2M       │     │ attempt_number       │
                         │ configs M2M      │     └──────────────────────┘
                         │ on_failure       │
                         └──────────────────┘

Infrastructure

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│AgentDefinition   │     │  RuntimeTarget   │     │  InfraService    │
│──────────────────│     │──────────────────│     │──────────────────│
│ tier             │     │ backend_type     │     │ service_type     │
│ runtime          │     │ endpoint         │     │ connection_url   │
│ image            │     │ namespace        │     │ is_healthy       │
│ default_cpu      │     │ is_default       │     │ consecutive_fails│
│ default_memory   │     └──────────────────┘     └──────────────────┘
│ cmd_override     │
└──────────────────┘

┌──────────────────┐     ┌──────────────────┐
│DispatcherInstance│     │    EventRoute    │
│──────────────────│     │──────────────────│
│ endpoint_url     │     │ event_type       │
│ dispatch_mode    │     │ source           │
│ bus_config       │     │ target_wf_id     │
│ status           │     │ signal_name      │
│ last_heartbeat   │     │ transform        │
└──────────────────┘     └──────────────────┘

Secrets

┌──────────────────┐
│     Secret       │
│──────────────────│
│ organization_id  │
│ team_id (null)   │
│ workspace_id(null)│
│ category         │
│ backend          │
│ path_or_arn      │
│ encrypted_value  │
└──────────────────┘

Secrets scope hierarchically: organization-wide, team-scoped, or workspace-scoped. team_id and workspace_id are nullable -- a null scope means the secret is available at the broader level.

Scoping Rules

Model	Scoped to	Notes
Task	Project	Via project_id FK
WorkflowInstance	Project	Via project_id FK
Skill	Organization	Shared across all teams/workspaces in the org
Config	Organization	Same as skills
Secret	Org / Team / Workspace	Narrowest scope wins
DispatcherInstance	Global	Not tenant-scoped -- dispatchers serve any org
InfraService	Global	Registered once, referenced by dependency resolution
AgentDefinition	Global	Shared image catalogue
RuntimeTarget	Global	Cluster endpoints