Skip to main content

Velox Developer Guide

Summary​

This guide is for developers joining the Velox velox repository. It is part of the internal Velox Product Knowledge Base (PKB), not end-user documentation.

Velox is primarily a Delphi VCL codebase with three main runtime projects: Velox Designer, VeloxService, and VeloxAPIService. The repository also contains a VeloxTest harness, a separate .NET XSD helper tool, shared runtime classes, Designer forms, scripting imports, patched vendor code, third-party vendor source, and local build/install-copy scripts.

The source code, project files, and scripts are the authority for this guide. Where build, test, release, or dependency behaviour cannot be determined from this repository, that is stated explicitly.

Source Basis​

Primary source locations used for this guide:

  • AGENTS.md - permanent repository guidance and safety rules.
  • VeloxGroup.groupproj - Delphi project group for Velox, VeloxService, VeloxAPIService, and VeloxTest.
  • Velox.dpr, VeloxService.dpr, VeloxAPIService.dpr, VeloxTest.dpr - executable startup, runtime flags, FastMM/madExcept setup, and initial configuration loading.
  • Velox.dproj, VeloxService.dproj, VeloxAPIService.dproj, VeloxTest.dproj - Delphi project configuration, platforms, output paths, compiler defines, version metadata, and search paths.
  • _Build Core.bat, _Build Velox Dev 32.bat, _Build Velox Dev 64.bat, _Build Velox Dev.bat, _Build Velox Dev Beta.bat, _Build Velox Dev Beta Prod.bat, _Build Velox Dev Beta Prod 64.bat, _Build Velox Trial.bat, _Build Velox Service Test.bat - command-line build orchestration.
  • _UPDATE INSTALL *.bat - install-folder copy scripts.
  • _CodeSign.bat - legacy/unsafe code-signing reference. It should not be treated as current release process without review.
  • VeloxXSD\VeloxXSD.csproj, VeloxXSD\VeloxXSD.bat - XSD helper project and documented command-line parameters.
  • Classes\Tools\vxConfigPath.pas - ProgramData paths and AppDataFolder.cfg override.
  • Classes\vxCon.pas - Connections.json loading and connection-key validation.
  • Classes\vxSetup.pas - General Setup defaults and runtime configuration.
  • Classes\Service\*.pas, VeloxService\classMain.pas, VeloxAPIService\classMain.pas, VeloxAPIService\vxWebModule.pas - service/runtime execution.
  • Forms\frmMain.pas, Forms\frmSetupGeneral.pas, Forms\*.pas, Forms\Transports\*.pas - Designer shell and setup forms.

Repository Layout​

Root Projects​

  • Velox.dpr / Velox.dproj - Velox Designer, the main Windows VCL GUI application for creating and managing Velox configuration.
  • VeloxService.dpr / VeloxService.dproj - Windows service for scheduled, monitored, transport, and other non-REST background Flow execution.
  • VeloxAPIService.dpr / VeloxAPIService.dproj - Windows service that hosts REST/API Flow execution through WebBroker and Indy.
  • VeloxTest.dpr / VeloxTest.dproj - VCL test harness that starts in service-like test mode.
  • VeloxGroup.groupproj - Delphi project group containing the four main Delphi projects.
  • VeloxTestGroup.groupproj - additional project group present in the repository; its exact intended workflow was not traced in this pass.
  • VeloxXSD\ - separate .NET 6.0-windows helper executable used by the Designer XSD workflow.

Core Source Folders​

  • Classes\ - shared Velox business/runtime classes.
  • Classes\GUI\ - Designer-facing helpers, database update/version tooling, service management helpers, module update/sync helpers, and tree-related UI support.
  • Classes\Service\ - service-side managers, execution items, queues, timers, threads, REST manager, and transport runtime orchestration.
  • Classes\Tools\ - common utility code, path/config handling, IPC helpers, constants, type definitions, SQL helpers, JSON helpers, and related support.
  • Classes\Transports\ - transport base class and concrete inbound/outbound transport implementations.
  • Forms\ - Designer VCL forms.
  • Forms\Transports\ - transport setup UI.
  • Forms\Action\ - ignored by repository guidance as trial/test/backup code.
  • Forms\LinkedAction\ - ignored by repository guidance as trial/test/backup code.
  • Components\ - local component source and component test projects.
  • Scripting\ - Pascal Script integration, imports, generated/imported script interfaces, and custom script imports.
  • Imports\ - imported Delphi type libraries, including IBM MQ-related imports.
  • Images\ - image assets.
  • EventMessages\ - Windows event message project/source.
  • ReportBuilder\ - ReportBuilder-related source used by the project.

