From c92c91ac20ce316362b4babb5868d2862e4d7b5e Mon Sep 17 00:00:00 2001
From: johndoe6345789 <john.doe6345789@gmail.com>
Date: Wed, 21 Jan 2026 01:49:51 +0000
Subject: [PATCH] Create comprehensive project documentation in PROMPT.md

Added detailed project documentation for a hybrid TypeScript/C++ package system, including architecture, design philosophy, and guidelines for contributors.
---
 PROMPT.md | 710 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 710 insertions(+)
 create mode 100644 PROMPT.md

diff --git a/PROMPT.md b/PROMPT.md
new file mode 100644
index 000000000..6c2c5b194
--- /dev/null
+++ b/PROMPT.md
@@ -0,0 +1,710 @@
+# 🚀 MEGA PROMPT: Hybrid TypeScript/C++ Package System
+
+**Version**: 1.0  
+**Last Updated**: January 2026  
+**For**: AI Assistants working on 3-frontend package bootstrap system
+
+---
+
+## 🎯 PROJECT ESSENCE
+
+This is a **hybrid TypeScript/C++ bootloader system** that powers a modular package architecture. Three frontends (CLI, Qt6, Next.js) act as **entry points** that bootstrap a NestJS-based package system. The system is pragmatic: schemas are improvable, not sacred; patterns come from functional programming; and delightfulness matters.
+
+### The Mental Model
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User Input                               │
+│              (CLI / Qt6 GUI / Next.js Web)                  │
+└──────────────┬──────────────────────────────────────────────┘
+               │
+               ▼
+        ┌──────────────┐
+        │  Bootloader  │  ← Frontend-specific logic
+        │   (3x)       │    - Routes/state management
+        └──────────────┘
+               │
+               ▼
+        ┌──────────────┐
+        │  Package     │  ← Central coordinator
+        │  System      │    - Loads packages from /packages/
+        │ (NestJS)     │    - Manages seed data & schemas
+        └──────────────┘
+               │
+        ┌──────┴──────┐
+        ▼             ▼
+    ┌────────┐   ┌────────┐
+    │ DBAL   │   │ C++    │
+    │ Layer  │   │ Daemons│
+    │        │   │(Media) │
+    └────────┘   └────────┘
+        │             │
+        └──────┬──────┘
+               ▼
+        ┌──────────────┐
+        │  Database    │
+        │(PostgreSQL)  │
+        └──────────────┘
+```
+
+**Key Principle**: Seed data lives in `/packages/*/seed/`, not scattered elsewhere. Schemas are single source of truth but improvable.
+
+---
+
+## 📋 PRIORITY READING (In Order)
+
+1. **IMMEDIATE_FIXES.md** ⭐ - What's actually broken right now
+2. **claude.md** - System overview and patterns
+3. **agents.md** - Agent guidelines for this codebase
+4. **README.md** - Project structure and setup
+5. **ROADMAP.md** (if exists) - Vision and evolution
+6. **docs/** - Architecture, testing, deployment guides
+7. **schemas/** - Data models (understand but improve if needed)
+
+---
+
+## 🏗️ ARCHITECTURE AT A GLANCE
+
+### Three Frontends (Each a Bootloader)
+
+| Frontend | Purpose | Tech Stack | Startup Flow |
+|----------|---------|-----------|--------------|
+| **CLI** | Command-line interface | TypeScript/Node | Read config → Load packages → Execute |
+| **Qt6** | Desktop GUI application | C++/Qt6 | Parse Qt resources → Load packages → Render |
+| **Next.js** | Web application | TypeScript/React | HTTP request → Load packages → Render page |
+
+**Critical**: Each frontend is a **bootloader**. It doesn't contain business logic—it loads and orchestrates packages.
+
+### Package System (The Heart)
+
+```
+/packages/
+├── [package-name]/
+│   ├── seed/                 ← REAL seed data (not /dbal/shared/seeds/)
+│   │   ├── metadata.json     ← Package manifest
+│   │   ├── page-config/      ← Routes/pages
+│   │   ├── workflow/         ← Automation workflows
+│   │   ├── credential/       ← API credentials
+│   │   ├── component/        ← UI components
+│   │   └── [entity-type]/    ← Other entity types
+│   ├── src/                  ← Business logic (if TypeScript package)
+│   ├── package.json
+│   └── README.md
+```
+
+**Pattern**: Each package is self-contained. Seed data describes what the package does. Business logic implements it.
+
+### DBAL Layer (Database Access)
+
+- **Phase 2** (Current): TypeScript DBAL in `/dbal/development/`
+- **Phase 3** (Future): C++ daemon in `/dbal/production/`
+- **Shared**: YAML schemas at `/dbal/shared/api/schema/entities/` (source of truth)
+
+**Rule**: Always use `getDBALClient()` from `@/dbal`, never raw Prisma.
+
+### Schemas: Two Layers
+
+| Layer | Location | Purpose | Editable? |
+|-------|----------|---------|-----------|
+| **Entity Schemas** | `/dbal/shared/api/schema/entities/*.yaml` | Database structure (source of truth) | Yes, improve as needed |
+| **Validation Schemas** | `/schemas/seed-data/*.schema.json` | Seed data validation | Yes, extend for new features |
+| **Package Schemas** | `/schemas/package-schemas/*.schema.json` | Package system architecture | Yes, treat as blueprint |
+
+**Philosophy**: Schemas are **improvable**. If they lack features, extend them. They're not dogma.
+
+---
+
+## 🎨 DESIGN PHILOSOPHY (How to Think)
+
+### 1. Functional Programming First
+
+```typescript
+// ✅ GOOD: Functional, pure, composable
+const loadPackage = (path: string) => readJSON(path);
+const filterActive = (packages: Package[]) => packages.filter(p => p.active);
+const orchestrate = pipe(loadPackages, filterActive, initializeAll);
+
+// ❌ BAD: Imperative, class-heavy, side effects
+class PackageManager {
+  private packages: Package[] = [];
+  async load(path) { this.packages = await readJSON(path); }
+  async filter() { this.packages = this.packages.filter(p => p.active); }
+}
+```
+
+### 2. Make It Delightful
+
+- Code should be obvious. If it requires 20 comments, refactor it.
+- Styling matters. Use Tailwind (web), Qt stylesheets (desktop), ANSI colors (CLI).
+- Error messages should hint at solutions, not just fail.
+- Performance should feel snappy.
+
+### 3. Schemas Are Improvable
+
+```json
+// If schema lacks what you need:
+// 1. Document the gap
+// 2. Extend the schema
+// 3. Update examples
+// 4. Move on
+
+// Example: Script schema is JSON AST, but n8n-style is simpler for visual GUIs
+{
+  "trigger": "http.post",
+  "input": { "body": "{ name, email }" },
+  "steps": [
+    { "action": "validate.email", "target": "$input.email" },
+    { "action": "db.create", "table": "users", "data": "$input" }
+  ],
+  "output": { "userId": "$steps[1].id" }
+}
+// This coexists with JSON AST for complex logic. Both are valid.
+```
+
+### 4. No Magic, No Lua
+
+- **No Lua**: JSON is sufficient for visual scripting (n8n, Scratch patterns).
+- **No magic imports**: Be explicit. Use dependency injection.
+- **No hidden state**: Logs should explain what's happening.
+
+### 5. GUIs Over Raw Input
+
+```typescript
+// ❌ RAW: User types CSS directly
+<TextArea label="CSS" value={rawCSS} onChange={setCss} />
+
+// ✅ GUI: Dropdowns + composition
+<StyleBuilder
+  properties={{
+    color: <ColorPicker />,
+    fontSize: <FontSizeSelect options={[12, 14, 16, 18, ...]} />,
+    layout: <LayoutSelect options={['flex', 'grid', 'block']} />,
+  }}
+/>
+```
+
+---
+
+## 📁 PROJECT STRUCTURE
+
+```
+.
+├── IMMEDIATE_FIXES.md              ⭐ Current priorities
+├── claude.md                        System overview
+├── agents.md                        Agent guidelines
+├── README.md                        Project intro
+├── ROADMAP.md                       Vision & evolution
+│
+├── docs/                            Architecture & guides
+│   ├── TESTING_GUIDE.md
+│   ├── DEPLOYMENT.md
+│   ├── COMPONENTS.md
+│   └── ...
+│
+├── schemas/                         Data model definitions
+│   ├── seed-data/                  Validation schemas for seed files
+│   │   ├── page-config.schema.json
+│   │   ├── workflow.schema.json
+│   │   ├── component.schema.json
+│   │   └── ...
+│   └── package-schemas/            Package system definitions
+│       ├── metadata_schema.json
+│       ├── entities_schema.json
+│       └── ...
+│
+├── packages/                        Modular packages (REAL seed data here)
+│   ├── package-name/
+│   │   ├── seed/
+│   │   │   ├── metadata.json
+│   │   │   ├── page-config/
+│   │   │   ├── workflow/
+│   │   │   └── ...
+│   │   ├── src/                    (if TypeScript package)
+│   │   └── package.json
+│   └── ...
+│
+├── dbal/                            Database abstraction layer
+│   ├── development/                 TypeScript DBAL (Phase 2, current)
+│   │   ├── src/
+│   │   ├── prisma/
+│   │   └── package.json
+│   ├── production/                  C++ DBAL (Phase 3, future)
+│   │   ├── include/
+│   │   ├── src/
+│   │   └── CMakeLists.txt
+│   └── shared/
+│       ├── api/schema/entities/    YAML entity schemas (source of truth)
+│       ├── seeds/                  Bootstrap seeds (minimal)
+│       └── docs/
+│
+├── frontends/                       Entry points (bootloaders)
+│   ├── cli/                         TypeScript CLI
+│   │   ├── src/commands/
+│   │   └── package.json
+│   ├── qt6/                         C++ Qt6 desktop GUI
+│   │   ├── src/
+│   │   └── CMakeLists.txt
+│   └── nextjs/                      TypeScript/React web
+│       ├── src/app/
+│       ├── src/components/
+│       └── package.json
+│
+├── old/                             Pre-refactor reference code
+│   └── [legacy patterns for understanding changes]
+│
+└── [support files]
+    ├── package.json
+    ├── tsconfig.json
+    ├── CMakeLists.txt
+    └── ...
+```
+
+---
+
+## 🔧 CORE PATTERNS
+
+### Pattern 1: Functional Package Loading
+
+```typescript
+// ✅ GOOD: Pure, composable, testable
+const loadPackageMetadata = (path: string): Promise<PackageMetadata> =>
+  readJSON(`${path}/seed/metadata.json`);
+
+const loadPackageSeed = (path: string, entityType: string): Promise<any[]> =>
+  readJSON(`${path}/seed/${entityType}/data.json`).catch(() => []);
+
+const initializePackages = async (packagePaths: string[]) =>
+  Promise.all(packagePaths.map(async (path) => ({
+    metadata: await loadPackageMetadata(path),
+    pages: await loadPackageSeed(path, 'page-config'),
+    workflows: await loadPackageSeed(path, 'workflow'),
+  })));
+```
+
+### Pattern 2: Schema-Driven Validation
+
+```typescript
+// Validate seed data against schema
+const validateSeedData = (data: unknown, schemaPath: string): ValidationResult => {
+  const schema = loadSchema(schemaPath);
+  const validator = ajv.compile(schema);
+  const valid = validator(data);
+  
+  return {
+    valid,
+    errors: validator.errors || [],
+  };
+};
+
+// Usage
+const result = validateSeedData(seedData, '/schemas/seed-data/workflow.schema.json');
+if (!result.valid) {
+  console.error('Seed validation failed:', result.errors);
+}
+```
+
+### Pattern 3: Bootloader Flow (Frontend-Agnostic)
+
+```typescript
+// Each frontend implements this flow differently, but structure is same
+interface BootloaderFlow {
+  1_readConfig: () => Promise<Config>;
+  2_loadPackages: (config: Config) => Promise<Package[]>;
+  3_validatePackages: (packages: Package[]) => Promise<ValidationResult>;
+  4_initializeDatabase: (packages: Package[]) => Promise<void>;
+  5_renderUI: (packages: Package[]) => Promise<void>;
+}
+
+// CLI Implementation
+async function cliBootloader() {
+  const config = readConfigFile('./metabuilder.config.json');
+  const packages = await loadPackagesFromDisk(config.packagesDir);
+  const validation = await validatePackages(packages);
+  
+  if (!validation.valid) {
+    console.error('Validation failed:', validation.errors);
+    process.exit(1);
+  }
+  
+  await initializeDatabase(packages);
+  await cliRender(packages);
+}
+
+// Qt6 Implementation
+async function qt6Bootloader() {
+  const config = readConfigFromResources();
+  const packages = await loadPackagesFromDisk(config.packagesDir);
+  const validation = await validatePackages(packages);
+  
+  if (!validation.valid) {
+    showErrorDialog(validation.errors);
+    return;
+  }
+  
+  await initializeDatabase(packages);
+  qt6Render(packages);
+}
+
+// Next.js Implementation
+export async function pageBootloader() {
+  const config = loadConfigFromEnv();
+  const packages = await loadPackagesFromDisk(config.packagesDir);
+  const validation = await validatePackages(packages);
+  
+  if (!validation.valid) {
+    return NextResponse.json({ error: validation.errors }, { status: 400 });
+  }
+  
+  await initializeDatabase(packages);
+  return renderNextPage(packages);
+}
+```
+
+### Pattern 4: N8N-Style Workflows (Over JSON AST)
+
+```json
+// Simple, visual, drop-and-drop friendly
+{
+  "id": "workflow_user_signup",
+  "name": "User Signup Flow",
+  "trigger": {
+    "type": "form.submit",
+    "formId": "form_signup"
+  },
+  "steps": [
+    {
+      "id": "validate_email",
+      "action": "validate.email",
+      "input": { "email": "$trigger.email" },
+      "onError": "step_show_error"
+    },
+    {
+      "id": "check_exists",
+      "action": "db.query",
+      "query": "SELECT id FROM users WHERE email = $1",
+      "params": ["$validate_email.input.email"],
+      "onSuccess": "step_check_result"
+    },
+    {
+      "id": "check_result",
+      "action": "condition",
+      "if": "$check_exists.rows.length > 0",
+      "then": "step_error_exists",
+      "else": "step_create_user"
+    },
+    {
+      "id": "create_user",
+      "action": "db.insert",
+      "table": "users",
+      "data": {
+        "email": "$trigger.email",
+        "name": "$trigger.name",
+        "createdAt": "now()"
+      }
+    },
+    {
+      "id": "send_email",
+      "action": "email.send",
+      "to": "$trigger.email",
+      "template": "welcome",
+      "vars": { "name": "$trigger.name" }
+    },
+    {
+      "id": "redirect_success",
+      "action": "response.redirect",
+      "url": "/welcome"
+    },
+    {
+      "id": "error_exists",
+      "action": "response.error",
+      "status": 409,
+      "message": "Email already registered"
+    },
+    {
+      "id": "show_error",
+      "action": "response.error",
+      "status": 400,
+      "message": "$validate_email.error"
+    }
+  ],
+  "output": {
+    "success": "$create_user.id",
+    "message": "User created successfully"
+  }
+}
+```
+
+This is **simpler than JSON AST**, **visual-friendly**, and **platform-agnostic**.
+
+### Pattern 5: GUI Designer, Not Raw Input
+
+```typescript
+// Component: StyleBuilder (instead of <TextArea>)
+<StyleBuilder
+  value={componentStyle}
+  onChange={setComponentStyle}
+  sections={[
+    {
+      title: "Layout",
+      fields: [
+        { name: "display", label: "Display", type: "select", options: ["flex", "grid", "block"] },
+        { name: "justifyContent", label: "Justify Content", type: "select", options: ["center", "start", "end", "space-between"] },
+      ]
+    },
+    {
+      title: "Colors",
+      fields: [
+        { name: "backgroundColor", label: "Background", type: "color" },
+        { name: "color", label: "Text Color", type: "color" },
+      ]
+    },
+    {
+      title: "Spacing",
+      fields: [
+        { name: "padding", label: "Padding", type: "spacing-picker" },
+        { name: "margin", label: "Margin", type: "spacing-picker" },
+      ]
+    },
+  ]}
+/>
+
+// Dropdown values can come from a dedicated designer panel:
+// "Create a dropdown designer that lets admins define custom options"
+// This is better than raw CSS input.
+```
+
+---
+
+## 🛠️ C++ TOOLING NOTES
+
+### CMake + Conan + Ninja
+
+```bash
+# Setup (one time)
+conan install . --build=missing -of build
+
+# Build
+cd build
+cmake ..
+ninja
+
+# Run
+./metabuilder-cli
+./metabuilder-qt6
+./metabuilder-daemon
+```
+
+### Structure for C++ Code
+
+```cpp
+// ✅ GOOD: Functional, clear ownership
+#include <vector>
+#include <string>
+
+namespace metabuilder {
+  // Pure function: load package metadata
+  PackageMetadata loadPackageMetadata(const std::string& path);
+  
+  // Pure function: validate seed data
+  ValidationResult validateSeedData(const json& data, const std::string& schemaPath);
+  
+  // Composition: orchestrate loading + validation
+  std::vector<Package> loadAndValidatePackages(const std::vector<std::string>& paths);
+}
+
+// Usage
+auto packages = metabuilder::loadAndValidatePackages({
+  "/packages/auth",
+  "/packages/dashboard",
+});
+```
+
+---
+
+## ⚠️ CRITICAL RULES
+
+### Do ✅
+
+- **Read IMMEDIATE_FIXES.md first** - It's your actual priority list
+- **Use functional patterns** - Avoid heavy OOP classes
+- **Keep packages self-contained** - Seed data + business logic live together
+- **Validate against schemas** - But improve schemas as you go
+- **Make error messages helpful** - "Port 3000 in use: try `lsof -i :3000`"
+- **Test the bootloaders** - Each frontend should load packages the same way
+- **Use N8N-style workflows** - Visual, composable, no JSON AST complexity
+- **Build GUIs, not raw inputs** - Dropdowns over textareas
+- **Document decisions** - Leave breadcrumbs for future contributors
+
+### Don't ❌
+
+- **Don't treat schemas as immutable** - Improve them
+- **Don't use Lua** - JSON is sufficient
+- **Don't hardcode values** - Use seed data
+- **Don't ignore old/** - It shows what changed and why
+- **Don't skip validation** - Catch errors early
+- **Don't over-engineer** - Simple and obvious beats clever
+- **Don't mix bootloader logic with business logic** - Keep separation clear
+
+---
+
+## 🚀 QUICK START FOR YOUR BOT
+
+### When Starting Work
+
+1. **Read IMMEDIATE_FIXES.md** - See what's actually broken
+2. **Identify the subsystem** - Which frontend? Which package? DBAL?
+3. **Find the schema** - Understand the data model
+4. **Check old/** - See how it used to work
+5. **Follow functional patterns** - Pure functions, composition
+6. **Make it delightful** - Good errors, good styling
+
+### When Fixing Bugs
+
+```
+1. Reproduce the bug (with logs)
+2. Trace through bootloader flow
+3. Check schema validation
+4. Fix in lowest layer (DBAL > Package Logic > Frontend)
+5. Add test case
+6. Validate schema if needed
+7. Update docs if pattern changes
+```
+
+### When Adding Features
+
+```
+1. Update schema first (if new entity type)
+2. Add seed example to a test package
+3. Implement in DBAL/package logic
+4. Add frontend UI (using GUI builders, not raw input)
+5. Test all 3 bootloaders
+6. Document in README
+```
+
+---
+
+## 📊 SUBAGENT COORDINATION
+
+If using multiple agents, divide work like this:
+
+| Subagent | Focus |
+|----------|-------|
+| **Schema Agent** | Improve `/schemas/`, add validation, extend as needed |
+| **C++ Agent** | Build/fix `/dbal/production/`, `/frontends/qt6/`, C++ CLI |
+| **TypeScript Agent** | Maintain `/dbal/development/`, `/frontends/nextjs/`, `/frontends/cli/` |
+| **Package Agent** | Create/fix packages in `/packages/`, write seed data |
+| **Testing Agent** | Build test suites, ensure all 3 bootloaders work |
+
+Each agent should understand the full architecture but own their subsystem.
+
+---
+
+## 🎯 SUCCESS CRITERIA
+
+Your work is done when:
+
+- [ ] IMMEDIATE_FIXES.md is fully addressed
+- [ ] C++ CLI builds and runs without errors
+- [ ] All 3 bootloaders load packages the same way
+- [ ] Schemas are extended for new features (if needed)
+- [ ] Error messages are helpful and actionable
+- [ ] Code follows functional programming style
+- [ ] UI uses GUI builders, not raw input
+- [ ] Tests pass across all platforms
+- [ ] Documentation is updated
+
+---
+
+## 📞 GETTING HELP
+
+**If stuck:**
+
+1. Check IMMEDIATE_FIXES.md for context
+2. Look at old/ to see how it used to work
+3. Search schemas/ for the data model
+4. Check docs/ for architecture guides
+5. Trace through one bootloader (CLI is usually simplest)
+6. Ask: "What would be delightful here?"
+
+**If schema lacks features:**
+
+1. Document the gap
+2. Extend the schema
+3. Add example
+4. Move on
+
+**If code feels complex:**
+
+1. Break into pure functions
+2. Add logging
+3. Simplify the data flow
+4. Make error messages helpful
+
+---
+
+## 🎨 STYLE GUIDE
+
+### Code
+
+```typescript
+// ✅ GOOD
+const loadPackage = async (path: string) => {
+  const data = await readJSON(`${path}/seed/metadata.json`);
+  return validatePackageMetadata(data);
+};
+
+// Compose
+const packages = await Promise.all(paths.map(loadPackage));
+```
+
+### Errors
+
+```typescript
+// ✅ GOOD
+throw new Error(`Failed to load package from ${path}: ${originalError.message}. Try checking the file exists with: ls -la ${path}`);
+
+// ❌ BAD
+throw new Error('Load failed');
+```
+
+### Styling (Web)
+
+```tsx
+// ✅ Use Tailwind
+<button className="bg-blue-500 hover:bg-blue-600 px-4 py-2 rounded text-white font-semibold">
+  Create Package
+</button>
+
+// CSS (Qt6)
+button {
+  background-color: #2563eb;
+  padding: 8px 16px;
+  border-radius: 4px;
+  color: white;
+}
+
+// CLI (ANSI colors)
+console.log('\x1b[32m✓\x1b[0m Package loaded');
+```
+
+---
+
+## 📚 REFERENCE
+
+- **IMMEDIATE_FIXES.md** - Current blockers (read first)
+- **claude.md** - System overview
+- **agents.md** - Agent guidelines
+- **README.md** - Project structure
+- **ROADMAP.md** - Vision
+- **docs/** - Architecture guides
+- **schemas/** - Data models
+- **packages/** - Modular packages
+- **dbal/** - Database layer
+- **frontends/** - CLI, Qt6, Next.js bootloaders
+- **old/** - Reference for changes
+
+---
+
+**Last Note**: This system is built for delightfulness. If something feels rough, make it better. If schemas lack features, extend them. If code is complex, simplify it. The goal is a system that's obvious, maintainable, and genuinely good to use.
+
+Good luck! 🚀