# Domain model

## Installation and workspace

### Installation

Represents system-wide configuration and bootstrap state.

Invariants:

- exactly one installation record;
- owner bootstrap can complete only once;
- configured schema/product version is traceable;
- primary locale and timezone are validated.

### Workspace

The first release exposes one active workspace, but content rows carry `WorkspaceId` to
make authorization boundaries explicit.

Fields:

- ID
- Name
- Slug
- CreatedAt
- Settings version
- ArchivedAt (future-safe)

### Membership

Connects an interactive user to a workspace role:

- Reader
- Editor
- Administrator

Invariants:

- at least one enabled administrator exists;
- disabled users cannot act through existing sessions;
- service accounts are not memberships and receive no implicit role.

## Knowledge

### Page

The current published state and tree location.

Core fields:

- ID / WorkspaceId
- ParentPageId
- SortKey
- Title
- Slug
- Markdown
- DocumentType
- DocumentStatus
- CurrentRevisionNumber
- ConcurrencyVersion
- CreatedBy / UpdatedBy
- CreatedAt / UpdatedAt / PublishedAt
- TrashedAt / PurgeAfter

Invariants:

- title is non-empty and bounded;
- parent is in the same workspace;
- a page cannot parent itself or create a cycle;
- current revision number increases monotonically;
- ordinary changes cannot mutate immutable revisions;
- trashed pages are excluded from normal navigation/search.

### PageRevision

Immutable snapshot of semantically relevant page state:

- Page identity and revision number
- Title, slug and Markdown
- Parent/order snapshot
- Document type/status
- typed metadata snapshot
- author/source/change summary
- created timestamp
- content hash

Restoring creates a new revision.

### Draft

User-private mutable work based on a specific page revision:

- User / Page or draft key
- Base revision/concurrency version
- Markdown and metadata
- UpdatedAt / ExpiresAt

A draft never silently publishes.

### PageLink

Derived relation from an authored internal link:

- SourcePageId
- target stable PageId when resolved
- original target text
- display label
- occurrence/anchor information
- resolution state

Derived records can be rebuilt from revisions.

### PageRelation

Explicit semantic relationship:

- Source / Target
- relation type
- label
- creator/time

### Tag and PageTag

Tags are case-insensitively unique per workspace. Display casing is preserved.

### Favorite and RecentVisit

User-specific convenience records. They never grant content access.

## Attachments

### AttachmentBlob

Physical deduplicated content:

- SHA-256 key
- byte length
- detected media type
- storage state
- created timestamp
- integrity status
- preview state

Blob paths are derived only from the hash.

### AttachmentReference

Logical attachment:

- ID / WorkspaceId
- Blob hash
- Original filename
- Description / alt text / caption
- Uploader
- created/trashed timestamps

### AttachmentUsage

Connects a reference to a page, project update or other supported owner.

Deleting a usage does not remove shared content. Orphan cleanup follows retention.

## Projects

### Project

- ID / WorkspaceId
- Name / Slug
- Summary
- Lifecycle status
- Priority
- Start/target/completion dates
- Repository/live/documentation links
- Current-state Markdown
- Owner
- Created/updated metadata
- concurrency version

### ProjectDocument

Connects a project to a page with a role:

- Overview
- Architecture
- Deployment
- Testing
- Troubleshooting
- Security
- Release
- Other

### ProjectUpdate

Immutable chronological update:

- project
- timestamp and author/source
- category
- title
- summary Markdown
- verification status
- optional commit/release/issue/URL
- linked pages/decisions/milestones
- correction/supersession link

Corrections append; they do not rewrite historical audit.

### ProjectMilestone

Named project milestone, distinct from repository build milestones:

- state
- target/completion date
- summary
- order
- linked updates/pages

### TechnologyTag

Normalized project technology classification.

## Decisions

### DecisionRecord

Typed profile linked to one canonical page:

- ID / ProjectId / PageId
- Decision number
- Status
- DecisionDate
- SupersedesDecisionId
- SupersededByDecisionId
- Summary

The page holds durable Markdown sections. The profile holds queryable lifecycle metadata.

Invariants:

- accepted numbering is unique per project;
- supersession cannot cycle;
- a superseded record identifies its replacement;
- decision history is not deleted during ordinary project deletion.

## Runbooks

### RunbookProfile

Typed profile linked to a canonical page:

- ID / PageId
- Owner
- Risk level
- LastValidatedAt / ValidatedBy
- validation status
- expected section anchors

The page's Markdown must contain or explicitly mark:

- Purpose
- Scope
- Prerequisites
- Steps
- Validation
- Rollback
- Risks

The platform displays and validates structure; it never executes steps.

## Imports

### ImportJob

- ID / adapter/version
- source fingerprint and safe descriptor
- status
- preflight plan version
- started/completed timestamps
- actor
- counts and validation outcome
- rollback status

### ImportItem

One discovered source item and its target mapping:

- stable source identity/hash
- source kind/path descriptor
- target entity ID
- planned action
- status
- conflict/diagnostic data

All imported entities carry import provenance sufficient for scoped rollback.

## Audit and integration

### AuditEvent

Append-only security and content action record:

- actor kind and ID
- source (web, API, import, system)
- action
- target type/ID
- safe summary
- correlation ID
- timestamp
- network/user-agent metadata under retention policy

Page bodies, passwords and token secrets are excluded.

### OutboxMessage

Transactional integration event:

- ID
- event type/version
- aggregate identity
- safe payload
- occurred/available time
- processing attempts/status

The initial product may use it for cache/index repair and future integrations.