Velox Architecture

Summary

This document describes the internal architecture of the Velox repository as it exists in the source code. It is part of the Velox Product Knowledge Base (PKB), intended for future developers, AI agents, and technical writers.

Velox is a Delphi VCL product made up of a desktop Designer, a Windows worker service, and a Windows API service. These executable projects share a large domain/runtime library under Classes\, a VCL forms layer under Forms\, and a configuration/database persistence model centered on module classes such as TvxModule, TvxActionMan, data definitions, transports, reports, maps, setup, logging, and REST/API definitions.

The code is the source of truth. Where behavior could not be determined from source inspection, this document states that explicitly rather than inventing behavior.

Related PKB Documents

• Developer Guide
• Domain Model
• Knowledge Map
• Technical Review TODO

Source Basis

Primary source locations used for this architecture document:

• VeloxGroup.groupproj - Delphi project group for the main Velox projects.
• Velox.dpr:58, Velox.dpr:65, Velox.dpr:92, Velox.dpr:110, Velox.dpr:112, Velox.dpr:114, Velox.dpr:130 - Designer startup sequence.
• VeloxService.dpr:42, VeloxService.dpr:50, VeloxService.dpr:56, VeloxService.dpr:61, VeloxService.dpr:63, VeloxService.dpr:64 - worker service startup sequence.
• VeloxAPIService.dpr:47, VeloxAPIService.dpr:55, VeloxAPIService.dpr:61, VeloxAPIService.dpr:66, VeloxAPIService.dpr:68, VeloxAPIService.dpr:69 - API service startup sequence.
• VeloxTest.dpr:60, VeloxTest.dpr:68, VeloxTest.dpr:76, VeloxTest.dpr:82, VeloxTest.dpr:88, VeloxTest.dpr:94, VeloxTest.dpr:110 - test harness startup sequence.
• Forms\frmMain.pas - main Designer form and application shell.
• VeloxService\classMain.pas:25, VeloxService\classMain.pas:39, VeloxService\classMain.pas:96, VeloxService\classMain.pas:128, VeloxService\classMain.pas:178, VeloxService\classMain.pas:193, VeloxService\classMain.pas:449, VeloxService\classMain.pas:724 - worker service lifecycle, managers, IPC, and shutdown.
• VeloxAPIService\classMain.pas:26, VeloxAPIService\classMain.pas:39, VeloxAPIService\classMain.pas:93, VeloxAPIService\classMain.pas:120, VeloxAPIService\classMain.pas:193, VeloxAPIService\classMain.pas:212, VeloxAPIService\classMain.pas:584, VeloxAPIService\classMain.pas:440 - API service lifecycle, WebBroker bridge, REST manager, IPC, and shutdown.
• VeloxAPIService\vxWebModule.pas:12, VeloxAPIService\vxWebModule.pas:50, VeloxAPIService\vxWebModule.pas:61 - WebBroker module dispatch to gRESTManager.
• Classes\vxModule.pas:86, Classes\vxModule.pas:1483, Classes\vxModule.pas:1510, Classes\vxModule.pas:2012, Classes\vxModule.pas:2871, Classes\vxModule.pas:2948 - base module model, load/save, relation handling, and logging.
• Classes\vxActionMan.pas:299, Classes\vxActionMan.pas:1994, Classes\vxActionMan.pas:3004 - action manager module and execution.
• Classes\Service\vxManagerREST.pas:56, Classes\Service\vxManagerREST.pas:314, Classes\Service\vxManagerREST.pas:561, Classes\Service\vxManagerREST.pas:567 - REST endpoint synchronization and execution.
• Classes\vxAPI.pas:63, Classes\vxAPI.pas:262, Classes\vxAPI.pas:536, Classes\vxAPI.pas:916 - API module and OpenAPI export support.
• Classes\vxSetup.pas:16, Classes\vxSetup.pas:308, Classes\vxSetup.pas:749 - setup module and reload path.
• Classes\vxCon.pas:14, Classes\vxCon.pas:67, Classes\vxCon.pas:213 - system connection configuration.
• Classes\vxSQLConPool.pas:16, Classes\vxSQLConPool.pas:76, Classes\vxSQLConPool.pas:91 - SQL connection pool.
• Classes\Tools\vxConfigPath.pas:12, Classes\Tools\vxConfigPath.pas:155, Classes\Tools\vxConfigPath.pas:432, Classes\Tools\vxConfigPath.pas:433 - application data/configuration paths.

