Skip to main content

Velox Web Developer Guide

This guide is for developers joining the velox-web repository. This repository contains the current ASP.NET Core web front end that works from the VxData database.

Repository Layout​

  • velox.web.sln - Visual Studio solution for the web application.
  • velox.web\ - ASP.NET Core web application with Razor views, areas, controllers, filters, static assets, and startup in velox.web\Program.cs.
  • velox.data\ - EF Core contexts, identity models, data models, repositories, validation, and AutoMapper configuration.
  • velox.service\ - service layer over repositories and business workflows.
  • velox.common\ - shared models, exceptions, extensions, helpers, enums, repository bases, and context abstractions.
  • velox.external.addressfinder\ - AddressFinder integration.
  • velox.external.googleaddress\ - Google address integration.
  • velox.web.test\ - NUnit test project.
  • velox.web\Areas\Administration\ - administration UI and controllers.
  • velox.web\Areas\Transaction\ - transaction/user workflow UI and controllers.
  • velox.web\Areas\Api\ - API endpoints such as transaction upload/webhook routes.
  • velox.web\wwwroot\ - static assets.
  • velox.web\gulpfile.js and velox.web\package.json - frontend asset tooling.
  • vendor\ - vendor/client assets.
  • zUnneeded Code\ - inactive or historical code. Do not treat as production code unless explicitly asked.
  • velox-kb\VeloxPKB\docs\velox-web\ - PKB/developer documentation for this repository.

Build Process​

Prerequisites inferred from the repository:

  • Visual Studio 2022 or .NET SDK capable of building .NET 9 projects.
  • NuGet access to nuget.org.
  • DevExtreme/DevExpress package source configured by NuGet.config.
  • Node.js/npm if modifying frontend assets.

Build the .NET solution:

dotnet restore velox.web.sln
dotnet build velox.web.sln

Run the web app:

dotnet run --project velox.web\velox.web.csproj

The velox.web launch profile uses:

  • https://localhost:5001
  • http://localhost:5000
  • launch URL Transaction/Shipment

Frontend asset workflow:

cd velox.web
npm install
npx gulp build

The older root README.md mentions Node.js, DevExpress, Gulp, npm install, and gulp build. Prefer the actual project files when commands differ.

Debugging​

Debug the app from Visual Studio using the velox.web profile, or use dotnet run from the command line.

Important startup behavior:

  • velox.web\Program.cs is the active startup file.
  • Services are registered through module loading via AddModules().
  • DataModule registers VxConfigContext, VxDataContext, ASP.NET Identity, repositories, and AutoMapper.
  • Routes are mapped for areas, API routes, OAuth callbacks, and the default Transaction area route.
  • AppConfig:HomePageTransaction controls the default Transaction-area controller.

Configuration:

  • Connection strings are read from ConnectionStrings:VxConfig and ConnectionStrings:VxData.
  • Local appsettings.json may contain machine-specific values. Use local overrides or user secrets rather than adding real secrets.
  • Identity, email, address provider, cache, app, and layout settings are loaded from configuration.

When debugging data issues:

  1. Confirm whether the issue is in VxConfig or VxData.
  2. Check EF model mappings in velox.data\Context.
  3. Check repository/service behavior before changing controllers.
  4. Check matching SQL/schema in velox-data if the database shape is involved.

Coding Standards Inferred From The Project​

  • Follow existing ASP.NET Core MVC/Razor/Area patterns.
  • Keep controllers thin where service/repository layers already exist.
  • Use EF Core through the existing VxConfigContext and VxDataContext patterns.
  • Keep database schema changes in velox-data; do not invent migrations in this repository unless explicitly asked.
  • Preserve DevExtreme response/update patterns in grid-oriented controllers and repositories.
  • Treat client-supplied filenames, paths, headers, and upload bodies as untrusted.
  • Avoid .Result and .Wait() in request paths; prefer async all the way.
  • Do not enable EF Core sensitive data logging for production configuration.
  • Do not add third-party dependencies without approval.
  • Do not use zUnneeded Code as a source of production patterns unless the task explicitly targets it.

Typical Workflow​

For a UI/controller change:

  1. Identify the area: Administration, Transaction, API, OAuth, Identity, or shared layout.
  2. Read the controller, view, service, repository, and model involved.
  3. Preserve existing route and DevExtreme conventions.
  4. Make the smallest change that fits the existing pattern.
  5. Build velox.web.sln.
  6. Run the affected page or endpoint locally.
  7. Update user documentation in velox-kb if user-facing behavior changes.

For a data/repository change:

  1. Read the entity model and context mapping.
  2. Read the repository base class and matching concrete repository.
  3. Check service methods that wrap the repository.
  4. Confirm whether schema changes are needed in velox-data.
  5. Add or update tests in velox.web.test where practical.

For frontend assets:

  1. Work under velox.web\wwwroot or the existing asset source folders.
  2. Use the existing Gulp/npm toolchain.
  3. Build assets and verify generated CSS/JS output.

Common Pitfalls​

  • Root Program.cs, Startup.cs, and Program - Copy.cs are legacy/inactive relative to velox.web\Program.cs.
  • zUnneeded Code contains historical code and should not drive new implementation.
  • appsettings.json can contain local machine values and secrets; do not copy those into new environments.
  • Request/form limits are currently broad; be careful with upload endpoints and memory pressure.
  • Webhook upload handling touches both controller and service code.
  • EF context files are large and schema-coupled; changes may need coordination with velox-data.
  • The test project targets .NET 6 while the web app targets .NET 9; test compatibility should be checked before assuming all tests run cleanly.
  • DevExtreme package resolution depends on the configured local DevExpress package source.

Important Concepts​

VxConfig​

The configuration database contains Velox setup/configuration data used by services and the web app.

VxData​

The data database contains business transaction data that users review, search, and manage through the web app.

Areas​

The app uses ASP.NET Core Areas to separate Administration, Transaction, API, OAuth, and Identity workflows.

Repository And Service Layers​

Repositories encapsulate EF Core access. Services expose business operations to controllers and components.

DevExtreme​

Many list/detail workflows are built around DevExtreme data loading, grid updates, and validation patterns.

Webhook Uploads​

API upload endpoints receive external payloads and write files for Velox processing. Treat all caller-provided metadata as unsafe until validated.

Unclear Areas​

  • The planned replacement path for this web app with Angular or React is not fully described in this repository.
  • The intended production secret-management approach is unclear from static review.
  • The complete test run status is unclear without executing the solution in a configured development environment.