Vendor and Patch Folders​

  • Vendor\ - third-party vendor source. Do not modify unless explicitly instructed.
  • Modified\ - third-party/vendor code patched for Velox. Changes here should be rare, isolated, and tied to a specific Velox need.
  • Vendor\Git Clone *.bat and Vendor\Git Update *.bat - helper scripts for fetching/updating some vendor dependencies. They do not form a complete dependency management system.

Generated, Historical, and Local Folders​

  • Win32\ and Win64\ - build output folders.
  • __history\, __recovery\, _BACKUP\, Classes\_NEW\, Forms\Action\, Forms\LinkedAction\ - history, recovery, backup, trial, test, or experimental folders. Do not treat these as active production source unless a task explicitly targets them.
  • .git, .agents, local .identcache, .dproj.local, .delphilsp.json, .dxsettings, and similar files - Git/local IDE metadata. Do not treat machine-local files as release process.

Documentation Folders​

  • velox-kb\VeloxPKB\docs\velox\ - internal PKB/developer Markdown documentation maintained for this repository.
  • _Documentation\ - developer notes, reference material, research, and informal working documents.
  • MadExceptWebsite\ and UpdateWebsite\ - website/update-related assets. Their current release ownership was not fully traced in this pass.

Project Structure​

Executable Projects​

VeloxGroup.groupproj defines targets for Velox, VeloxService, VeloxAPIService, and VeloxTest. The project group has no explicit inter-project build dependencies.

Shared Runtime Model​

The main projects share core units under Classes\. Important shared classes include:

  • TvxModule in Classes\vxModule.pas - base persisted module, relation, template, and logging foundation.
  • TvxSetup in Classes\vxSetup.pas - General Setup module and global gSetup.
  • TvxConnection in Classes\vxCon.pas - runtime system connection and config/log/data connection selection.
  • TvxActionMan in Classes\vxActionMan.pas - Flow/Action module and flow execution.
  • TvxActionPool in Classes\vxActionPool.pas - pooled action instances for runtime execution.
  • TvxDataDef, TvxDBDef, TvxFileDef in Classes\vxDataDef.pas, Classes\vxDBDef.pas, and Classes\vxFileDef.pas - data definition model.
  • TvxDBCon and TvxFileCon in Classes\vxDBCon.pas and Classes\vxFileCon.pas - database and file connection modules.
  • TvxTransport and transport subclasses under Classes\Transports\ - inbound/outbound communication.
  • TvxMap, TvxReport, TvxSQLScript, TvxScriptlet, TvxVariableGroup, and TvxAPI - major module types used by flows.

Important Services​

  • TVeloxWorker in VeloxService\classMain.pas - Windows service worker for background execution.
  • TVeloxAPIWorker in VeloxAPIService\classMain.pas - Windows API service worker.
  • TvxScheduleManager in Classes\Service\vxManagerScheduler.pas - scheduled Flow manager.
  • TvxMonitorManager in Classes\Service\vxManagerMonitor.pas - file monitor Flow manager.
  • TvxTransportManagerIn in Classes\Service\vxManagerTransportIn.pas - inbound transport manager.
  • TvxTransportManagerOut in Classes\Service\vxManagerTransportOut.pas - outbound transport manager and queue.
  • TvxRESTManager in Classes\Service\vxManagerREST.pas - REST endpoint synchronization and API Flow dispatch.

Important Forms​

  • TMain in Forms\frmMain.pas - main Designer shell.
  • TSetupGeneral in Forms\frmSetupGeneral.pas - General Setup, service controls, API service settings, proxy, email, and runtime options.
  • TSetupActions in Forms\frmSetupActions.pas - Flow/Action setup.
  • Forms\frmSetupDBCon.pas, Forms\frmSetupFileCon.pas, Forms\frmSetupDBDefs.pas, and file definition setup forms - connection and definition configuration.
  • Forms\frmSetupMaps.pas, Forms\frmSetupMapDesign.pas, Forms\frmSetupReports.pas, Forms\frmSetupSQLScript.pas, Forms\frmSetupScriptlet.pas, Forms\frmSetupVariableGroup.pas, Forms\frmSetupAPI.pas - major module setup forms.
  • Forms\Transports\frmTransport*.pas - transport setup forms.
  • Forms\frmLogs.pas, Forms\frmLogDetails.pas, Forms\frmManageLogs.pas, Forms\frmManageTransportLogs.pas - log and transport log views.

