Spec-Driven JSON Documentation Engine (SDDE)

An ultra-compact, portable, and AI-optimized documentation ecosystem.

SDDE enforces a strict separation of raw documentation data (stored as flat JSON files) and the rendering UI (a zero-dependency Read-Only SPA Viewer). This design completely eliminates structural breakage when documentation is compiled or updated by AIs, minimizes Context Load for Large Language Models, and integrates seamlessly with Git-based workflows.

🚀 Key Features

• Zero-Dependency CLI: Written entirely using native Node.js APIs (http, fs, path). Starts instantly in < 5ms with zero NPM dependency bloating.
• Folder-as-a-Tree AST: Naturally reflects the project folder structure. Handles folders as nested sections and hides prepended index numbers used for sorting (e.g. 01-architecture displays visually as Architecture).
• Modern Dark Glassmorphism SPA: Rendered using high-fidelity Vanilla CSS, custom animations, custom scrollbars, and premium typography (Inter/Outfit).
• Interactive Diagrams: Generates diagrams directly from text schemas via Mermaid.js, and injects svg-pan-zoom for seamless mouse drags, wheel zoom scrolling, and viewport resets.
• Path Traversal Protection: Employs strict URL routing resolution ensuring static and API loads never escape the designated /docs root.

📂 System Directory Structure

sdde/
├── package.json               # Package definitions and binary registry
├── README.md                  # Detailed system instructions and schemas
├── bin/
│   └── cli.js                 # Local server and folder-as-a-tree compiler
├── frontend/
│   ├── index.html             # The Glassmorphic SPA shell
│   └── app.js                 # SPA engine (JSON parser, Mermaid, svg-pan-zoom hook)
└── docs/                      # Target documentation folder
    ├── spec.config.json       # Global project metadata
    ├── index.json             # Welcome/Intro page spec
    └── 01-architecture/
        ├── database-benchmarks.json  # Data metrics spec page
        └── vtt-engine.json           # Interactive Mermaid pipeline spec

🛠️ Installation & Usage

You can use SDDE either from this repository during development or as a lightweight dev dependency in another workspace.

1. Install from GitHub Packages

Add the GitHub Packages registry for the scope and install SDDE as a dev dependency:

npm config set @pixelfehler310:registry https://npm.pkg.github.com
npm install -D @pixelfehler310/sdde

1.1 Initialize a Consumer Workspace

From the root of the consuming repository, scaffold the minimum SDDE setup:

npx sdde init

This creates docs/ if needed, writes starter specs, copies the SDDE skill into .github/skills/sdde-spec-writer/, and adds docs:dev and docs:validate scripts to the local package.json when present.

2. Run the Local Server

From the root of the consuming repository, spin up the server:

npx sdde dev

Alternatively, specify a custom port or target directory:

npx sdde dev --port 8080 C:\path\to\custom\docs

2.1 Validate Documentation Specs

Before concluding documentation changes, validate the full docs tree:

npx sdde validate

If you used sdde init, the generated package scripts are also available:

npm run docs:dev
npm run docs:validate

2.2 Update the Copied Skill

When the package version changes, sync the packaged skill into the current repository:

npx sdde sync-skill

Add --force to overwrite existing skill files.

3. View in Browser

Open the following link to view your interactive spec dashboard:

• http://localhost:3000

📋 JSON Schema Standards

To ensure successful visual hydration, all JSON specs must comply with flat, easy-to-generate schemas.

1. Global Config (spec.config.json)

Placed at the root of the /docs directory to govern overall metadata.

{
  "projectName": "SDDE Spec Engine",
  "version": "1.2.0",
  "theme": "dark" // "dark" | "light" | "system"
}

2. Content Pages (page.json)

Every documentation page is a simple JSON file containing title, description, optional order (for navigation sorting), and an array of content blocks.

{
  "title": "Welcome Screen",
  "description": "Short explanation of the spec content.",
  "order": 1,
  "content": [
    {
      "type": "heading",
      "level": 1,
      "text": "Welcome Header"
    },
    {
      "type": "paragraph",
      "text": "Supports **bold** formats and `inline code` elements."
    },
    {
      "type": "bullet-list",
      "items": [
        "First item here with **bolding**.",
        "Second item with `code snippet` formatting."
      ]
    },
    {
      "type": "table",
      "headers": ["Resource", "Status", "Response Time"],
      "rows": [
        ["/api/tree", "Active", "0.08 ms"],
        ["/api/page", "Active", "0.14 ms"]
      ]
    },
    {
      "type": "diagram",
      "format": "mermaid",
      "code": "graph LR\n    A[JSON Spec] --> B[CLI Engine]\n    B --> C[SPA Viewer]"
    }
  ]
}

🤖 Guidelines for AI Co-Authors

AIs and LLMs can edit files safely without breaking the user experience:

1. Never write raw HTML or script tags inside JSON files.
2. Stick strictly to the content block array schema (heading, paragraph, bullet-list, table, diagram).
3. Maintain small, specialized files (keep them under 5KB). This keeps context windows extremely compact, resulting in fast compilation and lower tokens consumption.