287 lines
7.7 KiB
Markdown
287 lines
7.7 KiB
Markdown
# 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
|
||
|
||
```mermaid
|
||
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.
|