Build​

Required Toolchain​

  • Delphi 13.1 / Embarcadero Studio 37.0 is the expected Delphi toolchain.
  • The repository guidance says Delphi source is available read-only at C:\Program Files (x86)\Embarcadero\Studio\37.0\source\ when needed.
  • The command-line build script calls C:\Program Files (x86)\Embarcadero\Studio\37.0\bin\rsvars.bat.
  • The build script expects madExcept patching at C:\Program Files (x86)\madCollection\madExcept\Tools\madExceptPatch.exe.
  • VeloxXSD requires a .NET SDK capable of building net6.0-windows.

The exact clean-machine installation procedure for all Delphi components and third-party libraries is not fully described in this repository.

IDE Build​

Open VeloxGroup.groupproj in Delphi 13.1 for normal development across the main projects.

The Delphi projects support Win32 and Win64 platforms. The .dproj files output to:

  • .\$(Platform)\$(Config)\
  • .\$(Platform)\$(Config)\DCU\

Project metadata includes Release and Debug configurations. The command-line scripts primarily build Release.

Command-Line Compile​

Use _Build Core.bat for a single project compile and madExcept patch:

call "C:\_GIT\Velox\velox\_Build Core.bat" C:\_GIT\Velox\velox\ Velox Release Win64

Important details from _Build Core.bat:

  • Argument 1 is the repository folder path.
  • Argument 2 is the project name without .dproj.
  • Argument 3 is the configuration, such as Release.
  • Argument 4 is the platform, such as Win32 or Win64.
  • The script runs msbuild %2.dproj /t:build /p:config=%3 /p:platform=%4.
  • The script then patches the built executable with madExcept using the project .mes file and generated .map file.

The script comments mention .dproj, but the active command appends .dproj. Follow the current callers and pass Velox, VeloxService, or VeloxAPIService, not Velox.dproj.

Build Scripts​

  • _Build Velox Dev 64.bat - builds Velox, VeloxService, and VeloxAPIService as Win64 Release, copies install files, and calls an external dev install Git update script.
  • _Build Velox Dev 32.bat - builds the three main projects as Win32 Release and Win64 Release, copies install files, and calls external 32-bit and 64-bit dev install Git update scripts.
  • _Build Velox Dev.bat - full dev build workflow. Inspect before running because it performs copy/update work beyond compilation.
  • _Build Velox Dev Beta.bat, _Build Velox Dev Beta Prod.bat, _Build Velox Dev Beta Prod 64.bat - build and copy/update broader channel sets. Inspect before running.
  • _Build Velox Trial.bat - builds Win32/Win64 Release outputs and updates trial install folders/Git scripts.
  • _Build Velox Service Test.bat - builds only VeloxService Win64 Release.
  • _Build Velox - no git update *.bat - build/copy workflows intended to avoid external Git update scripts.

Treat scripts other than _Build Core.bat as release/install-copy workflows, not simple compile commands.

Build Outputs and Symbols​

Release output folders are:

  • Win32\Release\
  • Win64\Release\

The .dproj files enable map file generation in many configurations. _Build Core.bat uses the .map file when running madExceptPatch.exe.

VeloxXSD Build​

VeloxXSD\VeloxXSD.csproj is separate from the Delphi project group and targets net6.0-windows.

VeloxXSD\VeloxXSD.bat documents runtime parameters:

  • output folder, without trailing slash
  • output XSD file name
  • one or more XML sample file paths

The repository does not show a complete build/release script for VeloxXSD alongside the Delphi build scripts.

Debugging​

Shared Startup Behaviour​

The main executables initialize FastMM5 and madExcept, set runtime flags, load the system connection, create system logging, and then create the relevant UI/service form.

Common startup/configuration details:

  • Connection selection uses gSystemConnection.Load(GetParamVal('c', True)).
  • The -c=<key> style parameter selects a connection key from Connections.json.
  • Runtime config is loaded from ProgramData paths resolved by Classes\Tools\vxConfigPath.pas.
  • CreateSystemLog is called after system connection loading.

