The-transit-Project/monitoring_ui/docs/MONITORING_UI.md

Transit Control Room

monitoring_ui is a React + Vite operations dashboard for the XTransit service group. It gives an operator one place to answer four questions:

1. Are the services reachable right now?
2. What kind of data does each service provide?
3. Which errors and bad requests have been recorded?
4. Can I safely inspect a real API response without building a curl command by hand?

The dashboard is a browser-only application. It does not introduce a database, server-side session store, or monitoring proxy. Requests go directly from the browser to the configured services.

1. What It Monitors

Surface	Default URL	Health request	Purpose
Auth API	http://localhost:5000	GET /me	Login, JWT sessions, and current-user information
Employee API	https://employees.xtransit.testinstance.nl	GET /health	Employee onboarding and employee records
Transit API	http://localhost:5001	GET /health	Schedules, routes, GPS, fleet, and administration
Error Log API	http://localhost:5003	GET /health	Centralized service errors and bad requests
Admin UI	http://localhost:5174	GET /health	Availability of the deployed React administration console

The URLs are development defaults only. For a deployed dashboard, use the Connections screen or build-time VITE_* variables.

Health semantics

• healthy: the request returned a successful HTTP status.
• degraded: the service answered, but returned a non-success status such as 401, 403, or 503.
• offline: the browser could not establish a response, usually because the service is stopped, the URL is wrong, TLS failed, or CORS blocked the request.
• checking: the first poll has not completed yet.

The Auth API uses /me because it does not currently expose a public /health endpoint. Without a JWT this normally appears as degraded, not as a broken service. Add a token in Connections when an authenticated Auth API signal is required.

Transit health includes database reachability. Employee health currently confirms process reachability only. Admin UI health is supplied by the nginx configuration in admin_ui/nginx.conf and returns a small JSON document.

2. Features

Overview

The Overview tab contains one card per monitored surface. Each card shows:

• current status;
• response time for the latest poll;
• a compact latency history from recent polls;
• the returned health payload.

The top-level pulse shows how many surfaces are healthy and the average latency across completed checks. Polling can be set to 15 seconds, 30 seconds, or one minute.

Service catalog

The Service catalog is a human-readable map of the data each service serves. It is deliberately maintained as a small allowlisted catalog rather than attempting to discover every Express route at runtime. This keeps the dashboard understandable and avoids exposing internal routes or implementation details.

Errors and bad requests

The Errors & bad requests tab reads:

GET /error_log?limit=80
Authorization: Bearer <admin-jwt>

The Error Log API restricts this endpoint to administrator tokens. The dashboard displays timestamp, service, route or sub-service, and normalized error text. The dashboard does not write new logs itself; the existing APIs already report their failures to error_log_api.

If the token is missing, the dashboard explains how to configure it. If the token is expired or not an administrator token, the API response is shown as a load failure rather than silently displaying an empty incident list.

Request lab

The Request lab executes only known routes listed in testerRoutes inside monitoring_ui/src/App.jsx. It supports representative calls for:

• Auth API current-session inspection;
• Employee API health;
• Transit API health;
• public schedule progress;
• driver daily schedule;
• recent Error Log API entries.

The selected service, method, and path determine the destination. An optional JSON body can be entered for future write routes. Non-GET requests require a browser confirmation before execution.

This is an operator diagnostic tool, not a general-purpose arbitrary URL proxy. Keep the allowlist intentionally narrow when adding routes.

Connections

The Connections tab edits the five service base URLs and the optional admin JWT. Values are stored in localStorage under:

• transit-monitor-urls
• transit-monitor-token

This makes local experimentation convenient, but it also means the token is readable by JavaScript running on the same origin. Use the dashboard only in a trusted browser profile and do not use it on a shared workstation with untrusted browser extensions.

3. Local Development

cd monitoring_ui
npm install
npm run dev

Open the URL printed by Vite, normally http://localhost:5173.

Build and preview the production bundle:

npm run build
npm run preview

The app uses React 18 and Vite 5, matching the existing admin UI's frontend generation approach. Its main files are:

monitoring_ui/
├── index.html          browser entry point
├── package.json        scripts and dependencies
├── vite.config.mjs     Vite React configuration
├── src/
│   ├── main.jsx        React bootstrap
│   ├── App.jsx         service model, polling, tabs, request lab
│   └── styles.css      responsive control-room styling
└── README.md           short navigation pointer

4. Configuration

Build-time environment variables

Create monitoring_ui/.env.local for a deployed or non-default environment:

VITE_AUTH_API=https://auth.example.test
VITE_EMPLOYEE_API=https://employees.xtransit.testinstance.nl
VITE_TRANSIT_API=https://transit.example.test
VITE_ERROR_LOG_API=https://error.example.test
VITE_ADMIN_UI=https://admin.example.test

Vite reads these variables when the app is built. They are not secrets. Do not put JWTs, database passwords, signing keys, or API credentials in .env.local values that will be shipped to the browser.

The Connections screen is useful when the same build needs to point at different environments. Its values override the initial defaults in the current browser only.

CORS requirements

