Skip to main content

Velox Web2 Developer Guide

This guide is for developers joining the velox-web2 repository. This repository is an Aspire/.NET front end to VeloxAPIService, with database-driven API route mapping and OpenAPI/Swagger/Scalar presentation.

Repository Layout​

  • Velox.sln - Visual Studio solution.
  • Velox.AppHost\ - .NET Aspire app host. Entry point is Velox.AppHost\AppHost.cs.
  • Velox.ServiceDefaults\ - shared Aspire service defaults, health checks, service discovery, resilience, and OpenTelemetry setup.
  • Velox.ApiService\ - ASP.NET Core API service. This is the main product-specific project.
  • Velox.ApiService\Program.cs - API startup, EF Core setup, OpenAPI/Scalar/Swagger setup, and database-driven route mapping.
  • Velox.ApiService\Endpoints\VeloxAPI.cs - proxy forwarding to the Delphi VeloxAPIService.
  • Velox.ApiService\Service\UserService.cs - bearer token lookup/auth helper.
  • Velox.ApiService\DBContext\ - EF Core contexts for VxConfig and VxData.
  • Velox.ApiService\ModelConfig\ - EF models for Velox configuration database tables.
  • Velox.ApiService\ModelData\ - EF models for VxData tables.
  • Velox.ApiService\wwwroot\openapi\ - OpenAPI JSON documents served by dynamic docs endpoints.
  • Velox.Web\ - Blazor web front end.
  • velox-kb\VeloxPKB\docs\velox-web2\ - PKB/developer documentation for this repository.

Build Process​

Prerequisites inferred from the repository:

  • Visual Studio 2022 with .NET 9 support.
  • .NET Aspire workload/support for the AppHost project.
  • SQL Server access for the configured VxConfig and VxData connection strings.
  • A reachable Delphi VeloxAPIService when testing proxy behavior.

Build the solution:

dotnet restore Velox.sln
dotnet build Velox.sln

Run the Aspire app host:

dotnet run --project Velox.AppHost\Velox.AppHost.csproj

Run the API service directly:

dotnet run --project Velox.ApiService\Velox.ApiService.csproj

Run the Blazor web project directly:

dotnet run --project Velox.Web\Velox.Web.csproj

Launch settings expose local HTTP/HTTPS endpoints for the AppHost, API service, and web project. Prefer AppHost when testing service discovery and full local composition.

Debugging​

AppHost​

Velox.AppHost\AppHost.cs starts:

  • Velox.ApiService as resource name api
  • Velox.Web as resource name web

The web project waits for the API service and references it through Aspire service discovery.

ApiService​

Velox.ApiService\Program.cs performs several startup-sensitive operations:

  • configures service defaults and Problem Details
  • registers VxConfigContext and VxDataContext
  • registers named HttpClient proxy
  • loads setup/API/action data from the configuration database
  • maps OpenAPI document endpoints from database rows
  • maps Swagger UI and Scalar API reference
  • maps dynamic proxy endpoints from database action configuration

If the service fails on startup, first check:

  1. ConnectionStrings:VxConfig
  2. ConnectionStrings:VxData
  3. required rows in VxSetup
  4. active VxApi and VxApiAction rows
  5. route values such as API production URL and REST endpoint
  6. availability of OpenAPI JSON files under wwwroot\openapi

Proxy Debugging​

Dynamic endpoints forward requests to the Delphi VeloxAPIService through ProxyEndpoint.ProxyVeloxAPIService.

When debugging proxy issues:

  • Confirm the upstream VeloxAPIService address from setup/config data.
  • Confirm the mapped local route printed/logged at startup.
  • Check bearer token handling in UserService.
  • Check forwarded headers and X-UserNum behavior.
  • Test large request/response bodies for streaming behavior.
  • Check timeout behavior on the named proxy HttpClient.

Coding Standards Inferred From The Project​

  • Use .NET 9 and modern ASP.NET Core minimal API patterns already present in the project.
  • Keep Aspire service defaults centralized in Velox.ServiceDefaults.
  • Keep database access through scoped EF Core contexts.
  • Do not capture scoped contexts in singleton services.
  • Do not enable EF Core sensitive data logging for production configuration.
  • Treat database-driven route configuration as startup-critical.
  • Validate empty, invalid, duplicate, or conflicting route values when changing dynamic endpoint mapping.
  • Do not downgrade HTTPS or broaden proxy header forwarding unless explicitly scoped to local development and guarded by configuration.
  • Treat identity headers as trusted only between controlled server-side components.
  • Do not add third-party dependencies without approval.

Typical Workflow​

For API route/proxy work:

  1. Read Velox.ApiService\Program.cs.
  2. Read Velox.ApiService\Endpoints\VeloxAPI.cs.
  3. Check relevant EF models under ModelConfig.
  4. Confirm how the route is represented in the VxConfig database.
  5. Validate route construction with realistic database values.
  6. Run through AppHost if service discovery or web integration is involved.
  7. Test against a running Delphi VeloxAPIService.

For OpenAPI documentation work:

  1. Check OpenAPI document names in VxConfig.
  2. Check files under Velox.ApiService\wwwroot\openapi.
  3. Test /openapi/{schemaName}.
  4. Test Swagger UI and Scalar.

For Blazor work:

  1. Work under Velox.Web.
  2. Keep service discovery references aligned with AppHost.
  3. Run through AppHost before assuming the full local experience works.

Common Pitfalls​

  • Velox.AppHost uses AppHost.cs, not Program.cs.
  • ApiService route mapping depends on live database rows during startup.
  • Missing VxSetup rows or invalid API/action rows can stop the API from starting.
  • UrlHelpers.GetLastSegment can hide invalid URL values by returning an empty segment.
  • Proxy behavior currently includes local-development assumptions; do not promote those to production without review.
  • OpenAPI documents must exist under wwwroot\openapi for the mapped docs endpoints to work.
  • Sensitive EF logging is currently present in code paths; production behavior should be guarded before deployment.
  • The Blazor project still appears lightweight/template-like compared with the API service.

Important Concepts​

Aspire AppHost​

The AppHost composes local services and provides service discovery, health checks, and dashboard-style development support.

ApiService​

The API service is the bridge between public/API documentation endpoints and the Delphi VeloxAPIService.

Database-Driven Routes​

Routes are loaded from Velox configuration database rows at startup. Changes to database route configuration are not automatically live unless the service restarts or reload behavior is added.

ProxyEndpoint​

The proxy endpoint forwards mapped HTTP requests to the Delphi upstream service and injects server-side identity context.

Scalar And Swagger​

The API service exposes OpenAPI documentation through Scalar and Swagger UI, using OpenAPI JSON files and API metadata from the database.

VxConfig And VxData​

VxConfig provides Velox configuration and API route metadata. VxData provides user/data context such as bearer-token user lookup.

Unclear Areas​

  • The final relationship between velox-web2 and velox-web is unclear.
  • Whether dynamic routes should reload without service restart is unclear.
  • The production TLS/proxy/header policy is not fully settled in this repository.
  • The final authentication contract for invalid or expired bearer tokens is unclear.