From 6be946325b4b2703877ebda6a4c6d333e04b31f5 Mon Sep 17 00:00:00 2001
From: Jerry Tian <jerryrt@gmail.com>
Date: Mon, 7 Apr 2025 21:41:16 -0400
Subject: [PATCH] doc: document for prompt and template

---
 .../api_scripts/prompt_and_template.md        | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 apps/demo-nextjs-app-router/api_scripts/prompt_and_template.md

diff --git a/apps/demo-nextjs-app-router/api_scripts/prompt_and_template.md b/apps/demo-nextjs-app-router/api_scripts/prompt_and_template.md
new file mode 100644
index 0000000..a90624c
--- /dev/null
+++ b/apps/demo-nextjs-app-router/api_scripts/prompt_and_template.md
@@ -0,0 +1,116 @@
+# Template Database Schema Documentation
+
+## Overview
+
+This document outlines the JSON schema for a template database system. The database manages templates for digital content generation, including both image and video capabilities, with references to external media files.
+
+## Schema Structure
+
+### Top-Level Structure
+
+```json
+{
+  "timestamp": 1712331158783,
+  "templates": [
+    // Array of template items
+  ]
+}
+```
+
+### Template Item Structure
+
+Each template in the database has the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Date-time based unique identifier |
+| name | string | Internal reference name (used for folder organization) |
+| title | string | User-facing display title |
+| description | string | Detailed description of the template |
+| coverImage | string | Filename of template's cover image (jpg/png) |
+| sampleVideo | string | Filename of sample video (mp4) |
+| imagePrompt | string | Text prompt for image generation |
+| imageEngine | string | API engine for image generation (currently "openai-o4") |
+| videoPrompt | string | Text prompt for video generation |
+| videoEngine | string | Engine for video generation (currently "luma" or "wan2") |
+
+## File Structure
+
+Files referenced in the schema are organized in the following folder structure:
+
+```
+/templates/
+  /{name}/
+    /{coverImage}
+    /{sampleVideo}
+```
+
+## Example JSON Database
+
+```json
+{
+  "timestamp": 1712331158783,
+  "templates": [
+    {
+      "id": "2025-04-07T12-30-45-123Z",
+      "name": "sunset-beach",
+      "title": "Tropical Beach Sunset",
+      "description": "A beautiful tropical beach scene with palm trees silhouetted against a vibrant sunset over the ocean.",
+      "coverImage": "cover.jpg",
+      "sampleVideo": "sample.mp4",
+      "imagePrompt": "A stunning tropical beach at sunset, with silhouettes of palm trees, golden-orange sky reflecting on calm ocean waters, no people, photorealistic style.",
+      "imageEngine": "openai-o4",
+      "videoPrompt": "Camera slowly panning across a tropical beach at sunset, palm trees swaying gently in the breeze, golden light reflecting on gentle waves, cinematic lighting.",
+      "videoEngine": "luma"
+    },
+    {
+      "id": "2025-04-07T13-15-22-456Z",
+      "name": "space-nebula",
+      "title": "Cosmic Nebula Explorer",
+      "description": "A spectacular journey through colorful space nebulae and distant galaxies.",
+      "coverImage": "nebula-cover.png",
+      "sampleVideo": "space-journey.mp4",
+      "imagePrompt": "A breathtaking view of a colorful space nebula with stars, cosmic dust, and swirling gases in purple, blue and pink hues, ultra high definition, space photography style.",
+      "imageEngine": "openai-o4",
+      "videoPrompt": "Slow journey through a colorful cosmic nebula, moving past stars and swirling gases, gradual color shifts from purple to blue to pink, distant galaxies visible, ultra HD quality.",
+      "videoEngine": "wan2"
+    },
+    {
+      "id": "2025-04-07T14-22-18-789Z",
+      "name": "urban-future",
+      "title": "Futuristic Cityscape",
+      "description": "A hyper-modern cityscape with advanced architecture, flying vehicles, and holographic displays.",
+      "coverImage": "future-city.jpg",
+      "sampleVideo": "city-flythrough.mp4",
+      "imagePrompt": "Hyper-futuristic cityscape at dusk with neon lights, holographic billboards, flying vehicles, sleek skyscrapers, advanced technology, cyberpunk aesthetic but clean and utopian.",
+      "imageEngine": "openai-o4",
+      "videoPrompt": "Flying through a futuristic city at dusk, weaving between tall skyscrapers with holographic displays, flying vehicles passing by, neon lights reflecting off glass buildings, advanced technology visible everywhere.",
+      "videoEngine": "luma"
+    }
+  ]
+}
+```
+
+## Usage Guidelines
+
+1. **Updating the Database**:
+   - When updating the database, increment the top-level `timestamp` field.
+   - Use a consistent date-time format for new template IDs.
+
+2. **File References**:
+   - Cover images should be placed in `/{name}/` folder with the filename specified in `coverImage`.
+   - Sample videos should be placed in `/{name}/` folder with the filename specified in `sampleVideo`.
+
+3. **Engine Values**:
+   - `imageEngine` is currently limited to "openai-o4".
+   - `videoEngine` is currently limited to either "luma" or "wan2".
+
+## Validation
+
+When implementing this schema, consider adding validation to ensure:
+- All required fields are present
+- Engine values are from the allowed set
+- Referenced files exist in the expected locations
+- IDs follow the expected date-time format pattern
+
+This documentation provides the structural foundation for managing your template system's metadata and file references.
\ No newline at end of file