Because the dashboard calls services directly, every monitored API must allow the dashboard origin. The existing Auth, Transit, and Error Log services already expose permissive CORS middleware. Employee API has matching browser CORS middleware in employee_api/index.js.

For production, replace wildcard CORS with an explicit dashboard origin where practical. At minimum, allow:

• GET, POST, OPTIONS, and any methods used by approved tester routes;
• Content-Type;
• Authorization.

If the browser console reports a refused connection but direct curl succeeds, check CORS before changing the dashboard code.

5. Authentication and Security

The dashboard does not implement a second login system. It accepts a JWT created by the existing Auth API. Obtain a token through the normal admin login flow, then paste it into Connections.

The Error Log API verifies both JWT validity and the isAdmin claim. A valid non-admin token is not sufficient to read centralized errors.

Operational safeguards:

• never commit .env.local or copied tokens;
• avoid putting production JWTs in screenshots, issue reports, or browser history;
• keep the request lab allowlist small;
• require confirmation for all mutating requests;
• prefer read-only routes for routine diagnostics;
• use HTTPS for deployed APIs and dashboard access;
• restrict CORS to known origins in production;
• consider moving token handling to an authenticated same-origin backend if the dashboard becomes a multi-user production console.

6. Deployment Options

Static hosting

The dashboard can be hosted as static files from any web server that supports SPA fallback to index.html. Build it with:

npm run build

Publish monitoring_ui/dist. Configure the web server to serve index.html for unknown application paths. The current dashboard uses client-side tab state and does not require route rewrites beyond the root page, but SPA fallback remains a sensible default.

Container hosting

The repository includes a Node build stage followed by nginx in monitoring_ui/Dockerfile. Runtime configuration is written to env-config.js by monitoring_ui/docker-entrypoint.sh, so the same image can be promoted between environments without baking service URLs into the JavaScript bundle.

The root Compose stack deploys this image as monitoring_ui on host port 5175. Set these Compose variables when deploying:

AUTH_API=https://auth.xtransit.testinstance.nl
EMPLOYEE_API=https://employees.xtransit.testinstance.nl
TRANSIT_API=https://transit.xtransit.testinstance.nl
ERROR_LOG_API=https://error.xtransit.testinstance.nl
ADMIN_UI=https://admin.xtransit.testinstance.nl

The Gitea workflow detects changes under monitoring_ui/**, builds monitoring_ui/Dockerfile, and pushes the image as monitoring_ui:<branch> and monitoring_ui:<commit>. The dev branch includes the image in the Portainer redeploy dependency chain.

Reverse proxy

A reverse proxy can place the dashboard and service domains behind one TLS boundary. This is often preferable for production because it simplifies CORS and gives operators a single origin. It is not required for local development.

7. Troubleshooting

All cards show offline

1. Check that the API processes are running.
2. Check the URL in Connections, including protocol and port.
3. Open the health URL directly in a browser or use curl.
4. Inspect the browser console for CORS or TLS errors.
5. Confirm that Docker port mappings match docker-compose.yml.

Auth API shows degraded

GET /me requires a bearer token. Paste a current admin JWT into Connections. A 401 means the API answered and is reachable, but the supplied token is absent or invalid.

Error list is empty

An empty list can mean either that no errors were returned or that the request was not authorized. Check the Errors tab status text and verify that the token has isAdmin: true. The Error Log API also requires its database table data.errors to exist.

Employee API cannot be called from the dashboard

Check that the deployed image includes the CORS middleware from employee_api/index.js. A stale container image may still be running an earlier version.

Admin UI health fails

Rebuild the admin UI image after adding admin_ui/nginx.conf. The endpoint is:

curl -i http://localhost:5174/health

Expected body:

{ "status": "ok", "service": "admin_ui" }

Health is slow

The dashboard measures full browser request time, including DNS, TLS, network, and API processing. Compare the dashboard value with a server-side curl from the same network before diagnosing application latency.

8. Extending the Dashboard

To add a service:

1. Add its base URL to configured.
2. Add its metadata to serviceMeta.
3. Add a health path to healthPaths.
4. Add representative safe routes to testerRoutes.
5. Add its environment variable to this document and .env.local examples.
6. Confirm the service has CORS headers and an appropriate health endpoint.
7. Run npm run build and perform a browser smoke test.

To add a request route, include a short label and keep the route literal. Avoid user-entered arbitrary URLs, unrestricted HTTP methods, or unrestricted request headers.

Useful future extensions include:

• a time-window chart backed by a real metrics store;
• service version/build information in health payloads;
• threshold-based alerts for latency and repeated failures;
• export of incident rows for an operator handoff;
• a same-origin authenticated backend if the tool becomes a shared production console;
• a dedicated /health endpoint for Auth API so authentication status and process health are separate signals.

9. Validation Checklist

Before shipping a dashboard change:

cd monitoring_ui
npm install
npm run build

Then verify in a browser:

• all five cards render;
• one healthy local service shows a payload and latency;
• an unavailable service is clearly marked offline;
• Connections persists URL changes after reload;
• an admin JWT loads Error Log API data;
• an invalid token produces a visible error state;
• each Request lab route targets the expected service;
• the layout remains usable at a narrow mobile width.