📄 Service Contracts – Swift Signals

This document defines the service contracts for all microservices in the Swift Signals system. It includes gRPC specifications for internal services and REST specifications for the API Gateway.

📦 Services Overview

Service Name	Description	Protocol	Public?
user-auth-service	Handles user registration, login, and admin privileges	gRPC	❌
simulation-service	Manages intersection and traffic simulations	gRPC	❌
optimization-service	Optimises simulations using AI models (e.g. SUMO + ML)	gRPC	❌
api-gateway	Single entry point for frontend requests (REST → gRPC)	REST/gRPC	✅

🧑‍💼 user-auth-service

📌 Overview

Handles user account creation, login, and access control. Only this service interacts with the user database and JWT creation.

📁 Proto File:

service UserService {
  rpc Signup(SignupRequest) returns (SignupResponse);
  rpc Login(LoginRequest) returns (LoginResponse);
  rpc WhoAmI(WhoAmIRequest) returns (UserInfoResponse);
  rpc BanUser(BanUserRequest) returns (BanUserResponse);
}

message SignupRequest {
  string email = 1;
  string password = 2;
}
message SignupResponse {
  string user_id = 1;
  string jwt_token = 2;
}
message LoginRequest {
  string email = 1;
  string password = 2;
}
message LoginResponse {
  string jwt_token = 1;
}
message WhoAmIRequest {}
message UserInfoResponse {
  string user_id = 1;
  Role role = 2;
}
message BanUserRequest {
  string user_id = 1;
}
message BanUserResponse {
  bool success = 1;
}

enum Role {
  user = 0
  admin = 1
}

🚦 simulation-service

📌 Overview

Handles creation and management of simulation instances, including intersection setup and traffic parameters.

📁 Proto File:

service SimulationService {
  rpc CreateSimulation(CreateSimulationRequest) returns (SimulationResponse);
  rpc GetSimulations(GetSimulationsRequest) returns (GetSimulationsResponse);
  rpc GetSimulationById(GetSimulationByIdRequest) returns (SimulationResponse);
}

message CreateSimulationRequest {
  string user_id = 1;
  IntersectionType intersection_type = 2;
  repeated float coordinates = 3;
  string light_timing = 4;
  int32 traffic_flow = 5;
  bytes time_series_data = 6; // optional
}

message SimulationResponse {
  string simulation_id = 1;
  Status status = 2;
}

message GetSimulationsRequest {
  string user_id = 1;
}
message GetSimulationsResponse {
  repeated SimulationResponse simulations = 1;
}

message GetSimulationByIdRequest {
  string simulation_id = 1;
}

enum IntersectionType {
  FOUR_WAY = 0;
  THREE_WAY = 1;
  ROUNDABOUT = 2;
}

enum Status {
  PENDING = 0;
  RUNNING = 1;
  COMPLETE = 2;
}

⏱️ optimisation-service

📌 Overview

Receives simulation configurations and performs optimization using AI (e.g. SUMO + heuristics or ML models). Responds with a new simulation state or recommended light timings.

📁 Proto File: [optimisation.proto](TODO: add link)

service OptimisationService {
  rpc OptimiseSimulation(OptimiseRequest) returns (OptimiseResponse);
  rpc GetOptimisationStatus(StatusRequest) returns (StatusResponse);
}

message OptimiseRequest {
  string simulation_id = 1;
}
message OptimiseResponse {
  string optimised_simulation_id = 1;
  string status = 2; // "queued", "running", "done"
}
message StatusRequest {
  string simulation_id = 1;
}
message StatusResponse {
  string status = 1;
  string message = 2;
}

enum Status {
  QUEUED = 0;
  RUNNING = 1;
  DONE = 2;  
}

🌐 api-gateway

📌 Overview

The only public-facing service. Handles REST requests from the frontend, translates them to gRPC requests for backend services, and returns responses.

🔐 Authentication

Required for all endpoints (except signup/login): JWT Bearer token

📥 REST Inputs

Endpoint	Method	Input Fields	Description
/auth/signup	POST	name, surname, email, password	Registers a new user
/auth/login	POST	email, password	Logs in and returns JWT
/simulations	GET	(JWT in headers)	Get all simulations for logged-in user
/simulations/{id}	GET	(ID in URL)	Get simulation with specified ID
/simulations	POST	intersectionType,coordinates,lightTiming,trafficFlow	Create a new simulation
/simulations/{id}/optimise	POST	(ID in URL)	Starts optimisation for simulation

📤 REST Outputs

Endpoint	Method	Response Fields	Description
/auth/signup	POST	userID, token	User ID and JWT
/auth/login	POST	token	JWT
/simulations	GET	[simulationID, name, ...]	List of simulations
/simulations/{id}	GET	simulationID, name, ...	Simulation info
/simulations	POST	simulationID	Created simulation's ID
/simulations/{id}/optimise	POST	optimisationID, status	Optimisation status

📝 Notes

• All internal services communicate using gRPC
• External clients use a REST API via the API Gateway
• Fields and message formats follow .proto definitions
• All endpoints are secured with JWT auth
• Admin-only actions (e.g., banning users) are restricted by role