DevUtilityHub — Technical Reference

This is the technical companion to the Functional Reference. It covers the architecture, every API contract, the frontend structure, testing approach, and the CI/CD pipeline that ships both services.

Architecture

The backend follows a strict three-layer pattern. Each layer has one job and no knowledge of the layers above it.

Technology Stack

Backend

Frontend

API Reference

All endpoints accept and return application/json. Every response body includes two common fields:

• isValid: boolean — whether the operation succeeded
• errorMessage: string | null — parse or validation error detail; null on success

A 500 response always returns { "error": "An unexpected error occurred." }. The detail field is only appended in the Development environment.

The max request body size is 1 MB. Larger payloads receive a 413.

Health check

No request body. Used by the frontend’s ApiStatusContext on mount and by Azure App Service health probes.

{ "status": "ok" }

Format / Minify / Validate

{
  "input":        "string   — text to process",
  "action":       "\"format\" | \"minify\" | \"validate\"",
  "overrideType": "\"json\" | \"xml\" | \"plain\"   (optional)"
}

{
  "output":       "string   — transformed text (same as input for validate)",
  "detectedType": "\"json\" | \"xml\" | \"plain\"",
  "isValid":      "boolean",
  "errorMessage": "string | null"
}

Detection order: JSON parse → XML parse → plain text fallback. overrideType skips this sequence entirely.

Text Transform

{
  "input":      "string",
  "operations": ["trim", "uppercase", "sort"]
}

{
  "output":            "string",
  "appliedOperations": ["trim", "uppercase", "sort"],
  "isValid":           "boolean",
  "errorMessage":      "string | null"
}

Operations run sequentially in the order provided. appliedOperations in the response reflects exactly what was executed — the UI displays this as a pipeline tag list.

Diff

{
  "textA": "string   — original",
  "textB": "string   — modified"
}

{
  "lines": [
    {
      "type":       "\"added\" | \"removed\" | \"unchanged\"",
      "content":    "string",
      "lineNumber": 1
    }
  ],
  "addedCount":   "integer",
  "removedCount": "integer",
  "isValid":      "boolean",
  "errorMessage": "string | null"
}

Powered by DiffPlex (InlineDiffBuilder in word-diff mode, line granularity). lineNumber is 1-indexed and represents position in the diff output, not in either source text. Empty inputs return an empty lines array with counts of 0.

Timestamp Convert

{
  "direction":      "\"toHuman\" | \"toUnix\"",
  "unixValue":      "integer | null   — required when direction = \"toHuman\"",
  "isMilliseconds": "boolean          — true if unixValue is in ms (default: false)",
  "humanValue":     "string  | null   — required when direction = \"toUnix\"",
  "timeZoneId":     "string  | null   — IANA timezone ID, e.g. \"America/New_York\""
}

{
  "seconds":      "integer",
  "ms":           "integer",
  "utc":          "string   — RFC 2822, e.g. \"Wed, 15 Nov 2023 06:13:20 GMT\"",
  "iso":          "string   — ISO 8601, e.g. \"2023-11-15T06:13:20.0000000Z\"",
  "local":        "string | null   — offset-aware, null if no timeZoneId given",
  "isValid":      "boolean",
  "errorMessage": "string | null"
}

humanValue accepts: ISO 8601, YYYY-MM-DD HH:mm, YYYY-MM-DD, MM/DD/YYYY, the shorthands now / today / yesterday / tomorrow, and natural-language expressions via Microsoft.Recognizers.Text.DateTime (e.g. "next Monday", "3 days ago").

Encode / Decode

{
  "input":     "string",
  "operation": "\"encode\" | \"decode\"",
  "encoding":  "\"base64\" | \"url\" | \"html\""
}

Frontend Architecture

Pages and routes

useApi<T> — shared async state hook

Every page goes through this single hook:

const { data, loading, error, call, reset } = useApi<DiffResponse>();

// Trigger a call:
await call(() => diffApi.compare({ textA, textB }));

call sets loading: true, awaits the promise, then sets either data or error. It also notifies ApiStatusContext of the outcome so the connection indicator in the header stays current.

ApiStatusContext

API client modules

Each tool has a dedicated module in src/api/. All share one Axios instance configured in src/api/client.ts:

export const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  headers: { "Content-Type": "application/json" },
});

VITE_API_BASE_URL is the only environment variable the frontend needs.

Data Flow

A worked example — user formats a JSON string:

User types JSON → clicks PRETTIFY
        │
        ▼
FormatterPage.tsx
  collects { input, action: "format" }
  calls formatApi.process(request)
        │
        ▼
src/api/client.ts  [Axios]
  POST /api/format/process   →   FormatController.cs
        │
        ▼
FormatController.cs
  [HttpPost("process")]
  delegates to _formatService.Process(request)
        │
        ▼
FormatService.cs
  InputTypeDetector.Detect(input)  →  "json"
  JsonFormatter.Format(input)       →  pretty-printed string
  returns FormatResponse { output, detectedType: "json", isValid: true }
        │
        ▼
HTTP 200  { output: "...", detectedType: "json", isValid: true }
        │
        ▼
useApi sets data  →  FormatterPage renders output in the right pane

Configuration & Environment

Backend

No secrets in config files. All configuration is through environment variables set on the host or in Azure App Service application settings.

CORS allowed origins are hardcoded in Program.cs:

• https://devtoolkit.nikkapaola.com (production frontend)
• http://localhost:5173 (local Vite dev server)

Frontend

Testing

Unit tests target the Core layer directly. No HTTP context, no DI container, no mocks — just function calls.

The test project at backend/DevUtilityHub.Tests/ mirrors the Core module structure. Services are also tested where orchestration logic warrants it.

cd backend
dotnet test

CI/CD & Deployment

Two independent GitHub Actions workflows, each scoped to its own directory path. Neither workflow runs if only the other service changed.

Frontend → Cloudflare Pages

Workflow: .github/workflows/deploy-frontend.yml
Trigger: Push to main with changes in frontend/**, or manual dispatch.

1. Checkout
2. Node 20 setup (npm cache)
3. npm ci
4. npm run build   ← VITE_API_BASE_URL injected from GitHub secret
5. cloudflare/pages-action@v1  →  deploys dist/

Backend → Azure App Service

Workflow: .github/workflows/deploy-backend.yml
Trigger: Push to main with changes in backend/**, or manual dispatch.

Two jobs run sequentially:

Job 1: build-and-test

dotnet restore
dotnet build --configuration Release
dotnet test

Job 2: build-and-deploy (only runs if tests pass)

dotnet publish --configuration Release --runtime linux-x64 --self-contained
azure/login@v2
azure/webapps-deploy@v3  →  App Service: dev-utility-hub-api

The publish is --self-contained so no .NET runtime is required on the host. The App Service plan is Azure Free F1 — this is why Docker is not used in production; F1 does not support container deployment.

Docker

Docker is available for local development only. The Dockerfile lives at backend/DevUtilityHub.Api/Dockerfile.

# Build and run production image locally
docker build -t devutilityhub-api ./backend/DevUtilityHub.Api
docker run -p 5294:8080 -e ASPNETCORE_ENVIRONMENT=Development devutilityhub-api

A docker-compose.debug.yml at the repo root maps localhost:5294 → 8080 (API) and localhost:4024 → 4024 (VS Code remote debugger) for integrated debugging:

docker compose -f docker-compose.debug.yml up