Skip to main content

Velox KB Domain Model

This document describes the product/content concepts represented by the velox-kb repository. This repository is the user-facing knowledge domain for Velox, especially the in-app Code Library.

Domain Boundary​

velox-kb owns documentation content and documentation navigation concepts.

It represents:

  • user-facing explanation of Velox concepts
  • Code Library reference content
  • scripting reference content
  • documentation categories and index metadata
  • future/public documentation site content

It does not own runtime product behavior. When behavior is unclear from code, documentation should state that it is unclear rather than inventing a rule.

Documentation Audience​

The primary audience is a technical Velox user.

Typical readers include:

  • integration designers
  • support users
  • implementation consultants
  • customer technical users
  • operators configuring or troubleshooting Velox
  • users writing or reading Velox scripts

The repository should explain product behavior in user language rather than source-code language, except where a technical reference is necessary.

Documentation Surface​

A documentation surface is a place where help content is consumed.

Current/future surfaces:

  • Code Library: in-app reference content surfaced by Velox Designer.
  • Public/user documentation site: expected public documentation surface.
  • Docusaurus test site: current scaffold/test documentation site.
  • Install copy: documentation copied into install/runtime locations.

The Code Library is the most concrete active surface visible in this repository.

Code Library​

The Code Library is a structured reference library for Velox scripting and product symbols.

It contains:

  • classes
  • functions
  • constants
  • types
  • variables
  • scripting guide content

Business purpose:

  • help users build and understand Velox scripts
  • explain available objects, functions, variables, and data types
  • provide quick reference inside Velox Designer
  • support users while configuring flows and maps

Documentation Item​

A documentation item is a single help topic or reference entry.

Examples:

  • a function page
  • a class page
  • a constant page
  • a type page
  • a scripting guide article
  • a variable page

Each item should have a clear audience, topic, and path.

Symbol​

A symbol is a named item exposed to users through scripting or configuration reference.

Symbol categories include:

  • function
  • class
  • constant
  • type
  • variable

Symbol documentation often includes:

  • declaration
  • description
  • usage guidance
  • related items
  • deprecation state where applicable

Code Library Index​

The Code Library index is the navigation/lookup model for symbols.

It connects:

  • symbol name
  • category
  • visibility
  • declaration text
  • path to the Markdown item
  • see-more/see-also/deprecated metadata

The index is generated or maintained as metadata. The generator/process is unclear from this repository.

Documentation Category​

A category groups documentation items into a navigable knowledge area.

Major categories visible in the Code Library:

  • Classes
  • Constants
  • Functions
  • Scripting Guide
  • Types
  • Variables

Categories help users find related concepts without knowing exact symbol names.

Scripting Guide​

The scripting guide explains how users write Velox scripts.

Concepts likely covered by this surface:

  • syntax
  • statements
  • operators
  • data types
  • datasets
  • events
  • includes
  • map/flow scripting behavior
  • compilation errors
  • testing values

This content is user-facing even when it references technical language.

Generated Documentation Templates​

Root markdown files such as SourceDataView.md, DestDataView.md, and M_Variable.md appear to be templates for generated documentation.

Concepts:

  • placeholder text
  • generated reference pages
  • consistent wording for repeated Velox objects

The exact generation process is unclear.

Public Documentation Site​

The Velox folder contains a Docusaurus site scaffold.

Business purpose if activated:

  • publish Velox documentation outside the application
  • organize install, configuration, usage, scripting, troubleshooting, and reference material
  • provide searchable documentation for customer users

Current status is unclear because scaffold/sample content is still present and repository guidance says to ignore it for now.

Documentation Lifecycle​

Typical content lifecycle:

  1. Product behavior changes in a source repository.
  2. The documentation impact is identified.
  3. User-facing content is updated in velox-kb\Velox\docs\.
  4. Code Library entries are updated if the behavior affects scripting/reference content.
  5. Index metadata is regenerated or checked where needed.
  6. Content is copied into install/runtime locations when packaging a release.

Concept Relationships​

  • A documentation surface presents many documentation items.
  • The Code Library is a documentation surface focused on symbols and scripting.
  • A symbol has one documentation item and may appear in the Code Library index.
  • A category groups related documentation items.
  • The index links symbols to item paths and metadata.
  • Generated templates help produce repeated documentation items.
  • Install packages carry copied documentation content from this repository.

Documentation Principles​

  • Write for users first.
  • Use consistent Velox terminology.
  • State unclear behavior as unclear.
  • Avoid internal implementation detail unless users need it to operate Velox safely.
  • Keep Code Library file names and indexed paths stable unless a task explicitly changes the index/model.
  • Keep documentation aligned with product behavior in velox, velox-data, velox-web, and velox-web2.

Unclear From This Repository​

  • The tool/process that generates CodeLibrary\_Index.json.
  • Which documentation surface is the long-term public site.
  • How Code Library content is validated before release.
  • Which conceptual docs should live outside Code Library once the public docs site is settled.