The-transit-Project/monitoring_ui/docs/azure-project-plan.md

Project Plan

Status: Planning Created: 2026-09-20 Mode: NEW

---

1. Project Overview

Goal: Build a secure React + Vite operations console that monitors the existing XTransit APIs, summarizes service capabilities and errors, and provides a guarded live request tester. The project is designed so that every module is independently testable.

App Type: SPA + API

API Login: Yes

Mode: NEW

Deployment Plan: No deployment plan found

---

2. Monitoring Proxy API — backend

Component	Technology
Language	TypeScript
Runtime	Node
Package Manager	npm
Test Runner	vitest
Mocking Library	vi.mock
Test Command	npm test
Orchestration	docker-compose

The proxy owns environment configuration, upstream health aggregation, the allowlisted endpoint catalog, authenticated request execution, error-log reads, response redaction, CORS, rate limiting, and normalized error responses. It must fail closed for unknown targets, unsafe methods, oversized bodies, and excessive timeouts.

3. Transit Monitor Dashboard — frontend

Component	Technology
Language	TypeScript
Framework	React + Vite
Package Manager	npm
Test Runner	vitest
Mocking Library	vi.mock
Test Command	npm test

The dashboard consumes only the proxy API, keeps polling and response-history state in memory, and exposes environment selection, service health, capabilities, errors, and the guarded tester as focused operator workflows.

4. Services Required

Azure Service	Role in App	Environment Variable	Default Value (Local)	Classification
None	The console reads existing XTransit APIs and does not add persistence, queues, cache, or file storage.	—	—	Enhancement

5. Prerequisites

Run

Tool	Service(s)	Installed	Version
Node.js	*	✅	v22.22.1
npm	*	✅	9.2.0
TypeScript	*	❓	Verify through project dependencies
Vitest	*	❓	Verify through project dependencies

Debug

Tool	Service(s)	Installed	Version
Docker	monitoring-proxy-api, transit-monitor-dashboard	✅	29.1.3
Docker Compose	monitoring-proxy-api, transit-monitor-dashboard	✅	v5.5.0
VS Code Docker extension	monitoring-proxy-api, transit-monitor-dashboard	❓	Verify in VS Code
VS Code ESLint extension	monitoring-proxy-api, transit-monitor-dashboard	❓	Verify in VS Code

Double-check all tools marked ❓ before proceeding.

6. Design System & UI

Component Library: Fluent UI v9 Style Direction: A calm, data-dense transit control room with a warm paper-white canvas, ink-black typography, cobalt actions, and signal colors reserved for service state. Use compact 4px control corners, crisp dividers, restrained elevation, and generous horizontal rhythm so operators can scan incidents without visual noise. Typography: Segoe UI Variable, Segoe UI, sans-serif

Color Palette

Token	Hex	Usage
primary	#155EEF	Operator actions, active dashboard navigation, and selected service filters
accent	#F59E0B	Watch states, response-time highlights, and attention markers
surface	#F6F8FB	Main console canvas and quiet page background
text	#172033	Service names, route labels, and incident details
muted	#667085	Polling timestamps, metadata, and supporting descriptions
border	#D9E0EA	Console dividers, table rules, and input outlines

Pages

Page	Route	Purpose	Layout
Command Center	/	See the current health picture, polling freshness, and the most important service signals.	header, nav, sidebar, main, hero, grid, table, actions
Service Catalog	/services	Inspect each upstream service's capabilities and representative route coverage.	header, nav, sidebar, main, tabs, card-list, table, actions
Request Lab	/requests	Run a bounded, authenticated request against an allowlisted upstream route and inspect timing.	`header, nav, sidebar, main, form, split(form	table), action-bar`
Incident Log	/incidents	Review normalized error-log activity and filter by service or severity.	header, nav, sidebar, main, tabs, table, card-list

Sample Content

Command Center — service health:

Service	Endpoint	Latency	Status
Transit API	/health	184 ms	Operational
Employee API	/health	96 ms	Operational
Error Log API	/health	121 ms	Degraded
Admin UI	http://localhost:5173	42 ms	Operational

