DevRunbook-Public/docs/05-domain-model.md

05 — Domain and data model

Domain boundaries

Identity and workspace

Owns users, workspaces, memberships and authorization. The MVP may expose one personal workspace per user while retaining workspace IDs in the model for future team support.

Playbook registry

Owns playbook identity, immutable versions, lifecycle, source, compatibility, content digest and publication state.

Repository intelligence

Owns repository identities, manual profiles, source observations, profile snapshots, commands, protected paths and health findings.

Composition

Owns drafts, normalized inputs, resolved policies, prompt blocks, lint findings, rendered output and generated runs.

Artifacts

Owns exported Markdown, Run Packs, manifests, digests, retention and download authorization.

Integrations

Owns forge connections, encrypted credentials, capability snapshots, synchronization jobs and health.

Quality

Owns lint rules, evaluation cases, fixture references, evaluation results and quality status.

Audit and operations

Owns audit events, job state, operational metrics and retention.

Conceptual relationships

erDiagram
    USER ||--o{ WORKSPACE_MEMBERSHIP : has
    WORKSPACE ||--o{ WORKSPACE_MEMBERSHIP : contains
    WORKSPACE ||--o{ REPOSITORY : owns
    WORKSPACE ||--o{ COMPOSITION_DRAFT : owns
    WORKSPACE ||--o{ GENERATED_RUN : owns
    WORKSPACE ||--o{ INTEGRATION : owns

    PLAYBOOK ||--o{ PLAYBOOK_VERSION : versions
    PLAYBOOK_VERSION ||--o{ PLAYBOOK_EVALUATION : evaluated_by
    PLAYBOOK_VERSION ||--o{ COMPOSITION_DRAFT : selected_by
    PLAYBOOK_VERSION ||--o{ GENERATED_RUN : frozen_in

    REPOSITORY ||--o{ REPOSITORY_PROFILE_REVISION : profile_versions
    REPOSITORY ||--o{ REPOSITORY_SNAPSHOT : observed_as
    REPOSITORY_SNAPSHOT ||--o{ REPOSITORY_FINDING : produces
    REPOSITORY_PROFILE_REVISION ||--o{ COMPOSITION_DRAFT : used_by
    REPOSITORY_PROFILE_REVISION ||--o{ GENERATED_RUN : frozen_in

    COMPOSITION_DRAFT ||--o{ DRAFT_INPUT : contains
    COMPOSITION_DRAFT ||--o{ PROMPT_LINT_FINDING : reports
    GENERATED_RUN ||--o{ GENERATED_ARTIFACT : exports
    GENERATED_RUN ||--o{ RUN_FEEDBACK : receives

    INTEGRATION ||--o{ INTEGRATION_SECRET : references
    INTEGRATION ||--o{ SYNC_JOB : runs

Core records

The complete relational contract and deletion behavior are defined in docs/27-database-reference.md and database/reference-schema.sql. The records below summarize the domain-facing fields.

user

• id
• normalized unique email
• display name
• password hash managed by the authentication implementation
• instance role and account status
• password/session timestamps

workspace and workspace_membership

• workspace identity, type and lifecycle timestamps
• membership user, role and creation timestamp
• every private resource is authorized through workspace membership

auth_session, invitation and password_reset_token

Revocable session and single-use token records store hashes, never bearer values. Expiry, use and revocation are explicit.

playbook

Mutable identity record.

• id UUID
• slug globally unique stable slug
• namespace such as builtin, private.<workspace> or future registry namespace
• source_type built_in, private, imported, remote_registry
• created_at, updated_at

playbook_version

Immutable published content or mutable draft revision.

• id UUID
• playbook_id
• semantic_version
• status draft, reviewed, validated, battle_tested, deprecated
• package_api_version
• title, summary, category
• risk_tier
• package_json normalized canonical document
• template_text
• content_digest
• published_at
• supersedes_version_id
• created_by

Unique: (playbook_id, semantic_version) and content_digest within source namespace as appropriate.

Published rows are immutable at the application layer and protected by tests. A correction creates a new version.

repository

• id
• workspace_id
• display_name
• source_type manual, gitea
• external_owner, external_name, external_id
• integration_id nullable
• default_branch
• archived
• timestamps

repository_profile_revision

An immutable normalized profile used for composition.

• id
• repository_id
• revision_number
• profile_json
• source_snapshot_id nullable
• content_digest
• created_by
• created_at

repository_snapshot

Evidence captured from an integration.

• id
• repository_id
• integration_id
• captured_at
• capability_snapshot_json
• evidence_json
• evidence_digest
• sync_job_id

repository_finding

• id
• snapshot_id
• rule_id
• severity info, low, medium, high
• title
• rationale
• evidence_pointer
• recommended_playbook_slug
• status open, dismissed, resolved

composition_draft

Mutable user workspace.

• id
• workspace_id
• playbook_version_id
• repository_profile_revision_id nullable
• input_json
• autonomy_level
• work_mode
• last_render_digest
• updated_at
• created_by

generated_run

Immutable generation record. “Run” does not imply that Codex executed it.

• id
• workspace_id
• source_draft_id nullable
• playbook_version_id
• playbook_snapshot_json
• repository_profile_snapshot_json nullable
• normalized_input_json
• policy_snapshot_json
• rendered_prompt
• render_digest
• lint_result_json
• generated_at
• generated_by

generated_artifact

• id
• run_id
• artifact_type prompt_text, markdown, run_pack_zip, agents_suggestion
• storage_key
• filename
• size_bytes
• sha256
• expires_at nullable
• created_at

integration

• id
• workspace_id
• type gitea
• display_name
• base_url
• status configured, healthy, degraded, disabled
• capabilities_json
• last_checked_at
• timestamps

integration_secret

The database stores encrypted material and metadata, never a retrievable plaintext response.

• id
• integration_id
• secret_kind
• encrypted_value
• key_version
• last_four optional safe identifier
• created_at, rotated_at

playbook_evaluation

• id
• playbook_version_id
• case_id
• fixture_version
• environment_json
• result_status
• dimension_scores_json
• evidence_artifact_key
• executed_at
• executed_by

Additional operational records

The reference schema also defines:

• favorites, collections and collection items;
• invitations, password resets and sessions;
• run feedback;
• evaluation cases and immutable results;
• PostgreSQL-backed jobs with leases and retries;
• append-only audit events;
• singleton instance setup/configuration state.

The application may store draft lint findings inside draft JSON, but final lint results and provenance are frozen in generated_run. Do not create a second contradictory source of truth.

Indexing strategy

• GIN full-text index over playbook title, summary, category, tags and intent fields;
• B-tree indexes on workspace ownership, lifecycle, category, risk and update timestamps;
• unique digest indexes for immutable package and run content;
• trigram index for tolerant title/tag matching if extension support is available;
• partial indexes for active playbook versions and pending jobs.

Retention

• playbook versions: retained indefinitely unless legally required otherwise;
• generated runs: operator-configurable, default indefinite for personal self-hosting;
• generated binary artifacts: default 90 days while immutable run text remains;
• integration snapshots: default latest 20 per repository plus referenced snapshots;
• audit events: default 180 days;
• operational logs: default 14–30 days.

Deleting a repository may anonymize or detach historical runs rather than destroying their frozen profile snapshot, depending on user selection and legal requirements.