# Entity Definitions

This document describes the core entities in the Release Orchestrator data model.

## Entity Relationship Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                          ENTITY RELATIONSHIPS                               │
│                                                                             │
│  ┌──────────┐       ┌──────────────┐       ┌────────────┐                  │
│  │ Tenant   │───────│ Environment  │───────│ Target     │                  │
│  └──────────┘       └──────────────┘       └────────────┘                  │
│       │                    │                     │                          │
│       │                    │                     │                          │
│       ▼                    ▼                     ▼                          │
│  ┌──────────┐       ┌──────────────┐       ┌────────────┐                  │
│  │ Component│       │ Approval     │       │ Agent      │                  │
│  └──────────┘       │ Policy       │       └────────────┘                  │
│       │             └──────────────┘             │                          │
│       │                    │                     │                          │
│       ▼                    │                     ▼                          │
│  ┌──────────┐              │              ┌─────────────┐                  │
│  │ Version  │              │              │ Deployment  │                  │
│  │ Map      │              │              │ Task        │                  │
│  └──────────┘              │              └─────────────┘                  │
│       │                    │                     │                          │
│       │                    │                     │                          │
│       ▼                    │                     ▼                          │
│  ┌─────────────────────────┼─────────────────────────────┐                 │
│  │                         │                             │                 │
│  │  ┌──────────┐     ┌─────▼─────┐     ┌─────────────┐  │                 │
│  │  │ Release  │─────│ Promotion │─────│ Deployment  │  │                 │
│  │  └──────────┘     └───────────┘     │ Job         │  │                 │
│  │       │                 │           └─────────────┘  │                 │
│  │       │                 │                 │          │                 │
│  │       │                 ▼                 │          │                 │
│  │       │           ┌───────────┐           │          │                 │
│  │       │           │ Approval  │           │          │                 │
│  │       │           └───────────┘           │          │                 │
│  │       │                 │                 │          │                 │
│  │       │                 ▼                 ▼          │                 │
│  │       │           ┌───────────┐     ┌───────────┐   │                 │
│  │       │           │ Decision  │     │ Generated │   │                 │
│  │       │           │ Record    │     │ Artifacts │   │                 │
│  │       │           └───────────┘     └───────────┘   │                 │
│  │       │                 │                 │          │                 │
│  │       │                 └────────┬────────┘          │                 │
│  │       │                          │                   │                 │
│  │       │                          ▼                   │                 │
│  │       │                    ┌───────────┐             │                 │
│  │       └───────────────────►│ Evidence  │◄────────────┘                 │
│  │                            │ Packet    │                                │
│  │                            └───────────┘                                │
│  │                                  │                                      │
│  │                                  ▼                                      │
│  │                            ┌───────────┐                                │
│  │                            │ Version   │                                │
│  │                            │ Sticker   │                                │
│  │                            └───────────┘                                │
│  │                                                                         │
│  └─────────────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────────────────┘
```

## Core Entities

### Environment

Represents a deployment target environment (dev, staging, production).

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `name` | string | Unique name (e.g., "prod") |
| `display_name` | string | Display name (e.g., "Production") |
| `order_index` | integer | Promotion order |
| `config` | JSONB | Environment configuration |
| `freeze_windows` | JSONB | Active freeze windows |
| `required_approvals` | integer | Approvals needed for promotion |
| `require_sod` | boolean | Require separation of duties |
| `created_at` | timestamp | Creation time |

### Target

Represents a deployment target (host, service).

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `environment_id` | UUID | Environment reference |
| `name` | string | Target name |
| `target_type` | string | Type (docker_host, compose_host, etc.) |
| `connection` | JSONB | Connection configuration |
| `labels` | JSONB | Target labels |
| `health_status` | string | Current health status |
| `current_digest` | string | Currently deployed digest |

### Agent

Represents a deployment agent.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `name` | string | Agent name |
| `version` | string | Agent version |
| `capabilities` | JSONB | Agent capabilities |
| `status` | string | online/offline/degraded |
| `last_heartbeat` | timestamp | Last heartbeat time |

### Component

Represents a deployable component (maps to an image repository).

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `name` | string | Component name |
| `display_name` | string | Display name |
| `image_repository` | string | Image repository URL |
| `versioning_strategy` | JSONB | How versions are determined |
| `default_channel` | string | Default version channel |

### Version Map

Maps image tags to digests and semantic versions.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `component_id` | UUID | Component reference |
| `tag` | string | Image tag |
| `digest` | string | Image digest (sha256:...) |
| `semver` | string | Semantic version |
| `channel` | string | Version channel (stable, beta) |

### Release

A versioned bundle of component digests.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `name` | string | Release name |
| `display_name` | string | Display name |
| `components` | JSONB | Component/digest mappings |
| `source_ref` | JSONB | Source code reference |
| `status` | string | draft/ready/deployed/deprecated |
| `created_by` | UUID | Creator user reference |

### Promotion

A request to promote a release to an environment.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `release_id` | UUID | Release reference |
| `source_environment_id` | UUID | Source environment (nullable) |
| `target_environment_id` | UUID | Target environment |
| `status` | string | Promotion status |
| `decision_record` | JSONB | Gate evaluation results |
| `workflow_run_id` | UUID | Associated workflow run |
| `requested_by` | UUID | Requesting user |
| `requested_at` | timestamp | Request time |

### Approval

An approval or rejection of a promotion.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `promotion_id` | UUID | Promotion reference |
| `approver_id` | UUID | Approving user |
| `action` | string | approved/rejected |
| `comment` | string | Approval comment |
| `approved_at` | timestamp | Approval time |

### Deployment Job

A deployment execution job.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `promotion_id` | UUID | Promotion reference |
| `release_id` | UUID | Release reference |
| `environment_id` | UUID | Environment reference |
| `status` | string | Job status |
| `strategy` | string | Deployment strategy |
| `artifacts` | JSONB | Generated artifacts |
| `rollback_of` | UUID | If rollback, original job |

### Deployment Task

A task to deploy to a single target.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `job_id` | UUID | Job reference |
| `target_id` | UUID | Target reference |
| `digest` | string | Digest to deploy |
| `status` | string | Task status |
| `agent_id` | UUID | Assigned agent |
| `logs` | text | Execution logs |
| `previous_digest` | string | Previous digest (for rollback) |

### Evidence Packet

Immutable audit evidence for a promotion/deployment.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `promotion_id` | UUID | Promotion reference |
| `packet_type` | string | Type of evidence |
| `content` | JSONB | Evidence content |
| `content_hash` | string | SHA-256 of content |
| `signature` | string | Cryptographic signature |
| `signer_key_ref` | string | Signing key reference |
| `created_at` | timestamp | Creation time (no update) |

### Version Sticker

Version marker placed on deployment targets.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `target_id` | UUID | Target reference |
| `release_id` | UUID | Release reference |
| `promotion_id` | UUID | Promotion reference |
| `sticker_content` | JSONB | Sticker JSON content |
| `content_hash` | string | Content hash |
| `written_at` | timestamp | Write time |
| `drift_detected` | boolean | Drift detection flag |

## Workflow Entities

### Workflow Template

A reusable workflow definition.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference (null for builtin) |
| `name` | string | Template name |
| `version` | integer | Template version |
| `nodes` | JSONB | Step nodes |
| `edges` | JSONB | Step edges |
| `inputs` | JSONB | Input definitions |
| `outputs` | JSONB | Output definitions |
| `is_builtin` | boolean | Is built-in template |

### Workflow Run

An execution of a workflow template.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `template_id` | UUID | Template reference |
| `template_version` | integer | Template version at execution |
| `status` | string | Run status |
| `context` | JSONB | Execution context |
| `inputs` | JSONB | Input values |
| `outputs` | JSONB | Output values |
| `started_at` | timestamp | Start time |
| `completed_at` | timestamp | Completion time |

### Step Run

Execution of a single step within a workflow run.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `workflow_run_id` | UUID | Workflow run reference |
| `node_id` | string | Node ID from template |
| `status` | string | Step status |
| `inputs` | JSONB | Resolved inputs |
| `outputs` | JSONB | Produced outputs |
| `logs` | text | Execution logs |
| `attempt_number` | integer | Retry attempt number |

## Plugin Entities

### Plugin

A registered plugin.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `plugin_id` | string | Unique plugin identifier |
| `version` | string | Plugin version |
| `vendor` | string | Plugin vendor |
| `manifest` | JSONB | Plugin manifest |
| `status` | string | Plugin status |
| `entrypoint` | string | Plugin entrypoint path |

### Plugin Instance

A tenant-specific plugin configuration.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `plugin_id` | UUID | Plugin reference |
| `tenant_id` | UUID | Tenant reference |
| `config` | JSONB | Tenant configuration |
| `enabled` | boolean | Is enabled for tenant |

## Integration Entities

### Integration

A configured external integration.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Tenant reference |
| `type_id` | string | Integration type |
| `name` | string | Integration name |
| `config` | JSONB | Integration configuration |
| `credential_ref` | string | Vault credential reference |
| `health_status` | string | Connection health |

## References

- [Database Schema](schema.md)
- [Module Overview](../modules/overview.md)