GZMTEC

Transforming Public Transport with Smarter, Real-Time Insights

Overview

Built with the tools and technologies:

GZMTEC is Metropolia GZM dedicated, unofficial engine for planning trips with estimated deviations using historical data, running on OTP v2.9.0. It uses database and JavaVM running on a dedicatied server with open and documented API to use at own's call. The engine can be adjusted to any other public transport system when provided with database in the same structure as the original and equivalent of GTFS and PBF files in designated system. The database structure can be adjusted to the other system, however we do not provide support for engines with changed source code. The project is available on browsers and as an Android 7+ native app.

Project Structure

└── gzmtec/
    ├── .github
    │   └── workflows
    ├── API_DOCUMENTATION.md
    ├── LICENSE
    ├── README.md
    ├── backend
    │   ├── .env.example
    │   ├── config
    │   ├── controllers
    │   ├── coverage
    │   ├── logger.js
    │   ├── middleware
    │   ├── models
    │   ├── package-lock.json
    │   ├── package.json
    │   ├── routes
    │   ├── scripts
    │   ├── server.js
    │   ├── services
    │   └── tests
    ├── frontend
    │   ├── .editorconfig
    │   ├── .gitignore
    │   ├── .prettierrc
    │   ├── .vscode
    │   ├── android
    │   ├── angular.json
    │   ├── capacitor.config.ts
    │   ├── package-lock.json
    │   ├── package.json
    │   ├── public
    │   ├── src
    │   ├── tsconfig.app.json
    │   ├── tsconfig.json
    │   └── tsconfig.spec.json
    ├── package-lock.json
    ├── package.json
    └── template.sql

The repository is splitted into two main catalogues:

• frontend - provides Angular-driven website sending requests to the API and fetching them into UI, it is a minimal version to provide the most efficient and fastest user experience
• backend - provides Node.js server developed in MVC model that runs the API (server.js) and archiving new deviations records to the database (logger.js). .env files has to but put there

Project Index (backend only)

GZMTEC/

backend

⦿ backend

File Name	Summary
server.js	- Sets up the core Express server to handle API requests, manage middleware, and route traffic to specific controllers and endpoints - It establishes the applications main entry point, enabling communication between clients and backend services, and integrates essential configurations such as environment variables, CORS policies, and database connections to support the overall architecture.
.env.example	- Defines environment variables essential for configuring backend services, including database connections, server ports, and authentication secrets - Facilitates seamless setup and deployment by providing standardized parameters for connecting to the database, frontend, and JVM components, ensuring consistent environment configuration across development and production environments within the overall architecture.
package.json	- Facilitates core backend functionalities including user authentication, data management, and API interactions within the application architecture - It integrates essential dependencies for server operations, security, and database connectivity, supporting a scalable and secure environment for client-server communication - This component ensures reliable handling of user data and authentication processes, forming the backbone of the applications backend infrastructure.
logger.js	- Initialize and configure the deviation logging service within the backend architecture, enabling real-time monitoring of deviations or anomalies - By setting up environment variables, database connections, and starting the deviation logger, it ensures continuous oversight of system performance and issues, supporting proactive maintenance and operational transparency across the entire codebase.

controllers

⦿ backend.controllers

File Name	Summary
tripPlanner.controller.js	- Provides route planning and real-time transit deviation estimation by integrating external trip data with live vehicle positions and historical deviation records - Facilitates accurate, timely public transportation itineraries, enhancing user experience through dynamic adjustments based on current conditions and historical patterns within the broader transportation system architecture.
apiStatus.controller.js	- Provides an endpoint to retrieve the current API status, serving as a health check within the backend architecture - It facilitates monitoring and ensures system availability by delivering real-time status information, supporting overall system reliability and operational transparency across the applications services.
user.controller.js	- Defines core user management functionalities, including registration, authentication, and handling user-specific favorite routes - Facilitates secure login via JWT tokens and manages user data interactions with the database, supporting personalized features within the applications architecture - Serves as a key controller layer connecting user actions to backend data operations.
deviationLogger.controller.js	- Facilitates logging of deviations related to trips, lines, stops, and vehicles within the backend architecture - It acts as an intermediary that receives deviation data, invokes the data model to store the information, and responds with success or error messages - This component ensures accurate tracking of operational anomalies, supporting overall system monitoring and analysis.
deviationOperations.controller.js	- Provides an API endpoint to estimate deviation metrics for transit stops based on line, stop, and time parameters - It retrieves average deviation data, processes it to compute a meaningful statistic, and returns comprehensive results - This controller facilitates real-time deviation analysis, supporting the broader systems goal of monitoring and optimizing transit operations.

config

⦿ backend.config

File Name	Summary
cache.js	- Establishes a caching mechanism to optimize data retrieval and reduce backend load by storing temporary data with a 24-hour expiration - Integral to the overall architecture, it enhances application performance and scalability by efficiently managing frequently accessed data across the backend services.
db.js	- Establishes a centralized connection pool to the MySQL database, enabling efficient and scalable data access across the backend - It manages database configurations securely via environment variables, ensuring reliable connectivity and resource management for data operations within the overall application architecture.

scripts

⦿ backend.scripts