Velox Designer Debugging​

Run Velox.dproj from the Delphi IDE.

Designer startup in Velox.dpr:

  • sets IsServer := False
  • sets IsBackground := False
  • configures FastMM report output
  • loads the system connection
  • checks/loads database state
  • creates the system log
  • creates gSetup
  • creates TMain

Useful startup parameters observed in the source:

  • -c=<key> - select connection key.
  • -test or -st=true - start in test mode.
  • -tm=true or -testmaster - enable test master mode.
  • -a=true - enable alpha mode.

VeloxService Debugging​

VeloxService is a Windows service. For lifecycle, IPC, threading, cancellation, and service-control changes, verify behaviour as a real Windows service.

Service startup in VeloxService.dpr and VeloxService\classMain.pas:

  • sets IsServer := True
  • sets IsBackground := True
  • loads the selected system connection
  • creates the system log
  • creates TVeloxWorker
  • loads gSetup
  • loads variable groups
  • creates execution managers
  • synchronizes schedule, monitor, inbound transport, and outbound transport work

The service code contains a USECONSOLE define path in both the .dpr and classMain.pas. Source comments say both locations must be kept consistent. Treat this as a debugging aid, not a production mode.

VeloxAPIService Debugging​

VeloxAPIService is also a Windows service.

API service startup in VeloxAPIService.dpr and VeloxAPIService\classMain.pas:

  • sets IsServer := True
  • sets IsBackground := True
  • loads the selected system connection
  • creates the system log
  • creates TVeloxAPIWorker
  • loads gSetup
  • loads variable groups
  • creates TvxRESTManager
  • starts the WebBroker/Indy HTTP server

REST request flow passes through:

  • Indy TIdHTTPWebBrokerBridge
  • WebBroker request handling
  • VeloxAPIService\vxWebModule.pas
  • TvxRESTManager
  • Flow execution classes under Classes\Service\ and Classes\vxActionMan.pas

General Setup stores API service domain, port, SSL flag, and certificate fields. The current source also references separate gateway/SSL assumptions in existing docs and code comments, but final SSL ownership should be verified before changing service SSL behaviour.

VeloxTest Debugging​

VeloxTest is a VCL harness for service-like runtime work.

VeloxTest.dpr sets:

  • IsTest := True
  • IsServer := True
  • IsBackground := True

It loads the system connection, creates the system log, loads setup, disables vxConfig.EnableDebug after setup loading, and creates TMain.

Use VeloxTest when it is more convenient than attaching to a service, but do not assume it is identical to production service hosting.

Diagnostics​

The applications use:

  • FastMM5 for memory diagnostics and leak reporting.
  • madExcept for exception handling and patched release executables.
  • Velox system logging through TvxSystemLog and log database abstractions.
  • Windows service/event logging for service paths.

FastMM report filenames are set per executable under the Velox log path, such as VeloxFastMMReport.txt, VeloxServiceFastMMReport.txt, VeloxAPIServiceFastMMReport.txt, and VeloxTestFastMMReport.txt.

Testing​

Automated Tests​

No DUnit/TestFramework-style automated test suite was found by searching the repository for common Delphi test framework markers.

This does not prove there are no external tests. It only means this repository does not visibly contain a standard Delphi automated unit-test suite in the inspected source.

Repo-Owned Test Harness​

VeloxTest is the main test harness found in the repository. It starts with service/test flags but displays a VCL form. Use it for development checks that need service-like runtime state without fully hosting as a Windows service.

Manual and Integration Testing​

Testing is currently source- and workflow-driven:

  • Build the affected project.
  • Run Designer workflows when changing forms, module setup, serialization, or user configuration.
  • Run VeloxService as a real service when changing schedules, monitors, transport managers, service shutdown, IPC, locking, or thread lifecycle.
  • Run VeloxAPIService when changing REST endpoints, API Flow execution, OpenAPI-related flow properties, HTTP request handling, or API service setup.
  • Test both Win32 and Win64 for changes touching pointers, handles, Windows messages, COM/OLE, shell execution, native transports, external DLLs, or low-level component callbacks.
  • Test configuration import/export when changing TvxModule, published properties, DefineProperty, old property readers, class registration, or template loading.
  • Test database upgrade paths when changing schema update code.