Service Catalog — service capability:

Service	Capability	Route	Access
Transit API	Daily schedules	/bus/schedule/daily	Authenticated
Transit API	Route detail	/bus/routes/:routeId	Authenticated
Employee API	Create employee	/createemployee	Admin
Error Log API	Read error log	/error_log	Admin

Request Lab — request preset:

Service	Method	Path	Expected result
Transit API	GET	/bus/schedules/overview	Schedule summary
Transit API	GET	/bus/admin/drivers	Driver roster
Employee API	GET	/health	Service health

Note: Transit API bus endpoints are now served under the /bus/ prefix. Enter /bus/... paths in the Request Lab for bus routes; /health stays unprefixed. The legacy unprefixed bus paths still work but return a Deprecation response header.

Incident Log — normalized incident:

Time	Service	Code	Message	Severity
09:42:18	Error Log API	BAD_REQUEST	Missing route identifier	Warning
09:37:04	Transit API	FORBIDDEN	Admin role required	Info
09:18:51	Employee API	INTERNAL_ERROR	Employee lookup timed out	Critical

7. Project Structure

monitoring_dashboard/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── index.html
├── Dockerfile
├── docker-compose.yml
├── src/
│   ├── main.tsx
│   ├── App.tsx
│   ├── api/client.ts
│   ├── api/types.ts
│   ├── components/
│   │   ├── AppShell.tsx
│   │   ├── HealthSummary.tsx
│   │   ├── ServiceCard.tsx
│   │   ├── RequestForm.tsx
│   │   └── IncidentTable.tsx
│   ├── pages/
│   │   ├── CommandCenter.tsx
│   │   ├── ServiceCatalog.tsx
│   │   ├── RequestLab.tsx
│   │   └── IncidentLog.tsx
│   └── styles/
│       └── theme.css
└── server/
    ├── package.json
    ├── tsconfig.json
    ├── Dockerfile
    └── src/
        ├── index.ts
        ├── config.ts
        ├── routes/health.ts
        ├── routes/catalog.ts
        ├── routes/requests.ts
        ├── routes/incidents.ts
        ├── middleware/auth.ts
        ├── middleware/rateLimit.ts
        ├── services/upstreamClient.ts
        ├── services/healthAggregator.ts
        └── services/redaction.ts

8. Route Definitions

#	Method	Path	Description	Request Body	Response Body	Status Codes
1	GET	/api/health	Aggregate health for auth, employee, transit, error-log APIs, and admin UI.	—	{ status, checkedAt, services: [{ id, status, latencyMs, endpoint }] }	200, 503
2	GET	/api/catalog	Return the allowlisted service and endpoint capability catalog.	—	{ services: [{ id, label, capabilities: [{ method, path, access }] }] }	200, 401
3	GET	/api/incidents	Read normalized error activity from the error-log API with bounded filters.	—	{ incidents: [{ id, occurredAt, service, code, message, severity }] }	200, 400, 401, 502
4	POST	/api/requests/execute	Execute one authenticated request against an allowlisted upstream route with safe limits.	{ serviceId, method, path, query, body, timeoutMs }	{ requestId, status, durationMs, headers, data, redactions }	200, 400, 401, 403, 408, 429, 502
5	GET	/api/requests/history	Return in-memory request timing and status history for the current process.	—	{ items: [{ requestId, serviceId, method, path, status, durationMs, executedAt }] }	200, 401
6	GET	/api/config/environments	List configured environment names without exposing secrets.	—	{ environments: [{ id, label, active }] }	200, 401
7	POST	/api/config/environments/select	Select a configured upstream environment for the signed-in operator session.	{ environmentId }	{ environmentId, label, selectedAt }	200, 400, 401, 404

9. Next Steps

1. Run azure-project-scaffold to execute this plan
2. Run azure-project-integrate to wire the frontend to live data, smoke-test the backend, and create the migrations
3. Run azure-debug-plan → azure-debug-generate for Docker emulators and VS Code debugging
4. Run the azure-deploy agent when ready; it uses azure-app-onboard for architecture, cost estimation, IaC generation, provisioning, and health verification