File Name	Summary
deviationLogger.js	- Facilitates automated logging of active vehicle deviations at regular intervals, supporting real-time monitoring and data collection within the system - Integrates with the deviation logging service to ensure consistent recording of deviation data, enabling timely detection and analysis of vehicle performance issues across the entire architecture.

middleware

⦿ backend.middleware

File Name	Summary
envValidator.middleware.js	- Ensures the integrity of the applications environment configuration by verifying the presence of essential environment variables during startup - This validation step prevents runtime errors related to missing configuration, supporting reliable deployment and operation within the overall backend architecture - It acts as a safeguard, maintaining consistency and stability across the systems environment setup.
auth.middleware.js	- Implements authentication middleware to secure API endpoints by verifying JSON Web Tokens - It ensures that only requests with valid tokens can access protected resources, maintaining user authentication state across the backend architecture - This middleware is essential for safeguarding sensitive data and enforcing access control within the applications server-side logic.

models

⦿ backend.models

File Name	Summary
deviationOperations.model.js	- Provides functionality to retrieve aggregated deviation data for specific transit lines and stops, focusing on deviations within a defined time window and weekday - Facilitates analysis of punctuality patterns by grouping deviations per trip and vehicle, supporting operational insights and performance monitoring within the broader transportation management system.
user.model.js	- Defines user-related data operations within the backend architecture, facilitating user account management and personalization features - Handles creation, retrieval, and deletion of user information and favorite routes, integrating with the database to support user authentication, profile management, and route customization functionalities essential for a personalized user experience.
deviationLogger.model.js	- Provides functionality to log deviations related to trips, lines, stops, and vehicles into the database, capturing contextual data such as weekday and timestamp - Serves as a core component for tracking operational anomalies within the backend architecture, enabling analysis and reporting of deviations to improve transit service reliability and performance monitoring.
sdip.model.js	- Defines a deprecated data model related to public transportation, specifically for the SDIP system, and references a service for further data handling - It categorizes vehicle types such as trams, buses, and trolleybuses, contributing to the overall architecture by supporting transportation data management and integration within the backend infrastructure.
apiStatus.model.js	- Provides a health check endpoint for the backend API, enabling monitoring of service availability and responsiveness - It returns the current operational status and timestamp, supporting system health assessments and ensuring reliable communication within the overall architecture - This component plays a crucial role in maintaining system stability and facilitating proactive issue detection.

services

⦿ backend.services

File Name	Summary
deviationLogger.service.js	- Provides functionality to log deviations of active vehicles by retrieving real-time vehicle data, processing deviation metrics, and storing normalized deviation records - Integrates with external services to gather vehicle statuses and ensures deviations are accurately recorded for monitoring and analysis within the broader transportation management system - Facilitates tracking vehicle adherence to schedules and operational performance.
sdip.service.js	- Provides an interface to retrieve real-time transportation data from the SDIP system, including stops, departures, and vehicle statuses - It integrates caching for efficiency and supports seamless data access for other services or frontend components, facilitating accurate and timely transit information within the overall architecture.

routes

⦿ backend.routes

api

⦿ backend.routes.api

File Name	Summary
apiRouter.js	- Defines API routes for core backend functionalities, including deviation estimation, trip route searching, service status checks, and fetching transit stops - Serves as a central hub connecting client requests to relevant controllers and services, facilitating seamless communication within the applications architecture and supporting features related to trip planning and transit data retrieval.

users

⦿ backend.routes.users

File Name	Summary
userRouter.js	- Defines user-related API endpoints for managing favorite items, enabling authenticated users to add and retrieve their favorites - Integrates route handling with authentication middleware to ensure secure access, serving as a key component in the user management architecture within the backend - Facilitates seamless interaction between client requests and user data operations.
authRouter.js	- Defines authentication-related routes for user registration and login within the backend API, facilitating secure access control - Integrates with user controllers to handle authentication logic and middleware for protected endpoints, contributing to the overall architecture by enabling user identity management and access security across the application.

Prerequisities

• npm 11
• Node.js 24
• Angular 21
• OTP 2.9.0
• XAMPP (or any other local database software)

Installation

1. Run npm install in both frontend and backend catalogue
2. Create the .env file in backend catalogue, follow the .env.example
3. Run ng g environments and fill them like that:

export const environment = {
  production: true/false,
  apiUrl: 'ipaddressofyourserver/localhost' 
};

5. Setup a local database with schema located in template.sql and fill them with your data.
6. Download GTFS files of your choice. Also get PBF map file of your area. Put them all in a folder of your choice. Remember to have "gtfs" phrase somewhere in GTFS files names.
7. Run a local OTP instance on your server. The OTP is available here. Localization of OTP jar can be anywhere. You can use the command java -Xmx8G -jar otp-jar.jar --build --serve ./otp-data where otp-jar.jar is where your OTP jar is located and ./otp-data is the folder where GTFS and PBF files are located.
8. Run node server.js in backend folder and ng serve --host 0.0.0.0 in frontend folder. Make sure CORS policies do not lock out your app in any way.
9. The app is available at localhost:4200. If you don't want to run only locally we recommend to forward the following apps ports on your router:

• database (if using XAMPP: port 3306)

• JVM with OTP (usually port 8080)

• backend (as we specified in the code port 3000)

• frontend (as we specified in the code port 4200)

  Remember to eventually adjust changed addresses in environments in frontend and .env in backend.