Skip to main content

Velox Web Architecture

This document is based on source inspection of the velox-web repository. Where behavior is not clear from source, it is marked as unclear.

Overall Architecture​

velox-web is an ASP.NET Core web portal over the VxData database. It provides user interaction with integration data, especially transaction review and administration screens, and exposes a small webhook/file API surface.

The application follows a layered architecture:

  • velox.web: ASP.NET Core MVC/Razor UI and API controllers.
  • velox.service: business services and external calls, including Velox API/flow calls.
  • velox.data: EF Core DbContexts, entity models, repositories, data models, Identity models, validation, and AutoMapper profiles.
  • velox.common: shared configuration, context, repository base types, extensions, exceptions, helpers, and abstractions.
  • velox.external.addressfinder and velox.external.googleaddress: external address lookup integrations.

The active web host appears to be velox.web\Program.cs. The root-level Program.cs and Startup.cs are older/alternate host files; they are not referenced by velox.web\velox.web.csproj and their runtime status is unclear.

Solution and Project Structure​

Main solution: velox.web.sln.

Projects:

  • velox.web: ASP.NET Core MVC web application targeting net9.0.
  • velox.data: EF Core SQL Server data access and repository layer.
  • velox.service: business services and pipelines.
  • velox.common: shared infrastructure and configuration.
  • velox.external.addressfinder: AddressFinder integration.
  • velox.external.googleaddress: Google address integration.
  • velox.web.test: test project. Test coverage scope was not inspected in depth.

Major velox.web folders:

  • Areas\Transaction: transaction user workflows, including shipment UI.
  • Areas\Administration: admin/config/reference-data screens.
  • Areas\Dashboard: dashboard/search/system-log screens.
  • Areas\Identity: login/register/reset-password screens.
  • Areas\Api: webhook/file API endpoints.
  • Views\_Shared and wwwroot: layout, static assets, JS/CSS/images/fonts.

Startup Sequence​

Active startup sequence in velox.web\Program.cs:

  1. Create a WebApplicationBuilder.
  2. Bind LayoutConfig from configuration.
  3. Call AddModules() to register repository/service/config modules by reflection.
  4. Add memory cache.
  5. Add ASP.NET session with a .VeloxWeb.Session cookie and 12-hour idle timeout.
  6. Add HttpClient.
  7. Add Razor Pages with JSON property naming policy disabled for DevExtreme compatibility.
  8. Add MVC controllers/views with AppInitFilter.
  9. Add endpoint API explorer, Swagger, and OpenAPI.
  10. Increase form and multipart limits to int.MaxValue.
  11. Configure cookie paths and 12-hour cookie expiry.
  12. Build the app.
  13. Configure development exception page or production exception/status-code handlers.
  14. Enable HTTPS redirection and static files.
  15. Map OpenAPI and Swagger UI.
  16. Enable routing, authentication, authorization, and session.
  17. Read AppConfig:HomePageTransaction, defaulting to Home if missing.
  18. Map static assets.
  19. Map area routes, API route, OAuth route, and default Transaction-area route.
  20. Run the web host.

Purpose of Each Major Project​

  • velox.web: user-facing MVC portal, Razor views, controllers, API endpoints, layouts, static assets, and app startup.
  • velox.data: SQL Server data model and persistence; owns VxDataContext, VxConfigContext, repositories, Identity models, and data models.
  • velox.service: business/service layer that coordinates repositories, mapping, web hook handling, shipment workflows, account operations, and Velox API/flow calls.
  • velox.common: shared abstractions and infrastructure used by all layers.
  • External provider projects: address lookup service adapters.
  • velox.web.test: tests. The active test strategy is unclear.

Key Frameworks and Libraries​

Visible frameworks and packages include:

  • ASP.NET Core MVC/Razor targeting .NET 9.
  • Entity Framework Core SQL Server.
  • ASP.NET Core Identity.
  • AutoMapper and AutoMapper.Collection.
  • DevExtreme ASP.NET Core/Data.
  • Swashbuckle/OpenAPI.
  • Newtonsoft.Json.
  • Microsoft.AspNet.OData.
  • MailKit/NETCore.MailKit.
  • Azure Key Vault configuration packages.
  • AddressFinder and Google address APIs through local integration projects.
  • TypeScript tooling and static frontend assets.

Configuration Loading​

Configuration is mainly loaded from velox.web\appsettings.json and appsettings.Development.json.

Configuration sections include:

  • ConnectionStrings: VxConfig and VxData.
  • EmailConfig: SMTP/mail settings.
  • CacheConfig: cache durations.
  • AddressFinderConfig and GoogleAddressConfig: address provider settings.
  • AppConfig: application number, admin-only mode, and default home controllers per area.
  • LayoutConfig: layout, direction, theme, footer text, and background count.

