Traffic lights simulation (CLI)

Requirements

• Node.js (recommended: 18+)

Run

Build:

npm ci

npm run sim -- input.json output.json

Run:

node dist/main.js input.json output.json

Run test:

npm test

Input format

Input must be JSON with the required shape:

{
  "commands": [
    { "type": "addVehicle", "vehicleId": "vehicle1", "startRoad": "south", "endRoad": "north" },
    { "type": "step" }
  ]
}

Supported roads: north, south, east, west.

Output format

Output is JSON in the required format:

{
  "stepStatuses": [
    { "leftVehicles": ["vehicle1"] }
  ]
}

Algorithm

The simulator models a four-way intersection (North, South, West, East), where each incoming road is split into three independent lanes: LEFT, STRAIGHT, and RIGHT. Vehicles are stored in separate queues per (road, movement) pair, allowing precise tracking of traffic demand in each direction.

On every simulation step, the system selects a single green phase from a predefined set of non-conflicting movement groups. The selection is driven by a pressure-based scoring function, which assigns higher priority to movements with more vehicles and longer waiting times. The phase with the highest aggregated pressure is activated for the current step.

Each phase represents a safe combination of allowed movements that are considered non-conflicting under the model assumptions. Vehicles are then dequeued from the corresponding lanes according to the active phase rules.

The system prioritizes fairness and efficiency by increasing the weight (pressure) of vehicles based on their waiting time. The pressure grows non-linearly over time (quadratically), which strongly prioritizes long-waiting vehicles.

---

Assumptions

• The intersection consists of four approaches (N, S, W, E), each treated as an independent incoming road.

• Each road contains three lanes:

  • LEFT turn lane
  • STRAIGHT lane
  • RIGHT turn lane

• The model assumes channelized traffic flow, meaning each (road, movement) pair behaves as an independent stream with its own queue.

• The simulation operates in discrete time steps. In each step, at most one vehicle per (road, movement) queue is allowed to pass through the intersection.

• Traffic light control is based on a finite set of predefined green phases, each representing a group of allowed movements executed simultaneously.

• The phase design ensures no conflicting movements are activated at the same time, based on the following safety assumptions:

  • Left-turn safety assumption: Opposing left turns are treated as non-conflicting under the assumption of a simplified, large intersection model where vehicle trajectories are separated and do not overlap.
  • Right-turn safety assumption: Right turns are treated as non-conflicting with crossing left-turn movements originating from perpendicular approaches (e.g., S→E vs E→S). This assumption is based on simplified lane separation and turning geometry, where vehicle trajectories do not overlap within the intersection space.

• Vehicles are assumed to follow deterministic, instantaneous crossing behavior per step, meaning that once a movement is green, the first vehicle in the corresponding queue exits the intersection.