Skip to main content

Velox Help Architecture

This document is based on inspection of the velox-kb repository. The repository contains documentation content and a Docusaurus test site, not Velox runtime product code.

Overall Architecture​

velox-kb is the user-facing documentation repository for Velox. It currently contains two different documentation surfaces:

  • CodeLibrary: markdown and JSON reference content used by the Velox application Code Library.
  • Velox: a Docusaurus site scaffold/test project. Repository guidance says to read it but ignore it for now.

The root markdown files SourceDataView.md, DestDataView.md, and M_Variable.md are template-style markdown fragments with %s placeholders, apparently used for generated Code Library documentation. The exact generator is not present in the active repository files inspected.

Solution and Project Structure​

Top-level structure:

  • CodeLibrary: the main active content area for Velox Code Library help.
  • Velox: Docusaurus site scaffold with docs, blog, src, and static.
  • Root batch files:
    • 1. Velox Edit.bat: runs npm run start under Velox.
    • 2. Velox Build.bat: runs npm run build under Velox.
    • 3. Velox Test.bat: runs npm run serve under Velox.
  • Root markdown templates: SourceDataView.md, DestDataView.md, M_Variable.md.

CodeLibrary contains a large hierarchical markdown library for:

  • Classes.
  • Constants.
  • Functions.
  • Scripting guide.
  • Types.
  • Variables.

CodeLibrary\_Index.json maps documented symbols to declaration text and markdown paths. It groups entries by categories such as functions and classes.

Startup Sequence​

There is no Velox product executable startup sequence in this repository.

The Docusaurus test site sequence is:

  1. Change directory to C:\_GIT\Velox\velox-kb\Velox.
  2. Run one of:
    • npm run start for local editing.
    • npm run build for static build output.
    • npm run serve to serve the built site.

How the Velox application loads CodeLibrary\_Index.json and markdown files is not implemented here; that runtime behavior belongs to the velox repository.

Purpose of Each Major Area​

  • CodeLibrary: user-facing reference documentation surfaced inside Velox's Help > Code Library menu and potentially public docs.
  • CodeLibrary\_Index.json: symbol index linking declarations to markdown files.
  • Velox: Docusaurus test/static documentation site.
  • Root templates: reusable markdown patterns for generated variable/data-view docs.

Key Frameworks and Libraries​

Visible frameworks/tools:

  • Markdown and MDX.
  • JSON.
  • Docusaurus 3.1.1.
  • React 18.
  • prism-react-renderer.
  • Node/npm scripts.

The Docusaurus config still contains scaffold/default site values, so it should not be treated as a finished public Velox documentation site.

Configuration Loading​

Documentation configuration is file-based:

  • CodeLibrary\_Index.json is the symbol/path index for Code Library content.
  • Docusaurus reads Velox\docusaurus.config.js, Velox\sidebars.js, and files under Velox\docs.
  • The root batch files hardcode the local workspace path to the Docusaurus folder.

The runtime configuration used by the Velox application to locate and render Code Library files is unclear from this repository alone.

Logging​

There is no repository-specific logging architecture.

Docusaurus/npm commands produce console output when run. The Velox application may have its own logging when loading Help/Code Library content, but that is not defined here.

Database Access Architecture​

There is no database access layer in this repository.

Some Code Library markdown describes database-related scripting objects and functions, but those are documentation artifacts, not executable database access code.

Plugin/Module Architecture​

There is no code plugin architecture here.

The closest architectural concept is the Code Library content model:

  • CodeLibrary\_Index.json provides symbol metadata.
  • Markdown files provide the displayed content.
  • Paths are stored using Windows-style path separators.

How the Velox application turns this into menus/search/display is unclear from this repository.

Flow Execution Architecture​

This repository does not execute Velox flows.

It documents concepts and scripting APIs that users may use while designing flows in Velox Designer. The exact relationship between generated Code Library entries and runtime script/function registration is implemented in velox, not in this repository.

Serialization Formats​

Visible formats include:

  • Markdown (.md).
  • MDX (.mdx).
  • JSON (_Index.json, package files, Docusaurus category files).
  • JavaScript/CSS for Docusaurus.
  • Images/assets.
  • Batch scripts.

Major Design Patterns Used​

  • File-per-symbol reference documentation.
  • Central JSON index pointing to symbol documentation files.
  • Hierarchical documentation categories.
  • Static site generation through Docusaurus for the experimental/test site.
  • Template markdown fragments for generated documentation pages.

Areas of Technical Debt​

  • The Docusaurus project has been updated from the default scaffold branding for the PKB site, though sample blog content may still exist until the publishing model is finalized.
  • Repository guidance says the Docusaurus project should be ignored for now, so the active public docs architecture is not settled.
  • The generation process for CodeLibrary\_Index.json and the many symbol markdown files is unclear from active files.
  • Root batch files hardcode local paths.
  • Template files contain raw %s placeholders; the renderer/generator contract is unclear.

Questions About the Architecture​

  • What tool generates or updates CodeLibrary\_Index.json and the symbol markdown files?
  • Which docs are intended for TinaCMS/TinaDocs versus in-app Code Library display?
  • Should the Docusaurus scaffold be removed, completed, or replaced?
  • What validation exists to ensure every _Index.json path points to an existing markdown file?
  • How should user-facing conceptual documentation be organized outside CodeLibrary?