Overall Architecture

Velox is organized around three main runtime surfaces:

• Velox Designer - the desktop VCL application used to configure modules, actions, definitions, transports, reports, scripts, setup, and supporting objects.
• Velox Service - the Windows service runtime that executes background integration work through schedule, monitor, and transport managers.
• Velox API Service - the Windows service runtime that exposes configured API endpoints through an Indy/WebBroker HTTP server and dispatches requests through TvxRESTManager.

All three surfaces share the same core module architecture. The shared code loads configuration from a configured system database connection, uses persistent TvxModule descendants for major product concepts, and logs through Velox logging classes.

The repository does not show a separate microservice architecture. The major runtime boundaries are Delphi executable projects that share in-process libraries and communicate with the configuration database, file system, external transport endpoints, and each other through service management/IPC mechanisms.

Executable Projects

The project group VeloxGroup.groupproj contains the main executable projects.

Project	Entry point	Runtime type	Purpose
Velox Designer	Velox.dpr	VCL desktop application	Interactive configuration and operation of the Velox product. Creates the main form TMain from Forms\frmMain.pas.
Velox Service	VeloxService.dpr	Windows service application	Background runtime for schedules, monitors, inbound transports, and outbound transports. Creates TVeloxWorker from VeloxService\classMain.pas.
Velox API Service	VeloxAPIService.dpr	Windows service application	HTTP/API runtime backed by WebBroker and TvxRESTManager. Creates TVeloxAPIWorker from VeloxAPIService\classMain.pas.
Velox Test	VeloxTest.dpr	VCL test harness	Test/support executable that starts like a background/server runtime but creates a VCL main form. Exact operational role is not fully documented in code comments.

The project files include both Win32 and Win64 configuration. The codebase therefore needs to remain aware of 32-bit and 64-bit differences in pointer sizes, external DLL availability, COM/OLE DB provider availability, and filesystem/registry redirection. Detailed risk items are tracked in Technical Review TODO.

Shared Libraries

The shared runtime is primarily source-based rather than packaged as a separate Delphi package in this repository.

Area	Source location	Role
Core module model	Classes\vxModule.pas	Base module lifecycle, persistence, relationships, and logging integration.
Action/flow runtime	Classes\vxActionMan.pas and related action classes	Configured action managers and action items used to execute Velox flows.
Data definitions	Classes\vxDBDef.pas, Classes\vxFileDef.pas, related definition units	Database/file data definitions used by maps, actions, transports, and APIs.
Mapping	Classes\vxMap.pas	Data mapping module and execution.
Reporting	Classes\vxReport.pas	Report module based on ReportBuilder concepts.
API definition	Classes\vxAPI.pas	API module, API action items, and OpenAPI export support.
Service managers	Classes\Service\*.pas	Background managers for schedules, monitors, transports, REST/API execution, and related service work.
Transports	Classes\Transports\*.pas	Transport base classes and concrete transport implementations such as POP, SMTP, SFTP, MSMQ, IBM MQ, and others.
Configuration	Classes\vxSetup.pas, Classes\vxCon.pas, Classes\Tools\vxConfigPath.pas	Setup module, system connection loading, and application data paths.
Forms	Forms\*.pas	Designer UI forms for module configuration, logs, setup, templates, code libraries, XSD generation, and other workflows.
Vendor/modified libraries	Vendor\, Modified\	Third-party and locally modified libraries referenced by project search paths.

Key frameworks and libraries visible from project files and source references include:

