Skip to main content

Velox Web2 Domain Model

This document describes the business/product concepts represented by the velox-web2 repository. This repository is a newer .NET front end for Velox API publishing, documentation, and proxying to the Delphi VeloxAPIService.

Domain Boundary​

velox-web2 owns the API-facing experience around published Velox API flows.

It represents:

  • API catalog/discovery
  • OpenAPI document presentation
  • dynamic endpoint publishing
  • API caller authentication context
  • proxying requests to the Delphi VeloxAPIService
  • future Blazor web/API front-end surface

It does not execute Velox flows itself. Flow execution remains in the Delphi VeloxAPIService.

API Catalog​

The API catalog is the set of active Velox APIs available to external callers.

Catalog concepts:

  • API name/module name
  • OpenAPI schema name
  • production base URL
  • active/archive state
  • linked API actions

The catalog is read from the Velox configuration database.

API Definition​

An API definition represents a published API grouping.

Business meaning:

  • groups related API actions
  • has documentation identity
  • has a base URL segment
  • points to an OpenAPI document
  • is managed in Velox configuration

An API definition is not the flow itself. It is the public-facing contract around one or more Velox API actions.

API Action​

An API action is the public endpoint mapping for a Velox action configured for REST/API use.

Concepts:

  • HTTP method
  • REST endpoint
  • linked Velox action
  • base API URL
  • active/archive state

When a request reaches this endpoint, it is proxied to the Delphi VeloxAPIService, which executes the Velox flow.

Endpoint​

An endpoint is the externally reachable URL/method pair exposed by Velox.ApiService.

Endpoint identity is derived from:

  • API base URL segment
  • REST endpoint
  • HTTP method

Endpoint correctness depends on valid Velox configuration data.

OpenAPI Document​

An OpenAPI document describes the public API contract for callers.

Concepts:

  • schema file name
  • API title/module name
  • documented operations
  • request/response shape
  • Swagger UI display
  • Scalar display

OpenAPI files are served from static files and linked to API records from the config database. The generation source is outside this repository, most likely core Velox API/OpenAPI behavior.

API Consumer​

An API consumer is an external system or user calling a published Velox API endpoint.

Consumer concerns:

  • bearer token or authorization header
  • request method and route
  • query string
  • request body
  • response payload
  • status/error handling

The consumer interacts with velox-web2; the actual flow execution is delegated upstream.

Bearer Token User​

The current auth model treats a bearer token as a user identifier that can be looked up in VxData.

Concepts:

  • bearer token
  • user GUID
  • user number
  • authorization result
  • X-UserNum identity forwarded to upstream Velox API execution

The final production authentication contract is unclear from this repository.

Proxy Request​

A proxy request is the server-side forwarding of an external API call to the Delphi VeloxAPIService.

Concepts:

  • public request
  • authenticated user context
  • upstream Velox API service address
  • forwarded headers
  • forwarded body
  • upstream response
  • downstream response

The proxy adapts a public/documented endpoint to the internal VeloxAPIService endpoint that executes the flow.

Upstream VeloxAPIService​

The upstream VeloxAPIService is the Delphi service that actually executes API-triggered flows.

Business meaning:

  • receives the proxied request
  • runs the configured Velox action/flow
  • returns the API response

velox-web2 depends on this service being reachable and correctly configured.

API Documentation Experience​

The repository exposes API documentation through:

  • OpenAPI JSON endpoints
  • Swagger UI
  • Scalar API reference
  • static branding/customization files

The documentation experience lets API consumers discover and test published Velox APIs.

Route Publication Lifecycle​

Typical lifecycle:

  1. A Velox flow/action is configured for REST/API behavior.
  2. The action is linked into a Velox API definition.
  3. OpenAPI schema is generated and made available as a JSON file.
  4. velox-web2 starts and reads active API/action records from VxConfig.
  5. Dynamic routes are mapped for each active API action.
  6. API consumers call those routes.
  7. Requests are authenticated and proxied to the Delphi VeloxAPIService.
  8. Flow execution response is returned to the caller.

Blazor Web Surface​

Velox.Web is a Blazor web project in this solution.

Current business role appears future-facing or scaffold-like.

Potential concepts:

  • API/documentation landing page
  • management or browsing UI
  • front end to API service capabilities

The final role is unclear.

VxConfig And VxData​

VxConfig​

VxConfig provides API catalog and routing metadata:

  • setup/API address
  • API definitions
  • API actions
  • linked Velox actions
  • OpenAPI schema names

VxData​

VxData provides API-user context:

  • users
  • user numbers
  • related business data available to flows

Concept Relationships​

  • An API definition contains one or more API actions.
  • An API action becomes a public endpoint.
  • An endpoint points to the upstream VeloxAPIService.
  • An OpenAPI document describes an API definition for consumers.
  • An API consumer calls an endpoint using authorization.
  • A bearer token user becomes forwarded user context for flow execution.
  • A proxy request connects public API calls to internal Velox flow execution.

Unclear From This Repository​

  • The final authentication/token model.
  • Whether dynamic API routes should refresh without service restart.
  • The source-of-truth generation process for OpenAPI JSON files.
  • The final product role of the Blazor Velox.Web project.
  • The final relationship between velox-web2 and velox-web.