BRIEFING 02

OrbitPrompt — Technical Specifications

Version: 1.0
Version:Last Updated:Project Type:Target Platform:prompt archive and management system
목차 · 뭘 말하는가
클립 2편 (탭하면 소리)
백서 전문

Version: 1.0 Last Updated: 2025-12-12 Project Type: Static Web Application / PWA Target Platform: GitHub Pages

Table of Contents

  1. System Overview
  2. Architecture
  3. Technology Stack
  4. Repository Structure
  5. Installation & Setup
  6. Development Workflow
  7. Deployment
  8. Component Specifications
  9. PWA Configuration
  10. Maintenance & Troubleshooting
  11. API Reference

System Overview

Purpose

OrbitPrompt is a prompt archive and management system designed for AI interaction templates. It provides a searchable, production-ready interface for organizing and accessing prompt files with a sophisticated tagging system (D1xP5x style).

Key Features

Target Users

Architecture

System Design

┌─────────────────────────────────────────────────┐
│                GitHub Pages                      │
│            (Static File Hosting)                │
└──────────────────┬──────────────────────────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
┌───────▼────────┐   ┌────────▼────────┐
│  index.html    │   │   prompts/      │
│  (UI Layer)    │   │  (Data Layer)   │
└───────┬────────┘   └────────┬────────┘
        │                     │
        │   ┌─────────────────┘
        │   │
        ▼   ▼
┌─────────────────┐
│  index.json     │
│ (Auto-generated)│
└─────────────────┘
        ▲
        │
┌───────┴────────┐
│ GitHub Actions │
│ (CI/CD Layer)  │
└────────────────┘

Data Flow

  1. Developer adds .html prompt files to prompts/ directory
  2. GitHub Actions detects changes and regenerates index.json
  3. index.html fetches index.json on page load
  4. JavaScript parses filenames and renders the UI
  5. User searches and navigates prompts in real-time

Design Principles

Technology Stack

Core Technologies

ComponentTechnologyVersionPurpose
FrontendHTML5, CSS3, JavaScript (ES6+)NativeUI and business logic
HostingGitHub Pages-Static file serving
CI/CDGitHub Actionsv4Automated indexing
PWAService Workers, Web Manifest-Offline support and installability
IndexingNode.jsv20+Build-time file scanning
Data FormatJSON-Prompt file registry

Dependencies

Runtime: None (Vanilla JavaScript)

Build/Dev Tools:

Browser Support

Repository Structure

OrbitPrompt/
├── .github/
│   └── workflows/
│       └── update-index.yml       # CI/CD: Auto-generates index.json
├── prompts/
│   ├── index.json                 # Auto-generated file list
│   ├── Gitgub-publishing.html     # Example prompt file
│   └── D1xP5xL2xC3xE5.html       # D1xP5x format prompt (example)
├── .gitignore                     # Git exclusions
├── README.md                      # User documentation
├── TECHNICAL_SPECIFICATIONS.md    # This document
├── generate-index.js              # Local indexing script
├── index.html                     # Main application UI
├── manifest.webmanifest          # PWA manifest
├── orbitprompt-logo.png          # Application icon (192x192)
└── sw.js                         # Service Worker for PWA

File Descriptions

Core Application Files

index.html (27 KB)

generate-index.js (721 bytes)

sw.js (339 bytes)

manifest.webmanifest (459 bytes)

Configuration Files

.github/workflows/update-index.yml

.gitignore

Content Files

prompts/

Installation & Setup

Prerequisites

Step 1: Fork or Clone Repository

# Clone the repository
git clone https://github.com/dtslib1979/OrbitPrompt.git
cd OrbitPrompt

# Or fork and clone your fork
git clone https://github.com/YOUR_USERNAME/OrbitPrompt.git
cd OrbitPrompt

Step 2: Configure GitHub Pages

  1. Navigate to Settings → Pages in your GitHub repository
  2. Configure:
  3. Source: Deploy from branch
  4. Branch: main (or your default branch)
  5. Folder: / (root)
  6. Click Save
  7. Wait 1-2 minutes for deployment
  8. Visit https://YOUR_USERNAME.github.io/OrbitPrompt/

Step 3: Verify Installation