• Delphi VCL and Windows service framework.
• A modified Vcl.SvcMgr under Modified\.
• FastMM5.
• madExcept.
• Midas/client dataset components.
• DevExpress VCL components.
• Indy and WebBroker.
• Devart/dbExpress SQL Server connectivity and OLE DB related configuration.
• ReportBuilder.
• RemObjects Pascal Script.
• NativeXML, MSXML, System.JSON, SuperObject, Neon JSON, and OpenAPI-Delphi.
• SecureBridge/SFTP and other transport-related libraries.
• Cromis IPC.
• SynEdit, VirtualTreeView, ChromeTabs, and HTML/Markdown viewing components.

The exact licensing and deployment requirements for each vendor library are not fully determinable from this architecture pass.

Startup Sequence

Designer Startup

The Designer startup sequence is defined in Velox.dpr.

Important source locations:

• Velox.dpr:58 sets IsDesigner := True.
• Velox.dpr:59 sets IsServer := False.
• Velox.dpr:60 sets IsBackground := False.
• Velox.dpr:65 calls Application.Initialize.
• Velox.dpr:92 loads gSystemConnection from the -c command-line parameter.
• Velox.dpr:110 calls CreateSystemLog.
• Velox.dpr:112 creates and loads gSetup.
• Velox.dpr:114 creates the TMain form.
• Velox.dpr:130 enters Application.Run.

Velox Service Startup

The worker service startup sequence is defined in VeloxService.dpr and VeloxService\classMain.pas.

Important source locations:

• VeloxService.dpr:42 sets IsDesigner := False.
• VeloxService.dpr:43 sets IsServer := True.
• VeloxService.dpr:44 sets IsBackground := True.
• VeloxService.dpr:50 calls Application.Initialize.
• VeloxService.dpr:56 loads gSystemConnection from the -c command-line parameter.
• VeloxService.dpr:61 calls CreateSystemLog.
• VeloxService.dpr:63 creates TVeloxWorker.
• VeloxService.dpr:64 enters Application.Run.
• VeloxService\classMain.pas:128 implements ServiceStart.
• VeloxService\classMain.pas:178 implements ServiceExecute.

VeloxService\classMain.pas comments state that ServiceStart and ServiceExecute run in TServiceThread, not the main thread. This is important for thread safety because manager creation, synchronization, IPC, logging, and shutdown coordination occur in service-thread context.

Velox API Service Startup

The API service startup sequence is defined in VeloxAPIService.dpr and VeloxAPIService\classMain.pas.

Important source locations:

• VeloxAPIService.dpr:47 sets IsDesigner := False.
• VeloxAPIService.dpr:48 sets IsServer := True.
• VeloxAPIService.dpr:49 sets IsBackground := True.
• VeloxAPIService.dpr:55 calls Application.Initialize.
• VeloxAPIService.dpr:61 loads gSystemConnection from the -c command-line parameter.
• VeloxAPIService.dpr:66 calls CreateSystemLog.
• VeloxAPIService.dpr:68 creates TVeloxAPIWorker.
• VeloxAPIService.dpr:69 enters Application.Run.
• VeloxAPIService\classMain.pas:212 creates gRESTManager.
• VeloxAPIService\classMain.pas:213 creates the TIdHTTPWebBrokerBridge instance.

Application Lifecycle

Common Lifecycle Pattern

The main executables follow a common lifecycle:

1. Set global runtime flags such as IsDesigner, IsServer, and IsBackground.
2. Initialize the Delphi application/service framework.
3. Load the system connection using gSystemConnection.Load(GetParamVal('c', True)).
4. Create the system log.
5. Create the primary runtime object or form.
6. Enter the VCL/service application loop.

This pattern is visible in Velox.dpr, VeloxService.dpr, VeloxAPIService.dpr, and VeloxTest.dpr.

Designer Lifecycle

The Designer creates the shared setup module before creating the main form:

• gSetup := TvxSetup.CreateAndLoad(nil) in Velox.dpr:112.
• Application.CreateForm(TMain, Main) in Velox.dpr:114.

The detailed UI lifecycle is centered on Forms\frmMain.pas. The main form is responsible for loading and presenting configuration, switching UI modes, and coordinating Designer workflows. The exact complete form initialization sequence should be read directly from Forms\frmMain.pas when making UI changes.

Worker Service Lifecycle

