──────

### Summary of Changes 1. Documentation Consolidation: • Relocated the docs/ folder and all repository .md files (README.md, DEPLOYMENT.md, DOCKER_README.md, DOMAINS_README.md, GETTING_STARTED.md, CI_CD_PORTAINER_GUIDE.md, ADMIN_DEPLOYMENT_SUMMARY.md, SECURITY_PRIVATE_FILES.md, handoff.md, azure-project-plan.md, plus service-specific READMEs) into . • Updated document links in README.md. 2. AI Agent Project Map: • Created PROJECT_MAP.md in the project root containing complete architecture diagrams, service specs, ports, DB schemas, environment variables, and developer workflows. • Added PROJECT_MAP.md to .gitignore. 3. Monitoring UI & Infrastructure Integration: • Added monitoring_ui service to docker-compose.yml (port 5175). • Configured Gitea workflow docker-build.yml for monitoring_ui builds. • Added CORS middleware headers in index.js. • Added nginx.conf copy step in Dockerfile. ────── ### Recommended Commit Message docs: consolidate project documentation into monitoring_ui and add agent project map - Move all markdown documentation files and docs/ folder into monitoring_ui/docs/ - Update documentation hub index (monitoring_ui/docs/README.md) with relative paths - Generate comprehensive AI agent reference map (PROJECT_MAP.md) in repository root - Add PROJECT_MAP.md and monitoring_ui build output/env overrides to .gitignore - Integrate monitoring_ui service into docker-compose.yml and Gitea CI workflow - Configure CORS handling in employee_api for monitoring dashboard access ────── ### Alternative Short Commit Message refactor(docs): move docs to monitoring_ui and create AI agent PROJECT_MAP.md
2026-09-20 23:33:55 +02:00
parent f935bbeb8c
commit 635a130f0b
195 changed files with 28309 additions and 957 deletions
@@ -0,0 +1,169 @@
+# 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 monitoring request lab;
+- 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.