Database Testing​

The repository guidance states that the Velox database is Microsoft SQL Server 2025.

Schema changes, when explicitly requested, belong in:

  • Classes\GUI\vxDBUpdateVersion.pas
  • Classes\GUI\vxDBUpdate.pas

Do not create a parallel migration system.

Validation Before Finishing Work​

For code changes, validate as far as the local machine allows:

  • Build the affected project/configuration.
  • Run the most relevant manual/test-harness workflow.
  • Run service/API service checks for runtime work.
  • Include Win32 and Win64 validation for architecture-sensitive changes.
  • Report anything that could not be run.

For documentation-only PKB changes, a build is not required unless the documentation task also changes code or claims behaviour that needs compilation verification.

Release Process​

What the Repository Shows​

The repository contains local build/install-copy scripts, not a complete public release pipeline.

Observed release-like workflow:

  1. Build Velox, VeloxService, and VeloxAPIService using _Build Core.bat.
  2. Patch each executable with madExcept.
  3. Copy Velox*.exe outputs into install folders under C:\_GIT\Velox\Install\install-velox*.
  4. Copy selected Win32 Designer output into Velox32\Velox.exe inside some 64-bit install folders.
  5. Call external scripts under C:\_GIT\Velox\_gitscripts\Install\Update\ to update install Git repositories.

The install folders live outside this repo in the root Velox workspace Install\ area.

Release Channels Visible in Scripts​

Script names indicate these channels:

  • Dev
  • Beta
  • Prod
  • Trial
  • 32-bit and 64-bit install variants

The scripts update install folders such as:

  • install-velox64dev
  • install-velox64
  • install-velox64trial
  • similar 32-bit/beta/prod folders

Exact external publishing, customer download, release approval, and version-tagging process is not fully contained in this repository.

Code Signing​

_CodeSign.bat exists, but it references old/non-Velox paths and contains sensitive signing material. Do not treat it as current release process without review and cleanup.

The current, approved code-signing process is unclear from this repository.

Versioning​

Version metadata is stored in the .dproj files. For example, Velox.dproj contains product/file version metadata under VerInfo_* properties.

No complete release-version policy was found in this repository. Do not infer version bump rules from a single .dproj value.

Release Cautions​

  • Do not run broad build scripts casually. Many do copying and external Git updates after compiling.
  • Use _Build Core.bat for compile-only checks.
  • Inspect the specific _UPDATE INSTALL ... FOLDER.bat script before using it.
  • Do not publish, sign, or update install repositories unless that is explicitly requested.
  • Do not commit generated binaries, map files, local build outputs, local IDE files, or machine-specific configuration.

Configuration​

Runtime Configuration Paths​

Classes\Tools\vxConfigPath.pas resolves default common application data to:

C:\ProgramData\Velox\

Important subfolders include:

  • Config\
  • Log\
  • Schema\
  • Certificate\
  • Temp\
  • Files\

The executable folder can contain AppDataFolder.cfg to override the common app data folder name.

Connections​

Connection configuration is read from:

C:\ProgramData\Velox\Config\Connections.json

Classes\vxCon.pas validates the connection key, display name, config number, and database key assignments. Startup parameter -c=<key> selects a connection key.

General Setup​

General Setup is loaded through TvxSetup and global gSetup. It controls service, API service, email, proxy, default file path, diagnostics, transport retry settings, web/API URL fields, and other runtime settings.

Related source:

  • Classes\vxSetup.pas
  • Forms\frmSetupGeneral.pas
  • Forms\frmSetupGeneral.dfm

Installed Defaults​

The repository guidance says installed default ProgramData folders and files are maintained outside this repository under:

C:\_GIT\Velox\Install\ProgramData\install-veloxprogramdata

When changing installed default configuration, inspect source defaults and the install template.

Coding Conventions​

General Delphi Style​

  • Use Delphi 13.1-compatible code.
  • Follow the existing VCL and Delphi style in nearby units.
  • Prefer explicit, readable code over clever abstractions.
  • Keep changes small and local.
  • Preserve public APIs, published properties, streaming contracts, database fields, configuration keys, and file formats unless explicitly asked to change them.
  • Avoid introducing new global state unless it follows an existing runtime pattern and is necessary.
  • Use existing helpers and subsystem patterns before adding new utility layers.