TVeloxWorker owns the background manager objects:

• FScheduleManager: TvxScheduleManager in VeloxService\classMain.pas:39.
• FMonitorManager in VeloxService\classMain.pas:40.
• FTransportManagerIn in VeloxService\classMain.pas:41.
• FTransportManagerOut in VeloxService\classMain.pas:42.

The service lifecycle includes:

• ServiceCreate for service object creation.
• ServiceStart for startup handling and IPC setup.
• ServiceExecute for runtime manager creation and synchronization.
• ServiceStop and ServiceStopShutdown for shutdown.

The exact manager loop behavior is implemented in the manager classes under Classes\Service\ and should be inspected there for changes to schedule, monitor, and transport execution semantics.

API Service Lifecycle

TVeloxAPIWorker owns:

• FWebServer: TIdHTTPWebBrokerBridge in VeloxAPIService\classMain.pas:39.
• Global REST manager creation in VeloxAPIService\classMain.pas:212.

The API service lifecycle includes:

• service creation/start/execute/stop methods in VeloxAPIService\classMain.pas;
• REST endpoint synchronization through TvxRESTManager.Synchronise;
• HTTP request dispatch through TRESTModule.WebModuleBeforeDispatch;
• request execution through gRESTManager.ExecuteAPIForEndpoint.

Runtime Architecture

The Velox runtime is module-centric. Major product concepts are implemented as descendants of TvxModule or related persistent classes. Modules are loaded from the configuration database, executed or edited by runtime components, and persisted back through module save/load methods.

Important module architecture classes:

• TvxModule in Classes\vxModule.pas:86.
• TvxActionMan in Classes\vxActionMan.pas:299.
• TvxDBDef in Classes\vxDBDef.pas:17.
• TvxFileDef in Classes\vxFileDef.pas:17.
• TvxMap in Classes\vxMap.pas:334.
• TvxReport in Classes\vxReport.pas:21.
• TvxAPI in Classes\vxAPI.pas:63.
• TvxTransport in Classes\Transports\vxTransport.pas:42.
• TvxSetup in Classes\vxSetup.pas:16.

Service Architecture

Velox Worker Service

The worker service coordinates background integration work through four manager fields on TVeloxWorker:

Manager	Source field	Role inferred from code names and usage
Schedule manager	FScheduleManager	Synchronizes and runs scheduled actions.
Monitor manager	FMonitorManager	Synchronizes and runs configured monitors.
Inbound transport manager	FTransportManagerIn	Synchronizes and runs inbound transport work.
Outbound transport manager	FTransportManagerOut	Synchronizes and runs outbound transport work.

VeloxService\classMain.pas:193 through VeloxService\classMain.pas:196 create these managers during service execution. Synchronization calls are visible later in ServiceExecute, including calls for schedule, monitor, inbound transport, and outbound transport managers.

Service IPC handling is implemented in TVeloxWorker.OnIPCExecuteRequest at VeloxService\classMain.pas:449. The full external IPC message contract is not completely described by this architecture pass; service code should be read before changing IPC commands.

Velox API Service

The API service hosts WebBroker through TIdHTTPWebBrokerBridge and dispatches requests to TvxRESTManager.

Important source locations:

• VeloxAPIService\classMain.pas:39 declares FWebServer.
• VeloxAPIService\classMain.pas:212 creates gRESTManager.
• VeloxAPIService\classMain.pas:213 creates TIdHTTPWebBrokerBridge.
• VeloxAPIService\vxWebModule.pas:50 handles WebModuleBeforeDispatch.
• VeloxAPIService\vxWebModule.pas:61 calls gRESTManager.ExecuteAPIForEndpoint.
• Classes\Service\vxManagerREST.pas:561 implements ExecuteAPIForEndpoint.

Classes\Service\vxManagerREST.pas:567 comments that ExecuteAPIForEndpoint is called from WebModuleBeforeDispatch and runs in the request thread. This is a key thread-safety concern for API endpoint execution and shared module access.

Communication Between Components

Velox components communicate through several mechanisms:

