The-transit-Project/admin_ui/README.md

Weekly schedules and shifts

The schedule manager uses the weekly template model. Administrators create a departure for a bus line in one of three categories: weekdays, Saturday, or Sunday. The UI creates the corresponding day_of_week rows and assigns drivers through transit.shifts, rather than storing a driver on transit.schedules.

The active UI uses these transit API endpoints:

• GET /admin/weekly-schedules
• GET /admin/shift-drivers
• POST /admin/weekly-schedules
• PUT /admin/weekly-schedules/:scheduleId/shift
• DELETE /admin/weekly-schedules/:scheduleId

Transit Admin Control Center

Modern React + Vite web application for comprehensive transit system administration.

Features

✅ Stop Management - Create and manage transit stops with geolocation ✅ Bus Lines - Define routes with start/end stops and estimated durations ✅ Fleet Management - Monitor and view fleet vehicles ✅ Stop Linking - Assign stops to bus lines with order and ETA ✅ JWT Authentication - Secure authentication with role-based access ✅ Production Ready - Docker containerized with runtime env configuration ✅ Error Log Viewer - Inspect centralized error logs from all services

Local Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

cd admin_ui
npm install

Environment Configuration

Create a .env file in the admin_ui directory:

VITE_AUTH_API=https://auth.xtransit.testinstance.nl
VITE_TRANSIT_API=https://transit.xtransit.testinstance.nl
VITE_ERROR_LOG_API=https://error.xtransit.testinstance.nl

Run Development Server

npm run dev

The app will be available at http://localhost:5173

Build for Production

npm run build

This creates a production bundle in the dist/ directory.

Docker Deployment

Build Docker Image

docker build -t xtransit/admin_ui:latest .

Run with Docker

docker run -p 5174:80 \
  -e VITE_AUTH_API=/api/auth \
  -e VITE_TRANSIT_API=/api/transit \
  xtransit/admin_ui:latest

Using Docker Compose

The admin UI is integrated into the main docker-compose.yml at the project root.

From the project root:

# Start all services including admin UI
docker-compose up -d

# Access the admin UI
http://localhost:5174

Configuration

Environment Variables

Variable	Description	Default
VITE_AUTH_API	Auth API URL	https://auth.xtransit.testinstance.nl
VITE_TRANSIT_API	Transit API URL	https://transit.xtransit.testinstance.nl

Runtime Configuration

When running in Docker, environment variables are injected at runtime via docker-entrypoint.sh which creates /usr/share/nginx/html/env-config.js. This allows configuration without rebuilding the image.

Architecture

Technology Stack

• Frontend: React 18.2 + Vite 5.0
• HTTP Client: Axios 1.4
• Server: Nginx (Alpine Linux)
• Build: Multi-stage Docker build for optimized image size

Component Structure

• App.jsx - Main app router, session management
• Login.jsx - Authentication with dev token helper
• StopsManager.jsx - Create/list transit stops
• BusLinesManager.jsx - Create/list bus routes
• FleetManager.jsx - View fleet vehicles
• LinkStop.jsx - Link stops to bus lines
• ErrorLogViewer.jsx - Central error log viewer

API Integration

The app communicates with:

• Auth API (/login, /me)
• Transit API (/admin/stops, /admin/bus-lines, /admin/fleet/buses)
• Error Log API (/error_log)

All requests include JWT Bearer token for authentication.

Authentication

Login Flow

1. User enters user code and password
2. Client calls POST /login
3. Receives JWT token with userId and userCode
4. JWT is stored in localStorage
5. All API requests include Authorization: Bearer <token>

Admin Authorization

Users must have a userCode in their JWT and, for admin access, the isAdmin flag set by the auth_api based on the ADMIN_USER_CODES environment variable.

Production Setup

1. Remove dev token button from Login.jsx
2. Implement real authentication system (OAuth/SAML)
3. Configure proper JWT generation in auth_api
4. Set strong JWT_SECRET environment variable
5. Configure ADMIN_USER_CODES with actual admin user IDs
6. Configure VITE_ERROR_LOG_API if you use a custom logging endpoint

Troubleshooting

Issue: "Admin UI not loading"

• Verify container is running: docker ps
• Check logs: docker-compose logs admin_ui
• Clear browser cache (Ctrl+Shift+R)

Issue: "API connection refused"

• Ensure auth_api and transit_api are running
• Check environment variables are set correctly
• Verify network connectivity between containers

Issue: "Permission denied" on admin operations

• Verify JWT token includes valid userCode
• Check ADMIN_USER_CODES environment variable
• Ensure database user has appropriate permissions

Deployment

See DEPLOYMENT.md for comprehensive deployment guide.

Production Checklist

• Remove development authentication helpers
• Set strong JWT_SECRET
• Configure proper ADMIN_USER_CODES
• Enable HTTPS/SSL
• Configure CORS for production domain
• Set up monitoring and logging
• Configure database backups
• Document admin procedures

Support

For issues or questions:

1. Check service logs: docker-compose logs admin_ui
2. Verify API connectivity: Visit API URLs directly
3. Check browser console for client-side errors
4. Review DEPLOYMENT.md for troubleshooting

License

Part of the XTransit project