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

Transit Project Guide

This repository contains the XTransit service group, its React administration console, the monitoring dashboard, and a retained legacy client.

Repository Map

Directory	Responsibility	Default port
auth_api/	Authentication and JWT issuance	5000
employee_api/	Employee onboarding and management	4000
transit_api/	Routes, schedules, fleet, GPS, and admin operations	5001
error_log_api/	Central error collection and protected log reads	5003
admin_ui/	React + Vite operations console served by nginx	5174
monitoring_ui/	React + Vite service monitoring dashboard	5173 in dev
deprecated/	Retained Flutter bus-terminal client	n/a
windows_xp_driver_ui/	Legacy driver UI work	n/a

Public domains and their intended roles are listed in DOMAINS_README.md.

Prerequisites

• Git
• Node.js 18+
• npm
• Docker 20.10+ and Docker Compose v2 for container workflows
• PostgreSQL for non-mock API development
• access to the configured database schemas and service credentials

Local API Development

Each Node service has its own package.json and starts independently:

npm --prefix ./auth_api install
npm --prefix ./employee_api install
npm --prefix ./transit_api install
npm --prefix ./error_log_api install

The services read database and JWT settings from environment variables. Keep credentials in an ignored .env file or your secret manager. Never commit database passwords, JWT signing keys, or production tokens.

Transit API development can use DEV_MOCK=1 for in-memory mock storage where supported. Mock mode is for development and should not be used as a production health signal.

Docker and Deployment

The root docker-compose.yml pulls service images from the configured registry and expects an external PostgreSQL instance. Provide a server-side .env, then:

docker compose --env-file .env pull
docker compose --env-file .env up -d

Useful operations:

docker compose ps
docker compose logs -f auth_api
docker compose logs -f transit_api
docker compose up -d --force-recreate
docker compose down

See DOCKER_README.md, DEPLOYMENT.md, and CI/CD and Portainer for infrastructure-specific procedures.

The current compose stack exposes:

• auth_api on port 5000;
• employee_api on port 4000;
• transit_api on port 5001;
• error_log_api on port 5003;
• admin_ui on port 5174;
• monitoring_ui on port 5175.

The monitoring dashboard is currently a separate Vite application. Its full operation and deployment notes are in MONITORING_UI.md. Its image is built and pushed by the Gitea workflow when monitoring_ui/**, docker-compose.yml, or the workflow changes.

Environment Variables

The exact variable names are defined by docker-compose.yml and each service's database module. Common deployment values include:

POSTGRES_HOST=your.db.host
POSTGRES_PORT=5432
POSTGRES_DB=transit_db
POSTGRES_USER_AUTH=auth_user
POSTGRES_PASSWORD_AUTH=strong_password
POSTGRES_USER_EMPLOYEE=employee_user
POSTGRES_PASSWORD_EMPLOYEE=strong_password
POSTGRES_USER_TRANSIT=transit_user
POSTGRES_PASSWORD_TRANSIT=strong_password
POSTGRES_USER_LOGGER=error_logger
POSTGRES_PASSWORD_LOGGER=strong_password
JWT_SECRET=replace-with-a-secret
ADMIN_USER_CODES=42,101
ERROR_LOG_API_URL=https://error.example.test/error_log

Use the names required by the active compose file. Do not copy these placeholders into a production environment without replacing them.

Database Prerequisites

The APIs expect their configured schemas and tables to exist. The central error logger requires at least:

CREATE SCHEMA IF NOT EXISTS data;

CREATE TABLE IF NOT EXISTS data.errors (
  id BIGSERIAL PRIMARY KEY,
  "date" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  service TEXT NOT NULL,
  partofservice TEXT,
  error TEXT NOT NULL
);

Use separate database users with the minimum required permissions. The exact transit, route, worker, and fleet schemas are part of the deployment database setup rather than this application repository.

API Health and Debugging

The primary health requests are:

GET http://localhost:4000/health
GET http://localhost:5001/health
GET http://localhost:5003/health
GET http://localhost:5174/health

Auth API currently uses GET /me, which requires a JWT. The monitoring dashboard documents the distinction between process health and authenticated health in MONITORING_UI.md.

When a service fails:

1. Check container status and logs.
2. Check the service's environment variables.
3. Check database network connectivity and credentials.
4. Check that required schemas and permissions exist.
5. Call the health endpoint directly.
6. Check the central Error Log API if the service was able to report its failure.

Admin UI

The admin UI manages stops, bus lines, fleet, schedules, and timetable views. Its API and schedule-specific documentation remains next to the source in admin_ui/. The nginx image now exposes /health as JSON for the monitoring dashboard.

Build it locally with:

cd admin_ui
npm install
npm run build
npm run dev

CI and Registry

The GitHub Actions workflow builds service images and pushes them to the configured container registry. Registry authentication requires a token with the appropriate package permissions. Keep registry credentials outside source control.

Security Rules

• keep secrets in ignored environment files or a secret manager;
• use TLS at public boundaries;
• use least-privilege database users;
• restrict CORS origins for production deployments;
• keep admin JWTs out of logs and screenshots;
• review allowlisted routes before expanding the admin console request lab;
• keep the monitoring control room unauthenticated and read-only;
• treat DEV_MOCK=1 as a local development setting only.

Documentation Policy

Use docs/ for project-wide operational and architectural guidance. Keep service-specific API details next to the service when they are maintained with that service. The root README.md should remain a concise orientation page with links, not a second deployment manual.