Mechanism	Participants	Source evidence	Notes
Configuration database	Designer, worker service, API service, modules	TvxModule.LoadModule, TvxModule.SaveModule, TvxSQLConPool, gSystemConnection	Primary persistent shared state.
IPC	Designer/service tooling and Windows services	VeloxService\classMain.pas:449, VeloxAPIService\classMain.pas:584	IPC handlers exist in both services. Full message schema is not fully described here.
HTTP	API clients and Velox API Service	VeloxAPIService\vxWebModule.pas, Classes\Service\vxManagerREST.pas	Requests route through WebBroker to TvxRESTManager.
Filesystem	Runtime, Designer, imports/exports, transports	Classes\Tools\vxConfigPath.pas, file definition/transport classes	Used for application data, config files, module templates, file transports, and import/export.
External transport protocols	Worker service and external systems	Classes\Transports\*.pas	Concrete protocol behavior depends on individual transport classes.
Logs	All runtimes and Designer log views	Classes\vxModule.pas, Forms\frmLogs.pas	Used for diagnostics and runtime traceability.

No message broker that globally coordinates all Velox components is evident in this source pass. Some transport modules may use queues such as MSMQ or IBM MQ for business integration traffic, but those are transport implementations rather than a universal internal bus.

Persistence Architecture

Velox persistence is centered on SQL-backed module storage plus structured serialization for module content, logs, and import/export formats.

Important persistence source locations:

• Classes\vxModule.pas:1483 - LoadModuleTemplate.
• Classes\vxModule.pas:1499 - SaveModuleTemplate.
• Classes\vxModule.pas:1510 - LoadModule.
• Classes\vxModule.pas:2012 - SaveModule.
• Classes\vxModule.pas:2871 - log save handling.
• Classes\vxModule.pas:2948 - log load handling.
• Classes\vxSQLConPool.pas:16 - SQL connection pool class.
• Classes\vxSQLConPool.pas:76 - global SQL connection pool.
• Classes\vxSQLConPool.pas:91 - connection acquisition.

The database schema itself is maintained outside this repository in the Velox data/database repositories. This document only describes the Delphi-side persistence architecture visible in the Velox source.

Serialization Formats

Serialization and data formats visible from source and project dependencies include:

• SQL/database persistence for modules, logs, setup, relations, and runtime configuration.
• JSON for configuration and API-related work, including Connections.json and API payload support.
• XML/XSD through XML libraries and XSD generation forms.
• ReportBuilder template serialization for report and module template behavior.
• File formats handled through file definitions and import/export code. Exact supported file formats depend on the specific TvxFileDef and related classes.
• OpenAPI schema export through TvxAPI.CreateOpenAPISchema and TvxAPI.ExportOpenAPISchema.

The exact physical database tables and all serialized field formats are not fully enumerated in this architecture document. Use module load/save methods and database scripts as the source of truth when table-level behavior matters.

Configuration Architecture

Configuration is layered:

1. Application data path - calculated by Classes\Tools\vxConfigPath.pas.
2. System connection selection - loaded by gSystemConnection.Load(GetParamVal('c', True)).
3. Setup module - loaded by TvxSetup.CreateAndLoad.
4. Runtime module configuration - loaded from the configuration database through module classes and managers.
5. Service-specific runtime state - loaded/synchronized by worker and API service managers.

Important source locations:

• Classes\Tools\vxConfigPath.pas:155 implements common app data folder resolution.
• Classes\Tools\vxConfigPath.pas:432 reads custom app data configuration.
• Classes\Tools\vxConfigPath.pas:433 assigns gAppDataPath.
• Classes\vxCon.pas:213 implements connection loading.
• Classes\vxSetup.pas:308 implements TvxSetup.CreateAndLoad.
• Classes\vxSetup.pas:749 implements setup reload.

Known related configuration:

• AppDataFolder.cfg is referenced by path configuration code.
• Connections.json is referenced by project documentation and connection-loading conventions.
• The -c command-line parameter selects the system connection used during startup.
• Install\ProgramData\install-veloxprogramdata\ is referenced in project guidance as the installed default ProgramData template, but installer behavior is outside this Velox-only architecture pass.

