──────

### 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,219 @@
+## 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
+
+Production admin panel: `https://admin.xtransit.testinstance.nl`
+
+For the separate service monitoring dashboard, see
+[`../docs/MONITORING_UI.md`](../docs/MONITORING_UI.md). The monitoring dashboard
+is deployed independently on host port `5175` and checks this admin UI through
+`GET /health`.
+
+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
+
+```bash
+cd admin_ui
+npm install
+```
+
+### Environment Configuration
+
+Create a `.env` file in the `admin_ui` directory:
+
+```env
+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
+
+```bash
+npm run dev
+```
+
+The app will be available at `http://localhost:5173`
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+This creates a production bundle in the `dist/` directory.
+
+## Docker Deployment
+
+### Build Docker Image
+
+```bash
+docker build -t xtransit/admin_ui:latest .
+```
+
+### Run with Docker
+
+```bash
+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:
+
+```bash
+# 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](../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