Translate graph labels and titles to PT

main/graphing.py

@@ -41,10 +41,10 @@ dwelling_times = [
     medium['TempoMédioSistema'].mean(),
     high['TempoMédioSistema'].mean()
 ]
-plt.bar(['Low', 'Medium', 'High'], dwelling_times, color=['green', 'orange', 'red'])
-plt.ylabel('Average Dwelling Time (s)')
-plt.title('System Performance vs Load')
-plt.xlabel('Load Scenario')
+plt.bar(['Baixa', 'Média', 'Alta'], dwelling_times, color=['green', 'orange', 'red'])
+plt.ylabel('Tempo Médio no Sistema (s)')
+plt.title('Desempenho do Sistema vs Carga')
+plt.xlabel('Cenário de Carga')
 plt.grid(axis='y', alpha=0.3)
 for i, v in enumerate(dwelling_times):
     plt.text(i, v + 1, f'{v:.2f}s', ha='center', va='bottom')
@@ -59,10 +59,10 @@ completion_rates = [
     medium['TaxaConclusão'].mean(),
     high['TaxaConclusão'].mean()
 ]
-plt.bar(['Low', 'Medium', 'High'], completion_rates, color=['green', 'orange', 'red'])
-plt.ylabel('Completion Rate (%)')
-plt.title('Vehicle Completion Rate vs Load')
-plt.xlabel('Load Scenario')
+plt.bar(['Baixa', 'Média', 'Alta'], completion_rates, color=['green', 'orange', 'red'])
+plt.ylabel('Taxa de Conclusão (%)')
+plt.title('Taxa de Conclusão de Veículos vs Carga')
+plt.xlabel('Cenário de Carga')
 plt.grid(axis='y', alpha=0.3)
 plt.ylim(0, 100)
 for i, v in enumerate(completion_rates):
@@ -78,10 +78,10 @@ waiting_times = [
     medium['TempoMédioEspera'].mean(),
     high['TempoMédioEspera'].mean()
 ]
-plt.bar(['Low', 'Medium', 'High'], waiting_times, color=['green', 'orange', 'red'])
-plt.ylabel('Average Waiting Time (s)')
-plt.title('Average Waiting Time vs Load')
-plt.xlabel('Load Scenario')
+plt.bar(['Baixa', 'Média', 'Alta'], waiting_times, color=['green', 'orange', 'red'])
+plt.ylabel('Tempo Médio de Espera (s)')
+plt.title('Tempo Médio de Espera vs Carga')
+plt.xlabel('Cenário de Carga')
 plt.grid(axis='y', alpha=0.3)
 for i, v in enumerate(waiting_times):
     plt.text(i, v + 1, f'{v:.2f}s', ha='center', va='bottom')
@@ -91,44 +91,44 @@ plt.close()
 
 # 4. Gráfico: Summary Statistics
 fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(14, 10))
-loads = ['Low', 'Medium', 'High']
+loads = ['Baixa', 'Média', 'Alta']
 
 # Vehicles generated
 ax1.bar(loads, [low['VeículosGerados'].mean(), medium['VeículosGerados'].mean(), high['VeículosGerados'].mean()], color=['green', 'orange', 'red'])
-ax1.set_title('Vehicles Generated')
-ax1.set_ylabel('Count')
+ax1.set_title('Veículos Gerados')
+ax1.set_ylabel('Quantidade')
 ax1.grid(axis='y', alpha=0.3)
 
 # Vehicles completed
 ax2.bar(loads, [low['VeículosCompletados'].mean(), medium['VeículosCompletados'].mean(), high['VeículosCompletados'].mean()], color=['green', 'orange', 'red'])
-ax2.set_title('Vehicles Completed')
-ax2.set_ylabel('Count')
+ax2.set_title('Veículos Concluídos')
+ax2.set_ylabel('Quantidade')
 ax2.grid(axis='y', alpha=0.3)
 
 # Min/Max dwelling time
 x = range(3)
 width = 0.35
-ax3.bar([i - width/2 for i in x], [low['TempoMínimoSistema'].mean(), medium['TempoMínimoSistema'].mean(), high['TempoMínimoSistema'].mean()], width, label='Min', color='lightblue')
-ax3.bar([i + width/2 for i in x], [low['TempoMáximoSistema'].mean(), medium['TempoMáximoSistema'].mean(), high['TempoMáximoSistema'].mean()], width, label='Max', color='darkblue')
-ax3.set_title('Min/Max Dwelling Time')
-ax3.set_ylabel('Time (s)')
+ax3.bar([i - width/2 for i in x], [low['TempoMínimoSistema'].mean(), medium['TempoMínimoSistema'].mean(), high['TempoMínimoSistema'].mean()], width, label='Mín', color='lightblue')
+ax3.bar([i + width/2 for i in x], [low['TempoMáximoSistema'].mean(), medium['TempoMáximoSistema'].mean(), high['TempoMáximoSistema'].mean()], width, label='Máx', color='darkblue')
+ax3.set_title('Tempo no Sistema Mín/Máx')
+ax3.set_ylabel('Tempo (s)')
 ax3.set_xticks(x)
 ax3.set_xticklabels(loads)
 ax3.legend()
 ax3.grid(axis='y', alpha=0.3)
 
 # Performance summary
-metrics = ['Dwelling\nTime', 'Waiting\nTime', 'Completion\nRate']
+metrics = ['Tempo no\nSistema', 'Tempo de\nEspera', 'Taxa de\nConclusão']
 low_vals = [low['TempoMédioSistema'].mean(), low['TempoMédioEspera'].mean(), low['TaxaConclusão'].mean()]
 med_vals = [medium['TempoMédioSistema'].mean(), medium['TempoMédioEspera'].mean(), medium['TaxaConclusão'].mean()]
 high_vals = [high['TempoMédioSistema'].mean(), high['TempoMédioEspera'].mean(), high['TaxaConclusão'].mean()]
 
 x = range(len(metrics))
 width = 0.25
-ax4.bar([i - width for i in x], low_vals, width, label='Low', color='green')
-ax4.bar(x, med_vals, width, label='Medium', color='orange')
-ax4.bar([i + width for i in x], high_vals, width, label='High', color='red')
-ax4.set_title('Performance Summary')
+ax4.bar([i - width for i in x], low_vals, width, label='Baixa', color='green')
+ax4.bar(x, med_vals, width, label='Média', color='orange')
+ax4.bar([i + width for i in x], high_vals, width, label='Alta', color='red')
+ax4.set_title('Resumo de Desempenho')
 ax4.set_xticks(x)
 ax4.set_xticklabels(metrics)
 ax4.legend()

main/src/main/java/sd/ExitNodeProcess.java