Plugin Architecture

No standalone external plugin package architecture was confirmed in this source pass.

The extensibility model visible in code is source/class based:

• Module types are implemented as Delphi classes derived from TvxModule or related base classes.
• Action behavior is implemented through TvxActionMan and action item classes.
• Transport behavior is implemented through TvxTransport descendants under Classes\Transports\.
• File definition behavior is implemented through TvxFileDef and related classes.
• API endpoint behavior is implemented through TvxAPI and TvxAPIActionItem.
• Scripting support is provided through Pascal Script imports and script-related classes.
• Classes are registered in units such as Classes\vxAPI.pas and concrete module/transport units.

If Velox has a deployment-time plugin model outside these source-level extension points, it was not found during this architecture update and should be treated as unclear until source evidence is identified.

Dependency Graph

The graph below shows the high-level dependency direction among the main executable projects, shared source areas, external libraries, and persistence/communication surfaces.

Practical dependency guidance:

• Most business/runtime changes will touch Classes\ first.
• Designer changes typically touch both Forms\ and Classes\.
• Service execution changes typically touch VeloxService\classMain.pas plus manager classes under Classes\Service\.
• API changes typically touch VeloxAPIService\, Classes\Service\vxManagerREST.pas, Classes\vxAPI.pas, and action/data modules.
• Changes to shared module classes can affect all three runtimes.

High-Level Data Flow

Background Integration Flow

The exact path depends on the configured action manager and action items. TvxActionMan.ExecuteOnce is implemented in Classes\vxActionMan.pas:1994.

API Request Flow

The REST manager comments state that API execution runs in the request thread. Any changes to API execution must account for concurrency, shared module state, database connection ownership, and logging synchronization.

Designer Configuration Flow

The exact synchronization path from Designer changes to running services is not fully documented in this pass. IPC handlers and manager Synchronise methods indicate that services can be instructed to refresh runtime state, but the full command contract should be confirmed from the relevant Designer and service code before modifying this flow.

Important Classes

Class	Source location	Architectural role
TvxModule	Classes\vxModule.pas	Base persistent module with load/save, relationship, and logging behavior.
TvxActionMan	Classes\vxActionMan.pas	Action manager/flow module used by schedules, monitors, transports, APIs, and Designer configuration.
TvxSetup	Classes\vxSetup.pas	Global setup module loaded by Designer and used by runtime code.
TvxConnection	Classes\vxCon.pas	System connection configuration object.
TvxSQLConPool	Classes\vxSQLConPool.pas	Shared SQL connection pooling abstraction.
TvxDBDef	Classes\vxDBDef.pas	Database definition module.
TvxFileDef	Classes\vxFileDef.pas	File definition module.
TvxMap	Classes\vxMap.pas	Mapping module.
TvxReport	Classes\vxReport.pas	Report module.
TvxAPI	Classes\vxAPI.pas	API module and OpenAPI-related behavior.
TvxAPIActionItem	Classes\vxAPI.pas	API endpoint/action item configuration.
TvxRESTManager	Classes\Service\vxManagerREST.pas	API service endpoint synchronization and HTTP request execution.
TvxTransport	Classes\Transports\vxTransport.pas	Transport base class.
TVeloxWorker	VeloxService\classMain.pas	Worker Windows service implementation.
TVeloxAPIWorker	VeloxAPIService\classMain.pas	API Windows service implementation.
TRESTModule	VeloxAPIService\vxWebModule.pas	WebBroker module that dispatches HTTP requests to gRESTManager.

Important Forms

Form	Source location	Architectural role
TMain	Forms\frmMain.pas	Main Velox Designer shell.
TSetupActions	Forms\frmSetupActions.pas	Main action/flow setup UI.
Ignored linked-action setup form	Forms\LinkedAction\frmSetupActions.pas	Trial/test/backup folder per repository guidance; not treated as active product architecture.
Log viewer	Forms\frmLogs.pas	Runtime log inspection and related operational actions.
XSD generation form	Forms\frmCreateXSD.pas	XSD generation workflow.
Config template importer	Forms\frmConfigTemplateImporter.pas	Configuration/template import and comparison workflow.
Module sync form	Forms\frmModuleSync.pas	Module synchronization workflow.
Usage/deletion safety form	Forms\frmCheckUsage.pas	Module usage checking workflow.
Code library form	Forms\frmCodeLibrary.pas	Code library/script support UI.