Naming and Structure​

  • Core classes commonly use Tvx... names.
  • Forms commonly use Tfrm... or setup form names already established in the file.
  • Global runtime objects use names such as gSetup, gSystemConnection, gVariableGroups, and gRESTManager.
  • Module descendants should follow existing TvxModule persistence, relation, and registration patterns.
  • Keep .pas and .dfm changes aligned for VCL forms.

Serialization and Compatibility​

Treat these as compatibility-critical:

  • Published properties.
  • .dfm streaming.
  • Module templates and .cfg import/export.
  • XML, JSON, file definition, map, report, and transport persisted data.
  • Classes.RegisterClass / UnRegisterClass usage.
  • DefineProperty, ReadOld..., class alias, and old-class conversion logic.

Legacy-looking code may be required for customer upgrades or old configuration imports. Do not remove it without tracing the compatibility path.

Threading and Runtime Stability​

Velox stability is especially important around services, transports, flow execution, and shutdown.

  • Preserve existing locking, cancellation, pool release, and ownership semantics unless the task explicitly changes them.
  • Do not introduce new TerminateThread usage.
  • Do not create unclear cross-thread object ownership.
  • Be careful with global state copied into threads for safety, such as debug flags.
  • Service shutdown, action pool cleanup, transport queues, monitor queues, and REST request execution require extra review.

Win32 and Win64 Compatibility​

Maintain both Win32 and Win64 compatibility.

  • Use pointer-width-safe types such as NativeInt, NativeUInt, WPARAM, LPARAM, or typed pointers for pointer-sized values.
  • Do not store object references, pointers, handles, or Windows message values in Integer, Cardinal, or other fixed 32-bit storage.
  • Recheck COM/OLE, shell execution, Windows API declarations, transport callbacks, and component event data on both platforms.
  • VxCompilerDefines.inc notes that PS_USECLASSICINVOKE is tied to legacy invoke behaviour and must be off for x64. Verify project defines before changing Pascal Script invocation behaviour.

Database Rules​

  • The Velox database target is Microsoft SQL Server 2025.
  • Do not rename columns, tables, stored procedures, or fields without approval.
  • Do not change schema unless explicitly requested.
  • When schema changes are requested, use Classes\GUI\vxDBUpdateVersion.pas and wire versions in Classes\GUI\vxDBUpdate.pas.
  • Keep logging database access behind log-specific abstractions such as SQLL and ActiveLog, even where they currently resolve through shared plumbing.

Dependency Management​

Dependency Sources​

Dependencies are managed through a mix of repository source folders, patched source folders, installed component suites, Delphi environment variables, and local scripts.

The .dproj search paths reference:

  • repository source under Classes\, Forms\, Components\, Imports\, ReportBuilder\, and Scripting\
  • patched vendor code under Modified\
  • third-party source under Vendor\
  • installed DevExpress VCL source through $(DXVCL)
  • Delphi environment paths through $(BDS) and rsvars.bat

Repository Vendor Dependencies​

Vendor names found in project search paths include:

  • BufferedString
  • ChromeTabs
  • Cromis
  • dbxoodbc
  • delphi-neon
  • Deltics
  • DevArtSQL
  • ExtraPrintDevices
  • Fastcode
  • FastMM5
  • Faststrings
  • GpDelphi
  • HTMLViewer
  • Indy
  • JOSE-JWT
  • MarkdownViewer
  • NativeExcel
  • NativeXML
  • OLEDB Direct
  • OpenAPI-Delphi
  • PascalScript
  • ReportBuilder
  • SecureBridge
  • Sqids
  • SuperObject
  • SynEdit
  • TurboPower LockBox3
  • TWebUpdate
  • VirtualTreeView

This list comes from Velox.dproj search paths and should be rechecked when dependency paths change.

Patched Vendor Dependencies​

Patched dependency folders referenced from project search paths include:

  • Modified\Cromis
  • Modified\DevExpress
  • Modified\Indy
  • Modified\PascalScript
  • Modified\ReportBuilder
  • Modified\SecureBridge
  • Modified\SuperObject
  • Modified\SynEdit
  • Modified\Vcl

Treat Modified\ as Velox-owned patches to external behaviour. Keep changes isolated and explain why a patch belongs there.

Installed Component Dependencies​

