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](../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:

```bash
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:

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

Useful operations:

```bash
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](../DOCKER_README.md), [DEPLOYMENT.md](../DEPLOYMENT.md), and [CI/CD and Portainer](../CI_CD_PORTAINER_GUIDE.md) 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](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:

```env
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:

```sql
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:

```text
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](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:

```bash
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.