Several forms are strongly coupled to module classes and shared runtime state. Any UI change should be reviewed for side effects on module persistence and service synchronization.

Important Services

Service/runtime object	Source location	Purpose
TVeloxWorker	VeloxService\classMain.pas	Windows service host for scheduled, monitored, inbound transport, and outbound transport runtime work.
TVeloxAPIWorker	VeloxAPIService\classMain.pas	Windows service host for HTTP/API runtime.
TvxScheduleManager	Classes\Service\	Scheduled action runtime. Exact class file should be checked before schedule changes.
Monitor manager	Classes\Service\	Monitor runtime. Exact class file should be checked before monitor changes.
Inbound transport manager	Classes\Service\	Inbound transport runtime. Exact class file should be checked before transport changes.
Outbound transport manager	Classes\Service\	Outbound transport runtime. Exact class file should be checked before transport changes.
TvxRESTManager	Classes\Service\vxManagerREST.pas	API endpoint synchronization and request execution.

Related Configuration

Configuration	Source evidence	Notes
-c command-line parameter	Velox.dpr, VeloxService.dpr, VeloxAPIService.dpr	Selects the system connection loaded by gSystemConnection.
App data path	Classes\Tools\vxConfigPath.pas	Determines where shared runtime configuration is read from.
AppDataFolder.cfg	Classes\Tools\vxConfigPath.pas	Allows custom application data folder selection.
Connections.json	Classes\vxCon.pas and project conventions	Stores configured system connection details.
Setup module	Classes\vxSetup.pas	Product-level setup loaded from persistent configuration.
Database version/update logic	Classes\GUI\vxDBUpdate.pas, Classes\GUI\vxDBUpdateVersion.pas	Used by Designer/database update workflows. Exact upgrade behavior should be read from these classes.

Design Patterns

Major patterns visible in the repository:

• Module object model - business concepts are represented as persistent module classes.
• Class registration and streamed persistence - module/action/report/API classes are registered and loaded from stored configuration.
• Manager pattern - background runtime work is coordinated by service managers.
• Form-driven configuration - Designer forms edit module state and persist it to the configuration database.
• Connection pooling - SQL access is mediated through connection pool classes.
• Threaded service/request execution - Windows services run in service thread context, and API endpoint execution runs in HTTP request threads.
• Template/import-export pattern - modules and configuration can be serialized for import/export workflows.

Technical Debt and Stability Notes

The following architecture-level risks are important for future work:

• Shared global objects such as gSystemConnection, gSetup, gRESTManager, and shared pools require careful lifetime and thread-safety review.
• API execution runs in request threads. Any mutable shared state in modules, actions, logs, or endpoint caches must be treated as concurrency-sensitive.
• Worker service managers run in service thread context. Shutdown, synchronization, and manager reload behavior require careful testing.
• The project supports Win32 and Win64. Pointer casts, external libraries, COM/OLE DB providers, and third-party binaries must be checked for both platforms.
• The source tree includes modified and vendor libraries. Upgrades must account for local changes and deployment compatibility.
• The Designer, worker service, and API service share large portions of runtime code. A change that looks UI-only or service-only may affect other executables through shared classes.

Detailed risk items are tracked in Technical Review TODO.

Questions and Unclear Areas

The following items were not fully determinable from this architecture update:

• The complete IPC message schema between Designer/service tooling and the Windows services.
• Whether Velox has any external deployment-time plugin package model beyond source-level class/module extension points.
• The exact operational role and expected usage of VeloxTest.exe.
• The complete database schema and all physical persistence formats, which are maintained outside this repository.
• The precise startup behavior of every Designer form workflow; each form should be read directly before modifying that workflow.
• The complete deployment requirements for each third-party library and external provider.