Prompt.system.deep Dive

# Prompt System Architecture

## Status

- Version: v0 (MVP)
- Stability: stable for single-user local usage
- Concurrency: optimistic (builder_content only)

## Scope

This document explains:
- data model
- FS + DB sync
- prompt lifecycle (create, read, update)

## Gotchas

- FS must NEVER be written before DB conflict check
- Paths are stored, not inferred
- output.json must always be valid JSON
- builder_content is stored as string (JSON.stringify)
- DB is source of truth for structure, not FS


## 1. Core Mental Model

* **Prompt = container**
* **Version = snapshot of data**
* **Filesystem (FS) = actual content**
* **Database (DB) = structure + metadata**

---

## 2. Data Layer Design

### Tables

#### prompts (container)

* id
* name
* template_id
* collection_id
* current_version_id
* created_at
* updated_at

#### prompt_versions (actual data)

* id
* prompt_id
* version_number
* label
* builder_content (JSON string)
* scratchpad_path
* output_path
* output_type (optional)
* created_at
* updated_at

#### collections (folders)

* id
* name
* parent_id (nested folders)

---

## 3. Filesystem Design

### Structure

Initial (no versioning):