Check that the following URLs are accessible:

https://YOUR_USERNAME.github.io/OrbitPrompt/
https://YOUR_USERNAME.github.io/OrbitPrompt/prompts/index.json
https://YOUR_USERNAME.github.io/OrbitPrompt/manifest.webmanifest

Step 4: (Optional) Local Development Setup

# No npm install needed - vanilla JavaScript!

# To regenerate index.json locally:
node generate-index.js

# To test locally, use any HTTP server:
# Python 3:
python3 -m http.server 8000

# Node.js (npx):
npx serve .

# Then visit: http://localhost:8000

Development Workflow

Adding a New Prompt

Method 1: Direct File Creation

  1. Create a new .html file in the prompts/ directory
cd prompts/
touch MyNewPrompt.html
# or
touch D2xP3xL2xC1xE4.html
  1. Add your prompt content (see Prompt File Format)
  1. Run the indexing script
node generate-index.js
  1. Commit and push
git add prompts/
git commit -m "Add new prompt: MyNewPrompt"
git push origin main

Method 2: Automatic Indexing (Recommended)

  1. Create and push the prompt file directly
cd prompts/
# Create your file
echo "<!DOCTYPE html>..." > NewPrompt.html

git add prompts/NewPrompt.html
git commit -m "Add NewPrompt"
git push origin main
  1. GitHub Actions will automatically:
  2. Detect the new file
  3. Update index.json
  4. Commit the changes
  5. Deploy to GitHub Pages

Prompt File Format

Minimal Structure

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Prompt Title</title>
</head>
<body>
    <h1>Your Prompt Title</h1>
    <p>Your prompt content here...</p>
</body>
</html>

Advanced Structure (Parksy Style)

See prompts/Gitgub-publishing.html for a full-featured example with:

Naming Conventions

D1xP5x Format (Recommended for Structured Prompts)

Format: D{depth}xP{phase}xL{level}xC{category}xE{evidence}.html

Parameters:

Examples:

Free-Form Naming

Any descriptive name works:

Parsing Behavior:

Testing Changes Locally

# Start local server
python3 -m http.server 8000

# Open browser
open http://localhost:8000

# Test search functionality
# Verify prompt links work
# Check responsive design

Deployment

Automatic Deployment (GitHub Pages)