The project search paths reference many DevExpress VCL source folders through $(DXVCL), including ExpressBars, ExpressEditors, ExpressQuantumGrid, ExpressScheduler, ExpressPrinting System, ExpressRichEdit, ExpressPDFViewer, and related libraries.

The project also relies on Embarcadero/Delphi installed libraries and normal Delphi MSBuild targets through $(BDS).

Adding or Updating Dependencies​

  • Do not add third-party dependencies without approval.
  • Do not edit Vendor\ unless explicitly instructed.
  • Prefer existing dependency families already used in the project.
  • If updating a vendor dependency, inspect both Vendor\ and Modified\ to avoid losing Velox patches.
  • Do not assume the vendor clone/update scripts produce a clean-machine build; they are helpers, not complete package-management documentation.

Typical Workflow​

  1. Read AGENTS.md.
  2. Read the relevant PKB docs in velox-kb\VeloxPKB\docs\velox\.
  3. Identify the owning subsystem and module type.
  4. Read the surrounding units and related forms before editing.
  5. Check persistence, serialization, class registration, database, thread, and Win32/Win64 implications.
  6. Make the smallest change that solves the task.
  7. Build the affected project where possible.
  8. Run the most relevant manual, service, API, or harness test.
  9. Report changed files, validation performed, risks, and anything that could not be tested.

Designer UI Workflow​

  • Check both .pas and .dfm.
  • Preserve component names and published properties unless the UI contract is intentionally changing.
  • Check related active forms when there are parallel implementations. Ignored trial/test/backup folders such as Forms\LinkedAction are only in scope when a task explicitly targets them.
  • Run Designer and exercise the changed setup form.

Service Workflow​

  • Check Designer service-management behaviour as well as service runtime code.
  • Check IPC refresh/synchronization if the setting can be changed while a service is running.
  • Validate service behaviour as a Windows service for lifecycle/threading changes.

API Workflow​

  • Check REST Flow configuration in TvxActionMan.
  • Check TvxRESTManager and VeloxAPIService\vxWebModule.pas.
  • Check TvxAPI and OpenAPI schema generation if endpoint/request/response metadata changes.
  • Preserve REST endpoint and OpenAPI contracts unless changing them is the task.

Schema Workflow​

  • Implement schema updates in Classes\GUI\vxDBUpdateVersion.pas.
  • Wire version execution in Classes\GUI\vxDBUpdate.pas.
  • Follow existing SQL/versioning conventions.
  • Test against the supported SQL Server configuration.

Documentation Workflow​

  • Developer/PKB documentation belongs in velox-kb\VeloxPKB\docs\velox\, not in the velox source repository.
  • User-facing documentation belongs in the separate velox-kb\Velox\ repository, not here.
  • Do not invent behaviour; mark unclear behaviour as unclear.
  • Link related PKB documents where useful.

Common Pitfalls​

  • _Build Core.bat appends .dproj; pass the project name without extension.
  • The broad build scripts copy install files and call external Git update scripts.
  • Build scripts use hard-coded local paths.
  • The code-signing script is not a current trustworthy release guide.
  • Project files contain local/generated IDE artifacts nearby; avoid committing local machine settings.
  • Vendor\ and Modified\ have different ownership rules.
  • Backup/history/recovery folders can look like active source.
  • Legacy class/property/readers may be upgrade/import compatibility code.
  • Some action, service, and transport runtime behaviour depends on global state such as IsDesigner, IsServer, IsBackground, IsTest, EnableDebug, and active/test connection mode.
  • Log access must remain abstracted through log-specific paths, even if current plumbing overlaps with config access.
  • REST execution is tied to Flow execution type, API metadata, and OpenAPI schema generation.
  • Forceful thread termination exists in the current codebase; do not normalize it into new code.
  • Pointer and handle casts that work in Win32 can fail in Win64.
  • Some behaviour depends on installed customer environment details not represented in source, such as database drivers, MQ libraries, services, certificates, and filesystem permissions.

Areas That Are Unclear From This Repository​

  • Complete clean-machine setup for every third-party Delphi component.
  • Complete automated test strategy beyond the VeloxTest harness and manual/integration workflows.
  • Complete public release pipeline after install-folder Git updates.
  • Current approved code-signing process.
  • Complete VeloxXSD release packaging workflow.
  • Final SSL ownership for VeloxAPIService versus any gateway/IIS layer.