# Data Model: Dokploy deployment integration

Entities

- Repository
  - Attributes: `id`, `name`, `full_name`, `clone_url`, `default_branch` (string, e.g., `main`), `compose_path` (string, default `docker-compose.yml`)
  - Validation: `clone_url` must be reachable; `compose_path` must exist in repository at deploy time

- Webhook
  - Attributes: `id`, `target_url` (Dokploy webhook URL), `secret` (reference to secret store), `events` (array, e.g., [`push`])
  - Validation: `target_url` must be an HTTPS URL; `secret` must be present when webhook signs payloads

- Deployment
  - Attributes: `id`, `repository_full_name`, `commit_sha`, `ref` (branch), `status` (`pending`, `running`, `success`, `failed`), `started_at`, `finished_at`, `logs_url`
  - Validation: `commit_sha` required for deterministic deploys; status transitions enforced (pending→running→(success|failed))

- Secret
  - Attributes: `name`, `type` (`ssh_key`|`token`|`registry`), `reference` (Dokploy secret id)
  - Validation: secrets must not be stored in repo; must be referenced by name in Dokploy config

- Operator
  - Attributes: `username`, `role` (`developer`|`operator`|`admin`), `contact` (email)

Relationships

- A `Repository` has one or more configured `Webhook`s.
- A `Webhook` creates zero-or-more `Deployment` runs over time.
- A `Deployment` may reference one or more `Secret` entries (e.g., `REPO_DEPLOY_KEY`, registry creds).

State Transitions (Deployment)

- `pending` -> `running` when Dokploy picks up the job
- `running` -> `success` when all services healthy
- `running` -> `failed` when one or more compose services fail to start or healthchecks fail

Notes

- The data model is intentionally lightweight; Dokploy manages most runtime state. These entities are useful for documenting contracts, runbooks, and acceptance tests.