Skip to content

Prompt Lifecycle

Jump to bottom
Valerio edited this page Aug 12, 2026 · 2 revisions

Prompt Lifecycle

Prompts are the central authored resource in UncannyPrompt. A prompt belongs to a project, can optionally live in a folder, can be tagged, shared, versioned, resolved with variables, favorited, pinned, and copied.

A prompt carries two bodies of text: Content, the positive prompt, and the optional NegativePrompt, describing what the model should avoid. Both are versioned, both take part in variable resolution, and both are exposed through the API and public links.

Core entities

Entity Role
Prompt Current editable prompt state and metadata
PromptVersion Immutable historical content snapshot
PromptTag Many-to-many link between prompts and tags
Favorite User-specific favorite/pin state
PromptNote User-authored notes attached to a prompt
VersionLabel Label metadata attached to a prompt version

Creation

PromptService.CreateAsync creates the prompt and the first PromptVersion in the same unit-of-work boundary. Tags are synchronized through the prompt service, not directly by controllers.

The initial version is the baseline for later diff/history UI and restore flows.

Updates

PromptService.UpdateAsync updates the current prompt metadata and content.

Versioning behavior is intentional:

  • A new PromptVersion is created when the prompt content changes.
  • A new PromptVersion is created when the negative prompt changes.
  • A new PromptVersion is also created when explicit version metadata such as a label or changelog is provided.
  • Metadata-only saves without content changes do not create unnecessary versions.

Blank or whitespace-only negative prompts are normalized to null before comparison, so re-saving an empty field does not create a version.

This keeps version history focused on meaningful content history, not every UI save event.

Version history and restore

PromptVersionService exposes version history and restore behavior. Restoring a version does not mutate an old row. Instead, the selected historical content becomes the current prompt content and is recorded through the normal versioning path.

Restore moves the positive and negative prompt together, so the two never drift apart. DiffAsync compares the content of the two versions and appends a [negative prompt] section only when their negative prompts differ.

Razor Pages expose version history through src/UncannyPrompt.WebApp/Pages/Versions.cshtml.

Favorites and pins

Favorites and pins are user-specific. They are represented through Favorite rows and surfaced in prompt DTOs.

Prompt listing uses batch mapping so that favorites and tags are fetched in bulk rather than through one query per prompt.

Copy logging

Copying or using a prompt can be logged through PromptService.LogCopyAsync. This supports auditability and future usage analytics.

Search

SearchService is the application-facing search abstraction. The current implementation delegates to SQL-backed prompt listing, but the contract keeps search separate from prompt CRUD so that a later OpenSearch implementation can replace the storage-specific details.

API and UI entry points

Entry point Purpose
PromptsController prompt CRUD, resolve/copy, favorites, pins, versions
ProjectsController project creation/listing
FoldersController folder tree/listing
TagsController tag CRUD
Index.cshtml primary prompt workspace
Projects.cshtml project explorer
Versions.cshtml version history

Source pointers

Clone this wiki locally