velox.common contains a Key Vault configuration extension, but no active call to that extension was found in the inspected active velox.web\Program.cs.

Sensitive-looking values are present in local appsettings files. They are not reproduced in this document.

Dependency registration uses the reflection-based AddModules() extension:

  • It scans solution assemblies for classes implementing IServiceCollectionModule.
  • DataModule registers repositories, EF Core contexts, Identity, claims transformation, and AutoMapper.
  • ServiceModule registers services and pipeline types.
  • PortalModule registers web AutoMapper profiles.
  • External provider modules register provider services and HttpClient.
  • ConfigurationModule registers configuration classes.

Logging​

The web project uses ASP.NET Core logging via injected ILogger<T> in controllers, services, and repositories.

Configuration sets logging levels under the Logging section. No custom logging provider setup was found in the active velox.web\Program.cs.

Database log data is visible through config/log models and repositories such as VxLogRepository, but the web application's runtime logging pipeline is not the same as Velox flow/system logging.

Database Access Architecture​

velox.data provides two EF Core contexts:

  • VxDataContext: VxData business/user/transaction database, also used as the ASP.NET Identity store.
  • VxConfigContext: Velox config/log-style database tables such as VX_ACTION, VX_SETUP, VX_LOG, VX_MAP, VX_REPORT, and related module tables.

DataModule configures both contexts with SQL Server connection strings from IDBConfig, and enables EF sensitive data logging.

The persistence pattern is:

  • EF Core entities model database tables.
  • Repository classes wrap entity access and authorization checks.
  • Service classes orchestrate repository calls and business operations.
  • AutoMapper maps EF entities to web/data models.
  • DevExtreme repository base classes return LoadResult data for grid endpoints.

AppInitFilter runs before controller actions and stores the current user's UserNum and UserRole on VxDataContext. Repositories use those values for authorization, for example checking whether a user is associated with parties on a shipment.

Plugin/Module Architecture​

The web application has an internal module-registration architecture rather than runtime plugins.

AddModules() discovers all classes implementing IServiceCollectionModule across solution assemblies and calls Load(IServiceCollection) on each. This gives each project a local place to register its services without one central startup file knowing every type.

This is dependency-injection modularity, not a customer/plugin extension system.

Flow Execution Architecture​

velox-web does not run Velox flows itself.

It can call Velox API/flow endpoints through IVeloxApiService:

  • VeloxApiService loads host/port settings such as VWSHost and VWSPort from the Setting service.
  • It looks up a VeloxFlow record by code.
  • It calls the Velox API service over HTTP using endpoints such as Flow/<ActionFid>?Num=<ids>.
  • Shipment printing and flow execution use this service path.

The webhook/file API in Areas\Api\Controllers\TransactionController.cs accepts uploads/download/list/update calls, authenticates bearer tokens through IUserService, writes files using IWebHookService, and reads status/files through IWebHookFileService.

The actual Velox flow execution engine is in the Delphi velox repository.

Serialization Formats​

Visible formats include:

  • JSON appsettings, OpenAPI output, package files, and API payloads.
  • Razor .cshtml views.
  • C# source.
  • SQL Server data through EF Core.
  • Static JS/CSS/fonts/images.
  • XML web.config in published payloads.
  • NuGet config.

DevExtreme requires JSON property naming behavior that preserves model property names.

Major Design Patterns Used​

  • Layered web/service/data/common architecture.
  • MVC Areas for feature grouping.
  • Repository and service layers over EF Core.
  • Reflection-based module registration.
  • AutoMapper projection/mapping.
  • DevExtreme data-source endpoint pattern.
  • Request filter for request/user context injection into DbContext.
  • ASP.NET Identity for authentication.
  • HTTP adapter service for calls into Velox API/flow execution.

Areas of Technical Debt​

  • Sensitive-looking config values are stored in appsettings files.
  • DataModule enables EF sensitive data logging.
  • Root Program.cs and Startup.cs appear to be older/duplicate startup code, creating ambiguity.
  • The active Key Vault configuration extension exists but does not appear wired into active startup.
  • velox.web.csproj explicitly removes several folders from compilation/content, suggesting leftover or excluded code.
  • Form/multipart limits are set to int.MaxValue, which may be risky without upstream controls.
  • Some service comments and TODOs indicate unfinished refactors, for example typed/named HTTP clients and custom shipment number behavior.

Questions About the Architecture​

  • Is velox.web\Program.cs definitively the only supported startup path?
  • Should appsettings secrets move to Key Vault or deployment-time configuration?
  • Which Areas are production-ready versus experimental?
  • What is the expected lifecycle of VeloxFlow records relative to Delphi Velox action FIDs?
  • How should the portal handle Velox API service unavailability beyond current error/null handling?