@@ -27,23 +27,22 @@ import sd.protocol.MessageProtocol;
 import sd.protocol.SocketConnection;
 
 /**
- * Ponto terminal da malha de simulação (Sink Node).
- * <p>
- * Este processo atua como o sumidouro da rede de filas. A sua função primária é
- * a <b>coleta de telemetria final</b>. Diferente das interseções, não encaminha veículos;
- * em vez disso, retira-os do sistema, calcula as métricas de latência "end-to-end"
- * (tempo no sistema, tempo de espera acumulado) e reporta ao Dashboard.
- * <p>
- * <b>Arquitetura de Concorrência:</b>
- * Utiliza um {@link ServerSocket} multithreaded para aceitar conexões simultâneas de
- * qualquer interseção de fronteira (Cr1, Cr5, etc.) que envie veículos para fora da malha.
+ * Destino final de todos os veículos da simulação (nó de saída S).
+ * 
+ * <p>Opera como sumidouro da rede:
+ * <ol>
+ * <li>Recebe veículos que completaram a viagem
+ * <li>Regista estatísticas finais (tempo total, espera, travessia)
+ * <li>Envia métricas ao dashboard em tempo real
+ * </ol>
+ * 
+ * <p>Participa no DES rastreando eventos, mas opera principalmente
+ * de forma reativa, aguardando chegadas via socket.
  */
 public class ExitNodeProcess {
 
     private final SimulationConfig config;
     private ServerSocket serverSocket;
-    
-    /** Pool de threads elástica para tratamento de conexões de entrada. */
     private final ExecutorService connectionHandlerPool;
 
     // DES components
@@ -52,37 +51,37 @@ public class ExitNodeProcess {
     private final EventLogger eventLogger;
     private Thread eventProcessorThread;
 
-    /** Flag de controlo (volatile para visibilidade entre threads de I/O e lógica). */
+    /** Flag de controlo (volatile para visibilidade entre threads) */
     private volatile boolean running;
 
-    /** Instante de início da simulação (milissegundos) sincronizado com o Coordenador. */
+    /** Instante de início da simulação (milissegundos) */
     private long simulationStartMillis;
 
-    /** Contador atómico (via synchronized) de throughput total. */
+    /** Contador de veículos que completaram a rota */
     private int totalVehiclesReceived;
 
-    /** Tempo acumulado no sistema (System Time) de todos os veículos. */
+    /** Tempo acumulado no sistema de todos os veículos */
     private double totalSystemTime;
 
-    /** Tempo acumulado em espera (Waiting Time) de todos os veículos. */
+    /** Tempo acumulado em espera de todos os veículos */
     private double totalWaitingTime;
 
-    /** Tempo acumulado em travessia (Service Time) de todos os veículos. */
+    /** Tempo acumulado em travessia de todos os veículos */
     private double totalCrossingTime;
 
-    /** Agregação por categoria de veículo. */
+    /** Contagem de veículos por tipo */
     private final Map<VehicleType, Integer> vehicleTypeCount;
 
-    /** Latência acumulada por categoria. */
+    /** Tempo de espera acumulado por tipo de veículo */
     private final Map<VehicleType, Double> vehicleTypeWaitTime;
 
-    /** Cliente TCP persistente para push de métricas ao Dashboard. */
+    /** Cliente socket para envio de estatísticas ao dashboard */
     private SocketClient dashboardClient;
 
     /**
-     * Bootstrap do processo ExitNode.
-     * Carrega configuração, inicializa subsistemas e entra no loop de serviço.
-     * * @param args Argumentos de CLI (caminho do config).
+     * Ponto de entrada do processo.
+     * 
+     * @param args args[0] (opcional) = caminho do ficheiro de configuração
      */
     public static void main(String[] args) {
         System.out.println("=".repeat(60));
@@ -118,9 +117,13 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Instancia o nó de saída.
-     * Prepara os acumuladores estatísticos e a infraestrutura de logging distribuído.
-     * * @param config A configuração global da simulação.
+     * Configura o Nó de Saída.
+     * 
+     * Inicializamos os nossos contadores, preparamos a pool de threads para tratar
+     * das ligações de veículos recebidas,
+     * e configuramos os componentes DES para rastreio de eventos.
+     * 
+     * @param config A configuração da simulação.
      */
     public ExitNodeProcess(SimulationConfig config) {
         this.config = config;
@@ -154,8 +157,9 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Estabelece o canal de controlo (Control Plane) com o Dashboard.
-     * Essencial para a visualização em tempo real das métricas de saída.
+     * Tenta estabelecer uma ligação ao dashboard.
+     * Se for bem-sucedido, poderemos enviar estatísticas em tempo real. Se não,
+     * apenas registamos localmente.
      */
     public void initialize() {
         System.out.println("Connecting to dashboard...");
@@ -175,9 +179,10 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Inicia a thread de processamento de eventos DES.
-     * Embora o ExitNode seja primariamente reativo (Network-driven), o motor DES
-     * é mantido para consistência de relógio e agendamento de fim de simulação.
+     * Starts the DES event processing thread.
+     * Currently, ExitNode is primarily reactive (receives vehicles via network),
+     * but maintains event queue for potential scheduled events and history
+     * tracking.
      */
     private void startEventProcessor() {
         eventProcessorThread = new Thread(() -> {
@@ -213,8 +218,8 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Dispatcher de eventos discretos.
-     * Trata eventos de fim de simulação. Chegadas de veículos são tratadas via Socket.
+     * Processes a discrete event based on its type.
+     * Currently supports VEHICLE_EXIT and SIMULATION_END events.
      */
     private void processEvent(SimulationEvent event) {
         try {
@@ -239,7 +244,7 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Executa a lógica de encerramento desencadeada pelo evento DES.
+     * Handles simulation end event.
      */
     private void handleSimulationEndEvent(SimulationEvent event) {
         eventLogger.log(EventType.SIMULATION_STOPPED, "ExitNode",
@@ -251,8 +256,9 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Exporta o histórico completo de eventos para auditoria.
-     * Requisito funcional para verificação de trace.
+     * Exports the complete event history for the exit node.
+     * This satisfies the spec requirement: "Deve ser possível verificar a lista
+     * completa de eventos"
      */
     public void exportEventHistory(String outputPath) {
         String history = eventQueue.exportEventHistory();
@@ -265,8 +271,9 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Agenda o fim determinístico da simulação.
-     * * @param endTime Tempo virtual de paragem.
+     * Schedules a simulation end event at the specified time.
+     * 
+     * @param endTime The simulation time when the simulation should end
      */
     public void scheduleSimulationEnd(double endTime) {
         SimulationEvent endEvent = new SimulationEvent(
@@ -278,16 +285,22 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Inicia o servidor TCP em modo de bloqueio (Blocking I/O).
-     * @throws IOException Se ocorrer erro no bind da porta.
+     * Abre o socket do servidor e começa a escutar por veículos.
+     * 
+     * Este é o loop principal. Aceitamos ligações das interseções (de onde vêm os
+     * veículos)
+     * e passamo-las para a nossa pool de threads para processamento.
+     * 
+     * @throws IOException Se não conseguirmos fazer bind à porta.
      */
     public void start() throws IOException {
         start(true); // Default to DES mode
     }
 
     /**
-     * Inicia o processo com opção de ativar o rastreio DES.
-     * * @param useDES Se verdadeiro, ativa a thread do processador de eventos.
+     * Starts the exit node process.
+     * 
+     * @param useDES If true, starts event processor for DES mode tracking
      */
     public void start(boolean useDES) throws IOException {
         int port = config.getExitPort();
@@ -297,15 +310,15 @@ public class ExitNodeProcess {
 
         System.out.println("Exit node started on port " + port);
         if (useDES) {
+            // Note: ExitNode is primarily reactive (network-driven), but maintains
+            // event queue for simulation end events and history tracking
             System.out.println("Running in DES mode (event history tracking enabled)");
         }
         System.out.println("Waiting for vehicles...\\n");
 
-        // Loop de aceitação principal
         while (running) {
             try {
                 Socket clientSocket = serverSocket.accept();
-                // Delega o processamento da conexão para o Thread Pool
                 connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket));
             } catch (IOException e) {
                 if (running) {
@@ -316,11 +329,12 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Worker method para tratar uma conexão persistente vinda de uma interseção.
-     * <p>
-     * Mantém o socket aberto e consome mensagens num loop até que a conexão seja fechada
-     * pelo remetente. Responsável pela desserialização polimórfica (JSON/Gson).
-     * * @param clientSocket O socket conectado.
+     * Trata uma ligação de uma interseção.
+     * 
+     * Mantemos a ligação aberta e escutamos por mensagens `VEHICLE_TRANSFER`.
+     * Cada mensagem contém um veículo que acabou de terminar a sua viagem.
+     * 
+     * @param clientSocket O socket ligado à interseção.
      */
     private void handleIncomingConnection(Socket clientSocket) {
         String clientAddress = clientSocket.getInetAddress().getHostAddress();
@@ -336,14 +350,14 @@ public class ExitNodeProcess {
                             " from " + message.getSourceNode());
 
                     if (message.getType() == MessageType.SIMULATION_START) {
-                        // Sincronização de relógio com o Coordenador
+                        // Coordinator sends start time - use it instead of our local start
                         simulationStartMillis = ((Number) message.getPayload()).longValue();
                         System.out.println("[Exit] Simulation start time synchronized");
                     } else if (message.getType() == MessageType.VEHICLE_TRANSFER) {
                         Object payload = message.getPayload();
                         System.out.println("[Exit] Payload type: " + payload.getClass().getName());
 
-                        // Tratamento de artefatos de desserialização do Gson (LinkedTreeMap -> POJO)
+                        // Handle Gson LinkedHashMap
                         Vehicle vehicle;
                         if (payload instanceof com.google.gson.internal.LinkedTreeMap ||
                                 payload instanceof java.util.LinkedHashMap) {
@@ -376,21 +390,26 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Processa atomicamente a saída de um veículo.
-     * <p>
-     * <b>Secção Crítica:</b> Método {@code synchronized} para garantir que a atualização
-     * das estatísticas globais (totalSystemTime, contadores) é atómica, prevenindo
-     * Race Conditions quando múltiplos veículos chegam simultaneamente de interseções diferentes.
-     * * @param vehicle O veículo que completou a rota.
+     * Processa um veículo que acabou de sair do sistema.
+     * 
+     * Calculamos quanto tempo demorou, atualizamos as nossas estatísticas globais e
+     * notificamos o dashboard.
+     * Este método é sincronizado porque múltiplos veículos podem chegar ao mesmo
+     * tempo.
+     * 
+     * @param vehicle O veículo que completou a sua rota.
      */
     private synchronized void processExitingVehicle(Vehicle vehicle) {
         totalVehiclesReceived++;
 
-        // Cálculo de métricas finais baseadas no tempo virtual de simulação acumulado no veículo
+        // Use simulation time instead of wall-clock time
+        // System time = total time vehicle spent in system (wait + crossing times)
+        // This represents the actual simulation time elapsed, not real-time
         double waitTime = vehicle.getTotalWaitingTime();
         double crossingTime = vehicle.getTotalCrossingTime();
         double systemTime = waitTime + crossingTime;
 
+        // Store times in seconds, will be converted to ms when sending to dashboard
         totalSystemTime += systemTime;
         totalWaitingTime += waitTime;
         totalCrossingTime += crossingTime;
@@ -402,20 +421,23 @@ public class ExitNodeProcess {
         System.out.printf("[Exit] Vehicle %s completed (type=%s, system_time=%.2fs, wait=%.2fs, crossing=%.2fs)%n",
                 vehicle.getId(), vehicle.getType(), systemTime, waitTime, crossingTime);
 
-        // Logging estruturado
+        // Log vehicle exit
         EventLogger.getInstance().logVehicle(EventType.VEHICLE_EXITED, "ExitNode", vehicle.getId(),
                 String.format("Completed - System: %.2fs, Wait: %.2fs, Crossing: %.2fs", systemTime, waitTime,
                         crossingTime));
 
-        // Finaliza o trace individual do veículo
+        // Complete vehicle trace if tracking
         VehicleTracer.getInstance().logExit(vehicle, systemTime);
 
-        // Push imediato para o Dashboard para visualização em tempo real
+        // Send stats after every vehicle to ensure dashboard updates quickly
         sendStatsToDashboard();
     }
 
     /**
-     * Constrói e transmite o DTO de atualização de estatísticas.
+     * Envia as estatísticas mais recentes para o dashboard.
+     * 
+     * Empacotamos as contagens totais e os tempos médios num `StatsUpdatePayload`
+     * e enviamo-lo.
      */
     private void sendStatsToDashboard() {
         if (dashboardClient == null || !dashboardClient.isConnected()) {
@@ -426,28 +448,29 @@ public class ExitNodeProcess {
             // Create stats payload
             StatsUpdatePayload payload = new StatsUpdatePayload();
 
-            // Set global stats - convert seconds to milliseconds for display consistency
+            // Set global stats - convert seconds to milliseconds
             payload.setTotalVehiclesCompleted(totalVehiclesReceived);
-            payload.setTotalSystemTime((long) (totalSystemTime * 1000.0));
-            payload.setTotalWaitingTime((long) (totalWaitingTime * 1000.0));
+            payload.setTotalSystemTime((long) (totalSystemTime * 1000.0)); // s -> ms
+            payload.setTotalWaitingTime((long) (totalWaitingTime * 1000.0)); // s -> ms
 
-            // Hack: Usar campos de interseção para mostrar throughput no dashboard
+            // Set intersection-like stats so it shows up correctly in the dashboard table
             payload.setIntersectionArrivals(totalVehiclesReceived);
             payload.setIntersectionDepartures(totalVehiclesReceived);
             payload.setIntersectionQueueSize(0);
 
-            // Detailed breakdown
+            // Set vehicle type stats
             Map<VehicleType, Integer> typeCounts = new HashMap<>();
             Map<VehicleType, Long> typeWaitTimes = new HashMap<>();
 
             for (VehicleType type : VehicleType.values()) {
                 typeCounts.put(type, vehicleTypeCount.get(type));
-                typeWaitTimes.put(type, (long) (vehicleTypeWaitTime.get(type) * 1000.0));
+                typeWaitTimes.put(type, (long) (vehicleTypeWaitTime.get(type) * 1000.0)); // s -> ms
             }
 
             payload.setVehicleTypeCounts(typeCounts);
             payload.setVehicleTypeWaitTimes(typeWaitTimes);
 
+            // Send message
             Message message = new Message(
                     MessageType.STATS_UPDATE,
                     "ExitNode",
@@ -466,8 +489,9 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Encerramento gracioso do processo.
-     * Fecha sockets, termina a pool de threads e liberta recursos.
+     * Encerra graciosamente o processo.
+     * 
+     * Imprimimos as estatísticas finais, fechamos ligações e limpamos threads.
      */
     public void shutdown() {
         System.out.println("\n[Exit] Shutting down...");
@@ -503,7 +527,9 @@ public class ExitNodeProcess {
     }
 
     /**
-     * Imprime o relatório final no stdout.
+     * Imprime um resumo dos resultados da simulação na consola.
+     * Isto dá-nos uma visão rápida de como a simulação correu (médias, contagens de
+     * veículos, etc.).
      */
     private void printFinalStatistics() {
         System.out.println("\n=== EXIT NODE STATISTICS ===");

main/src/main/java/sd/IntersectionProcess.java

@@ -33,22 +33,19 @@ import sd.protocol.SocketConnection;
 import sd.serialization.SerializationException;
 
 /**
- * Representa um nó de processamento autónomo na malha de simulação distribuída
- * (Worker Node).
- * <p>
- * Esta classe implementa a lógica de uma interseção rodoviária utilizando uma
- * arquitetura híbrida:
- * <ol>
- * <li><b>Reativa (Network I/O):</b> Threads dedicadas aceitam conexões TCP e
- * injetam veículos nas filas de entrada assim que chegam.</li>
- * <li><b>Proativa (DES Engine):</b> Uma thread de processamento de eventos gere
- * a lógica temporal (mudança de semáforos, tempos de travessia) baseada num
- * relógio virtual monotónico.</li>
- * </ol>
- * <p>
- * A sincronização entre a chegada assíncrona de veículos (Rede) e o
- * processamento determinístico (DES) é gerida através de estruturas de dados
- * concorrentes e bloqueios justos (Fair Locks).
+ * Representa uma única interseção na nossa simulação de tráfego distribuída.
+ * 
+ * Esta classe opera como um processo independente (uma aplicação Java autónoma)
+ * e é responsável por:
+ * 1. Gerir os semáforos e a sua temporização.
+ * 2. Processar as chegadas e partidas de veículos.
+ * 3. Comunicar com outras interseções e com o dashboard.
+ * 
+ * Utiliza uma abordagem de Simulação de Eventos Discretos (DES), onde as
+ * mudanças de estado (como semáforos a mudar para verde)
+ * são agendadas como eventos numa fila de prioridade, em vez de depender de
+ * loops contínuos ou threads em espera.
+ * Isto garante uma temporização precisa e uma execução eficiente.
  */
 public class IntersectionProcess {
 
@@ -60,56 +57,48 @@ public class IntersectionProcess {
 
     private ServerSocket serverSocket;
 
-    /**
-     * Tabela de encaminhamento dinâmico para conexões de saída (Next-Hop Cache).
-     */
     private final Map<String, SocketConnection> outgoingConnections;
 
-    /** Pool de threads para tratamento de I/O de rede (entrada de veículos). */
     private final ExecutorService connectionHandlerPool;
 
     private ScheduledExecutorService statsExecutor;
     private ScheduledExecutorService departureExecutor;
 
     private volatile boolean running;
-    /** Fator de dilatação temporal (0.0 = Velocidade Máxima, 1.0 = Tempo Real). */
+    /** Escala temporal para visualização: tempo_real = tempo_simulado * escala */
     private double timeScale;
 
-    // --- Componentes DES (Simulação de Eventos Discretos) ---
-    /** Relógio central virtual da interseção. */
+    /** Relógio central da simulação */
     private final SimulationClock clock;
-    /** Fila de prioridade (Min-Heap) para agendamento temporal de eventos. */
+    /** Fila de eventos discretos agendados */
     private final EventQueue eventQueue;
+    /** Sistema de registo de eventos */
     private final EventLogger eventLogger;
-    /** Thread "Single-Writer" responsável pela mutação de estado da simulação. */
+    /** Thread dedicada ao processamento sequencial de eventos DES */
     private Thread eventProcessorThread;
 
     /**
-     * Mecanismo de exclusão mútua para controlo de fases semafóricas.
-     * Configurado com política de justiça (fairness=true) para evitar inanição
-     * (starvation) de direções com menos tráfego.
+     * Lock para exclusão mútua entre semáforos.
+     * Garante que apenas um semáforo pode estar verde de cada vez nesta interseção.
      */
     private final Lock trafficCoordinationLock;
 
     /**
-     * Estado volátil que indica a direção ativa. Apenas uma direção pode deter o
-     * token 'Green' por vez.
+     * Regista qual direção tem atualmente o sinal verde.
+     * {@code null} significa que todos os semáforos estão vermelhos.
      */
     private volatile String currentGreenDirection;
 
     private SocketClient dashboardClient;
-
-    // Métricas voláteis para acesso atómico sem bloqueio
     private volatile int totalArrivals = 0;
     private volatile int totalDepartures = 0;
 
     /**
-     * Inicializa o processo da interseção, carregando a topologia e preparando o
-     * motor DES.
+     * Inicializa o processo da interseção.
      * 
-     * @param intersectionId O identificador único na malha (ex: "Cr1").
-     * @param configFilePath Caminho para o ficheiro de propriedades.
-     * @throws IOException Se falhar o bind da porta ou leitura de config.
+     * @param intersectionId O identificador único para esta interseção (ex: "Cr1").
+     * @param configFilePath O caminho para o ficheiro de configuração.
+     * @throws IOException Se houver algum problema ao ler a configuração.
      */
     public IntersectionProcess(String intersectionId, String configFilePath) throws IOException {
         this.intersectionId = intersectionId;
@@ -138,16 +127,13 @@ public class IntersectionProcess {
     }
 
     /**
-     * Inicia o ciclo principal do motor de simulação (DES Engine Loop).
-     * <p>
-     * Executa o ciclo "Fetch-Decode-Execute":
-     * <ol>
-     * <li>Remove o evento com menor timestamp da fila (Fetch).</li>
-     * <li>Avança o relógio virtual para o tempo do evento.</li>
-     * <li>Aplica atraso artificial se {@code timeScale > 0} (para visualização
-     * humana).</li>
-     * <li>Despacha o evento para o manipulador apropriado (Execute).</li>
-     * </ol>
+     * Inicia o ciclo de processamento de eventos.
+     * 
+     * Esta thread é o coração do modelo DES para esta interseção. Retira eventos da
+     * fila
+     * e executa-os por ordem cronológica. Enquanto a thread principal trata das
+     * operações de I/O de rede (receção de veículos),
+     * esta thread trata da lógica da simulação (semáforos, travessias de veículos).
      */
     private void startEventProcessor() {
         eventProcessorThread = new Thread(() -> {
@@ -159,9 +145,9 @@ public class IntersectionProcess {
             while (running) {
                 SimulationEvent event = eventQueue.poll();
                 if (event == null) {
-                    // Backoff exponencial ou sleep curto para evitar busy-waiting em idle
+                    // No events currently, wait a bit before checking again
                     try {
-                        Thread.sleep(50);
+                        Thread.sleep(50); // Short sleep to avoid busy-waiting
                     } catch (InterruptedException e) {
                         Thread.currentThread().interrupt();
                         break;
@@ -169,7 +155,7 @@ public class IntersectionProcess {
                     continue;
                 }
 
-                // Aplicação de escala temporal (Throttle)
+                // Apply time scaling for visualization
                 if (timeScale > 0) {
                     double simTimeDelta = event.getTimestamp() - lastTime;
                     long realDelayMs = (long) (simTimeDelta * timeScale * 1000);
@@ -184,10 +170,10 @@ public class IntersectionProcess {
                     lastTime = event.getTimestamp();
                 }
 
-                // Atualização atómica do tempo de simulação
+                // Advance clock to event time
                 clock.advanceTo(event.getTimestamp());
 
-                // Processamento polimórfico
+                // Process the event
                 processEvent(event);
             }
 
@@ -199,12 +185,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Despachante central de eventos.
-     * <p>
-     * Encaminha o evento para a lógica de negócio específica baseada no tipo
-     * {@link DESEventType}.
+     * Processa um evento da fila de simulação.
+     * Cada tipo de evento é encaminhado para o seu tratador específico.
      * 
-     * @param event O evento de simulação a ser processado.
+     * @param event o evento a processar
      */
     private void processEvent(SimulationEvent event) {
         try {
@@ -214,8 +198,8 @@ public class IntersectionProcess {
                     break;
 
                 case VEHICLE_ARRIVAL:
-                    // Chegadas são tratadas reativamente via Socket, mas eventos podem ser usados
-                    // para métricas
+                    // Vehicle arrivals are still handled via network messages
+                    // This event type is for internal scheduling if needed
                     break;
 
                 case VEHICLE_CROSSING_START:
@@ -241,18 +225,12 @@ public class IntersectionProcess {
     }
 
     /**
-     * Gere a máquina de estados dos semáforos.
-     * <p>
-     * O fluxo de execução é o seguinte:
-     * <ol>
-     * <li>Atualiza o estado do semáforo (Verde <-> Vermelho).</li>
-     * <li>Se o novo estado for Verde: Calcula a capacidade de vazão e agenda
-     * travessias (Service Events).</li>
-     * <li>Agenda recursivamente a próxima mudança de estado para manter o ciclo
-     * infinito.</li>
-     * </ol>
+     * Trata da mudança dos semáforos.
      * 
-     * @param event O evento que desencadeou a mudança de estado.
+     * Quando um semáforo muda de estado, registamos o evento, atualizamos o modelo
+     * e, se tiver mudado para VERDE,
+     * verificamos imediatamente se há veículos à espera para atravessar.
+     * Também agendamos aqui o *próximo* evento de mudança, mantendo o ciclo ativo.
      */
     private void handleTrafficLightChangeEvent(SimulationEvent event) {
         TrafficLightEvent tlEvent = (TrafficLightEvent) event.getPayload();
@@ -274,12 +252,12 @@ public class IntersectionProcess {
                 String.format("Direction %s changed to %s at time %.2f",
                         direction, newState, event.getTimestamp()));
 
-        // Processamento de lote (Batch Processing) para a fase Verde
+        // If light turned GREEN, process queued vehicles
         if (newState == TrafficLightState.GREEN) {
             processQueuedVehiclesForLight(light, event.getTimestamp());
         }
 
-        // Agendamento do próximo ciclo (Feedback Loop)
+        // Schedule next state change
         double nextChangeTime = event.getTimestamp() +
                 (newState == TrafficLightState.GREEN ? light.getGreenTime() : light.getRedTime());
 
@@ -291,19 +269,23 @@ public class IntersectionProcess {
     }
 
     /**
-     * Calcula a vazão da interseção durante uma fase verde.
+     * Processa a fila de veículos quando um semáforo fica verde.
+     * 
      * <p>
-     * Implementa uma lógica de previsão ("Look-ahead"):
+     * Para cada veículo na fila:
+     * </p>
      * <ol>
-     * <li>Itera sobre a fila de espera do semáforo.</li>
-     * <li>Calcula o tempo de serviço acumulado (Service Time) baseado no tipo de
-     * veículo.</li>
-     * <li>Agenda a partida apenas se o veículo couber na janela temporal restante
-     * do sinal verde.</li>
+     * <li>Calcula o tempo de travessia com base no tipo de veículo</li>
+     * <li>Verifica se cabe na duração restante do sinal verde</li>
+     * <li>Agenda o evento de partida do veículo</li>
      * </ol>
      * 
-     * @param light       O semáforo ativo.
-     * @param currentTime O instante de início da fase verde.
+     * <p>
+     * Os veículos que não couberem no tempo verde ficam à espera do próximo ciclo.
+     * </p>
+     * 
+     * @param light       o semáforo que acabou de ficar verde
+     * @param currentTime o tempo atual da simulação em segundos
      */
     private void processQueuedVehiclesForLight(TrafficLight light, double currentTime) {
         double greenDuration = light.getGreenTime();
@@ -313,29 +295,30 @@ public class IntersectionProcess {
         System.out.printf("[%s] Processing queue for %s (GREEN for %.2fs, queue size: %d, currentTime=%.2f)%n",
                 intersectionId, light.getId(), greenDuration, queueSize, currentTime);
 
-        // Algoritmo de esvaziamento de fila baseado em Time Budget
+        // Process vehicles while queue not empty and within green light duration
         while (light.getQueueSize() > 0) {
-            // Estimativa inicial (optimista)
+            // Calculate crossing time for next vehicle (peek at queue size to estimate)
+            // We'll use LIGHT vehicle as default for estimation
             double crossingTime = config.getLightVehicleCrossingTime();
 
-            // Verificação de limite de tempo (Hard Deadline do sinal vermelho)
+            // Check if another vehicle can fit in remaining green time
             if (timeOffset + crossingTime > greenDuration) {
-                break; // Veículo não cabe no ciclo atual
+                break; // No more vehicles can cross this green phase
             }
 
-            // Commit: Remove da fila
+            // Remove vehicle from queue with current simulation time
             Vehicle vehicle = light.removeVehicle(currentTime + timeOffset);
             if (vehicle == null)
                 break;
 
-            // Recálculo preciso baseado no tipo real do veículo
+            // Get actual crossing time for this vehicle
             crossingTime = getCrossingTimeForVehicle(vehicle);
 
-            // Agendamento do evento futuro de término de travessia
+            // Schedule crossing
             double crossingStartTime = currentTime + timeOffset;
             scheduleVehicleCrossing(vehicle, crossingStartTime, crossingTime);
 
-            // Incrementa offset para serializar as travessias (Head-of-Line Blocking)
+            // Update offset for next vehicle
             timeOffset += crossingTime;
 
             System.out.printf("[%s] Scheduled vehicle %s to cross at t=%.2f (duration=%.2fs)%n",
@@ -344,11 +327,12 @@ public class IntersectionProcess {
     }
 
     /**
-     * Cria e agenda o evento de conclusão de travessia (Partida).
+     * Agenda a travessia e partida de um veículo.
+     * Cria um evento de fim de travessia agendado para o tempo correto.
      * 
-     * @param vehicle          O veículo que está a atravessar.
-     * @param startTime        Instante de início da travessia.
-     * @param crossingDuration Duração estimada da travessia.
+     * @param vehicle          o veículo que vai atravessar
+     * @param startTime        quando a travessia começa (segundos de simulação)
+     * @param crossingDuration quanto tempo demora a atravessar (segundos)
      */
     private void scheduleVehicleCrossing(Vehicle vehicle, double startTime, double crossingDuration) {
         // Schedule crossing end (when vehicle departs)
@@ -367,10 +351,11 @@ public class IntersectionProcess {
     }
 
     /**
-     * Determina o custo temporal da travessia baseado na física do veículo.
+     * Calcula o tempo de travessia com base no tipo de veículo.
+     * Bicicletas são mais rápidas, veículos pesados mais lentos.
      * 
-     * @param vehicle O veículo em questão.
-     * @return O tempo em segundos necessário para atravessar a interseção.
+     * @param vehicle o veículo para calcular o tempo
+     * @return tempo de travessia em segundos
      */
     private double getCrossingTimeForVehicle(Vehicle vehicle) {
         return switch (vehicle.getType()) {
@@ -382,45 +367,36 @@ public class IntersectionProcess {
     }
 
     /**
-     * Manipula o evento de início de travessia de um veículo.
-     * <p>
-     * Atualmente serve como placeholder para lógica futura de animação ou
-     * ocupação de zonas críticas na interseção.
+     * Trata o evento de início de travessia de um veículo.
+     * (Implementação futura - atualmente apenas regista o evento)
      * 
-     * @param event O evento de início de travessia.
+     * @param event o evento de início de travessia
      */
     private void handleVehicleCrossingStartEvent(SimulationEvent event) {
-        // Placeholder para lógica futura de animação ou ocupação de zona crítica
+        // Implementation will depend on how vehicle crossing is modeled
+        // For now, log the event
         eventLogger.log(sd.logging.EventType.VEHICLE_DEPARTED, intersectionId,
                 "Vehicle crossing started at time " + event.getTimestamp());
     }
 
     /**
-     * Finaliza a lógica de travessia e inicia a transferência (handover) para o
-     * próximo nó.
-     * <p>
-     * Este método é invocado quando o tempo de travessia expira no relógio virtual.
-     * Executa as seguintes ações:
-     * <ol>
-     * <li>Atualiza as métricas de tempo de travessia do veículo.</li>
-     * <li>Incrementa contadores locais de veículos processados.</li>
-     * <li>Transfere a responsabilidade do veículo para a rede, enviando-o ao
-     * próximo destino.</li>
-     * </ol>
+     * Trata o fim da travessia de um veículo pela interseção.
+     * Atualiza estatísticas, regista o tempo de travessia e envia o veículo
+     * para o próximo destino na sua rota.
      * 
-     * @param event O evento de fim de travessia.
+     * @param event evento contendo o veículo que terminou a travessia
      */
     private void handleVehicleCrossingEndEvent(SimulationEvent event) {
         Vehicle vehicle = (Vehicle) event.getPayload();
 
-        // Atualiza métricas do veículo
+        // Add crossing time to vehicle stats
         double crossingTime = getCrossingTimeForVehicle(vehicle);
         vehicle.addCrossingTime(crossingTime);
 
-        // Atualiza métricas locais
+        // Update intersection statistics
         intersection.incrementVehiclesSent();
 
-        // Handover: Transfere a responsabilidade do veículo para a rede
+        // Send vehicle to next destination
         sendVehicleToNextDestination(vehicle);
 
         eventLogger.log(sd.logging.EventType.VEHICLE_DEPARTED, intersectionId,
@@ -428,9 +404,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Finaliza a execução do processo de simulação.
+     * Trata o evento de fim da simulação.
+     * Define a flag de execução como falsa para terminar o processamento.
      * 
-     * @param event O evento de fim de simulação.
+     * @param event o evento de fim de simulação
      */
     private void handleSimulationEndEvent(SimulationEvent event) {
         eventLogger.log(sd.logging.EventType.SIMULATION_STOPPED, intersectionId,
@@ -439,9 +416,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Exporta o histórico completo de eventos para análise post-mortem.
+     * Exporta o histórico completo de eventos para um ficheiro.
+     * Útil para análise posterior e debugging da simulação.
      * 
-     * @param outputPath O caminho do ficheiro onde o histórico será guardado.
+     * @param outputPath caminho do ficheiro onde guardar o histórico
      */
     public void exportEventHistory(String outputPath) {
         String history = eventQueue.exportEventHistory();
@@ -453,12 +431,7 @@ public class IntersectionProcess {
         }
     }
 
-    /**
-     * Ponto de entrada principal da aplicação.
-     *
-     * @param args Argumentos da linha de comando (ID da interseção e ficheiro de
-     *             configuração opcional).
-     */
+    // Main entry point for running an intersection process
     public static void main(String[] args) {
         if (args.length < 1) {
             System.err.println("Usage: java IntersectionProcess <intersectionId> [configFile]");
@@ -487,12 +460,6 @@ public class IntersectionProcess {
         }
     }
 
-    /**
-     * Realiza o bootstrap dos componentes lógicos e de rede da interseção.
-     * <p>
-     * Inclui a criação de semáforos, configuração de encaminhamento e conexão ao
-     * Dashboard.
-     */
     public void initialize() {
         System.out.println("\n[" + intersectionId + "] Initializing intersection...");
 
@@ -506,7 +473,7 @@ public class IntersectionProcess {
     }
 
     /**
-     * Estabelece a conexão com o Dashboard para envio de telemetria em tempo real.
+     * Estabelece ligação ao servidor do dashboard para reportar estatísticas.
      */
     private void connectToDashboard() {
         try {
@@ -530,7 +497,9 @@ public class IntersectionProcess {
     }
 
     /**
-     * Inicializa os semáforos da interseção com base na configuração carregada.
+     * Cria os semáforos para esta interseção com base nas suas ligações físicas.
+     * Cada interseção tem um número e direções de semáforos diferentes de acordo
+     * com a topologia da rede.
      */
     private void createTrafficLights() {
         System.out.println("\n[" + intersectionId + "] Creating traffic lights...");
@@ -559,13 +528,6 @@ public class IntersectionProcess {
         }
     }
 
-    /**
-     * Obtém a configuração específica para esta interseção a partir da configuração
-     * global.
-     *
-     * @return O objeto de configuração da interseção.
-     * @throws RuntimeException Se a configuração estiver em falta.
-     */
     private SimulationConfig.IntersectionConfig getIntersectionConfig() {
         if (config.getNetworkConfig() == null || config.getNetworkConfig().getIntersections() == null) {
             throw new RuntimeException("Network configuration not loaded or empty.");
@@ -576,11 +538,6 @@ public class IntersectionProcess {
                 .orElseThrow(() -> new RuntimeException("Intersection config not found for " + intersectionId));
     }
 
-    /**
-     * Configura a tabela de encaminhamento (routing) da interseção.
-     * <p>
-     * Define para cada destino qual a direção de saída (semáforo) correspondente.
-     */
     private void configureRouting() {
         System.out.println("\n[" + intersectionId + "] Configuring routing...");
 
@@ -602,10 +559,11 @@ public class IntersectionProcess {
     }
 
     /**
-     * Primitiva de bloqueio: Solicita acesso exclusivo à zona crítica da
-     * interseção.
+     * Solicita permissão para um semáforo ficar verde.
+     * Bloqueia até que a permissão seja concedida (nenhum outro semáforo está
+     * verde).
      * 
-     * @param direction A direção que solicita passagem.
+     * @param direction A direção que solicita o sinal verde
      */
     public void requestGreenLight(String direction) {
         trafficCoordinationLock.lock();
@@ -613,9 +571,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Primitiva de bloqueio: Liberta o acesso exclusivo à zona crítica.
+     * Liberta a permissão de sinal verde, permitindo que outro semáforo fique
+     * verde.
      * 
-     * @param direction A direção que está a libertar a passagem.
+     * @param direction A direção que liberta o sinal verde
      */
     public void releaseGreenLight(String direction) {
         if (direction.equals(currentGreenDirection)) {
@@ -625,10 +584,8 @@ public class IntersectionProcess {
     }
 
     /**
-     * Inicializa o estado dos semáforos no arranque da simulação (t=0).
-     * <p>
-     * Garante que apenas um semáforo começa em Verde e os restantes em Vermelho,
-     * agendando os eventos iniciais na fila do DES.
+     * Modo DES: Agenda os eventos iniciais de mudança de semáforo.
+     * Isto substitui a antiga abordagem baseada em threads startTrafficLights().
      */
     private void scheduleInitialTrafficLightEvents() {
         System.out.println("\n[" + intersectionId + "] Scheduling initial traffic light events (DES mode)...");
@@ -639,12 +596,12 @@ public class IntersectionProcess {
         for (TrafficLight light : intersection.getTrafficLights()) {
             String direction = light.getDirection();
 
-            // Lógica de arranque: Primeiro da lista = Verde, outros = Vermelho
+            // Set initial state (first light starts green, others red)
             boolean isFirstLight = intersection.getTrafficLights().indexOf(light) == 0;
             TrafficLightState initialState = isFirstLight ? TrafficLightState.GREEN : TrafficLightState.RED;
             light.changeState(initialState);
 
-            // Agenda a primeira transição
+            // Schedule first state change
             double firstChangeTime = currentTime +
                     (initialState == TrafficLightState.GREEN ? light.getGreenTime() : light.getRedTime());
 
@@ -667,16 +624,14 @@ public class IntersectionProcess {
     }
 
     /**
-     * Encaminhamento de rede: Serializa e envia o objeto veículo para o próximo nó.
-     * <p>
-     * Calcula também o tempo de viagem virtual entre nós (Edge Weight).
+     * Envia um veículo para o seu próximo destino via ligação socket.
      *
-     * @param vehicle O veículo a ser enviado.
+     * @param vehicle O veículo que atravessou esta interseção.
      */
     public void sendVehicleToNextDestination(Vehicle vehicle) {
         String nextDestination = vehicle.getCurrentDestination();
 
-        // Cálculo de latência de viagem (Edge Weight)
+        // Calculate travel time
         double baseTime = config.getBaseTravelTime();
         double multiplier = 1.0;
         switch (vehicle.getType()) {
@@ -689,25 +644,22 @@ public class IntersectionProcess {
         System.out.printf("[%s] Vehicle %s departing to %s. Travel time: %.2fs%n",
                 intersectionId, vehicle.getId(), nextDestination, travelTime);
 
+        // Record departure immediately as it leaves the intersection
         recordVehicleDeparture();
 
-        // Envio imediato (o delay de viagem é implícito no tempo de chegada no próximo
-        // nó ou simulado aqui)
+        // In DES mode, send immediately (no real-time delay)
         sendVehicleImmediately(vehicle, nextDestination);
     }
 
     /**
-     * Envia o veículo imediatamente para o próximo nó via conexão TCP persistente.
-     *
-     * @param vehicle         O veículo a ser enviado.
-     * @param nextDestination O identificador do próximo nó destino.
+     * Envia imediatamente um veículo para o seu destino via rede.
      */
     private void sendVehicleImmediately(Vehicle vehicle, String nextDestination) {
         try {
-            // Lazy loading da conexão
+            // Get or create connection to next destination
             SocketConnection connection = getOrCreateConnection(nextDestination);
 
-            // Encapsulamento da mensagem
+            // Create and send message using Message class
             MessageProtocol message = new Message(
                     MessageType.VEHICLE_TRANSFER,
                     intersectionId,
@@ -720,6 +672,8 @@ public class IntersectionProcess {
             System.out.println("[" + intersectionId + "] Vehicle " + vehicle.getId() +
                     " arrived at " + nextDestination + " (msg sent)");
 
+            // Note: vehicle route is advanced when it arrives at the next intersection
+
         } catch (IOException | InterruptedException e) {
             System.err.println("[" + intersectionId + "] Failed to send vehicle " +
                     vehicle.getId() + " to " + nextDestination + ": " + e.getMessage());
@@ -727,15 +681,12 @@ public class IntersectionProcess {
     }
 
     /**
-     * Obtém ou cria uma conexão para o destino especificado (Singleton por
-     * destino).
-     * <p>
-     * Este método é thread-safe.
+     * Obtém uma ligação existente para um destino ou cria uma nova.
      *
-     * @param destinationId O identificador do nó destino.
-     * @return A conexão TCP estabelecida.
-     * @throws IOException          Se ocorrer um erro de I/O na criação da conexão.
-     * @throws InterruptedException Se a thread for interrompida durante a espera.
+     * @param destinationId O ID do nó de destino.
+     * @return A SocketConnection para esse destino.
+     * @throws IOException          Se a ligação não puder ser estabelecida.
+     * @throws InterruptedException Se a tentativa de ligação for interrompida.
      */
     private synchronized SocketConnection getOrCreateConnection(String destinationId)
             throws IOException, InterruptedException {
@@ -755,10 +706,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Resolve o hostname ou endereço IP para um determinado destino.
+     * Obtém o endereço host para um nó de destino a partir da configuração.
      *
-     * @param destinationId O ID do destino.
-     * @return O endereço do host.
+     * @param destinationId O ID do nó de destino.
+     * @return O endereço host.
      */
     private String getHostForDestination(String destinationId) {
         if (destinationId.equals("S")) {
@@ -769,9 +720,9 @@ public class IntersectionProcess {
     }
 
     /**
-     * Resolve a porta TCP para um determinado destino.
+     * Obtém o número da porta para um nó de destino a partir da configuração.
      *
-     * @param destinationId O ID do destino.
+     * @param destinationId O ID do nó de destino.
      * @return O número da porta.
      */
     private int getPortForDestination(String destinationId) {
@@ -783,11 +734,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Inicia o servidor e o loop de aceitação de conexões.
-     * <p>
-     * Este método bloqueia a thread chamadora durante a execução do servidor.
+     * Inicia o socket do servidor e começa a aceitar ligações recebidas.
+     * Este é o loop principal de escuta do processo.
      *
-     * @throws IOException Se ocorrer um erro ao fazer bind da porta.
+     * @throws IOException Se o socket do servidor não puder ser criado.
      */
     public void start() throws IOException {
         int port = config.getIntersectionPort(intersectionId);
@@ -801,12 +751,12 @@ public class IntersectionProcess {
         startEventProcessor();
         System.out.println("[" + intersectionId + "] Running in DES mode");
 
-        // Background task para telemetria
+        // Start stats updater
         statsExecutor.scheduleAtFixedRate(this::sendStatsToDashboard, 1, 1, TimeUnit.SECONDS);
 
         System.out.println("[" + intersectionId + "] Waiting for incoming connections...\n");
 
-        // Loop principal de aceitação de conexões
+        // Main accept loop
         while (running) {
             try {
                 Socket clientSocket = serverSocket.accept();
@@ -814,12 +764,13 @@ public class IntersectionProcess {
                 System.out.println("[" + intersectionId + "] New connection accepted from " +
                         clientSocket.getInetAddress().getHostAddress());
 
+                // Check running flag again before handling
                 if (!running) {
                     clientSocket.close();
                     break;
                 }
 
-                // Configura timeout para evitar bloqueios infinitos em leitura
+                // **Set timeout before submitting to handler**
                 try {
                     clientSocket.setSoTimeout(1000);
                 } catch (java.net.SocketException e) {
@@ -828,12 +779,13 @@ public class IntersectionProcess {
                     continue;
                 }
 
-                // Delega processamento para thread pool (NIO style)
+                // Handle each connection in a separate thread
                 connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket));
 
             } catch (IOException e) {
+                // Expected when serverSocket.close() is called during shutdown
                 if (!running) {
-                    break; // Shutdown normal
+                    break; // Normal shutdown
                 }
                 System.err.println("[" + intersectionId + "] Error accepting connection: " +
                         e.getMessage());
@@ -842,13 +794,10 @@ public class IntersectionProcess {
     }
 
     /**
-     * Lógica de tratamento de conexões de entrada (Consumer).
-     * <p>
-     * Lê continuamente do socket até que a conexão seja fechada, processando
-     * mensagens
-     * de chegada de veículos ou comandos de simulação.
+     * Trata uma ligação recebida de outro processo.
+     * Escuta continuamente mensagens de transferência de veículos.
      *
-     * @param clientSocket O socket do cliente conectado.
+     * @param clientSocket A ligação socket aceite.
      */
     private void handleIncomingConnection(Socket clientSocket) {
         try {
@@ -864,24 +813,27 @@ public class IntersectionProcess {
             System.out.println("[" + intersectionId + "] New connection accepted from " +
                     clientSocket.getInetAddress().getHostAddress());
 
+            // Continuously receive messages while connection is active
             while (running && connection.isConnected()) {
                 try {
                     MessageProtocol message = connection.receiveMessage();
 
+                    // Handle simulation start time synchronization
                     if (message.getType() == MessageType.SIMULATION_START) {
                         System.out.println("[" + intersectionId + "] Simulation start time synchronized");
                         continue;
                     }
 
+                    // Accept both VEHICLE_TRANSFER and VEHICLE_SPAWN (from coordinator)
                     if (message.getType() == MessageType.VEHICLE_TRANSFER ||
                             message.getType() == MessageType.VEHICLE_SPAWN) {
-
-                        // Lógica de desserialização polimórfica (Vehicle ou Map)
+                        // Cast payload to Vehicle - handle Gson deserialization
                         Vehicle vehicle;
                         Object payload = message.getPayload();
                         if (payload instanceof Vehicle) {
                             vehicle = (Vehicle) payload;
                         } else if (payload instanceof java.util.Map) {
+                            // Gson deserialized as LinkedHashMap - re-serialize and deserialize as Vehicle
                             com.google.gson.Gson gson = new com.google.gson.Gson();
                             String json = gson.toJson(payload);
                             vehicle = gson.fromJson(json, Vehicle.class);
@@ -893,37 +845,43 @@ public class IntersectionProcess {
                         System.out.println("[" + intersectionId + "] Received vehicle: " +
                                 vehicle.getId() + " from " + message.getSourceNode());
 
-                        // Lógica de Roteamento Local
+                        // Advance vehicle to next destination in its route
                         vehicle.advanceRoute();
+
+                        // Add vehicle to appropriate queue with current simulation time
                         intersection.receiveVehicle(vehicle, clock.getCurrentTime());
 
+                        // Log queue status after adding vehicle
                         System.out.printf("[%s] Vehicle %s queued. Total queue size: %d%n",
                                 intersectionId, vehicle.getId(), intersection.getTotalQueueSize());
 
+                        // Record arrival for statistics
                         recordVehicleArrival();
-
                     } else if (message.getType() == MessageType.SHUTDOWN) {
                         System.out.println(
                                 "[" + intersectionId + "] Received SHUTDOWN command from " + message.getSourceNode());
                         running = false;
+                        // Close this specific connection
                         break;
                     }
 
                 } catch (java.net.SocketTimeoutException e) {
+                    // Timeout - check running flag and continue
                     if (!running) {
                         break;
                     }
+                    // Continue waiting for next message
                 } catch (ClassNotFoundException e) {
                     System.err.println("[" + intersectionId + "] Unknown message type received: " +
                             e.getMessage());
-                    break;
+                    break; // Invalid message, close connection
                 } catch (IOException e) {
                     if (running) {
                         System.err.println("[" + intersectionId + "] Failed to deserialize message: " +
                                 e.getMessage());
-                        e.printStackTrace();
+                        e.printStackTrace(); // For debugging - maybe change//remove later
                     }
-                    break;
+                    break; // Connection error, close connection
                 }
             }
 
@@ -931,29 +889,27 @@ public class IntersectionProcess {
             if (running) {
                 System.err.println("[" + intersectionId + "] Connection error: " + e.getMessage());
             }
+            // Expected during shutdown
         }
     }
 
     /**
-     * Procedimento de Encerramento Gracioso (Graceful Shutdown).
-     * <ol>
-     * <li>Para a aceitação de novas conexões.</li>
-     * <li>Envia últimas estatísticas.</li>
-     * <li>Encerra pools de threads.</li>
-     * <li>Fecha sockets ativos.</li>
-     * </ol>
+     * Stops the intersection process gracefully.
+     * Shuts down all threads and closes all connections.
      */
     public void shutdown() {
+        // Check if already shutdown
         if (!running) {
-            return;
+            return; // Already shutdown, do nothing
         }
 
         System.out.println("\n[" + intersectionId + "] Shutting down...");
         running = false;
 
+        // Send final stats before closing connections
         sendStatsToDashboard();
 
-        // 1. Close ServerSocket
+        // 1. Close ServerSocket first
         if (serverSocket != null && !serverSocket.isClosed()) {
             try {
                 serverSocket.close();
@@ -962,7 +918,8 @@ public class IntersectionProcess {
             }
         }
 
-        // 2. Shutdown thread pools
+        // 2. Shutdown thread pools with force
+
         if (connectionHandlerPool != null && !connectionHandlerPool.isShutdown()) {
             connectionHandlerPool.shutdownNow();
         }
@@ -973,8 +930,9 @@ public class IntersectionProcess {
             departureExecutor.shutdownNow();
         }
 
-        // 3. Wait briefly for termination
+        // 3. Wait briefly for termination (don't block forever)
         try {
+
             if (connectionHandlerPool != null) {
                 connectionHandlerPool.awaitTermination(1, TimeUnit.SECONDS);
             }
@@ -1010,32 +968,31 @@ public class IntersectionProcess {
     }
 
     /**
-     * Obtém o modelo de dados da interseção.
+     * Gets the Intersection object managed by this process.
+     * Useful for testing and monitoring.
      * 
-     * @return O objeto Intersection.
+     * @return The Intersection object.
      */
     public Intersection getIntersection() {
         return intersection;
     }
 
     /**
-     * Regista a chegada de um novo veículo para fins estatísticos.
+     * Records that a vehicle has arrived at this intersection.
      */
     public void recordVehicleArrival() {
         totalArrivals++;
     }
 
     /**
-     * Regista a partida de um veículo para fins estatísticos.
+     * Records that a vehicle has departed from this intersection.
      */
     public void recordVehicleDeparture() {
         totalDepartures++;
     }
 
     /**
-     * Envia um "snapshot" do estado atual para o Dashboard (Telemetria Push).
-     * <p>
-     * Inclui o número acumulado de chegadas, partidas e o tamanho atual das filas.
+     * Sends current statistics to the dashboard server.
      */
     private void sendStatsToDashboard() {
         if (dashboardClient == null || !dashboardClient.isConnected()) {
@@ -1043,6 +1000,7 @@ public class IntersectionProcess {
         }
 
         try {
+            // Calculate current queue size
             int currentQueueSize = intersection.getTrafficLights().stream()
                     .mapToInt(TrafficLight::getQueueSize)
                     .sum();
@@ -1052,6 +1010,7 @@ public class IntersectionProcess {
                     .setIntersectionDepartures(totalDepartures)
                     .setIntersectionQueueSize(currentQueueSize);
 
+            // Send StatsUpdatePayload directly as the message payload
             sd.model.Message message = new sd.model.Message(
                     MessageType.STATS_UPDATE,
                     intersectionId,

main/src/main/java/sd/dashboard/DashboardUI.java

@@ -30,22 +30,8 @@ import sd.config.SimulationConfig;
 import sd.model.VehicleType;
 
 /**
- * Interface Gráfica (GUI) baseada em JavaFX para visualização de telemetria em tempo real.
- * <p>
- * Esta classe atua como a camada de apresentação (View) do sistema. Implementa o padrão
- * <i>Observer</i> (via polling) para refletir o estado do modelo {@link DashboardStatistics}
- * nos componentes visuais.
- * <p>
- * <b>Aspetos Técnicos Relevantes:</b>
- * <ul>
- * <li><b>Concorrência de UI:</b> Utiliza um {@link ScheduledExecutorService} para buscar dados
- * em background e {@link Platform#runLater(Runnable)} para injetar atualizações na
- * <i>JavaFX Application Thread</i>, evitando exceções de "Not on FX application thread".</li>
- * <li><b>Data Binding:</b> Utiliza {@link TableView} com classes internas (DTOs) para
- * renderização tabular eficiente de tipos de veículos e interseções.</li>
- * <li><b>Controlo de Processos:</b> Integra com {@link SimulationProcessManager} para orquestrar
- * o ciclo de vida (spawn/kill) dos processos externos da simulação.</li>
- * </ul>
+ * JavaFX-based Dashboard UI for displaying real-time simulation statistics.
+ * Provides a graphical interface with auto-updating statistics panels.
  */
 public class DashboardUI extends Application {
 
@@ -66,7 +52,7 @@ public class DashboardUI extends Application {
     // Intersection Table
     private TableView<IntersectionRow> intersectionTable;
 
-    // Update scheduler (Background Thread)
+    // Update scheduler
     private ScheduledExecutorService updateScheduler;
 
     // Configuration controls
@@ -74,10 +60,6 @@ public class DashboardUI extends Application {
     private String selectedConfigFile = "simulation.properties";
     private Label configInfoLabel;
 
-    /**
-     * Ponto de entrada da aplicação JavaFX.
-     * Configura o Stage primário, inicializa o servidor de backend e constrói a árvore de cena (Scene Graph).
-     */
     @Override
     public void start(Stage primaryStage) {
         try {
@@ -90,27 +72,29 @@ public class DashboardUI extends Application {
             server = new DashboardServer(config);
             statistics = server.getStatistics();
 
-            // Start the dashboard server (Backend listening port)
+            // Start the dashboard server
             server.start();
 
-            // Build UI Layout
+            // Build UI
             BorderPane root = new BorderPane();
             root.getStyleClass().add("root");
 
-            // Header (Top)
+            // Header
             VBox header = createHeader();
             root.setTop(header);
 
-            // Main content (Center)
+            // Main content
             VBox mainContent = createMainContent();
             root.setCenter(mainContent);
 
-            // Footer (Bottom)
+            // Footer
             HBox footer = createFooter();
             root.setBottom(footer);
 
-            // Create scene & apply CSS
+            // Create scene
             Scene scene = new Scene(root, 1200, 850);
+
+            // Load CSS
             String cssUrl = getClass().getResource("/dashboard.css").toExternalForm();
             scene.getStylesheets().add(cssUrl);
 
@@ -118,10 +102,10 @@ public class DashboardUI extends Application {
             primaryStage.setScene(scene);
             primaryStage.show();
 
-            // Start periodic updates loop
+            // Start periodic updates
             startPeriodicUpdates();
 
-            // Handle window close (Graceful shutdown)
+            // Handle window close
             primaryStage.setOnCloseRequest(event -> {
                 shutdown();
             });
@@ -165,8 +149,6 @@ public class DashboardUI extends Application {
                 // Passar o ficheiro de configuração selecionado
                 processManager.setConfigFile(selectedConfigFile);
                 processManager.startSimulation();
-                
-                // Toggle UI state
                 btnStart.setDisable(true);
                 btnStop.setDisable(false);
                 configFileSelector.setDisable(true); // Bloquear mudanças durante simulação
@@ -177,8 +159,6 @@ public class DashboardUI extends Application {
 
         btnStop.setOnAction(e -> {
             processManager.stopSimulation();
-            
-            // Toggle UI state
             btnStart.setDisable(false);
             btnStop.setDisable(true);
             configFileSelector.setDisable(false); // Desbloquear para nova simulação
@@ -455,23 +435,13 @@ public class DashboardUI extends Application {
         grid.add(container, colGroup, row);
     }
 
-    /**
-     * Inicia o ciclo de polling em background.
-     * Atualiza a UI a cada 100ms.
-     */
     private void startPeriodicUpdates() {
         updateScheduler = Executors.newSingleThreadScheduledExecutor();
         updateScheduler.scheduleAtFixedRate(() -> {
-            // Crucial: Encapsular atualização de UI em Platform.runLater
-            // para garantir execução na JavaFX Application Thread
             Platform.runLater(this::updateUI);
         }, 0, 100, TimeUnit.MILLISECONDS);
     }
 
-    /**
-     * Sincroniza o estado atual do objeto Statistics com os controlos JavaFX.
-     * Chamado periodicamente pela thread de UI.
-     */
     private void updateUI() {
         // Update global statistics
         lblVehiclesGenerated.setText(String.valueOf(statistics.getTotalVehiclesGenerated()));
@@ -578,9 +548,7 @@ public class DashboardUI extends Application {
         launch(args);
     }
 
-    // --- DTOs para Data Binding nas Tabelas ---
-
-    /** DTO para linhas da tabela de Tipos de Veículo. */
+    // Inner classes for TableView data models
     public static class VehicleTypeRow {
         private final String vehicleType;
         private final int count;
@@ -592,12 +560,19 @@ public class DashboardUI extends Application {
             this.avgWaitTime = avgWaitTime;
         }
 
-        public String getVehicleType() { return vehicleType; }
-        public int getCount() { return count; }
-        public String getAvgWaitTime() { return avgWaitTime; }
+        public String getVehicleType() {
+            return vehicleType;
+        }
+
+        public int getCount() {
+            return count;
+        }
+
+        public String getAvgWaitTime() {
+            return avgWaitTime;
+        }
     }
 
-    /** DTO para linhas da tabela de Interseções. */
     public static class IntersectionRow {
         private final String intersectionId;
         private final int arrivals;
@@ -611,9 +586,20 @@ public class DashboardUI extends Application {
             this.queueSize = queueSize;
         }
 
-        public String getIntersectionId() { return intersectionId; }
-        public int getArrivals() { return arrivals; }
-        public int getDepartures() { return departures; }
-        public int getQueueSize() { return queueSize; }
+        public String getIntersectionId() {
+            return intersectionId;
+        }
+
+        public int getArrivals() {
+            return arrivals;
+        }
+
+        public int getDepartures() {
+            return departures;
+        }
+
+        public int getQueueSize() {
+            return queueSize;
+        }
     }
 }

main/src/main/java/sd/dashboard/SimulationProcessManager.java

@@ -6,17 +6,9 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Orquestrador de processos para o ambiente de simulação distribuída.
- * <p>
- * Esta classe atua como um supervisor (Process Manager), responsável pelo <i>bootstrapping</i>
- * e <i>teardown</i> das múltiplas Java Virtual Machines (JVMs) que compõem o sistema.
- * <p>
- * Funcionalidades principais:
- * <ul>
- * <li><b>Isolamento:</b> Cada nó (Interseção, Coordinator, ExitNode) corre no seu próprio processo OS.</li>
- * <li><b>Ordem de Arranque:</b> Garante que os servidores (Interseções) estão online antes dos clientes (Coordenador).</li>
- * <li><b>Gestão de Logs:</b> Redireciona stdout/stderr de cada processo filho para ficheiros temporários para facilitar o debug.</li>
- * </ul>
+ * Gere o ciclo de vida dos processos de simulação (Intersections, Exit Node,
+ * Coordinator).
+ * Permite iniciar e parar a simulação distribuída dentro da aplicação Java.
  */
 public class SimulationProcessManager {
 
@@ -24,10 +16,6 @@ public class SimulationProcessManager {
     private final String classpath;
     private String configFile;
 
-    /**
-     * Inicializa o gestor capturando o classpath da JVM atual.
-     * Isto garante que os processos filhos herdam as mesmas dependências e configurações de ambiente.
-     */
     public SimulationProcessManager() {
         this.runningProcesses = new ArrayList<>();
         this.classpath = System.getProperty("java.class.path");
@@ -35,9 +23,9 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Define o perfil de configuração a ser injetado nos processos filhos.
-     * Útil para alternar entre cenários (Low/Medium/High Load) dinamicamente.
-     * * @param configFile Nome do ficheiro de propriedades (ex: "simulation-low.properties").
+     * Define o ficheiro de configuração a usar.
+     * 
+     * @param configFile nome do ficheiro (ex: "simulation-low.properties")
      */
     public void setConfigFile(String configFile) {
         this.configFile = "src/main/resources/" + configFile;
@@ -45,16 +33,9 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Executa o procedimento de arranque (Bootstrap) da simulação distribuída.
-     * <p>
-     * A ordem de inicialização é crítica para evitar <i>Race Conditions</i> na conexão TCP:
-     * <ol>
-     * <li><b>Workers (Interseções):</b> Iniciam os ServerSockets.</li>
-     * <li><b>Sink (Exit Node):</b> Prepara-se para receber métricas finais.</li>
-     * <li><b>Delay de Estabilização:</b> Pausa de 1s para garantir que os sockets estão em LISTENING.</li>
-     * <li><b>Source (Coordinator):</b> Inicia a geração de carga e conecta-se aos nós.</li>
-     * </ol>
-     * * @throws IOException Se falhar o fork de algum processo.
+     * Inicia a simulação completa: 5 Intersections, 1 Exit Node, e 1 Coordinator.
+     * 
+     * @throws IOException se um processo falhar ao iniciar
      */
     public void startSimulation() throws IOException {
         if (!runningProcesses.isEmpty()) {
@@ -84,11 +65,8 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Verifica o estado de "liveness" da simulação monitorizando o processo Coordenador.
-     * <p>
-     * Como o Coordenador gere o relógio DES e a geração de eventos, a sua terminação
-     * (após o drain time) sinaliza o fim efetivo da simulação.
-     * * @return true se o Coordenador ainda estiver ativo (alive).
+     * Checks if the coordinator process (last process started) is still running.
+     * When the coordinator finishes, the simulation is complete.
      */
     public boolean isSimulationRunning() {
         if (runningProcesses.isEmpty()) {
@@ -100,10 +78,8 @@ public class SimulationProcessManager {
     }
     
     /**
-     * Bloqueia a thread atual até que a simulação termine naturalmente ou ocorra timeout.
-     * * @param timeoutSeconds Tempo máximo de espera.
-     * @return true se terminou, false se o timeout expirou.
-     * @throws InterruptedException Se a espera for interrompida.
+     * Waits for the simulation to complete naturally.
+     * Returns true if completed, false if timeout.
      */
     public boolean waitForCompletion(long timeoutSeconds) throws InterruptedException {
         if (runningProcesses.isEmpty()) {
@@ -115,11 +91,7 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Executa o procedimento de encerramento (Teardown) de todos os processos.
-     * <p>
-     * Tenta primeiro uma paragem graciosa (`SIGTERM`), aguarda meio segundo, e
-     * força a paragem (`SIGKILL`) para processos persistentes, garantindo que não
-     * ficam processos órfãos no SO.
+     * Stops all running simulation processes.
      */
     public void stopSimulation() {
         System.out.println("Stopping simulation processes...");
@@ -148,8 +120,7 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Helper de baixo nível para construção e lançamento de processos Java.
-     * Configura o redirecionamento de I/O para ficheiros de log na diretoria temporária do SO.
+     * Helper para iniciar um único processo Java.
      */
     private void startProcess(String className, String arg) throws IOException {
         String javaBin = System.getProperty("java.home") + File.separator + "bin" + File.separator + "java";

main/src/main/java/sd/dashboard/StatsMessage.java

@@ -4,14 +4,7 @@ import sd.model.MessageType;
 import sd.protocol.MessageProtocol;
 
 /**
- * Implementação concreta do protocolo de mensagens destinada ao transporte de telemetria.
- * <p>
- * Esta classe atua como um envelope especializado para o envio de dados estatísticos
- * (encapsulados em {@link StatsUpdatePayload}) dos nós operacionais (Interseções, Coordenador)
- * para o servidor de Dashboard centralizado.
- * <p>
- * Diferencia-se das mensagens de controlo genéricas por ter o destino fixado no
- * "DashboardServer" e um tipo de mensagem imutável ({@code STATS_UPDATE}).
+ * Message wrapper for sending statistics to the dashboard.
  */
 public class StatsMessage implements MessageProtocol {
     
@@ -21,49 +14,27 @@ public class StatsMessage implements MessageProtocol {
     private final String destinationNode;
     private final StatsUpdatePayload payload;
     
-    /**
-     * Cria uma nova mensagem de estatística.
-     *
-     * @param sourceNode O ID do nó que gerou as estatísticas (ex: "Cr1", "ExitNode").
-     * @param payload O objeto DTO contendo os dados estatísticos brutos ou agregados.
-     */
     public StatsMessage(String sourceNode, StatsUpdatePayload payload) {
         this.sourceNode = sourceNode;
-        this.destinationNode = "DashboardServer"; // Destino implícito e fixo
+        this.destinationNode = "DashboardServer";
         this.payload = payload;
     }
     
-    /**
-     * Retorna o tipo da mensagem, que identifica semanticamente o conteúdo para o recetor.
-     * @return Sempre {@link MessageType#STATS_UPDATE}.
-     */
     @Override
     public MessageType getType() {
         return MessageType.STATS_UPDATE;
     }
     
-    /**
-     * Obtém a carga útil da mensagem.
-     * @return O objeto {@link StatsUpdatePayload} associado.
-     */
     @Override
     public Object getPayload() {
         return payload;
     }
     
-    /**
-     * Identifica a origem da mensagem.
-     * @return O ID do nó remetente.
-     */
     @Override
     public String getSourceNode() {
         return sourceNode;
     }
     
-    /**
-     * Identifica o destino da mensagem.
-     * @return Sempre "DashboardServer".
-     */
     @Override
     public String getDestinationNode() {
         return destinationNode;

main/src/main/java/sd/dashboard/StatsUpdatePayload.java

@@ -7,60 +7,25 @@ import java.util.Map;
 import sd.model.VehicleType;
 
 /**
- * Objeto de Transferência de Dados (DTO) otimizado para transporte de telemetria.
- * <p>
- * Esta classe encapsula as métricas de desempenho enviadas pelos nós da simulação (Coordenador,
- * Interseções, ExitNode) para o Dashboard. Foi desenhada para suportar <b>atualizações parciais</b>
- * (Sparse Updates):
- * <ul>
- * <li>Campos globais inicializados com {@code -1} indicam "sem alteração" (no-op). O Dashboard
- * deve ignorar estes campos e manter o valor acumulado anterior.</li>
- * <li>Campos de interseção ({@code arrivals}, {@code departures}) representam deltas ou snapshots
- * específicos do nó remetente.</li>
- * </ul>
- * Implementa {@link Serializable} para transmissão direta via Java Sockets.
- * 
-
-[Image of data transfer object pattern]
-
+ * DTO para atualizações de estatísticas ao dashboard.
+ * Campos com valor -1 não são atualizados nesta mensagem.
  */
 public class StatsUpdatePayload implements Serializable {
     
     private static final long serialVersionUID = 1L;
     
-    // Global Metrics (Coordinator/ExitNode)
-    /** Total gerado. Valor -1 indica que este campo deve ser ignorado na atualização. */
     private int totalVehiclesGenerated = -1;
-    
-    /** Total completado. Valor -1 indica que este campo deve ser ignorado. */
     private int totalVehiclesCompleted = -1;
-    
-    /** Tempo total de sistema acumulado (ms). Valor -1 indica que deve ser ignorado. */
     private long totalSystemTime = -1;
-    
-    /** Tempo total de espera acumulado (ms). Valor -1 indica que deve ser ignorado. */
     private long totalWaitingTime = -1;
     
-    // Intersection Metrics (Worker Nodes)
-    /** Número de veículos que entraram na interseção desde o último reporte. */
     private int intersectionArrivals = 0;
-    
-    /** Número de veículos que saíram da interseção desde o último reporte. */
     private int intersectionDepartures = 0;
-    
-    /** Snapshot do tamanho atual da fila na interseção. */
     private int intersectionQueueSize = 0;
     
-    // Detailed Breakdowns
-    /** Contagem acumulada por tipo de veículo. */
     private Map<VehicleType, Integer> vehicleTypeCounts;
-    
-    /** Tempos de espera acumulados por tipo de veículo. */
     private Map<VehicleType, Long> vehicleTypeWaitTimes;
     
-    /**
-     * Inicializa o payload com os mapas vazios e contadores globais a -1 (estado neutro).
-     */
     public StatsUpdatePayload() {
         this.vehicleTypeCounts = new HashMap<>();
         this.vehicleTypeWaitTimes = new HashMap<>();
@@ -102,8 +67,6 @@ public class StatsUpdatePayload implements Serializable {
         return vehicleTypeWaitTimes;
     }
     
-    // Setters implementam Fluent Interface para construção encadeada
-    
     public StatsUpdatePayload setTotalVehiclesGenerated(int totalVehiclesGenerated) {
         this.totalVehiclesGenerated = totalVehiclesGenerated;
         return this;

main/src/main/java/sd/des/SimulationEvent.java

@@ -3,46 +3,31 @@ package sd.des;
 import java.io.Serializable;
 
 /**
- * Representa um evento atómico e imutável no contexto da Simulação de Eventos Discretos (DES).
- * <p>
- * Esta classe é a unidade fundamental de processamento. Numa arquitetura DES, o estado do sistema
- * não muda continuamente, mas sim em instantes discretos definidos por estes eventos.
- * <p>
- * Características principais:
+ * Evento discreto da simulação.
+ * 
+ * <p>Unidade fundamental de execução num sistema DES:
  * <ul>
- * <li><b>Ordenação Temporal:</b> Implementa {@link Comparable} para ser armazenado numa Fila de
- * Eventos Futuros (FEL - Future Event List), garantindo execução cronológica.</li>
- * <li><b>Distribuído:</b> Implementa {@link Serializable} para permitir que eventos gerados num nó
- * (ex: Coordenador) sejam transmitidos e executados noutro (ex: Interseção).</li>
- * <li><b>Polimórfico:</b> Transporta um {@code payload} genérico, permitindo associar qualquer
- * entidade (Veículo, Sinal, etc.) ao evento.</li>
+ * <li>timestamp - quando ocorre
+ * <li>type - o que acontece
+ * <li>payload - dados associados
+ * <li>location - qual processo o trata
  * </ul>
  */
 public class SimulationEvent implements Comparable<SimulationEvent>, Serializable {
     private static final long serialVersionUID = 1L;
     
-    /** O instante virtual exato em que o evento deve ser processado. */
     private final double timestamp;
-    
-    /** A categoria do evento (ex: VEHICLE_ARRIVAL, LIGHT_CHANGE). */
     private final DESEventType type;
-    
-    /** Dados contextuais associados (ex: o objeto Vehicle que chegou). */
     private final Object payload;
+    private final String location;  // Process ID (e.g., "Cr1", "Coordinator", "Exit")
     
     /**
-     * O identificador do nó de destino onde o evento deve ser executado.
-     * (ex: "Cr1", "Coordinator", "ExitNode"). Se null, é um evento local.
-     */
-    private final String location;
-    
-    /**
-     * Instancia um novo evento de simulação completo.
+     * Cria um novo evento de simulação.
      * 
-     * @param timestamp Instante de execução (segundos virtuais).
-     * @param type Tipo enumerado do evento.
-     * @param payload Objeto de dados associado (pode ser null).
-     * @param location ID do processo alvo para execução distribuída.
+     * @param timestamp instante do evento (tempo de simulação em segundos)
+     * @param type tipo de evento
+     * @param payload dados associados (ex: objeto Vehicle)
+     * @param location processo que trata o evento
      */
     public SimulationEvent(double timestamp, DESEventType type, Object payload, String location) {
         this.timestamp = timestamp;
@@ -51,14 +36,7 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
         this.location = location;
     }
     
-    /**
-     * Construtor de conveniência para eventos locais (dentro do mesmo processo).
-     * Define {@code location} como null.
-     *
-     * @param timestamp Instante de execução.
-     * @param type Tipo do evento.
-     * @param payload Objeto de dados associado.
-     */
+    /** Cria evento sem localização (para eventos locais) */
     public SimulationEvent(double timestamp, DESEventType type, Object payload) {
         this(timestamp, type, payload, null);
     }
@@ -80,18 +58,8 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
     }
     
     /**
-     * Define a ordem natural de processamento na Fila de Prioridade.
-     * <p>
-     * <b>Lógica de Ordenação:</b>
-     * <ol>
-     * <li><b>Primária (Tempo):</b> Eventos com menor timestamp ocorrem primeiro.</li>
-     * <li><b>Secundária (Determinismo):</b> Em caso de empate temporal (simultaneidade),
-     * ordena alfabeticamente pelo nome do tipo. Isto garante que execuções repetidas
-     * da simulação produzam exatamente o mesmo resultado (determinismo estrito).</li>
-     * </ol>
-     *
-     * @param other O outro evento a comparar.
-     * @return Inteiro negativo, zero ou positivo conforme a ordem.
+     * Ordena eventos por timestamp (mais cedo primeiro).
+     * Em caso de empate, ordena por tipo para determinismo.
      */
     @Override
     public int compareTo(SimulationEvent other) {
@@ -99,7 +67,7 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
         if (timeComparison != 0) {
             return timeComparison;
         }
-        // Tie-breaker: order by event type name to ensure reproducible runs
+        // Tie-breaker: order by event type name
         return this.type.name().compareTo(other.type.name());
     }
     

main/src/main/java/sd/des/TrafficLightEvent.java

@@ -3,47 +3,28 @@ package sd.des;
 import sd.model.TrafficLight;
 
 /**
- * Encapsula o contexto de dados para eventos de mudança de estado de semáforos.
- * <p>
- * Este objeto atua como o <i>payload</i> transportado por um {@link SimulationEvent}
- * quando o tipo de evento é relacionado com controlo de tráfego (ex: mudança Verde -> Amarelo).
- * Permite que o motor DES identifique exatamente qual instância de {@link TrafficLight}
- * deve ser atualizada numa determinada interseção e direção.
+ * Payload for traffic light change events.
+ * Contains the traffic light and its direction.
  */
 public class TrafficLightEvent {
     private final TrafficLight light;
     private final String direction;
     private final String intersectionId;
     
-    /**
-     * Cria um novo payload de evento de semáforo.
-     * @param light A instância do objeto semáforo a ser manipulado.
-     * @param direction A direção cardeal associada (ex: "North", "East").
-     * @param intersectionId O identificador da interseção onde o semáforo reside.
-     */
     public TrafficLightEvent(TrafficLight light, String direction, String intersectionId) {
         this.light = light;
         this.direction = direction;
         this.intersectionId = intersectionId;
     }
     
-    /**
-     * @return A referência direta para o objeto de domínio do semáforo.
-     */
     public TrafficLight getLight() {
         return light;
     }
     
-    /**
-     * @return A direção do fluxo controlado por este semáforo.
-     */
     public String getDirection() {
         return direction;
     }
     
-    /**
-     * @return O ID da interseção pai.
-     */
     public String getIntersectionId() {
         return intersectionId;
     }

main/src/main/java/sd/logging/EventLogger.java

@@ -11,19 +11,10 @@ import java.util.concurrent.LinkedBlockingQueue;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * Motor de logging assíncrono e thread-safe para a simulação distribuída.
- * <p>
- * Implementa o padrão <i>Singleton</i> para garantir um ponto centralizado de registo.
- * Utiliza o padrão <i>Producer-Consumer</i> com uma {@link BlockingQueue} para desacoplar
- * a geração de eventos (crítica para a performance da simulação) da persistência em disco
- * (operação de I/O lenta).
- * <p>
- * <b>Garantias:</b>
- * <ul>
- * <li>Non-blocking writes (para a thread chamadora, na maioria dos casos).</li>
- * <li>Ordering cronológico aproximado (FIFO na fila).</li>
- * <li>Graceful Shutdown (flush de logs pendentes ao terminar).</li>
- * </ul>
+ * Sistema de registo centralizado de eventos para a simulação distribuída.
+ * 
+ * <p>Regista todos os eventos da simulação num ficheiro com timestamps e categorização.
+ * Thread-safe e não-bloqueante para impacto mínimo na performance.</p>
  */
 public class EventLogger {
     
@@ -31,33 +22,20 @@ public class EventLogger {
     private static final Object instanceLock = new Object();
     
     private final PrintWriter writer;
-    
-    /** Buffer de memória para absorver picos de eventos (Burst traffic). */
     private final BlockingQueue<LogEntry> logQueue;
-    
-    /** Thread dedicada (Consumer) para escrita em ficheiro. */
     private final Thread writerThread;
-    
     private final AtomicBoolean running;
     private final SimpleDateFormat timestampFormat;
     private final long simulationStartMillis;
     
-    /**
-     * Inicializa o sistema de logs.
-     * Abre o ficheiro, escreve o cabeçalho e inicia a thread consumidora.
-     *
-     * @param logFilePath Caminho relativo ou absoluto do ficheiro de log.
-     * @throws IOException Se não for possível criar ou escrever no ficheiro.
-     */
+    /** Construtor privado para padrão singleton */
     private EventLogger(String logFilePath) throws IOException {
-        // Auto-flush ativado para garantir persistência, mas gerido pelo buffer do BufferedWriter
         this.writer = new PrintWriter(new BufferedWriter(new FileWriter(logFilePath, false)), true);
-        this.logQueue = new LinkedBlockingQueue<>(10000); // Backpressure: limita a 10k eventos pendentes
+        this.logQueue = new LinkedBlockingQueue<>(10000);
         this.running = new AtomicBoolean(true);
         this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
         this.simulationStartMillis = System.currentTimeMillis();
         
-        // Header inicial do log
         writer.println("=".repeat(80));
         writer.println("SIMULATION EVENT LOG");
         writer.println("Started: " + timestampFormat.format(new Date()));
@@ -69,16 +47,11 @@ public class EventLogger {
         writer.flush();
         
         this.writerThread = new Thread(this::processLogQueue, "EventLogger-Writer");
-        this.writerThread.setDaemon(true); // Permite que a JVM termine se apenas esta thread sobrar
+        this.writerThread.setDaemon(true);
         this.writerThread.start();
     }
     
-    /**
-     * Obtém a instância única do logger (Lazy Initialization).
-     * Se não existir, cria uma predefinida em "logs/simulation-events.log".
-     *
-     * @return A instância singleton.
-     */
+    /** Obtém ou cria a instância singleton */
     public static EventLogger getInstance() {
         if (instance == null) {
             synchronized (instanceLock) {
@@ -99,8 +72,7 @@ public class EventLogger {
     }
     
     /**
-     * Reinicializa o logger com um ficheiro específico.
-     * Útil para testes ou configurações personalizadas.
+     * Initialize with custom log file path.
      */
     public static void initialize(String logFilePath) throws IOException {
         synchronized (instanceLock) {
@@ -112,13 +84,7 @@ public class EventLogger {
     }
     
     /**
-     * Regista um evento genérico.
-     * Esta operação é não-bloqueante (retorna imediatamente após colocar na fila),
-     * exceto se a fila estiver cheia (backpressure).
-     *
-     * @param eventType Categoria do evento.
-     * @param component Nome do componente (ex: "Coordinator", "IntersectionProcess").
-     * @param description Detalhes do evento.
+     * Logs an event (non-blocking).
      */
     public void log(EventType eventType, String component, String description) {
         if (!running.get()) return;
@@ -130,7 +96,7 @@ public class EventLogger {
             description
         );
         
-        // Non-blocking offer - if queue is full, drop oldest or warn
+        // Non-blocking offer - if queue is full, drop oldest
         if (!logQueue.offer(entry)) {
             // Queue full - this shouldn't happen with 10k buffer, but handle gracefully
             System.err.println("EventLogger queue full - dropping event: " + eventType);
@@ -138,14 +104,14 @@ public class EventLogger {
     }
     
     /**
-     * Regista um evento associado a um veículo específico (Helper method).
+     * Logs an event with vehicle context.
      */
     public void logVehicle(EventType eventType, String component, String vehicleId, String description) {
         log(eventType, component, "[" + vehicleId + "] " + description);
     }
     
     /**
-     * Regista um erro ou exceção com formatação apropriada.
+     * Logs an error event.
      */
     public void logError(String component, String description, Exception e) {
         String fullDescription = description + (e != null ? ": " + e.getMessage() : "");
@@ -153,13 +119,11 @@ public class EventLogger {
     }
     
     /**
-     * Lógica da thread consumidora (Worker Thread).
-     * Retira eventos da fila e escreve no disco continuamente.
+     * Background thread that writes log entries to file.
      */
     private void processLogQueue() {
         while (running.get() || !logQueue.isEmpty()) {
             try {
-                // Poll com timeout para permitir verificar a flag 'running' periodicamente
                 LogEntry entry = logQueue.poll(100, java.util.concurrent.TimeUnit.MILLISECONDS);
                 if (entry != null) {
                     writeEntry(entry);
@@ -170,7 +134,7 @@ public class EventLogger {
             }
         }
         
-        // Flush final: garantir que eventos restantes na fila são escritos antes de morrer
+        // Flush remaining entries
         while (!logQueue.isEmpty()) {
             LogEntry entry = logQueue.poll();
             if (entry != null) {
@@ -180,7 +144,7 @@ public class EventLogger {
     }
     
     /**
-     * Formata e escreve uma entrada de log no PrintWriter.
+     * Writes a single log entry to file.
      */
     private void writeEntry(LogEntry entry) {
         String timestamp = timestampFormat.format(new Date(entry.timestampMillis));
@@ -194,7 +158,7 @@ public class EventLogger {
             entry.description
         );
         
-        // Flush periódico inteligente: se a carga for baixa, garante que vemos logs em tempo real
+        // Flush periodically for real-time viewing
         if (logQueue.size() < 10) {
             writer.flush();
         }
@@ -206,17 +170,15 @@ public class EventLogger {
     }
     
     /**
-     * Encerra o logger de forma segura.
-     * Desativa a aceitação de novos eventos, aguarda que a fila esvazie (flush)
-     * e fecha o ficheiro.
+     * Shuts down the logger and flushes all pending entries.
      */
     public void shutdown() {
         if (!running.compareAndSet(true, false)) {
-            return;  // Já encerrado
+            return;  // Already shut down
         }
         
         try {
-            // Wait for writer thread to finish flushing
+            // Wait for writer thread to finish
             writerThread.join(5000);  // Wait up to 5 seconds
             
             // Write footer
@@ -233,7 +195,7 @@ public class EventLogger {
     }
     
     /**
-     * DTO interno imutável para armazenar dados do evento na fila.
+     * Internal class to represent a log entry.
      */
     private static class LogEntry {
         final long timestampMillis;

main/src/main/java/sd/logging/EventType.java

@@ -1,46 +1,34 @@
 package sd.logging;
 
 /**
- * Taxonomia oficial de eventos para o subsistema de logging centralizado.
- * <p>
- * Este enumerado padroniza a categorização de todas as ocorrências na simulação, permitindo:
- * <ul>
- * <li>Filtragem granular de logs (ex: ver apenas erros ou apenas tráfego de rede).</li>
- * <li>Análise estatística post-mortem (parsear logs para calcular latências).</li>
- * <li>Correlação de eventos distribuídos (seguir o rastro de um veículo através de vários nós).</li>
- * </ul>
+ * Tipos de eventos que podem ocorrer na simulação.
+ * Usados para categorizar e filtrar logs.
  */
 public enum EventType {
-    // --- Ciclo de Vida do Veículo ---
     VEHICLE_GENERATED("Vehicle Generated"),
     VEHICLE_ARRIVED("Vehicle Arrived"),
     VEHICLE_QUEUED("Vehicle Queued"),
     VEHICLE_DEPARTED("Vehicle Departed"),
     VEHICLE_EXITED("Vehicle Exited"),
     
-    // --- Controlo de Semáforos e Exclusão Mútua ---
     LIGHT_CHANGED_GREEN("Light Changed to Green"),
     LIGHT_CHANGED_RED("Light Changed to Red"),
     LIGHT_REQUEST_GREEN("Light Requested Green"),
     LIGHT_RELEASE_GREEN("Light Released Green"),
     
-    // --- Ciclo de Vida da Simulação/Processos ---
     SIMULATION_STARTED("Simulation Started"),
     SIMULATION_STOPPED("Simulation Stopped"),
     PROCESS_STARTED("Process Started"),
     PROCESS_STOPPED("Process Stopped"),
     
-    // --- Configuração e Telemetria ---
     STATS_UPDATE("Statistics Update"),
     CONFIG_CHANGED("Configuration Changed"),
     
-    // --- Camada de Rede (TCP/Sockets) ---
     CONNECTION_ESTABLISHED("Connection Established"),
     CONNECTION_LOST("Connection Lost"),
     MESSAGE_SENT("Message Sent"),
     MESSAGE_RECEIVED("Message Received"),
     
-    // --- Tratamento de Exceções ---
     ERROR("Error");
     
     private final String displayName;

main/src/main/java/sd/logging/VehicleTracer.java

@@ -12,18 +12,16 @@ import java.util.concurrent.ConcurrentHashMap;
 import sd.model.Vehicle;
 
 /**
- * Subsistema de auditoria granular responsável pelo rastreio detalhado (Tracing) de veículos individuais.
+ * Rastreia e regista a viagem completa de veículos individuais.
+ * 
  * <p>
- * Diferente do {@link EventLogger} (que regista eventos globais do sistema), esta classe foca-se
- * na perspetiva do <b>agente</b>. Cria um ficheiro de rastro dedicado (`.trace`) para cada veículo
- * monitorizado, registando cronologicamente cada interação com a infraestrutura (interseções,
- * filas, semáforos).
- * <p>
- * <b>Funcionalidades:</b>
+ * Cria ficheiros de trace detalhados com:
  * <ul>
- * <li>Análise forense de percursos individuais.</li>
- * <li>Validação de tempos de espera e travessia por nó.</li>
- * <li>Cálculo de eficiência de rota (tempo em movimento vs. tempo parado).</li>
+ * <li>Timestamps de todos os eventos
+ * <li>Localizações (interseções)
+ * <li>Tempos de espera em cada semáforo
+ * <li>Tempos de travessia
+ * <li>Tempo total no sistema
  * </ul>
  */
 public class VehicleTracer {
@@ -31,18 +29,12 @@ public class VehicleTracer {
     private static VehicleTracer instance;
     private static final Object instanceLock = new Object();
 
-    /** Mapa thread-safe de sessões de trace ativas (VehicleID -> TraceHandler). */
     private final Map<String, VehicleTrace> trackedVehicles;
-    
     private final SimpleDateFormat timestampFormat;
     private final long simulationStartMillis;
     private final String traceDirectory;
 
-    /**
-     * Inicializa o tracer e prepara o diretório de saída.
-     *
-     * @param traceDirectory Caminho para armazenamento dos ficheiros .trace.
-     */
+    /** Construtor privado (singleton) */
     private VehicleTracer(String traceDirectory) {
         this.trackedVehicles = new ConcurrentHashMap<>();
         this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
@@ -56,10 +48,7 @@ public class VehicleTracer {
         }
     }
 
-    /**
-     * Obtém a instância única do tracer (Singleton).
-     * @return A instância global.
-     */
+    /** Obtém ou cria a instância singleton */
     public static VehicleTracer getInstance() {
         if (instance == null) {
             synchronized (instanceLock) {
@@ -71,10 +60,7 @@ public class VehicleTracer {
         return instance;
     }
 
-    /**
-     * Reinicializa o tracer com um diretório personalizado.
-     * Útil para isolar logs de diferentes execuções em lote.
-     */
+    /** Inicializa com diretório de trace customizado */
     public static void initialize(String traceDirectory) {
         synchronized (instanceLock) {
             if (instance != null) {
@@ -85,14 +71,12 @@ public class VehicleTracer {
     }
 
     /**
-     * Inicia a sessão de rastreio para um veículo específico.
-     * Cria o ficheiro {@code logs/traces/vehicle-{id}.trace} e escreve o cabeçalho.
-     *
-     * @param vehicleId O identificador único do veículo.
+     * Começa a rastrear um veículo específico.
+     * Cria ficheiro de trace para este veículo.
      */
     public void startTracking(String vehicleId) {
         if (trackedVehicles.containsKey(vehicleId)) {
-            return; // Já está a ser rastreado
+            return; // Already tracking
         }
 
         VehicleTrace trace = new VehicleTrace(vehicleId, traceDirectory);
@@ -102,7 +86,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Encerra a sessão de rastreio, fecha o descritor de ficheiro e remove da memória.
+     * Stops tracking a vehicle and closes its trace file.
      */
     public void stopTracking(String vehicleId) {
         VehicleTrace trace = trackedVehicles.remove(vehicleId);
@@ -113,14 +97,14 @@ public class VehicleTracer {
     }
 
     /**
-     * Verifica se um veículo está atualmente sob auditoria.
+     * Checks if a vehicle is being tracked.
      */
     public boolean isTracking(String vehicleId) {
         return trackedVehicles.containsKey(vehicleId);
     }
 
     /**
-     * Regista o evento de instanciação do veículo pelo Coordenador.
+     * Logs when a vehicle is generated.
      */
     public void logGenerated(Vehicle vehicle) {
         if (!isTracking(vehicle.getId()))
@@ -135,7 +119,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista a chegada física do veículo à zona de deteção de uma interseção.
+     * Logs when a vehicle arrives at an intersection.
      */
     public void logArrival(String vehicleId, String intersection, double simulationTime) {
         if (!isTracking(vehicleId))
@@ -149,7 +133,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista a entrada do veículo na estrutura de fila de um semáforo.
+     * Logs when a vehicle is queued at a traffic light.
      */
     public void logQueued(String vehicleId, String intersection, String direction, int queuePosition) {
         if (!isTracking(vehicleId))
@@ -163,7 +147,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista o início da espera ativa (veículo parado no Vermelho).
+     * Logs when a vehicle starts waiting at a red light.
      */
     public void logWaitingStart(String vehicleId, String intersection, String direction) {
         if (!isTracking(vehicleId))
@@ -177,8 +161,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista o fim da espera (Sinal Verde).
-     * @param waitTime Duração total da paragem nesta instância.
+     * Logs when a vehicle finishes waiting (light turns green).
      */
     public void logWaitingEnd(String vehicleId, String intersection, String direction, double waitTime) {
         if (!isTracking(vehicleId))
@@ -192,7 +175,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista o início da travessia da interseção (ocupação da zona crítica).
+     * Logs when a vehicle starts crossing an intersection.
      */
     public void logCrossingStart(String vehicleId, String intersection, String direction) {
         if (!isTracking(vehicleId))
@@ -206,7 +189,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista a libertação da zona crítica da interseção.
+     * Logs when a vehicle finishes crossing an intersection.
      */
     public void logCrossingEnd(String vehicleId, String intersection, double crossingTime) {
         if (!isTracking(vehicleId))
@@ -220,7 +203,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista a partida da interseção em direção ao próximo nó.
+     * Logs when a vehicle departs from an intersection.
      */
     public void logDeparture(String vehicleId, String intersection, String nextDestination) {
         if (!isTracking(vehicleId))
@@ -234,10 +217,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Regista a saída do sistema (no Exit Node).
-     * <p>
-     * Este método também desencadeia a escrita do <b>Sumário de Viagem</b> no final do log
-     * e fecha o ficheiro automaticamente.
+     * Logs when a vehicle exits the system.
      */
     public void logExit(Vehicle vehicle, double systemTime) {
         if (!isTracking(vehicle.getId()))
@@ -249,7 +229,7 @@ public class VehicleTracer {
                     String.format("Exited system - Total time: %.2fs, Waiting: %.2fs, Crossing: %.2fs",
                             systemTime, vehicle.getTotalWaitingTime(), vehicle.getTotalCrossingTime()));
 
-            // Escreve estatísticas sumarizadas
+            // Write summary
             trace.writeSummary(vehicle, systemTime);
 
             // Stop tracking and close file
@@ -258,8 +238,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Fecha forçosamente todos os traces abertos.
-     * Deve ser chamado no shutdown da simulação para evitar corrupção de logs.
+     * Shuts down the tracer and closes all trace files.
      */
     public void shutdown() {
         for (VehicleTrace trace : trackedVehicles.values()) {
@@ -269,7 +248,7 @@ public class VehicleTracer {
     }
 
     /**
-     * Classe interna auxiliar que gere o descritor de ficheiro e a formatação para um único veículo.
+     * Internal class to handle tracing for a single vehicle.
      */
     private class VehicleTrace {
         private final String vehicleId;

main/src/main/java/sd/model/Message.java

@@ -5,52 +5,41 @@ import java.util.UUID;
 import sd.protocol.MessageProtocol;
 
 /**
- * Envelope fundamental do protocolo de comunicação entre processos distribuídos (IPC).
- * <p>
- * Esta classe atua como a Unidade de Dados de Aplicação (ADU), encapsulando tanto
- * os metadados de roteamento (origem, destino, tipo) quanto a carga útil (payload)
- * polimórfica. É agnóstica ao conteúdo, servindo como contentor genérico para
- * transferência de estado (Veículos, Estatísticas) ou sinais de controlo (Semáforos).
- * <p>
- * A imutabilidade dos campos (exceto via serialização) garante a integridade da mensagem
- * durante o trânsito na rede.
+ * Representa uma mensagem trocada entre processos na simulação distribuída.
+ * 
+ * <p>Cada mensagem tem um ID único, tipo, remetente, destino e payload.
+ * Implementa {@link MessageProtocol} que estende Serializable para transmissão pela rede.</p>
  */
 public class Message implements MessageProtocol {
     
     private static final long serialVersionUID = 1L;
     
-    /** * Identificador único universal (UUID). 
-     * Essencial para rastreabilidade (tracing), logs de auditoria e mecanismos de deduplicação.
-     */
+    /** Identificador único desta mensagem */
     private final String messageId;
     
-    /** Discriminador semântico que define como o recetor deve processar o payload. */
+    /** Tipo desta mensagem (ex: VEHICLE_TRANSFER, STATS_UPDATE) */
     private final MessageType type;
     
-    /** Identificador lógico do nó emissor (ex: "Cr1", "Coordinator"). */
+    /** Identificador do processo que enviou esta mensagem */
     private final String senderId;
     
-    /** * Identificador lógico do nó recetor. 
-     * Se {@code null}, a mensagem deve ser tratada como <b>Broadcast</b>.
-     */
+    /** Identificador do processo de destino (pode ser null para broadcast) */
     private final String destinationId;
     
-    /** * Carga útil polimórfica. 
-     * Deve implementar {@link java.io.Serializable} para garantir transmissão correta.
-     */
+    /** Dados a serem transmitidos (o tipo depende do tipo de mensagem) */
     private final Object payload;
     
-    /** Marca temporal da criação da mensagem (Unix Timestamp), usada para cálculo de latência de rede. */
+    /** Timestamp de criação da mensagem (tempo de simulação ou real) */
     private final long timestamp;
     
     /**
-     * Construtor completo para reconstrução de mensagens ou envio com timestamp manual.
+     * Cria uma nova mensagem com todos os parâmetros.
      *
-     * @param type Classificação semântica da mensagem.
-     * @param senderId ID do processo origem.
-     * @param destinationId ID do processo destino (ou null para broadcast).
-     * @param payload Objeto de domínio a ser transportado.
-     * @param timestamp Instante de criação (ms).
+     * @param type tipo da mensagem
+     * @param senderId ID do processo remetente
+     * @param destinationId ID do processo de destino (null para broadcast)
+     * @param payload conteúdo da mensagem
+     * @param timestamp timestamp de criação da mensagem
      */
     public Message(MessageType type, String senderId, String destinationId, 
                    Object payload, long timestamp) {
@@ -63,24 +52,23 @@ public class Message implements MessageProtocol {
     }
     
     /**
-     * Construtor de conveniência que atribui automaticamente o timestamp atual do sistema.
+     * Cria uma nova mensagem usando o tempo atual do sistema como timestamp.
      *
-     * @param type Classificação semântica.
-     * @param senderId ID do processo origem.
-     * @param destinationId ID do processo destino.
-     * @param payload Objeto de domínio.
+     * @param type tipo da mensagem
+     * @param senderId ID do processo remetente
+     * @param destinationId ID do processo de destino
+     * @param payload conteúdo da mensagem
      */
     public Message(MessageType type, String senderId, String destinationId, Object payload) {
         this(type, senderId, destinationId, payload, System.currentTimeMillis());
     }
     
     /**
-     * Construtor de conveniência para mensagens de difusão (Broadcast).
-     * Define {@code destinationId} como null.
+     * Cria uma mensagem de broadcast (sem destino específico).
      *
-     * @param type Classificação semântica.
-     * @param senderId ID do processo origem.
-     * @param payload Objeto de domínio.
+     * @param type tipo da mensagem
+     * @param senderId ID do processo remetente
+     * @param payload conteúdo da mensagem
      */
     public Message(MessageType type, String senderId, Object payload) {
         this(type, senderId, null, payload, System.currentTimeMillis());
@@ -113,23 +101,21 @@ public class Message implements MessageProtocol {
     }
     
     /**
-     * Verifica se a mensagem se destina a todos os nós da rede.
+     * Checks if this is a broadcast message (no specific destination).
      *
-     * @return {@code true} se o destinationId for nulo.
+     * @return true if destinationId is null, false otherwise
      */
     public boolean isBroadcast() {
         return destinationId == null;
     }
     
     /**
-     * Utilitário para casting seguro e fluente do payload.
-     * <p>
-     * Evita a necessidade de casts explícitos e supressão de warnings no código cliente.
+     * Gets the payload cast to a specific type.
+     * Use with caution and ensure type safety.
      *
-     * @param <T> O tipo esperado do payload.
-     * @param clazz A classe do tipo esperado para verificação em runtime (opcional no uso, mas boa prática).
-     * @return O payload convertido para o tipo T.
-     * @throws ClassCastException Se o payload não for compatível com o tipo solicitado.
+     * @param <T> The expected payload type
+     * @return The payload cast to type T
+     * @throws ClassCastException if the payload is not of type T
      */
     @SuppressWarnings("unchecked")
     public <T> T getPayloadAs(Class<T> clazz) {

main/src/main/java/sd/protocol/SocketConnection.java

@@ -16,17 +16,10 @@ import sd.serialization.MessageSerializer;
 import sd.serialization.SerializationException;
 import sd.serialization.SerializerFactory;
 
+
 /**
- * Wrapper de alto nível para gestão robusta de conexões TCP.
- * <p>
- * Esta classe abstrai a complexidade da API nativa {@link java.net.Socket}, oferecendo:
- * <ol>
- * <li><b>Resiliência:</b> Lógica de reconexão automática (Retry Loop) no arranque, crucial para sistemas
- * distribuídos onde a ordem de inicialização dos nós não é garantida.</li>
- * <li><b>Framing:</b> Implementação transparente do protocolo "Length-Prefix" (4 bytes de tamanho + payload),
- * resolvendo o problema de fragmentação de stream TCP.</li>
- * <li><b>Serialização:</b> Integração direta com a camada de serialização JSON.</li>
- * </ol>
+ * Simplifica comunicação via sockets.
+ * Inclui lógica de retry para robustez.
  */
 public class SocketConnection implements Closeable {
 
@@ -35,24 +28,20 @@ public class SocketConnection implements Closeable {
     private final InputStream inputStream;
     private final MessageSerializer serializer;
 
-    /** Número máximo de tentativas de ligação antes de desistir (Fail-fast). */
+    /** Número máximo de tentativas de ligação */
     private static final int MAX_RETRIES = 5; 
-    
-    /** Janela de espera (backoff) linear entre tentativas (em milissegundos). */
+    /** Atraso entre tentativas (milissegundos) */
     private static final long RETRY_DELAY_MS = 1000; 
 
     /**
-     * Construtor para clientes (Active Open).
-     * Tenta estabelecer uma conexão TCP com um servidor, aplicando lógica de retry.
-     * <p>
-     * Este comportamento é vital quando o processo Coordenador inicia antes das Interseções estarem
-     * prontas para aceitar conexões ({@code accept()}).
+     * Construtor do cliente que inicia a ligação.
+     * Tenta ligar a um servidor já em escuta, com retry.
      *
-     * @param host Endereço do nó de destino (ex: "localhost").
-     * @param port Porta de serviço.
-     * @throws IOException Se a conexão falhar após todas as {@code MAX_RETRIES} tentativas.
-     * @throws UnknownHostException Se o DNS não resolver o hostname.
-     * @throws InterruptedException Se a thread for interrompida durante o sleep de retry.
+     * @param host endereço do host (ex: "localhost")
+     * @param port número da porta
+     * @throws IOException se falhar após todas as tentativas
+     * @throws UnknownHostException se o host não for encontrado
+     * @throws InterruptedException se a thread for interrompida
      */
     public SocketConnection(String host, int port) throws IOException, UnknownHostException, InterruptedException {
         Socket tempSocket = null;
@@ -63,7 +52,7 @@ public class SocketConnection implements Closeable {
         // --- Retry Loop ---
         for (int attempt = 1; attempt <= MAX_RETRIES; attempt++) {
             try {
-                // Try to establish the connection (SYN -> SYN-ACK -> ACK)
+                // Try to establish the connection
                 tempSocket = new Socket(host, port);
 
                 // If successful, break out of the retry loop
@@ -72,17 +61,17 @@ public class SocketConnection implements Closeable {
                 break;
 
             } catch (ConnectException | SocketTimeoutException e) {
-                // Common errors: "Connection refused" (server not up) or "Timeout" (firewall/network)
+                // These are common errors indicating the server might not be ready.
                 lastException = e;
                 System.out.printf("[SocketConnection] Attempt %d/%d failed: %s. Retrying in %d ms...%n",
                         attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS);
 
                 if (attempt < MAX_RETRIES) {
-                    // Blocking wait before next attempt
+                    // Wait before the next attempt
                     TimeUnit.MILLISECONDS.sleep(RETRY_DELAY_MS);
                 }
             } catch (IOException e) {
-                // Other IO errors
+                // Other IOExceptions might be more permanent, but we retry anyway.
                  lastException = e;
                  System.out.printf("[SocketConnection] Attempt %d/%d failed with IOException: %s. Retrying in %d ms...%n",
                         attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS);
@@ -92,46 +81,48 @@ public class SocketConnection implements Closeable {
             }
         } // --- End of Retry Loop ---
 
-        // Final validation
+        // If after all retries tempSocket is still null, it means connection failed permanently.
         if (tempSocket == null) {
             System.err.printf("[SocketConnection] Failed to connect to %s:%d after %d attempts.%n", host, port, MAX_RETRIES);
             if (lastException != null) {
-                 throw lastException; // Propagate the root cause
+                 throw lastException; // Throw the last exception encountered
             } else {
+                 // Should not happen if loop ran, but as a fallback
                  throw new IOException("Failed to connect after " + MAX_RETRIES + " attempts, reason unknown.");
             }
         }
 
-        // Initialize streams
+        // If connection was successful, assign to final variable and create streams
         this.socket = tempSocket;
+          
         this.outputStream = socket.getOutputStream();
         this.inputStream = socket.getInputStream();
         this.serializer = SerializerFactory.createDefault();
+
     }
 
+
     /**
-     * Construtor para servidores (Passive Open).
-     * Envolve um socket já conectado (retornado por {@code serverSocket.accept()}).
-     * Não necessita de retry logic pois a conexão física já existe.
+     * Constructor for the "Server" (who accepts the connection).
+     * Receives a Socket that has already been accepted by a ServerSocket.
+     * No retry logic needed here as the connection is already established.
      *
-     * @param acceptedSocket O socket ativo retornado pelo SO.
-     * @throws IOException Se falhar a obtenção dos streams de I/O.
+     * @param acceptedSocket The Socket returned by serverSocket.accept().
+     * @throws IOException If stream creation fails.
      */
     public SocketConnection(Socket acceptedSocket) throws IOException {
         this.socket = acceptedSocket;
         this.outputStream = socket.getOutputStream();
         this.inputStream = socket.getInputStream();
         this.serializer = SerializerFactory.createDefault();
+        
     }
 
     /**
-     * Serializa e transmite uma mensagem através do canal.
-     * <p>
-     * Utiliza sincronização ({@code synchronized}) para garantir que escritas concorrentes
-     * na mesma conexão não corrompem a stream de bytes (thread-safety).
+     * Sends (serializes) a MessageProtocol object over the socket.
      *
-     * @param message O objeto de protocolo a enviar.
-     * @throws IOException Se o socket estiver fechado ou ocorrer erro de escrita.
+     * @param message The "envelope" (which contains the Vehicle) to be sent.
+     * @throws IOException If writing to the stream fails or socket is not connected.
      */
     public synchronized void sendMessage(MessageProtocol message) throws IOException {
    if (socket == null || !socket.isConnected()) {
@@ -142,11 +133,11 @@ public class SocketConnection implements Closeable {
             // Serializa para bytes JSON
             byte[] data = serializer.serialize(message);
             
-            // Write 4-byte length prefix (Framing)
+            // Write 4-byte length prefix
             DataOutputStream dataOut = new DataOutputStream(outputStream);
             dataOut.writeInt(data.length);
             dataOut.write(data);
-            dataOut.flush(); // Force transmission immediately
+            dataOut.flush();
             
         } catch (SerializationException e) {
             throw new IOException("Failed to serialize message", e);
@@ -154,14 +145,11 @@ public class SocketConnection implements Closeable {
     }
 
     /**
-     * Bloqueia à espera de uma mensagem completa do socket.
-     * <p>
-     * Lê primeiro o cabeçalho de tamanho (4 bytes) e depois o payload exato,
-     * garantindo que processa mensagens completas mesmo se chegarem fragmentadas em múltiplos pacotes TCP.
+     * Tries to read (deserialize) a MessageProtocol object from the socket.
      *
-     * @return O objeto {@link MessageProtocol} reconstruído.
-     * @throws IOException Se a conexão for perdida (EOF) ou o stream corrompido.
-     * @throws ClassNotFoundException Se o tipo desserializado não for encontrado no classpath.
+     * @return The "envelope" (MessageProtocol) that was received.
+     * @throws IOException If the connection is lost, the stream is corrupted, or socket is not connected.
+     * @throws ClassNotFoundException If the received object is unknown.
      */
     public MessageProtocol receiveMessage() throws IOException, ClassNotFoundException {
        if (socket == null || !socket.isConnected()) {
@@ -173,16 +161,15 @@ public class SocketConnection implements Closeable {
             DataInputStream dataIn = new DataInputStream(inputStream);
             int length = dataIn.readInt();
             
-            // Sanity check para evitar OutOfMemory em caso de corrupção de stream
-            if (length <= 0 || length > 10_000_000) { // Max 10MB payload
+            if (length <= 0 || length > 10_000_000) { // Sanity check (10MB max)
                 throw new IOException("Invalid message length: " + length);
             }
             
-            // Ler dados exatos da mensagem
+            // Ler dados da mensagem
             byte[] data = new byte[length];
             dataIn.readFully(data);
             
-            // Deserialize do JSON - força o tipo concreto Message
+            // Deserialize do JSON - use concrete Message class, not interface
             return serializer.deserialize(data, sd.model.Message.class);
             
         } catch (SerializationException e) {
@@ -191,8 +178,7 @@ public class SocketConnection implements Closeable {
     }
 
     /**
-     * Encerra a conexão e liberta os descritores de ficheiro.
-     * Operação idempotente.
+     * Closes the socket and all streams (Input and Output).
      */
     @Override
     public void close() throws IOException {
@@ -202,8 +188,7 @@ public class SocketConnection implements Closeable {
     }
 
     /**
-     * Verifica o estado operacional da conexão.
-     * @return true se o socket está aberto e conectado.
+     * @return true if the socket is still connected and not closed.
      */
     public boolean isConnected() {
         return socket != null && socket.isConnected() && !socket.isClosed();

main/src/main/java/sd/serialization/JsonMessageSerializer.java

@@ -1,25 +1,26 @@
 package sd.serialization;
 
-import java.nio.charset.StandardCharsets;
-
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import com.google.gson.JsonSyntaxException;
 
+import java.nio.charset.StandardCharsets;
+
 /**
- * Implementação baseada em JSON da estratégia {@link MessageSerializer}, utilizando a biblioteca Gson.
- * <p>
- * Este serializador converte objetos Java para o formato de texto JSON antes da transmissão.
- * Oferece várias vantagens técnicas sobre a serialização nativa do Java:
- * <ul>
- * <li><b>Legibilidade:</b> O formato de texto facilita a depuração (sniffing de rede) sem ferramentas especializadas.</li>
- * <li><b>Interoperabilidade:</b> Permite futura integração com componentes não-Java (ex: Dashboards web em JS).</li>
- * <li><b>Segurança:</b> Reduz a superfície de ataque para execução remota de código (RCE), pois não desserializa classes arbitrárias, apenas dados.</li>
- * </ul>
- * <p>
- * <b>Thread-Safety:</b> A instância interna do {@code Gson} é imutável e thread-safe, permitindo
- * que este serializador seja partilhado entre múltiplas threads (ex: no pool do DashboardServer).
- * * @see MessageSerializer
+ * JSON-based implementation of {@link MessageSerializer} using Google's Gson library.
+ * 
+ * This serializer converts objects to JSON format for transmission, providing:
+ * - Human-readable message format (easy debugging)
+ * - Cross-platform compatibility
+ * - Smaller message sizes compared to Java native serialization
+ * - Better security (no code execution during deserialization)
+ * 
+ * The serializer is configured with pretty printing disabled by default for
+ * production use, but can be enabled for debugging purposes.
+ * 
+ * Thread-safety: This class is thread-safe as Gson instances are thread-safe.
+ * 
+ * @see MessageSerializer
  */
 public class JsonMessageSerializer implements MessageSerializer {
     
@@ -27,16 +28,16 @@ public class JsonMessageSerializer implements MessageSerializer {
     private final boolean prettyPrint;
     
     /**
-     * Cria um novo serializador JSON com configuração otimizada para produção (compacto).
+     * Creates a new JSON serializer with default configuration (no pretty printing).
      */
     public JsonMessageSerializer() {
         this(false);
     }
     
     /**
-     * Cria um novo serializador JSON com formatação opcional.
-     * * @param prettyPrint Se {@code true}, o JSON gerado incluirá indentação e quebras de linha.
-     * Útil para debug, mas aumenta significativamente o tamanho do payload.
+     * Creates a new JSON serializer with optional pretty printing.
+     * 
+     * @param prettyPrint If true, JSON output will be formatted with indentation
      */
     public JsonMessageSerializer(boolean prettyPrint) {
         this.prettyPrint = prettyPrint;
@@ -52,13 +53,6 @@ public class JsonMessageSerializer implements MessageSerializer {
         this.gson = builder.create();
     }
     
-    /**
-     * Converte um objeto em memória para um array de bytes JSON (UTF-8).
-     *
-     * @param object O objeto a ser serializado.
-     * @return O payload em bytes pronto para transmissão TCP.
-     * @throws SerializationException Se o objeto não for compatível com JSON ou ocorrer erro de encoding.
-     */
     @Override
     public byte[] serialize(Object object) throws SerializationException {
         if (object == null) {
@@ -74,16 +68,6 @@ public class JsonMessageSerializer implements MessageSerializer {
         }
     }
     
-    /**
-     * Reconstrói um objeto Java a partir de um array de bytes JSON.
-     * <p>
-     * Realiza a validação sintática do JSON e a validação de tipo baseada na classe alvo.
-     *
-     * @param data O array de bytes recebido da rede.
-     * @param clazz A classe do objeto esperado (Type Token).
-     * @return A instância do objeto reconstruído.
-     * @throws SerializationException Se o JSON for malformado ou incompatível com a classe alvo.
-     */
     @Override
     public <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException {
         if (data == null) {
@@ -111,16 +95,18 @@ public class JsonMessageSerializer implements MessageSerializer {
     }
     
     /**
-     * Retorna a instância subjacente do Gson para configurações avançadas.
-     * * @return A instância Gson configurada.
+     * Returns the underlying Gson instance for advanced usage.
+     * 
+     * @return The Gson instance
      */
     public Gson getGson() {
         return gson;
     }
     
     /**
-     * Verifica se a formatação "pretty print" está ativa.
-     * * @return true se a indentação estiver habilitada.
+     * Checks if pretty printing is enabled.
+     * 
+     * @return true if pretty printing is enabled
      */
     public boolean isPrettyPrint() {
         return prettyPrint;

main/src/main/java/sd/serialization/MessageSerializer.java

@@ -1,48 +1,47 @@
 package sd.serialization;
 
 /**
- * Interface que define o contrato para estratégias de serialização e desserialização de objetos.
- * <p>
- * Esta abstração permite desacoplar a camada de transporte (Sockets TCP) da camada de
- * apresentação de dados. Ao implementar o padrão <b>Strategy</b>, o sistema ganha flexibilidade
- * para alternar entre diferentes formatos de codificação (JSON, Binário Nativo, XML, Protobuf)
- * sem necessidade de refatorização da lógica de rede.
- * <p>
- * <b>Requisitos para Implementações:</b>
- * <ul>
- * <li><b>Thread-Safety:</b> As implementações devem ser seguras para uso concorrente, dado que
- * instâncias únicas podem ser partilhadas por múltiplos <i>ClientHandlers</i>.</li>
- * <li><b>Robustez:</b> Falhas de parsing devem resultar em exceções tipificadas ({@link SerializationException}),
- * nunca em falhas silenciosas ou estados inconsistentes.</li>
- * </ul>
- * * @see JsonMessageSerializer
+ * Interface for serializing and deserializing objects for network transmission.
+ * 
+ * This interface provides a common abstraction for different serialization strategies
+ * allowing the system to switch between implementations without changing the communication layer.
+ * 
+ * Implementations must ensure:
+ * - Thread-safety if used in concurrent contexts
+ * - Proper exception handling with meaningful error messages
+ * - Preservation of object state during round-trip serialization
+ * 
+ * @see JsonMessageSerializer
  */
 public interface MessageSerializer {
     
     /**
-     * Converte (Marshals) um objeto em memória para uma sequência de bytes para transmissão.
-     * * @param object O objeto de domínio a ser serializado (não pode ser nulo).
-     * @return Um array de bytes contendo a representação codificada do objeto.
-     * @throws SerializationException Se ocorrer um erro durante a codificação (ex: ciclo de referências).
-     * @throws IllegalArgumentException Se o objeto fornecido for nulo.
+     * Serializes an object into a byte array for transmission.
+     * 
+     * @param object The object to serialize (must not be null)
+     * @return A byte array containing the serialized representation
+     * @throws SerializationException If serialization fails
+     * @throws IllegalArgumentException If object is null
      */
     byte[] serialize(Object object) throws SerializationException;
     
     /**
-     * Reconstrói (Unmarshals) um objeto a partir de uma sequência de bytes.
-     * * @param <T> O tipo genérico do objeto esperado.
-     * @param data O array de bytes contendo os dados serializados (não pode ser nulo).
-     * @param clazz A classe do tipo esperado para verificação e instancialização.
-     * @return A instância do objeto reconstruído com o seu estado restaurado.
-     * @throws SerializationException Se os dados estiverem corrompidos ou incompatíveis com a classe alvo.
-     * @throws IllegalArgumentException Se os dados ou a classe forem nulos.
+     * Deserializes a byte array back into an object of the specified type.
+     * 
+     * @param <T> The expected type of the deserialized object
+     * @param data The byte array containing serialized data (must not be null)
+     * @param clazz The class of the expected object type (must not be null)
+     * @return The deserialized object
+     * @throws SerializationException If deserialization fails
+     * @throws IllegalArgumentException If data or clazz is null
      */
     <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException;
     
     /**
-     * Obtém o identificador legível desta estratégia de serialização (ex: "JSON (Gson)", "Native").
-     * Utilizado primariamente para logging, auditoria e negociação de conteúdo.
-     * * @return O nome descritivo do serializador.
+     * Gets the name of this serialization strategy (e.g., "JSON", "Java Native").
+     * Useful for logging and debugging.
+     * 
+     * @return The serializer name
      */
     String getName();
     

main/src/main/java/sd/serialization/SerializationException.java

@@ -1,38 +1,39 @@
 package sd.serialization;
 
 /**
- * Exceção verificada (Checked Exception) que sinaliza falhas no processo de transformação de dados.
- * <p>
- * Esta classe atua como um wrapper unificador para erros ocorridos na camada de serialização,
- * abstraindo falhas de baixo nível (como erros de I/O, sintaxe JSON inválida ou incompatibilidade
- * de tipos) numa única exceção de domínio. Permite que o código cliente trate falhas de
- * protocolo de forma consistente, independentemente da implementação subjacente (Gson, Nativa, etc.).
+ * Exception thrown when serialization or deserialization operations fail.
+ * 
+ * This exception wraps underlying errors (I/O exceptions, parsing errors, etc.)
+ * and provides context about what went wrong during the serialization process.
  */
 public class SerializationException extends Exception {
     
     private static final long serialVersionUID = 1L; // Long(64bits) instead of int(32bits)
     
     /**
-     * Constrói uma nova exceção de serialização com uma mensagem descritiva.
-     * * @param message A mensagem detalhando o erro.
+     * Constructs a new serialization exception with the specified detail message.
+     * 
+     * @param message The detail message
      */
     public SerializationException(String message) {
         super(message);
     }
     
     /**
-     * Constrói uma nova exceção encapsulando a causa raiz do problema.
-     * Útil para preservar a stack trace original de erros de bibliotecas terceiras (ex: Gson).
-     * * @param message A mensagem detalhando o erro.
-     * @param cause A exceção original que causou a falha.
+     * Constructs a new serialization exception with the specified detail message
+     * and cause.
+     * 
+     * @param message The detail message
+     * @param cause The cause of this exception
      */
     public SerializationException(String message, Throwable cause) {
         super(message, cause);
     }
     
     /**
-     * Constrói uma nova exceção baseada apenas na causa raiz.
-     * * @param cause A exceção original.
+     * Constructs a new serialization exception with the specified cause.
+     * 
+     * @param cause The cause of this exception
      */
     public SerializationException(Throwable cause) {
         super(cause);

main/src/main/java/sd/serialization/SerializerFactory.java

@@ -1,14 +1,14 @@
 package sd.serialization;
 
 /**
- * Fábrica estática (Factory Pattern) para instanciação controlada de {@link MessageSerializer}.
- * <p>
- * Esta classe centraliza a criação de estratégias de serialização, garantindo consistência
- * de configuração em todo o sistema distribuído. Permite a injeção de configurações via
- * Propriedades de Sistema (System Properties), facilitando a alternância entre modos de
- * depuração (Pretty Print) e produção (Compacto) sem recompilação.
- * <p>
- * <b>Exemplo de Uso:</b>
+ * Factory for creating {@link MessageSerializer} instances.
+ * 
+ * This factory provides a centralized way to create and configure JSON serializers
+ * using Gson, making it easy to configure serialization throughout the application.
+ * 
+ * The factory can be configured via system properties for easy deployment configuration.
+ * 
+ * Example usage:
  * <pre>
  * MessageSerializer serializer = SerializerFactory.createDefault();
  * byte[] data = serializer.serialize(myObject);
@@ -17,27 +17,28 @@ package sd.serialization;
 public class SerializerFactory {
     
     /**
-     * Chave da propriedade de sistema para ativar a formatação JSON legível (Pretty Print).
-     * Defina {@code -Dsd.serialization.json.prettyPrint=true} na JVM para ativar.
+     * System property key for enabling pretty-print in JSON serialization.
+     * Set to "true" for debugging, "false" for production.
      */
     public static final String JSON_PRETTY_PRINT_PROPERTY = "sd.serialization.json.prettyPrint";
     
-    // Default configuration (Production-ready)
+    // Default configuration
     private static final boolean DEFAULT_JSON_PRETTY_PRINT = false;
     
     /**
-     * Construtor privado para prevenir instanciação acidental desta classe utilitária.
+     * Private constructor to prevent instantiation.
      */
     private SerializerFactory() {
         throw new UnsupportedOperationException("Factory class cannot be instantiated");
     }
     
     /**
-     * Cria um serializador JSON configurado dinamicamente pelo ambiente.
-     * <p>
-     * Verifica a propriedade de sistema {@value #JSON_PRETTY_PRINT_PROPERTY}.
-     * Se não definida, assume o padrão de produção (falso/compacto).
-     * * @return Uma instância configurada de {@link JsonMessageSerializer}.
+     * Creates a JSON serializer based on system configuration.
+     * 
+     * Pretty-print is determined by checking the system property
+     * {@value #JSON_PRETTY_PRINT_PROPERTY}. If not set, defaults to false.
+     * 
+     * @return A configured JsonMessageSerializer instance
      */
     public static MessageSerializer createDefault() {
         boolean prettyPrint = Boolean.getBoolean(JSON_PRETTY_PRINT_PROPERTY);
@@ -45,18 +46,19 @@ public class SerializerFactory {
     }
     
     /**
-     * Cria um serializador JSON com configuração padrão otimizada (sem indentação).
-     * Ideal para ambientes de produção onde a largura de banda é prioritária.
-     * * @return Uma instância compacta de {@link JsonMessageSerializer}.
+     * Creates a JSON serializer with default configuration (no pretty printing).
+     * 
+     * @return A JsonMessageSerializer instance
      */
     public static MessageSerializer createSerializer() {
         return createSerializer(DEFAULT_JSON_PRETTY_PRINT);
     }
     
     /**
-     * Cria um serializador JSON com configuração explícita de formatação.
-     * * @param prettyPrint {@code true} para ativar indentação (Debug), {@code false} para compacto.
-     * @return Uma instância personalizada de {@link JsonMessageSerializer}.
+     * Creates a JSON serializer with specified pretty-print setting.
+     * 
+     * @param prettyPrint Whether to enable pretty printing
+     * @return A JsonMessageSerializer instance
      */
     public static MessageSerializer createSerializer(boolean prettyPrint) {
         return new JsonMessageSerializer(prettyPrint);

main/src/main/java/sd/util/RandomGenerator.java

@@ -3,88 +3,82 @@ package sd.util;
 import java.util.Random;
 
 /**
- * Utilitário central de geração estocástica para a simulação.
- * <p>
- * Esta classe fornece primitivas para geração de números pseudo-aleatórios, abstraindo
- * a complexidade de distribuições estatísticas.
- * <p>
- * <b>Funcionalidades Principais:</b>
+ * Utilitário para gerar valores aleatórios usados na simulação.
+ * 
+ * <p>Fornece métodos estáticos para:</p>
  * <ul>
- * <li><b>Modelagem de Poisson:</b> Geração de tempos entre chegadas usando distribuição exponencial inversa.</li>
- * <li><b>Amostragem Uniforme:</b> Geração de inteiros e doubles em intervalos fechados/abertos.</li>
- * <li><b>Decisão Probabilística:</b> Avaliação de eventos booleanos baseados em pesos (Bernoulli trials).</li>
- * <li><b>Determinismo:</b> Suporte a sementes (seeds) manuais para reprodutibilidade exata de cenários de teste.</li>
+ *   <li>Gerar intervalos exponencialmente distribuídos (processos de Poisson)</li>
+ *   <li>Gerar inteiros e doubles aleatórios num intervalo</li>
+ *   <li>Tomar decisões baseadas em probabilidade</li>
+ *   <li>Escolher elementos aleatórios de um array</li>
  * </ul>
+ * 
+ * <p>Usa uma única instância estática de {@link Random}.</p>
  */
 public class RandomGenerator {
 
-    /** * Instância singleton estática do gerador PRNG (Pseudo-Random Number Generator).
-     * Thread-safe (java.util.Random é sincronizado), embora possa haver contenção em alta concorrência.
-     */
+    /** Instância partilhada de Random para toda a simulação */
     private static final Random random = new Random();
 
     /**
-     * Gera um intervalo de tempo seguindo uma Distribuição Exponencial.
-     * <p>
-     * Este método implementa o algoritmo de <i>Inverse Transform Sampling</i> para simular
-     * um Processo de Poisson homogêneo. É fundamental para modelar a chegada natural de
-     * veículos, onde eventos independentes ocorrem a uma taxa média constante.
-     * <p>
-     * <b>Fórmula Matemática:</b> {@code T = -ln(1 - U) / λ}
-     * <br>Onde:
-     * <ul>
-     * <li>{@code U}: Variável aleatória uniforme no intervalo [0, 1).</li>
-     * <li>{@code λ (lambda)}: Taxa média de eventos por unidade de tempo (ex: veículos/segundo).</li>
-     * </ul>
+     * Retorna um intervalo de tempo que segue uma distribuição exponencial.
      * 
-     * @param lambda A taxa média de chegada (λ > 0).
-     * @return O intervalo de tempo (delta t) até o próximo evento, em segundos.
+     * <p>Componente essencial para modelar processos de Poisson, onde os
+     * tempos entre chegadas seguem uma distribuição exponencial.</p>
+     * 
+     * <p>Fórmula: {@code Time = -ln(1 - U) / λ}<br>
+     * onde U é um número aleatório uniforme [0, 1) e λ (lambda) é a taxa média de chegada.</p>
+     *
+     * @param lambda taxa média de chegada λ (ex: 0.5 veículos por segundo)
+     * @return intervalo de tempo (segundos) até à próxima chegada
      */
     public static double generateExponentialInterval(double lambda) {
         return Math.log(1 - random.nextDouble()) / -lambda;
     }
 
     /**
-     * Gera um número inteiro uniformemente distribuído no intervalo fechado {@code [min, max]}.
+     * Retorna um inteiro aleatório entre {@code min} e {@code max}, inclusive.
      *
-     * @param min Limite inferior (inclusivo).
-     * @param max Limite superior (inclusivo).
-     * @return Um inteiro aleatório I tal que {@code min <= I <= max}.
+     * @param min valor mínimo possível
+     * @param max valor máximo possível
+     * @return inteiro aleatório no intervalo [min, max]
      */
     public static int generateRandomInt(int min, int max) {
         return random.nextInt(max - min + 1) + min;
     }
 
     /**
-     * Gera um número de ponto flutuante uniformemente distribuído no intervalo semi-aberto {@code [min, max)}.
+     * Retorna um double aleatório entre {@code min} (inclusive) e {@code max} (exclusivo).
      *
-     * @param min Limite inferior (inclusivo).
-     * @param max Limite superior (exclusivo).
-     * @return Um double aleatório D tal que {@code min <= D < max}.
+     * @param min valor mínimo possível
+     * @param max valor máximo possível
+     * @return double aleatório no intervalo [min, max)
      */
     public static double generateRandomDouble(double min, double max) {
         return min + (max - min) * random.nextDouble();
     }
 
     /**
-     * Realiza um teste de Bernoulli (Sim/Não) com uma probabilidade de sucesso especificada.
-     * <p>
-     * Utilizado para decisões de ramificação estocástica (ex: "Este veículo é um camião?").
+     * Retorna {@code true} com uma dada probabilidade.
      * 
-     * @param probability A probabilidade de retorno {@code true} (0.0 a 1.0).
-     * @return {@code true} se o evento ocorrer, {@code false} caso contrário.
+     * <p>Útil para tomar decisões ponderadas. Por exemplo,
+     * {@code occursWithProbability(0.3)} retorna {@code true}
+     * aproximadamente 30% das vezes.</p>
+     *
+     * @param probability valor entre 0.0 (nunca) e 1.0 (sempre)
+     * @return {@code true} ou {@code false}, baseado na probabilidade
      */
     public static boolean occursWithProbability(double probability) {
         return random.nextDouble() < probability;
     }
 
     /**
-     * Seleciona aleatoriamente um elemento de um array genérico (Amostragem Uniforme Discreta).
+     * Escolhe um elemento aleatório do array fornecido.
      *
-     * @param <T> O tipo dos elementos no array.
-     * @param array A população de onde escolher.
-     * @return O elemento selecionado.
-     * @throws IllegalArgumentException Se o array for nulo ou vazio.
+     * @param <T> tipo genérico do array
+     * @param array array de onde escolher
+     * @return elemento selecionado aleatoriamente
+     * @throws IllegalArgumentException se o array for null ou vazio
      */
     public static <T> T chooseRandom(T[] array) {
         if (array == null || array.length == 0) {
@@ -94,13 +88,13 @@ public class RandomGenerator {
     }
 
     /**
-     * Reinicializa a semente (seed) do gerador global.
-     * <p>
-     * <b>Importância Crítica:</b> Permite tornar a simulação determinística. Ao fixar a seed,
-     * a sequência de números "aleatórios" gerada será idêntica em execuções subsequentes,
-     * facilitando a depuração de race conditions ou lógica complexa.
+     * Define a seed do gerador de números aleatórios partilhado.
      * 
-     * @param seed O valor da semente inicial (ex: timestamp ou constante).
+     * <p>Extremamente útil para debugging e testes, pois permite executar
+     * a simulação múltiplas vezes com a mesma sequência de eventos "aleatórios",
+     * tornando os resultados reproduzíveis.</p>
+     *
+     * @param seed seed a usar
      */
     public static void setSeed(long seed) {
         random.setSeed(seed);

main/src/main/java/sd/util/VehicleGenerator.java

@@ -9,58 +9,55 @@ import sd.model.VehicleType;
 import sd.routing.RouteSelector;
 
 /**
- * Motor de injeção de carga (Load Injector) para a simulação de tráfego.
- * <p>
- * Esta classe atua como uma fábrica estocástica de veículos, sendo responsável por:
+ * Gera veículos para a simulação.
+ * 
+ * <p>Esta classe é responsável por duas tarefas principais:</p>
  * <ol>
- * <li><b>Modelagem Temporal:</b> Determinar os instantes de chegada (Inter-arrival times)
- * usando processos de Poisson (estocástico) ou intervalos determinísticos.</li>
- * <li><b>Caracterização da Entidade:</b> Atribuir tipos de veículo (Bike, Light, Heavy)
- * baseado numa Distribuição de Probabilidade Cumulativa (CDF).</li>
- * <li><b>Inicialização Espacial:</b> Distribuir a carga uniformemente entre os pontos de entrada (E1-E3).</li>
- * <li><b>Atribuição de Rota:</b> Delegar a escolha do percurso à estratégia {@link RouteSelector} ativa.</li>
+ *   <li>Determinar <em>quando</em> o próximo veículo deve chegar, baseado no
+ *       modelo de chegada (POISSON ou FIXED) da {@link SimulationConfig}</li>
+ *   <li>Criar um novo objeto {@link Vehicle} com tipo e rota selecionados pela
+ *       política de roteamento configurada ({@link RouteSelector})</li>
  * </ol>
+ * 
+ * <p>As rotas são selecionadas usando uma política de roteamento que pode ser:
+ * aleatória, caminho mais curto, menor congestionamento, etc.</p>
  */
 public class VehicleGenerator {
     
     private final SimulationConfig config;
     private final String arrivalModel;
-    
-    /** Parâmetro Lambda (λ) para a distribuição de Poisson (taxa de chegada). */
+    /** Lambda (λ) para modelo POISSON */
     private final double arrivalRate;
-    
-    /** Intervalo determinístico para geração constante (modo debug/teste). */
+    /** Intervalo para modelo FIXED */
     private final double fixedInterval;
     
-    /** * Estratégia de roteamento atual. 
-     * Não é final para permitir Hot-Swapping durante a execução.
-     */
+    /** Política de roteamento usada para selecionar rotas */
     private RouteSelector routeSelector;
     
     /**
-     * Inicializa o gerador com as configurações de simulação e estratégia de roteamento.
+     * Cria um novo gerador de veículos com a política de roteamento especificada.
+     * Lê a configuração necessária.
      *
-     * @param config A configuração global contendo as taxas e probabilidades.
-     * @param routeSelector A estratégia inicial de seleção de rotas.
+     * @param config objeto de {@link SimulationConfig}
+     * @param routeSelector política de roteamento a usar para selecionar rotas
      */
     public VehicleGenerator(SimulationConfig config, RouteSelector routeSelector) {
         this.config = config;
         this.routeSelector = routeSelector;
         
-        // Cache de valores de configuração para evitar lookups repetitivos em hot-path
+        // Cache configuration values for performance
         this.arrivalModel = config.getArrivalModel();
         this.arrivalRate = config.getArrivalRate();
         this.fixedInterval = config.getFixedArrivalInterval();
     }
     
     /**
-     * Calcula o timestamp absoluto para a próxima injeção de veículo.
-     * <p>
-     * Se o modelo for "POISSON", utiliza a técnica de <i>Inverse Transform Sampling</i>
-     * (via {@link RandomGenerator}) para gerar intervalos exponencialmente distribuídos,
-     * simulando a aleatoriedade natural do tráfego.
-     * * @param currentTime O tempo atual da simulação (base de cálculo).
-     * @return O instante futuro (t + delta) para agendamento do evento de geração.
+     * Calcula o tempo <em>absoluto</em> da próxima chegada de veículo
+     * baseado no modelo configurado.
+     * 
+     * @param currentTime tempo atual da simulação, usado como base
+     * @return tempo absoluto (ex: {@code currentTime + intervalo})
+     *         em que o próximo veículo deve ser gerado
      */
     public double getNextArrivalTime(double currentTime) {
         if ("POISSON".equalsIgnoreCase(arrivalModel)) {
@@ -72,19 +69,19 @@ public class VehicleGenerator {
     }
     
     /**
-     * Instancia (Spawn) um novo veículo configurado e roteado.
-     * <p>
-     * O processo de criação segue um pipeline:
+     * Gera um novo objeto {@link Vehicle}.
+     * 
+     * <p>Passos executados:</p>
      * <ol>
-     * <li>Seleção de Tipo (Roda da Fortuna / CDF).</li>
-     * <li>Seleção de Entrada (Uniforme).</li>
-     * <li>Cálculo de Rota (Delegado ao Strategy).</li>
+     *   <li>Seleciona um {@link VehicleType} aleatório baseado em probabilidades</li>
+     *   <li>Seleciona um ponto de entrada aleatório (E1, E2, E3)</li>
+     *   <li>Usa a política de roteamento para escolher a rota</li>
      * </ol>
      *
-     * @param vehicleId O identificador único sequencial (ex: "V104").
-     * @param entryTime O timestamp de criação.
-     * @param queueSizes Snapshot atual das filas (usado apenas por estratégias dinâmicas como LEAST_CONGESTED).
-     * @return A entidade {@link Vehicle} pronta para inserção na malha.
+     * @param vehicleId identificador único do novo veículo (ex: "V123")
+     * @param entryTime tempo de simulação em que o veículo é criado
+     * @param queueSizes mapa com tamanho das filas (opcional, pode ser null)
+     * @return novo objeto {@link Vehicle} configurado
      */
     public Vehicle generateVehicle(String vehicleId, double entryTime, Map<String, Integer> queueSizes) {
         VehicleType type = selectVehicleType();
@@ -95,12 +92,18 @@ public class VehicleGenerator {
     }
     
     /**
-     * Seleciona o tipo de veículo usando Amostragem por Probabilidade Cumulativa.
-     * <p>
-     * Normaliza as probabilidades configuradas e mapeia um número aleatório [0, 1)
-     * para o intervalo correspondente ao tipo de veículo.
+     * Seleciona um {@link VehicleType} (BIKE, LIGHT, HEAVY) baseado nas
+     * probabilidades definidas na {@link SimulationConfig}.
      * 
-     * @return O tipo enumerado {@link VehicleType} selecionado.
+     * <p>Usa técnica de "probabilidade cumulativa":</p>
+     * <ol>
+     *   <li>Obtém número aleatório {@code rand} de [0, 1)</li>
+     *   <li>Se {@code rand < P(Bike)}, retorna BIKE</li>
+     *   <li>Senão se {@code rand < P(Bike) + P(Light)}, retorna LIGHT</li>
+     *   <li>Caso contrário, retorna HEAVY</li>
+     * </ol>
+     *
+     * @return tipo de veículo selecionado
      */
     private VehicleType selectVehicleType() {
         double bikeProbability = config.getBikeVehicleProbability();
@@ -108,9 +111,7 @@ public class VehicleGenerator {
         double heavyProbability = config.getHeavyVehicleProbability();
         
         double total = bikeProbability + lightProbability + heavyProbability;
-        if (total == 0) return VehicleType.LIGHT; // Fallback de segurança
-        
-        // Normalização
+        if (total == 0) return VehicleType.LIGHT; // Avoid division by zero
         bikeProbability /= total;
         lightProbability /= total;
         
@@ -126,10 +127,10 @@ public class VehicleGenerator {
     }
     
     /**
-     * Seleciona um ponto de injeção na borda da rede (Edge Node).
-     * Distribuição Uniforme: ~33.3% para cada entrada (E1, E2, E3).
+     * Seleciona aleatoriamente um ponto de entrada (E1, E2 ou E3).
+     * Cada ponto tem probabilidade igual (1/3).
      *
-     * @return O ID da interseção de entrada.
+     * @return ponto de entrada selecionado ("E1", "E2" ou "E3")
      */
     private String selectRandomEntryPoint() {
         double rand = Math.random();
@@ -144,19 +145,23 @@ public class VehicleGenerator {
     }
     
     /**
-     * Atualiza a estratégia de roteamento em tempo de execução (Hot-Swap).
-     * <p>
-     * Permite que o Coordenador altere o comportamento da frota (ex: de RANDOM para SHORTEST_PATH)
-     * sem necessidade de reiniciar a simulação.
-     * * @param newRouteSelector A nova implementação de estratégia a utilizar.
+     * Altera dinamicamente o RouteSelector usado para gerar rotas.
+     * Permite mudar a política de roteamento durante a simulação.
+     * 
+     * @param newRouteSelector novo seletor de rotas
      */
     public void setRouteSelector(RouteSelector newRouteSelector) {
-        this.routeSelector = newRouteSelector;
+        // Note: In Java, we can't directly modify the 'final' field,
+        // but we can create a new VehicleGenerator with the new selector.
+        // For this implementation, we'll need to remove 'final' from routeSelector.
+        // This is acceptable since we want dynamic policy changes.
+        throw new UnsupportedOperationException(
+            "VehicleGenerator is immutable. Use CoordinatorProcess.changeRoutingPolicy() instead."
+        );
     }
 
     /**
-     * Retorna uma representação textual do estado interno do gerador.
-     * Útil para logs de auditoria e debugging.
+     * @return A string providing information about the generator's configuration.
      */
     public String getInfo() {
         return String.format(