Every push to the main branch triggers:

  1. GitHub Actions Workflow (update-index.yml)
  2. Runs when prompts/*.html files change
  3. Updates prompts/index.json
  4. Commits changes back to the repository
  1. GitHub Pages
  2. Detects changes to main branch
  3. Rebuilds and deploys the site
  4. Usually completes in 30-60 seconds

Deployment URL Pattern

https://{username}.github.io/{repository-name}/

Example:

https://dtslib1979.github.io/OrbitPrompt/

Custom Domain Setup

To use a custom domain:

  1. Add a CNAME file to the repository root:
echo "prompts.yourdomain.com" > CNAME
git add CNAME
git commit -m "Add custom domain"
git push
  1. Configure DNS records at your domain provider:
Type: CNAME
Name: prompts (or @)
Value: your-username.github.io
  1. Wait for DNS propagation (5-60 minutes)

Monitoring Deployment

Check deployment status:

Component Specifications

1. Search Interface (index.html)

Search Algorithm

filteredPrompts = allPrompts.filter(prompt => 
    prompt.title.toLowerCase().includes(query) ||
    prompt.description.toLowerCase().includes(query) ||
    prompt.mode.toLowerCase().includes(query) ||
    prompt.complexity.toLowerCase().includes(query)
);

Features:

Parsing Logic

function parsePromptFile(filename) {
    const base = filename.replace('.html', '');
    
    // D1xP5x pattern matching
    const pattern = /D(\d+)xP(\d+)xL(\d+)xC(\d+)xE(\d+)/i;
    const match = base.match(pattern);
    
    if (match) {
        const [, d, p, l, c, e] = match;
        return {
            title: `D${d}P${p}L${l}C${c}E${e}`,
            complexity: `L${l}`,
            mode: getModeFromCode(c),
            description: `Depth ${d} · Phase ${p} · Evidence ${e}`,
            date: '2025-12-02'
        };
    }
    
    // Fallback for non-standard names
    return {
        title: base,
        complexity: 'L1',
        mode: 'GENERAL',
        description: 'Custom prompt template',
        date: '2025-12-02'
    };
}

Sorting Strategy

allPrompts.sort((a, b) => {
    // Primary: Sort by complexity (descending)
    const complexA = parseInt(a.complexity.replace('L', ''));
    const complexB = parseInt(b.complexity.replace('L', ''));
    if (complexA !== complexB) return complexB - complexA;
    
    // Secondary: Alphabetical by title
    return a.title.localeCompare(b.title);
});

2. Index Generator (generate-index.js)

Functionality

Usage

# Run manually
node generate-index.js

# Output example:
# Generated index.json with 2 files:
#   - D1xP5xL2xC3xE5.html
#   - Gitgub-publishing.html

Generated JSON Format

[
  "D1xP5xL2xC3xE5.html",
  "Gitgub-publishing.html"
]

3. Service Worker (sw.js)

Caching Strategy

Strategy: Network-first with cache fallback

self.addEventListener('fetch', (event) => {
  event.respondWith(
    fetch(event.request).catch(() => caches.match(event.request))
  );
});

Behavior:

  1. Try to fetch from network
  2. If offline, serve from cache
  3. No explicit caching in this implementation (browser manages cache)

Lifecycle

PWA Configuration

Manifest File (manifest.webmanifest)

{
  "name": "OrbitPrompt",
  "short_name": "OrbitPrompt",
  "start_url": "/OrbitPrompt/",
  "display": "standalone",
  "background_color": "#000000",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/OrbitPrompt/orbitprompt-logo.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/OrbitPrompt/orbitprompt-logo.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

Installation Requirements

For PWA installability, ensure:

  1. HTTPS: GitHub Pages provides this automatically
  2. Manifest: Present and linked in index.html
  3. Service Worker: Registered and active
  4. Icons: At least one icon (192x192 or larger)
  5. Start URL: Responds with 200 when offline

Testing PWA Features

Chrome DevTools:

  1. Open DevTools → Application tab
  2. Check "Manifest" section for errors
  3. Verify "Service Workers" are registered
  4. Test "Offline" mode in Network tab

Lighthouse:

# Run Lighthouse audit
npx lighthouse https://dtslib1979.github.io/OrbitPrompt/ --view

Maintenance & Troubleshooting

Common Issues

Issue: Prompts not appearing after adding new files

Symptoms:

Solutions:

  1. Check if index.json was updated
   cat prompts/index.json
  1. Manually regenerate index
   node generate-index.js
   git add prompts/index.json
   git commit -m "Update index"
   git push
  1. Verify GitHub Actions workflow ran successfully
  2. Visit Actions tab
  3. Check "Update Prompt Index" workflow
  1. Clear browser cache and hard reload (Ctrl+Shift+R)

Issue: GitHub Pages not updating

Solutions:

  1. Check deployment status in Actions tab
  2. Verify Pages settings point to correct branch/folder
  3. Wait 2-3 minutes for propagation
  4. Check if there are any build errors

Issue: PWA not installing on mobile

Solutions:

  1. Verify HTTPS (GitHub Pages auto-provides)
  2. Check manifest.webmanifest is accessible
  3. Ensure icon file exists and is correct size
  4. Test with Chrome's "Add to Home Screen" prompt

Updating Dependencies

None required - This is a zero-dependency project!

To update Node.js for development:

# Check current version
node --version

# Update via your package manager
# macOS (Homebrew):
brew upgrade node

# Ubuntu/Debian:
sudo apt update && sudo apt upgrade nodejs

Backup and Recovery

# Create backup of prompts directory
tar -czf prompts-backup-$(date +%Y%m%d).tar.gz prompts/

# Restore from backup
tar -xzf prompts-backup-YYYYMMDD.tar.gz

# Git-based recovery
git checkout main -- prompts/

API Reference

JavaScript API (for extending index.html)

Core Functions

##### parsePromptFile(filename)

Parses a filename into structured metadata.

Parameters:

Returns:

{
  title: string,        // Display name
  complexity: string,   // "L1" to "L9"
  mode: string,         // "ENGINEERING", "ARCHITECTURE", etc.
  description: string,  // Formatted description
  date: string         // ISO date string
}

##### getModeFromCode(code)

Maps category codes to mode names.

Parameters:

Returns:

##### createBar(prompt)

Generates HTML for a prompt list item.

Parameters:

prompt = {
  filename: string,
  title: string,
  complexity: string,
  mode: string,
  description: string,
  date: string
}

Returns: HTML string

##### loadPrompts()

Main initialization function. Fetches and renders prompts.

Async: Yes

Side Effects:

##### renderPrompts(prompts)

Renders prompt list or empty state.

Parameters:

Data Formats

index.json Schema

[
  "string",  // filename with .html extension
  "string",
  ...
]

Example:

[
  "D1xP1xL1xC1xE1.html",
  "D2xP3xL4xC5xE2.html",
  "CustomPrompt.html"
]

Prompt Metadata Object

{
  filename: "D1xP5xL2xC3xE5.html",
  title: "D1P5L2C3E5",
  complexity: "L2",
  mode: "CRITICAL",
  description: "Depth 1 · Phase 5 · Evidence 5",
  date: "2025-12-02"
}

Performance Optimization

Current Performance

Optimization Tips

  1. Image Optimization: Compress orbitprompt-logo.png if needed
   # Using ImageOptim or similar
   optipng -o7 orbitprompt-logo.png
  1. Lazy Loading Prompts: For 1000+ prompts, implement pagination
   // Add to index.html
   const PAGE_SIZE = 50;
   function renderPage(page) {
       const start = page * PAGE_SIZE;
       const end = start + PAGE_SIZE;
       renderPrompts(filteredPrompts.slice(start, end));
   }
  1. Service Worker Caching: Enhance sw.js with explicit caching
   const CACHE_NAME = 'orbitprompt-v2';
   const urlsToCache = ['/', '/index.html', '/prompts/index.json'];
   
   self.addEventListener('install', (event) => {
       event.waitUntil(
           caches.open(CACHE_NAME)
               .then(cache => cache.addAll(urlsToCache))
       );
   });

Security Considerations

Current Security Posture

Best Practices

  1. Content Sanitization: When adding prompts, avoid inline scripts
   <!-- ❌ Avoid -->
   <script>alert('xss')</script>
   
   <!-- ✅ Use -->
   <pre>&lt;script&gt;alert('xss')&lt;/script&gt;</pre>
  1. Repository Permissions: Limit write access to trusted contributors
  1. Secrets Management: Never commit API keys or secrets
   # Already configured in .gitignore
   *.env
   .env.local

Extension Points

Adding New Features

1. Category Filtering

Add dropdown filter in index.html:

<select id="categoryFilter">
    <option value="">All Categories</option>
    <option value="ENGINEERING">Engineering</option>
    <option value="ARCHITECTURE">Architecture</option>
    <!-- ... -->
</select>
document.getElementById('categoryFilter').addEventListener('change', (e) => {
    const category = e.target.value;
    filteredPrompts = category 
        ? allPrompts.filter(p => p.mode === category)
        : allPrompts;
    renderPrompts(filteredPrompts);
});

2. Export Functionality

Add export to CSV:

function exportToCSV() {
    const csv = [
        ['Title', 'Complexity', 'Mode', 'Description'],
        ...allPrompts.map(p => [p.title, p.complexity, p.mode, p.description])
    ].map(row => row.join(',')).join('\n');
    
    const blob = new Blob([csv], { type: 'text/csv' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'prompts.csv';
    a.click();
}

3. Dark Mode Toggle

Add manual dark mode toggle (currently auto-detected):

const darkModeToggle = document.createElement('button');
darkModeToggle.textContent = '🌙';
darkModeToggle.onclick = () => {
    document.body.classList.toggle('dark-mode');
    localStorage.setItem('darkMode', document.body.classList.contains('dark-mode'));
};

Conclusion

This technical specification provides a complete blueprint for understanding, replicating, and extending the OrbitPrompt system. The architecture prioritizes simplicity, performance, and maintainability through:

For questions or contributions, refer to the repository's issue tracker or submit pull requests following the development workflow outlined above.

Document Maintainers:

Related Resources: