finish 1st javadoc round

- Added BatchAnalysisDialog for running multiple simulations and generating reports.
- Implemented LeastCongestedRouteSelector for dynamic routing based on congestion levels.
- Created RandomRouteSelector for baseline random routing strategy.
- Developed ShortestPathRouteSelector to select routes based on the shortest path.
- Defined RouteSelector interface to standardize routing policy implementations.
- Introduced RoutingPolicy enum to manage available routing strategies.

.gitignore

@@ -53,4 +53,7 @@ build/
 *.pdf
 
 # JAR built pom file
-dependency-reduced-pom.xml
+dependency-reduced-pom.xml
+
+# Python env
+venv/

main/analysis/HIGH_LOAD_20251207-001113.csv

@@ -0,0 +1,6 @@
+Execução,VeículosGerados,VeículosCompletados,TaxaConclusão,TempoMédioSistema,TempoMédioEspera,TempoMínimoSistema,TempoMáximoSistema
+1,1784,877,49.16,64.58,61.43,32.29,129.16
+2,1782,363,20.37,53.77,51.01,26.88,107.53
+3,1786,883,49.44,53.09,50.08,26.54,106.17
+4,1845,179,9.70,63.92,60.27,31.96,127.84
+5,1872,953,50.91,65.41,62.16,32.70,130.81

main/analysis/HIGH_LOAD_20251207-001113.txt

@@ -0,0 +1,215 @@
+================================================================================
+ANÁLISE ESTATÍSTICA MULTI-EXECUÇÃO
+================================================================================
+Configuração: simulation-high.properties
+Número de Execuções: 5
+Data da Análise: 2025-12-07 00:11:13
+
+--------------------------------------------------------------------------------
+MÉTRICAS GLOBAIS
+--------------------------------------------------------------------------------
+
+Veículos Gerados:
+    Média:      1813.80    Desvio Padrão:      41.93
+    Mediana:    1786.00    IC 95%: [1754.13, 1873.47]
+    Mín:        1782.00    Máx:             1872.00
+
+Veículos Completados:
+    Média:       651.00    Desvio Padrão:     354.20
+    Mediana:     877.00    IC 95%: [146.96, 1155.04]
+    Mín:         179.00    Máx:              953.00
+
+Taxa de Conclusão (%):
+    Média:        35.92    Desvio Padrão:      19.44
+    Mediana:      49.16    IC 95%: [8.25, 63.58]
+    Mín:           9.70    Máx:               50.91
+
+Tempo Médio no Sistema (segundos):
+    Média:        60.15    Desvio Padrão:       6.17
+    Mediana:      63.92    IC 95%: [51.38, 68.93]
+    Mín:          53.09    Máx:               65.41
+
+Tempo Médio de Espera (segundos):
+    Média:        56.99    Desvio Padrão:       5.93
+    Mediana:      60.27    IC 95%: [48.55, 65.43]
+    Mín:          50.08    Máx:               62.16
+
+
+--------------------------------------------------------------------------------
+ANÁLISE POR TIPO DE VEÍCULO
+--------------------------------------------------------------------------------
+
+--- BIKE ---
+  Contagem de Veículos:
+    Média:       135.40    Desvio Padrão:      77.66
+    Mediana:     167.00    IC 95%: [24.89, 245.91]
+    Mín:          37.00    Máx:              211.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        55.15    Desvio Padrão:      12.01
+    Mediana:      54.23    IC 95%: [38.07, 72.24]
+    Mín:          43.41    Máx:               74.99
+
+
+--- LIGHT ---
+  Contagem de Veículos:
+    Média:       395.00    Desvio Padrão:     207.62
+    Mediana:     540.00    IC 95%: [99.55, 690.45]
+    Mín:         107.00    Máx:              548.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        59.79    Desvio Padrão:       7.28
+    Mediana:      61.58    IC 95%: [49.43, 70.15]
+    Mín:          50.81    Máx:               69.26
+
+
+--- HEAVY ---
+  Contagem de Veículos:
+    Média:       120.60    Desvio Padrão:      72.95
+    Mediana:     142.00    IC 95%: [16.79, 224.41]
+    Mín:          35.00    Máx:              202.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        49.20    Desvio Padrão:       8.62
+    Mediana:      50.31    IC 95%: [36.94, 61.46]
+    Mín:          35.51    Máx:               58.20
+
+
+--------------------------------------------------------------------------------
+ANÁLISE POR INTERSEÇÃO
+--------------------------------------------------------------------------------
+
+--- Cr1 ---
+  Tamanho Máximo da Fila:
+    Média:         3.20    Desvio Padrão:       5.54
+    Mediana:       1.00    IC 95%: [-4.68, 11.08]
+    Mín:           0.00    Máx:               13.00
+
+  Tamanho Médio da Fila:
+    Média:         3.20    Desvio Padrão:       5.54
+    Mediana:       1.00    IC 95%: [-4.68, 11.08]
+    Mín:           0.00    Máx:               13.00
+
+  Veículos Processados:
+    Média:       378.40    Desvio Padrão:     252.94
+    Mediana:     512.00    IC 95%: [18.46, 738.34]
+    Mín:          58.00    Máx:              600.00
+
+
+--- Cr2 ---
+  Tamanho Máximo da Fila:
+    Média:         0.60    Desvio Padrão:       1.34
+    Mediana:       0.00    IC 95%: [-1.31, 2.51]
+    Mín:           0.00    Máx:                3.00
+
+  Tamanho Médio da Fila:
+    Média:         0.60    Desvio Padrão:       1.34
+    Mediana:       0.00    IC 95%: [-1.31, 2.51]
+    Mín:           0.00    Máx:                3.00
+
+  Veículos Processados:
+    Média:       390.40    Desvio Padrão:     223.14
+    Mediana:     409.00    IC 95%: [72.87, 707.93]
+    Mín:          59.00    Máx:              599.00
+
+
+--- Cr3 ---
+  Tamanho Máximo da Fila:
+    Média:         6.20    Desvio Padrão:       8.67
+    Mediana:       0.00    IC 95%: [-6.14, 18.54]
+    Mín:           0.00    Máx:               18.00
+
+  Tamanho Médio da Fila:
+    Média:         6.20    Desvio Padrão:       8.67
+    Mediana:       0.00    IC 95%: [-6.14, 18.54]
+    Mín:           0.00    Máx:               18.00
+
+  Veículos Processados:
+    Média:       339.00    Desvio Padrão:     239.34
+    Mediana:     416.00    IC 95%: [-1.59, 679.59]
+    Mín:          57.00    Máx:              622.00
+
+
+--- Cr4 ---
+  Tamanho Máximo da Fila:
+    Média:         0.60    Desvio Padrão:       0.89
+    Mediana:       0.00    IC 95%: [-0.67, 1.87]
+    Mín:           0.00    Máx:                2.00
+
+  Tamanho Médio da Fila:
+    Média:         0.60    Desvio Padrão:       0.89
+    Mediana:       0.00    IC 95%: [-0.67, 1.87]
+    Mín:           0.00    Máx:                2.00
+
+  Veículos Processados:
+    Média:       123.40    Desvio Padrão:     116.13
+    Mediana:     109.00    IC 95%: [-41.85, 288.65]
+    Mín:          21.00    Máx:              316.00
+
+
+--- Cr5 ---
+  Tamanho Máximo da Fila:
+    Média:         2.40    Desvio Padrão:       1.14
+    Mediana:       2.00    IC 95%: [0.78, 4.02]
+    Mín:           1.00    Máx:                4.00
+
+  Tamanho Médio da Fila:
+    Média:         2.40    Desvio Padrão:       1.14
+    Mediana:       2.00    IC 95%: [0.78, 4.02]
+    Mín:           1.00    Máx:                4.00
+
+  Veículos Processados:
+    Média:       200.80    Desvio Padrão:     114.19
+    Mediana:     261.00    IC 95%: [38.31, 363.29]
+    Mín:          70.00    Máx:              305.00
+
+
+--- ExitNode ---
+  Tamanho Máximo da Fila: Sem dados
+
+  Tamanho Médio da Fila: Sem dados
+
+  Veículos Processados:
+    Média:       651.00    Desvio Padrão:     354.20
+    Mediana:     877.00    IC 95%: [146.96, 1155.04]
+    Mín:         179.00    Máx:              953.00
+
+
+--------------------------------------------------------------------------------
+RESUMOS INDIVIDUAIS DAS EXECUÇÕES
+--------------------------------------------------------------------------------
+
+Execução #1 [simulation-high.properties]:
+  Gerados: 1784, Completados: 877 (49.2%)
+  Tempo Médio no Sistema: 64.58s
+  Tempo Médio de Espera: 61.43s
+
+Execução #2 [simulation-high.properties]:
+  Gerados: 1782, Completados: 363 (20.4%)
+  Tempo Médio no Sistema: 53.77s
+  Tempo Médio de Espera: 51.01s
+
+Execução #3 [simulation-high.properties]:
+  Gerados: 1786, Completados: 883 (49.4%)
+  Tempo Médio no Sistema: 53.09s
+  Tempo Médio de Espera: 50.08s
+
+Execução #4 [simulation-high.properties]:
+  Gerados: 1845, Completados: 179 (9.7%)
+  Tempo Médio no Sistema: 63.92s
+  Tempo Médio de Espera: 60.27s
+
+Execução #5 [simulation-high.properties]:
+  Gerados: 1872, Completados: 953 (50.9%)
+  Tempo Médio no Sistema: 65.41s
+  Tempo Médio de Espera: 62.16s
+
+================================================================================
+FIM DO RELATÓRIO
+================================================================================

main/analysis/LOW_LOAD_20251207-000957.csv

@@ -0,0 +1,6 @@
+Execução,VeículosGerados,VeículosCompletados,TaxaConclusão,TempoMédioSistema,TempoMédioEspera,TempoMínimoSistema,TempoMáximoSistema
+1,371,187,50.40,42.28,38.65,21.14,84.57
+2,361,263,72.85,29.15,25.29,14.57,58.30
+3,368,197,53.53,38.02,33.95,19.01,76.04
+4,350,239,68.29,32.38,28.36,16.19,64.75
+5,373,212,56.84,23.36,19.96,11.68,46.73

main/analysis/LOW_LOAD_20251207-000957.txt

@@ -0,0 +1,209 @@
+================================================================================
+ANÁLISE ESTATÍSTICA MULTI-EXECUÇÃO
+================================================================================
+Configuração: simulation-low.properties
+Número de Execuções: 5
+Data da Análise: 2025-12-07 00:09:57
+
+--------------------------------------------------------------------------------
+MÉTRICAS GLOBAIS
+--------------------------------------------------------------------------------
+
+Veículos Gerados:
+    Média:       364.60    Desvio Padrão:       9.34
+    Mediana:     368.00    IC 95%: [351.30, 377.90]
+    Mín:         350.00    Máx:              373.00
+
+Veículos Completados:
+    Média:       219.60    Desvio Padrão:      31.19
+    Mediana:     212.00    IC 95%: [175.22, 263.98]
+    Mín:         187.00    Máx:              263.00
+
+Taxa de Conclusão (%):
+    Média:        60.38    Desvio Padrão:       9.71
+    Mediana:      56.84    IC 95%: [46.57, 74.20]
+    Mín:          50.40    Máx:               72.85
+
+Tempo Médio no Sistema (segundos):
+    Média:        33.04    Desvio Padrão:       7.41
+    Mediana:      32.38    IC 95%: [22.50, 43.58]
+    Mín:          23.36    Máx:               42.28
+
+Tempo Médio de Espera (segundos):
+    Média:        29.24    Desvio Padrão:       7.30
+    Mediana:      28.36    IC 95%: [18.85, 39.63]
+    Mín:          19.96    Máx:               38.65
+
+
+--------------------------------------------------------------------------------
+ANÁLISE POR TIPO DE VEÍCULO
+--------------------------------------------------------------------------------
+
+--- BIKE ---
+  Contagem de Veículos:
+    Média:        41.00    Desvio Padrão:       6.96
+    Mediana:      43.00    IC 95%: [31.09, 50.91]
+    Mín:          33.00    Máx:               50.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        25.91    Desvio Padrão:       3.91
+    Mediana:      26.98    IC 95%: [20.35, 31.47]
+    Mín:          19.60    Máx:               30.06
+
+
+--- LIGHT ---
+  Contagem de Veículos:
+    Média:       134.00    Desvio Padrão:      24.07
+    Mediana:     130.00    IC 95%: [99.74, 168.26]
+    Mín:         104.00    Máx:              167.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        29.34    Desvio Padrão:       6.83
+    Mediana:      27.89    IC 95%: [19.62, 39.06]
+    Mín:          20.73    Máx:               36.42
+
+
+--- HEAVY ---
+  Contagem de Veículos:
+    Média:        44.60    Desvio Padrão:       3.44
+    Mediana:      46.00    IC 95%: [39.71, 49.49]
+    Mín:          40.00    Máx:               48.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        32.11    Desvio Padrão:      15.90
+    Mediana:      30.74    IC 95%: [9.48, 54.74]
+    Mín:          18.09    Máx:               58.73
+
+
+--------------------------------------------------------------------------------
+ANÁLISE POR INTERSEÇÃO
+--------------------------------------------------------------------------------
+
+--- Cr1 ---
+  Tamanho Máximo da Fila:
+    Média:         0.60    Desvio Padrão:       1.34
+    Mediana:       0.00    IC 95%: [-1.31, 2.51]
+    Mín:           0.00    Máx:                3.00
+
+  Tamanho Médio da Fila:
+    Média:         0.60    Desvio Padrão:       1.34
+    Mediana:       0.00    IC 95%: [-1.31, 2.51]
+    Mín:           0.00    Máx:                3.00
+
+  Veículos Processados:
+    Média:        63.80    Desvio Padrão:      17.25
+    Mediana:      57.00    IC 95%: [39.25, 88.35]
+    Mín:          48.00    Máx:               91.00
+
+
+--- Cr2 ---
+  Tamanho Máximo da Fila:
+    Média:         0.80    Desvio Padrão:       1.79
+    Mediana:       0.00    IC 95%: [-1.75, 3.35]
+    Mín:           0.00    Máx:                4.00
+
+  Tamanho Médio da Fila:
+    Média:         0.80    Desvio Padrão:       1.79
+    Mediana:       0.00    IC 95%: [-1.75, 3.35]
+    Mín:           0.00    Máx:                4.00
+
+  Veículos Processados:
+    Média:        56.20    Desvio Padrão:      18.51
+    Mediana:      50.00    IC 95%: [29.86, 82.54]
+    Mín:          35.00    Máx:               78.00
+
+
+--- Cr3 ---
+  Tamanho Máximo da Fila:
+    Média:         1.00    Desvio Padrão:       1.41
+    Mediana:       0.00    IC 95%: [-1.01, 3.01]
+    Mín:           0.00    Máx:                3.00
+
+  Tamanho Médio da Fila:
+    Média:         1.00    Desvio Padrão:       1.41
+    Mediana:       0.00    IC 95%: [-1.01, 3.01]
+    Mín:           0.00    Máx:                3.00
+
+  Veículos Processados:
+    Média:        63.20    Desvio Padrão:      23.97
+    Mediana:      56.00    IC 95%: [29.09, 97.31]
+    Mín:          41.00    Máx:              104.00
+
+
+--- Cr4 ---
+  Tamanho Máximo da Fila:
+    Média:         1.80    Desvio Padrão:       2.49
+    Mediana:       0.00    IC 95%: [-1.74, 5.34]
+    Mín:           0.00    Máx:                5.00
+
+  Tamanho Médio da Fila:
+    Média:         1.80    Desvio Padrão:       2.49
+    Mediana:       0.00    IC 95%: [-1.74, 5.34]
+    Mín:           0.00    Máx:                5.00
+
+  Veículos Processados:
+    Média:        51.00    Desvio Padrão:      16.05
+    Mediana:      53.00    IC 95%: [28.16, 73.84]
+    Mín:          31.00    Máx:               70.00
+
+
+--- Cr5 ---
+  Tamanho Máximo da Fila: Sem dados
+
+  Tamanho Médio da Fila: Sem dados
+
+  Veículos Processados:
+    Média:        86.60    Desvio Padrão:      34.20
+    Mediana:      65.00    IC 95%: [37.94, 135.26]
+    Mín:          62.00    Máx:              139.00
+
+
+--- ExitNode ---
+  Tamanho Máximo da Fila: Sem dados
+
+  Tamanho Médio da Fila: Sem dados
+
+  Veículos Processados:
+    Média:       219.60    Desvio Padrão:      31.19
+    Mediana:     212.00    IC 95%: [175.22, 263.98]
+    Mín:         187.00    Máx:              263.00
+
+
+--------------------------------------------------------------------------------
+RESUMOS INDIVIDUAIS DAS EXECUÇÕES
+--------------------------------------------------------------------------------
+
+Execução #1 [simulation-low.properties]:
+  Gerados: 371, Completados: 187 (50.4%)
+  Tempo Médio no Sistema: 42.28s
+  Tempo Médio de Espera: 38.65s
+
+Execução #2 [simulation-low.properties]:
+  Gerados: 361, Completados: 263 (72.9%)
+  Tempo Médio no Sistema: 29.15s
+  Tempo Médio de Espera: 25.29s
+
+Execução #3 [simulation-low.properties]:
+  Gerados: 368, Completados: 197 (53.5%)
+  Tempo Médio no Sistema: 38.02s
+  Tempo Médio de Espera: 33.95s
+
+Execução #4 [simulation-low.properties]:
+  Gerados: 350, Completados: 239 (68.3%)
+  Tempo Médio no Sistema: 32.38s
+  Tempo Médio de Espera: 28.36s
+
+Execução #5 [simulation-low.properties]:
+  Gerados: 373, Completados: 212 (56.8%)
+  Tempo Médio no Sistema: 23.36s
+  Tempo Médio de Espera: 19.96s
+
+================================================================================
+FIM DO RELATÓRIO
+================================================================================

main/analysis/MEDIUM_LOAD_20251207-001034.csv

@@ -0,0 +1,6 @@
+Execução,VeículosGerados,VeículosCompletados,TaxaConclusão,TempoMédioSistema,TempoMédioEspera,TempoMínimoSistema,TempoMáximoSistema
+1,950,416,43.79,49.34,45.70,24.67,98.68
+2,886,480,54.18,35.08,31.69,17.54,70.16
+3,954,535,56.08,43.76,40.30,21.88,87.51
+4,948,354,37.34,41.68,37.96,20.84,83.37
+5,898,312,34.74,52.56,49.26,26.28,105.13

main/analysis/MEDIUM_LOAD_20251207-001034.txt

@@ -0,0 +1,203 @@
+================================================================================
+ANÁLISE ESTATÍSTICA MULTI-EXECUÇÃO
+================================================================================
+Configuração: simulation-medium.properties
+Número de Execuções: 5
+Data da Análise: 2025-12-07 00:10:34
+
+--------------------------------------------------------------------------------
+MÉTRICAS GLOBAIS
+--------------------------------------------------------------------------------
+
+Veículos Gerados:
+    Média:       927.20    Desvio Padrão:      32.48
+    Mediana:     948.00    IC 95%: [880.97, 973.43]
+    Mín:         886.00    Máx:              954.00
+
+Veículos Completados:
+    Média:       419.40    Desvio Padrão:      90.64
+    Mediana:     416.00    IC 95%: [290.42, 548.38]
+    Mín:         312.00    Máx:              535.00
+
+Taxa de Conclusão (%):
+    Média:        45.23    Desvio Padrão:       9.64
+    Mediana:      43.79    IC 95%: [31.50, 58.95]
+    Mín:          34.74    Máx:               56.08
+
+Tempo Médio no Sistema (segundos):
+    Média:        44.48    Desvio Padrão:       6.81
+    Mediana:      43.76    IC 95%: [34.79, 54.18]
+    Mín:          35.08    Máx:               52.56
+
+Tempo Médio de Espera (segundos):
+    Média:        40.98    Desvio Padrão:       6.83
+    Mediana:      40.30    IC 95%: [31.26, 50.71]
+    Mín:          31.69    Máx:               49.26
+
+
+--------------------------------------------------------------------------------
+ANÁLISE POR TIPO DE VEÍCULO
+--------------------------------------------------------------------------------
+
+--- BIKE ---
+  Contagem de Veículos:
+    Média:        75.80    Desvio Padrão:      15.96
+    Mediana:      71.00    IC 95%: [53.09, 98.51]
+    Mín:          56.00    Máx:               95.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        42.34    Desvio Padrão:      10.81
+    Mediana:      39.70    IC 95%: [26.96, 57.72]
+    Mín:          31.96    Máx:               55.19
+
+
+--- LIGHT ---
+  Contagem de Veículos:
+    Média:       263.20    Desvio Padrão:      58.29
+    Mediana:     265.00    IC 95%: [180.25, 346.15]
+    Mín:         204.00    Máx:              344.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        39.13    Desvio Padrão:       6.35
+    Mediana:      38.08    IC 95%: [30.09, 48.17]
+    Mín:          30.47    Máx:               47.99
+
+
+--- HEAVY ---
+  Contagem de Veículos:
+    Média:        80.40    Desvio Padrão:      19.11
+    Mediana:      80.00    IC 95%: [53.20, 107.60]
+    Mín:          52.00    Máx:              102.00
+
+  Tempo Médio no Sistema (segundos): Sem dados
+
+  Tempo Médio de Espera (segundos):
+    Média:        48.02    Desvio Padrão:      30.99
+    Mediana:      34.44    IC 95%: [3.92, 92.11]
+    Mín:          32.46    Máx:              103.40
+
+
+--------------------------------------------------------------------------------
+ANÁLISE POR INTERSEÇÃO
+--------------------------------------------------------------------------------
+
+--- Cr1 ---
+  Tamanho Máximo da Fila:
+    Média:         5.60    Desvio Padrão:      11.44
+    Mediana:       0.00    IC 95%: [-10.67, 21.87]
+    Mín:           0.00    Máx:               26.00
+
+  Tamanho Médio da Fila:
+    Média:         5.60    Desvio Padrão:      11.44
+    Mediana:       0.00    IC 95%: [-10.67, 21.87]
+    Mín:           0.00    Máx:               26.00
+
+  Veículos Processados:
+    Média:       156.00    Desvio Padrão:     122.81
+    Mediana:      98.00    IC 95%: [-18.76, 330.76]
+    Mín:          35.00    Máx:              306.00
+
+
+--- Cr2 ---
+  Tamanho Máximo da Fila: Sem dados
+
+  Tamanho Médio da Fila: Sem dados
+
+  Veículos Processados:
+    Média:       172.00    Desvio Padrão:     121.88
+    Mediana:     116.00    IC 95%: [-1.44, 345.44]
+    Mín:          66.00    Máx:              322.00
+
+
+--- Cr3 ---
+  Tamanho Máximo da Fila:
+    Média:         0.60    Desvio Padrão:       1.34
+    Mediana:       0.00    IC 95%: [-1.31, 2.51]
+    Mín:           0.00    Máx:                3.00
+
+  Tamanho Médio da Fila:
+    Média:         0.60    Desvio Padrão:       1.34
+    Mediana:       0.00    IC 95%: [-1.31, 2.51]
+    Mín:           0.00    Máx:                3.00
+
+  Veículos Processados:
+    Média:       168.40    Desvio Padrão:     133.38
+    Mediana:     121.00    IC 95%: [-21.40, 358.20]
+    Mín:          48.00    Máx:              326.00
+
+
+--- Cr4 ---
+  Tamanho Máximo da Fila: Sem dados
+
+  Tamanho Médio da Fila: Sem dados
+
+  Veículos Processados:
+    Média:        71.80    Desvio Padrão:      20.39
+    Mediana:      77.00    IC 95%: [42.79, 100.81]
+    Mín:          38.00    Máx:               92.00
+
+
+--- Cr5 ---
+  Tamanho Máximo da Fila:
+    Média:         3.60    Desvio Padrão:       3.85
+    Mediana:       2.00    IC 95%: [-1.87, 9.07]
+    Mín:           0.00    Máx:               10.00
+
+  Tamanho Médio da Fila:
+    Média:         3.60    Desvio Padrão:       3.85
+    Mediana:       2.00    IC 95%: [-1.87, 9.07]
+    Mín:           0.00    Máx:               10.00
+
+  Veículos Processados:
+    Média:       150.60    Desvio Padrão:      43.37
+    Mediana:     126.00    IC 95%: [88.88, 212.32]
+    Mín:         116.00    Máx:              209.00
+
+
+--- ExitNode ---
+  Tamanho Máximo da Fila: Sem dados
+
+  Tamanho Médio da Fila: Sem dados
+
+  Veículos Processados:
+    Média:       419.40    Desvio Padrão:      90.64
+    Mediana:     416.00    IC 95%: [290.42, 548.38]
+    Mín:         312.00    Máx:              535.00
+
+
+--------------------------------------------------------------------------------
+RESUMOS INDIVIDUAIS DAS EXECUÇÕES
+--------------------------------------------------------------------------------
+
+Execução #1 [simulation-medium.properties]:
+  Gerados: 950, Completados: 416 (43.8%)
+  Tempo Médio no Sistema: 49.34s
+  Tempo Médio de Espera: 45.70s
+
+Execução #2 [simulation-medium.properties]:
+  Gerados: 886, Completados: 480 (54.2%)
+  Tempo Médio no Sistema: 35.08s
+  Tempo Médio de Espera: 31.69s
+
+Execução #3 [simulation-medium.properties]:
+  Gerados: 954, Completados: 535 (56.1%)
+  Tempo Médio no Sistema: 43.76s
+  Tempo Médio de Espera: 40.30s
+
+Execução #4 [simulation-medium.properties]:
+  Gerados: 948, Completados: 354 (37.3%)
+  Tempo Médio no Sistema: 41.68s
+  Tempo Médio de Espera: 37.96s
+
+Execução #5 [simulation-medium.properties]:
+  Gerados: 898, Completados: 312 (34.7%)
+  Tempo Médio no Sistema: 52.56s
+  Tempo Médio de Espera: 49.26s
+
+================================================================================
+FIM DO RELATÓRIO
+================================================================================

main/graphing.py

@@ -0,0 +1,169 @@
+import pandas as pd
+import matplotlib.pyplot as plt
+import glob
+import os
+
+# Find CSV files using glob
+def load_latest_csv(pattern):
+    """Load the most recent CSV file matching the pattern"""
+    files = glob.glob(pattern)
+    if not files:
+        print(f"Warning: No files found matching '{pattern}'")
+        return None
+    # Sort by modification time, get the latest
+    latest_file = max(files, key=os.path.getmtime)
+    print(f"Loading: {latest_file}")
+    return pd.read_csv(latest_file)
+
+# Carregar dados
+print("Looking for analysis files...")
+low = load_latest_csv('analysis/LOW_LOAD_*.csv')
+medium = load_latest_csv('analysis/MEDIUM_LOAD_*.csv')
+high = load_latest_csv('analysis/HIGH_LOAD_*.csv')
+
+# Check if we have all data
+if low is None or medium is None or high is None:
+    print("\nError: Missing analysis files!")
+    print("Please run the batch analysis first:")
+    exit(1)
+
+# Print available columns for debugging
+print("\nAvailable columns in LOW_LOAD CSV:")
+print(low.columns.tolist())
+
+# Create output directory for graphs
+os.makedirs('graphs', exist_ok=True)
+
+# 1. Gráfico: Dwelling Time vs Load
+plt.figure(figsize=(10, 6))
+dwelling_times = [
+    low['TempoMédioSistema'].mean(),
+    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.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')
+plt.savefig('graphs/dwelling_time_comparison.png', dpi=300, bbox_inches='tight')
+print("\nGraph saved: graphs/dwelling_time_comparison.png")
+plt.close()
+
+# 2. Gráfico: Completion Rate vs Load
+plt.figure(figsize=(10, 6))
+completion_rates = [
+    low['TaxaConclusão'].mean(),
+    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.grid(axis='y', alpha=0.3)
+plt.ylim(0, 100)
+for i, v in enumerate(completion_rates):
+    plt.text(i, v + 2, f'{v:.1f}%', ha='center', va='bottom')
+plt.savefig('graphs/completion_rate_comparison.png', dpi=300, bbox_inches='tight')
+print("Graph saved: graphs/completion_rate_comparison.png")
+plt.close()
+
+# 3. Gráfico: Waiting Time vs Load
+plt.figure(figsize=(10, 6))
+waiting_times = [
+    low['TempoMédioEspera'].mean(),
+    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.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')
+plt.savefig('graphs/waiting_time_comparison.png', dpi=300, bbox_inches='tight')
+print("Graph saved: graphs/waiting_time_comparison.png")
+plt.close()
+
+# 4. Gráfico: Summary Statistics
+fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(14, 10))
+loads = ['Low', 'Medium', 'High']
+
+# 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.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.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.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']
+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.set_xticks(x)
+ax4.set_xticklabels(metrics)
+ax4.legend()
+ax4.grid(axis='y', alpha=0.3)
+
+plt.tight_layout()
+plt.savefig('graphs/summary_statistics.png', dpi=300, bbox_inches='tight')
+print("Graph saved: graphs/summary_statistics.png")
+plt.close()
+
+# Print summary statistics
+print("\n" + "="*60)
+print("SUMMARY STATISTICS")
+print("="*60)
+print(f"\nLOW LOAD:")
+print(f"  Avg Dwelling Time: {low['TempoMédioSistema'].mean():.2f}s")
+print(f"  Avg Waiting Time: {low['TempoMédioEspera'].mean():.2f}s")
+print(f"  Completion Rate: {low['TaxaConclusão'].mean():.1f}%")
+print(f"  Vehicles Generated: {low['VeículosGerados'].mean():.0f}")
+print(f"  Vehicles Completed: {low['VeículosCompletados'].mean():.0f}")
+
+print(f"\nMEDIUM LOAD:")
+print(f"  Avg Dwelling Time: {medium['TempoMédioSistema'].mean():.2f}s")
+print(f"  Avg Waiting Time: {medium['TempoMédioEspera'].mean():.2f}s")
+print(f"  Completion Rate: {medium['TaxaConclusão'].mean():.1f}%")
+print(f"  Vehicles Generated: {medium['VeículosGerados'].mean():.0f}")
+print(f"  Vehicles Completed: {medium['VeículosCompletados'].mean():.0f}")
+
+print(f"\nHIGH LOAD:")
+print(f"  Avg Dwelling Time: {high['TempoMédioSistema'].mean():.2f}s")
+print(f"  Avg Waiting Time: {high['TempoMédioEspera'].mean():.2f}s")
+print(f"  Completion Rate: {high['TaxaConclusão'].mean():.1f}%")
+print(f"  Vehicles Generated: {high['VeículosGerados'].mean():.0f}")
+print(f"  Vehicles Completed: {high['VeículosCompletados'].mean():.0f}")
+
+print("\n" + "="*60)
+print("All graphs saved in 'graphs/' directory!")
+print("="*60)

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

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

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

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

main/src/main/java/sd/analysis/MultiRunAnalyzer.java

@@ -5,41 +5,70 @@ import java.io.FileWriter;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.text.SimpleDateFormat;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.List;
+import java.util.Set;
+import java.util.TreeSet;
 
 import sd.model.VehicleType;
 
 /**
- * Executes multiple simulation runs and aggregates results.
+ * Responsável pela agregação e análise estatística de múltiplas execuções da simulação.
- * Calculates statistical measures including mean, standard deviation,
+ * <p>
- * and confidence intervals across all runs.
+ * Esta classe coleta resultados individuais ({@link SimulationRunResult}) e calcula
+ * métricas consolidadas, incluindo média, desvio padrão, mediana e intervalos de
+ * confiança de 95%. O objetivo é fornecer uma visão robusta do comportamento do
+ * sistema, mitigando a variância estocástica de execuções isoladas.
  */
 public class MultiRunAnalyzer {
     
+    /** Lista acumulada de resultados de execuções individuais. */
     private final List<SimulationRunResult> results;
+    
+    /** Identificador do ficheiro de configuração utilizado nas execuções. */
     private final String configurationFile;
     
+    /**
+     * Inicializa o analisador para um conjunto específico de configurações.
+     *
+     * @param configurationFile O caminho ou nome do ficheiro de configuração base.
+     */
     public MultiRunAnalyzer(String configurationFile) {
         this.configurationFile = configurationFile;
         this.results = new ArrayList<>();
     }
     
     /**
-     * Adds a completed simulation run result.
+     * Adiciona o resultado de uma execução de simulação concluída ao conjunto de dados.
+     *
+     * @param result O objeto contendo as métricas da execução individual.
      */
     public void addResult(SimulationRunResult result) {
         results.add(result);
     }
     
     /**
-     * Gets the number of completed runs.
+     * Retorna o número total de execuções armazenadas até o momento.
+     *
+     * @return O tamanho da lista de resultados.
      */
     public int getRunCount() {
         return results.size();
     }
     
     /**
-     * Generates a comprehensive statistical report.
+     * Gera um relatório estatístico abrangente formatado em texto.
+     * <p>
+     * O relatório inclui:
+     * <ul>
+     * <li>Métricas globais (throughput, tempos de espera, tempos no sistema).</li>
+     * <li>Análise segmentada por tipo de veículo ({@link VehicleType}).</li>
+     * <li>Análise de gargalos por interseção (tamanhos de fila).</li>
+     * <li>Resumos brutos das execuções individuais.</li>
+     * </ul>
+     *
+     * @return Uma String contendo o relatório completo formatado.
      */
     public String generateReport() {
         if (results.isEmpty()) {
@@ -50,65 +79,65 @@ public class MultiRunAnalyzer {
         
         // Header
         report.append("=".repeat(80)).append("\n");
-        report.append("MULTI-RUN STATISTICAL ANALYSIS\n");
+        report.append("ANÁLISE ESTATÍSTICA MULTI-EXECUÇÃO\n");
         report.append("=".repeat(80)).append("\n");
-        report.append("Configuration: ").append(configurationFile).append("\n");
+        report.append("Configuração: ").append(configurationFile).append("\n");
-        report.append("Number of Runs: ").append(results.size()).append("\n");
+        report.append("Número de Execuções: ").append(results.size()).append("\n");
-        report.append("Analysis Date: ").append(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date())).append("\n");
+        report.append("Data da Análise: ").append(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date())).append("\n");
         report.append("\n");
         
         // Global metrics
         report.append("-".repeat(80)).append("\n");
-        report.append("GLOBAL METRICS\n");
+        report.append("MÉTRICAS GLOBAIS\n");
         report.append("-".repeat(80)).append("\n\n");
         
-        report.append(analyzeMetric("Vehicles Generated", 
+        report.append(analyzeMetric("Veículos Gerados", 
             extractValues(r -> (double) r.getTotalVehiclesGenerated())));
         report.append("\n");
         
-        report.append(analyzeMetric("Vehicles Completed", 
+        report.append(analyzeMetric("Veículos Completados", 
             extractValues(r -> (double) r.getTotalVehiclesCompleted())));
         report.append("\n");
         
-        report.append(analyzeMetric("Completion Rate (%)", 
+        report.append(analyzeMetric("Taxa de Conclusão (%)", 
             extractValues(r -> r.getTotalVehiclesGenerated() > 0 
                 ? 100.0 * r.getTotalVehiclesCompleted() / r.getTotalVehiclesGenerated() 
                 : 0.0)));
         report.append("\n");
         
-        report.append(analyzeMetric("Average System Time (seconds)", 
+        report.append(analyzeMetric("Tempo Médio no Sistema (segundos)", 
             extractValues(r -> r.getAverageSystemTime())));
         report.append("\n");
         
-        report.append(analyzeMetric("Average Waiting Time (seconds)", 
+        report.append(analyzeMetric("Tempo Médio de Espera (segundos)", 
             extractValues(r -> r.getAverageWaitingTime())));
         report.append("\n");
         
         // Per-vehicle-type analysis
         report.append("\n");
         report.append("-".repeat(80)).append("\n");
-        report.append("PER-VEHICLE-TYPE ANALYSIS\n");
+        report.append("ANÁLISE POR TIPO DE VEÍCULO\n");
         report.append("-".repeat(80)).append("\n\n");
         
         for (VehicleType type : VehicleType.values()) {
             report.append("--- ").append(type).append(" ---\n");
             
-            report.append(analyzeMetric("  Vehicle Count", 
+            report.append(analyzeMetric("  Contagem de Veículos", 
                 extractValues(r -> (double) r.getVehicleCountByType().getOrDefault(type, 0))));
             report.append("\n");
             
-            report.append(analyzeMetric("  Avg System Time (seconds)", 
+            report.append(analyzeMetric("  Tempo Médio no Sistema (segundos)", 
                 extractValues(r -> r.getAvgSystemTimeByType().getOrDefault(type, 0.0))));
             report.append("\n");
             
-            report.append(analyzeMetric("  Avg Waiting Time (seconds)", 
+            report.append(analyzeMetric("  Tempo Médio de Espera (segundos)", 
                 extractValues(r -> r.getAvgWaitTimeByType().getOrDefault(type, 0.0))));
             report.append("\n\n");
         }
         
         // Per-intersection analysis
         report.append("-".repeat(80)).append("\n");
-        report.append("PER-INTERSECTION ANALYSIS\n");
+        report.append("ANÁLISE POR INTERSEÇÃO\n");
         report.append("-".repeat(80)).append("\n\n");
         
         Set<String> allIntersections = new TreeSet<>();
@@ -119,22 +148,22 @@ public class MultiRunAnalyzer {
         for (String intersection : allIntersections) {
             report.append("--- ").append(intersection).append(" ---\n");
             
-            report.append(analyzeMetric("  Max Queue Size", 
+            report.append(analyzeMetric("  Tamanho Máximo da Fila", 
                 extractValues(r -> (double) r.getMaxQueueSizeByIntersection().getOrDefault(intersection, 0))));
             report.append("\n");
             
-            report.append(analyzeMetric("  Avg Queue Size", 
+            report.append(analyzeMetric("  Tamanho Médio da Fila", 
                 extractValues(r -> r.getAvgQueueSizeByIntersection().getOrDefault(intersection, 0.0))));
             report.append("\n");
             
-            report.append(analyzeMetric("  Vehicles Processed", 
+            report.append(analyzeMetric("  Veículos Processados", 
                 extractValues(r -> (double) r.getVehiclesProcessedByIntersection().getOrDefault(intersection, 0))));
             report.append("\n\n");
         }
         
         // Individual run summaries
         report.append("-".repeat(80)).append("\n");
-        report.append("INDIVIDUAL RUN SUMMARIES\n");
+        report.append("RESUMOS INDIVIDUAIS DAS EXECUÇÕES\n");
         report.append("-".repeat(80)).append("\n\n");
         
         for (SimulationRunResult result : results) {
@@ -142,18 +171,24 @@ public class MultiRunAnalyzer {
         }
         
         report.append("=".repeat(80)).append("\n");
-        report.append("END OF REPORT\n");
+        report.append("FIM DO RELATÓRIO\n");
         report.append("=".repeat(80)).append("\n");
         
         return report.toString();
     }
     
     /**
-     * Analyzes a single metric and returns formatted statistics.
+     * Analisa uma métrica específica e retorna as estatísticas formatadas.
+     * <p>
+     * Calcula média, desvio padrão, mediana, intervalo de confiança (95%) e extremos (min/max).
+     *
+     * @param metricName O nome descritivo da métrica (ex: "Tempo de Espera").
+     * @param values A lista de valores numéricos brutos extraídos das execuções.
+     * @return Uma string formatada com os dados estatísticos.
      */
     private String analyzeMetric(String metricName, List<Double> values) {
         if (values.isEmpty() || values.stream().allMatch(v -> v == 0.0)) {
-            return metricName + ": No data\n";
+            return metricName + ": Sem dados\n";
         }
         
         double mean = StatisticalAnalysis.mean(values);
@@ -165,15 +200,21 @@ public class MultiRunAnalyzer {
         
         return String.format(
             "%s:\n" +
-            "    Mean:   %10.2f    Std Dev: %10.2f\n" +
+            "    Média:   %10.2f    Desvio Padrão: %10.2f\n" +
-            "    Median: %10.2f    95%% CI: [%.2f, %.2f]\n" +
+            "    Mediana: %10.2f    IC 95%%: [%.2f, %.2f]\n" +
-            "    Min:    %10.2f    Max:     %10.2f\n",
+            "    Mín:     %10.2f    Máx:          %10.2f\n",
             metricName, mean, stdDev, median, ci[0], ci[1], min, max
         );
     }
     
     /**
-     * Extracts values using a lambda function.
+     * Extrai valores numéricos dos resultados de simulação usando uma função mapeadora.
+     * <p>
+     * Utilizado internamente para transformar a lista de objetos complexos {@link SimulationRunResult}
+     * em listas simples de Doubles para processamento estatístico.
+     *
+     * @param extractor Função lambda que define qual campo extrair de cada resultado.
+     * @return Lista de valores double correspondentes.
      */
     private List<Double> extractValues(java.util.function.Function<SimulationRunResult, Double> extractor) {
         List<Double> values = new ArrayList<>();
@@ -184,7 +225,10 @@ public class MultiRunAnalyzer {
     }
     
     /**
-     * Saves the report to a file.
+     * Persiste o relatório gerado num ficheiro de texto.
+     *
+     * @param filename O caminho do ficheiro de destino.
+     * @throws IOException Se ocorrer um erro de escrita no disco.
      */
     public void saveReport(String filename) throws IOException {
         try (PrintWriter writer = new PrintWriter(new BufferedWriter(new FileWriter(filename)))) {
@@ -193,13 +237,31 @@ public class MultiRunAnalyzer {
     }
     
     /**
-     * Generates a CSV summary for easy import into spreadsheet tools.
+     * Gera um resumo em formato CSV para fácil importação em ferramentas de planilha.
+     * <p>
+     * Este método atua como um wrapper para {@link #saveCSVSummary(String)}.
+     *
+     * @param filename O caminho do ficheiro CSV de destino.
+     * @throws IOException Se ocorrer um erro de escrita no disco.
+     */
+    public void saveCSV(String filename) throws IOException {
+        saveCSVSummary(filename);
+    }
+    
+    /**
+     * Gera e grava o sumário CSV detalhado com métricas chave por execução.
+     * <p>
+     * Colunas incluídas: Execução, VeículosGerados, VeículosCompletados, TaxaConclusão,
+     * TempoMédioSistema, TempoMédioEspera, TempoMínimoSistema, TempoMáximoSistema.
+     *
+     * @param filename O caminho do ficheiro CSV de destino.
+     * @throws IOException Se ocorrer um erro de escrita no disco.
      */
     public void saveCSVSummary(String filename) throws IOException {
         try (PrintWriter writer = new PrintWriter(new BufferedWriter(new FileWriter(filename)))) {
             // Header
-            writer.println("Run,VehiclesGenerated,VehiclesCompleted,CompletionRate," +
+            writer.println("Execução,VeículosGerados,VeículosCompletados,TaxaConclusão," +
-                "AvgSystemTime,AvgWaitingTime,MinSystemTime,MaxSystemTime");
+                "TempoMédioSistema,TempoMédioEspera,TempoMínimoSistema,TempoMáximoSistema");
             
             // Data rows
             for (SimulationRunResult result : results) {
@@ -220,4 +282,4 @@ public class MultiRunAnalyzer {
             }
         }
     }
-}
+}

main/src/main/java/sd/analysis/SimulationBatchRunner.java

@@ -1,172 +0,0 @@
-package sd.analysis;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-import java.text.SimpleDateFormat;
-import java.util.Date;
-
-/**
- * Orquestra múltiplas execuções de simulação para análise estatística.
- * 
- * Em vez de correr uma única simulação manualmente, esta ferramenta permite
- * correr um "lote"
- * de N simulações consecutivas. Isto é essencial para recolher dados
- * estatisticamente significativos
- * (calcular intervalos de confiança, etc.) conforme exigido pelas
- * especificações do projeto.
- * 
- * Utilização:
- * java sd.analysis.SimulationBatchRunner <ficheiro-config> <num-execucoes>
- * <dir-saida>
- */
-public class SimulationBatchRunner {
-
-    public static void main(String[] args) {
-        if (args.length < 3) {
-            System.err.println("Usage: SimulationBatchRunner <config-file> <num-runs> <output-dir>");
-            System.err.println("Example: SimulationBatchRunner simulation-medium.properties 10 results/medium");
-            System.exit(1);
-        }
-
-        String configFile = args[0];
-        int numRuns;
-        String outputDir = args[2];
-
-        try {
-            numRuns = Integer.parseInt(args[1]);
-            if (numRuns < 1 || numRuns > 100) {
-                throw new IllegalArgumentException("Number of runs must be between 1 and 100");
-            }
-        } catch (NumberFormatException e) {
-            System.err.println("Error: Invalid number of runs: " + args[1]);
-            System.exit(1);
-            return;
-        }
-
-        System.out.println("=".repeat(80));
-        System.out.println("SIMULATION BATCH RUNNER");
-        System.out.println("=".repeat(80));
-        System.out.println("Configuration: " + configFile);
-        System.out.println("Number of Runs: " + numRuns);
-        System.out.println("Output Directory: " + outputDir);
-        System.out.println("=".repeat(80));
-        System.out.println();
-
-        // Create output directory
-        try {
-            Files.createDirectories(Paths.get(outputDir));
-        } catch (IOException e) {
-            System.err.println("Failed to create output directory: " + e.getMessage());
-            System.exit(1);
-        }
-
-        MultiRunAnalyzer analyzer = new MultiRunAnalyzer(configFile);
-
-        // Execute runs
-        for (int i = 1; i <= numRuns; i++) {
-            System.out.println("\n" + "=".repeat(80));
-            System.out.println("STARTING RUN " + i + " OF " + numRuns);
-            System.out.println("=".repeat(80));
-
-            SimulationRunResult result = executeSimulationRun(i, configFile, outputDir);
-
-            if (result != null) {
-                analyzer.addResult(result);
-                System.out.println("\n" + result);
-            } else {
-                System.err.println("Run " + i + " failed!");
-            }
-
-            // Pause between runs
-            if (i < numRuns) {
-                System.out.println("\nWaiting 10 seconds before next run...");
-                try {
-                    Thread.sleep(10000);
-                } catch (InterruptedException e) {
-                    Thread.currentThread().interrupt();
-                    break;
-                }
-            }
-        }
-
-        // Generate reports
-        System.out.println("\n\n" + "=".repeat(80));
-        System.out.println("ALL RUNS COMPLETE - GENERATING REPORTS");
-        System.out.println("=".repeat(80));
-
-        try {
-            String timestamp = new SimpleDateFormat("yyyyMMdd-HHmmss").format(new Date());
-            String reportFile = outputDir + "/analysis-report-" + timestamp + ".txt";
-            String csvFile = outputDir + "/summary-" + timestamp + ".csv";
-
-            analyzer.saveReport(reportFile);
-            analyzer.saveCSVSummary(csvFile);
-
-            System.out.println("\nReports generated:");
-            System.out.println("  - Analysis Report: " + reportFile);
-            System.out.println("  - CSV Summary: " + csvFile);
-            System.out.println();
-
-            // Print report to console
-            System.out.println(analyzer.generateReport());
-
-        } catch (IOException e) {
-            System.err.println("Failed to generate reports: " + e.getMessage());
-            e.printStackTrace();
-        }
-    }
-
-    /**
-     * Executa uma única instância da simulação.
-     * 
-     * Idealmente, este método iniciaria todos os processos necessários
-     * (Interseções, Nó de Saída, Coordenador),
-     * esperaria que terminassem e depois recolheria os resultados.
-     * 
-     * Atualmente, serve como um espaço reservado estrutural para demonstrar como
-     * funciona o pipeline de análise.
-     * Para correr uma simulação real, deve iniciar os componentes manualmente ou
-     * usar um script shell.
-     */
-    private static SimulationRunResult executeSimulationRun(int runNumber, String configFile, String outputDir) {
-        SimulationRunResult result = new SimulationRunResult(runNumber, configFile);
-
-        try {
-            // TODO: Implement actual simulation execution
-            // This would involve:
-            // 1. Starting intersection processes
-            // 2. Starting exit node process
-            // 3. Starting dashboard process
-            // 4. Running coordinator
-            // 5. Collecting results from dashboard/exit node
-            // 6. Shutting down all processes
-
-            System.out.println("NOTE: Actual simulation execution not yet implemented.");
-            System.out.println("This batch runner demonstrates the framework structure.");
-            System.out.println("To run actual simulations, you need to:");
-            System.out.println("  1. Start all intersection processes manually");
-            System.out.println("  2. Start exit node process");
-            System.out.println("  3. Start dashboard process");
-            System.out.println("  4. Run coordinator with the configuration file");
-            System.out.println("  5. Results will be collected automatically");
-
-            // Placeholder: simulate some results
-            // In real implementation, these would be collected from the actual simulation
-            result.setTotalVehiclesGenerated(100);
-            result.setTotalVehiclesCompleted(85);
-            result.setAverageSystemTime(120.5);
-            result.setMinSystemTime(45.2);
-            result.setMaxSystemTime(250.8);
-            result.setAverageWaitingTime(45.3);
-
-            return result;
-
-        } catch (Exception e) {
-            System.err.println("Error executing run " + runNumber + ": " + e.getMessage());
-            e.printStackTrace();
-            return null;
-        }
-    }
-
-}

main/src/main/java/sd/analysis/SimulationRunResult.java

@@ -6,8 +6,12 @@ import java.util.Map;
 import sd.model.VehicleType;
 
 /**
- * Stores the results of a single simulation run.
+ * Encapsula os dados telemétricos e estatísticos resultantes de uma única execução da simulação.
- * Contains all key metrics for post-simulation analysis.
+ * <p>
+ * Esta classe atua como um registo estruturado de métricas de desempenho, armazenando
+ * dados de latência (tempos de sistema/espera), vazão (throughput) e ocupação de recursos
+ * (tamanhos de fila). Os dados aqui contidos servem como base para a análise
+ * estatística agregada realizada pelo {@link MultiRunAnalyzer}.
  */
 public class SimulationRunResult {
     
@@ -17,11 +21,22 @@ public class SimulationRunResult {
     private final long endTimeMillis;
     
     // Global metrics
+    /** Total de veículos instanciados pelos geradores durante a execução. */
     private int totalVehiclesGenerated;
+    
+    /** Total de veículos que completaram o percurso e saíram do sistema com sucesso. */
     private int totalVehiclesCompleted;
+    
+    /** Média global do tempo total (em segundos) desde a geração até a saída. */
     private double averageSystemTime;        // seconds
+    
+    /** Menor tempo de sistema registado (em segundos). */
     private double minSystemTime;            // seconds
+    
+    /** Maior tempo de sistema registado (em segundos). */
     private double maxSystemTime;            // seconds
+    
+    /** Média global do tempo (em segundos) que os veículos passaram parados em filas. */
     private double averageWaitingTime;       // seconds
     
     // Per-type metrics
@@ -34,6 +49,12 @@ public class SimulationRunResult {
     private final Map<String, Double> avgQueueSizeByIntersection;
     private final Map<String, Integer> vehiclesProcessedByIntersection;
     
+    /**
+     * Inicializa um novo contentor de resultados para uma execução específica.
+     *
+     * @param runNumber O identificador sequencial desta execução.
+     * @param configurationFile O ficheiro de configuração utilizado.
+     */
     public SimulationRunResult(int runNumber, String configurationFile) {
         this.runNumber = runNumber;
         this.configurationFile = configurationFile;
@@ -48,6 +69,10 @@ public class SimulationRunResult {
         this.vehiclesProcessedByIntersection = new HashMap<>();
     }
     
+    /**
+     * Sinaliza o fim da recolha de dados para esta execução.
+     * (Placeholder para lógica de finalização de timestamps).
+     */
     public void markCompleted() {
         // This will be called when the run finishes
     }
@@ -57,6 +82,11 @@ public class SimulationRunResult {
     public String getConfigurationFile() { return configurationFile; }
     public long getStartTimeMillis() { return startTimeMillis; }
     public long getEndTimeMillis() { return endTimeMillis; }
+    
+    /**
+     * Calcula a duração total da execução em milissegundos.
+     * @return Delta entre fim e início.
+     */
     public long getDurationMillis() { return endTimeMillis - startTimeMillis; }
     
     public int getTotalVehiclesGenerated() { return totalVehiclesGenerated; }
@@ -66,21 +96,50 @@ public class SimulationRunResult {
     public double getMaxSystemTime() { return maxSystemTime; }
     public double getAverageWaitingTime() { return averageWaitingTime; }
     
+    /**
+     * Retorna o mapeamento de contagem de veículos por tipo.
+     * @return Uma cópia defensiva do mapa (snapshot).
+     */
     public Map<VehicleType, Integer> getVehicleCountByType() { 
         return new HashMap<>(vehicleCountByType); 
     }
+
+    /**
+     * Retorna o tempo médio no sistema segmentado por tipo de veículo.
+     * @return Uma cópia defensiva do mapa (snapshot).
+     */
     public Map<VehicleType, Double> getAvgSystemTimeByType() { 
         return new HashMap<>(avgSystemTimeByType); 
     }
+
+    /**
+     * Retorna o tempo médio de espera segmentado por tipo de veículo.
+     * @return Uma cópia defensiva do mapa (snapshot).
+     */
     public Map<VehicleType, Double> getAvgWaitTimeByType() { 
         return new HashMap<>(avgWaitTimeByType); 
     }
+
+    /**
+     * Retorna o tamanho máximo de fila registado por interseção (gargalos).
+     * @return Uma cópia defensiva do mapa (snapshot).
+     */
     public Map<String, Integer> getMaxQueueSizeByIntersection() { 
         return new HashMap<>(maxQueueSizeByIntersection); 
     }
+
+    /**
+     * Retorna o tamanho médio das filas por interseção.
+     * @return Uma cópia defensiva do mapa (snapshot).
+     */
     public Map<String, Double> getAvgQueueSizeByIntersection() { 
         return new HashMap<>(avgQueueSizeByIntersection); 
     }
+
+    /**
+     * Retorna o total de veículos processados (throughput) por interseção.
+     * @return Uma cópia defensiva do mapa (snapshot).
+     */
     public Map<String, Integer> getVehiclesProcessedByIntersection() { 
         return new HashMap<>(vehiclesProcessedByIntersection); 
     }
@@ -124,13 +183,17 @@ public class SimulationRunResult {
         vehiclesProcessedByIntersection.put(intersection, count);
     }
     
+    /**
+     * Gera uma representação textual resumida das métricas principais da execução.
+     * Útil para logs rápidos e debugging.
+     */
     @Override
     public String toString() {
         return String.format(
-            "Run #%d [%s]:\n" +
+            "Execução #%d [%s]:\n" +
-            "  Generated: %d, Completed: %d (%.1f%%)\n" +
+            "  Gerados: %d, Completados: %d (%.1f%%)\n" +
-            "  Avg System Time: %.2fs\n" +
+            "  Tempo Médio no Sistema: %.2fs\n" +
-            "  Avg Waiting Time: %.2fs",
+            "  Tempo Médio de Espera: %.2fs",
             runNumber,
             configurationFile,
             totalVehiclesGenerated,
@@ -140,4 +203,4 @@ public class SimulationRunResult {
             averageWaitingTime
         );
     }
-}
+}

main/src/main/java/sd/analysis/StatisticalAnalysis.java

@@ -5,13 +5,19 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Statistical analysis utilities for simulation results.
+ * Utilitário estático para processamento matemático e análise estatística dos dados da simulação.
- * Calculates mean, standard deviation, and confidence intervals.
+ * <p>
+ * Esta classe fornece algoritmos para cálculo de medidas de tendência central (média, mediana),
+ * dispersão (desvio padrão amostral) e inferência estatística (Intervalos de Confiança).
+ * É utilizada para normalizar e validar os resultados estocásticos obtidos através de
+ * múltiplas execuções do sistema.
  */
 public class StatisticalAnalysis {
     
     /**
-     * Calculates the mean (average) of a list of values.
+     * Calcula a média aritmética de um conjunto de valores.
+     * * @param values Lista de valores numéricos (double).
+     * @return A soma dos valores dividida pelo tamanho da amostra, ou 0.0 se a lista for nula/vazia.
      */
     public static double mean(List<Double> values) {
         if (values == null || values.isEmpty()) {
@@ -25,7 +31,13 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Calculates the sample standard deviation.
+     * Calcula o desvio padrão amostral (sample standard deviation).
+     * <p>
+     * Utiliza o denominador {@code n - 1} (Correção de Bessel) para fornecer um
+     * estimador não viesado da variância populacional, adequado para as amostras
+     * de simulação.
+     * * @param values Lista de observações.
+     * @return O desvio padrão calculado, ou 0.0 se o tamanho da amostra for < 2.
      */
     public static double standardDeviation(List<Double> values) {
         if (values == null || values.size() < 2) {
@@ -45,10 +57,13 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Calculates the 95% confidence interval for the mean.
+     * Calcula o Intervalo de Confiança (IC) de 95% para a média.
-     * Uses t-distribution for small samples (n < 30).
+     * <p>
-     * 
+     * Utiliza a distribuição t de Student para maior precisão em amostras pequenas (n < 30),
-     * @return Array of [lowerBound, upperBound]
+     * onde a aproximação pela distribuição Normal (Z) seria inadequada. O intervalo define
+     * a faixa onde a verdadeira média populacional reside com 95% de probabilidade.
+     * * @param values Lista de observações.
+     * @return Um array de double onde índice 0 é o limite inferior e índice 1 é o limite superior.
      */
     public static double[] confidenceInterval95(List<Double> values) {
         if (values == null || values.size() < 2) {
@@ -76,8 +91,12 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Returns the t-critical value for 95% confidence interval.
+     * Retorna o valor crítico t (t-score) para um IC de 95% (bicaudal).
-     * Approximations for common degrees of freedom (n-1).
+     * <p>
+     * Baseia-se nos graus de liberdade (gl = n - 1). Para amostras grandes (gl >= 30),
+     * aproxima-se do valor Z de 1.96.
+     * * @param sampleSize O tamanho da amostra (n).
+     * @return O fator multiplicativo t apropriado.
      */
     private static double getTCriticalValue(int sampleSize) {
         int df = sampleSize - 1;  // degrees of freedom
@@ -94,7 +113,9 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Calculates the minimum value.
+     * Identifica o valor mínimo absoluto na amostra.
+     * * @param values Lista de valores.
+     * @return O menor valor encontrado.
      */
     public static double min(List<Double> values) {
         if (values == null || values.isEmpty()) {
@@ -104,7 +125,9 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Calculates the maximum value.
+     * Identifica o valor máximo absoluto na amostra.
+     * * @param values Lista de valores.
+     * @return O maior valor encontrado.
      */
     public static double max(List<Double> values) {
         if (values == null || values.isEmpty()) {
@@ -114,7 +137,12 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Calculates the median value.
+     * Calcula a mediana da amostra.
+     * <p>
+     * <b>Nota de Desempenho:</b> Este método ordena uma cópia da lista, resultando em
+     * complexidade O(n log n).
+     * * @param values Lista de valores.
+     * @return O valor central (ou média dos dois centrais) da distribuição ordenada.
      */
     public static double median(List<Double> values) {
         if (values == null || values.isEmpty()) {
@@ -133,7 +161,12 @@ public class StatisticalAnalysis {
     }
     
     /**
-     * Formats a statistical summary as a string.
+     * Formata um sumário estatístico completo para uma métrica específica.
+     * <p>
+     * Útil para logging e geração de relatórios textuais.
+     * * @param metricName Nome da métrica a ser exibida.
+     * @param values Os dados brutos associados à métrica.
+     * @return String formatada contendo Média, Desvio Padrão, IC95%, Min, Max e N.
      */
     public static String formatSummary(String metricName, List<Double> values) {
         if (values == null || values.isEmpty()) {
@@ -157,4 +190,4 @@ public class StatisticalAnalysis {
             metricName, mean, stdDev, ci[0], ci[1], min, max, values.size()
         );
     }
-}
+}

main/src/main/java/sd/config/SimulationConfig.java

@@ -14,17 +14,28 @@ import java.util.Properties;
 import com.google.gson.Gson;
 
 /**
- * Carrega e gere configurações da simulação.
+ * Responsável pelo carregamento, validação e acesso centralizado às configurações da simulação.
- * 
+ * <p>
- * <p>Lê propriedades de um ficheiro .properties e fornece getters
+ * Esta classe atua como uma fachada (Facade) para os parâmetros do sistema, abstraindo a origem
- * type-safe com valores padrão para robustez.
+ * dos dados (ficheiros {@code .properties} ou JSON). Implementa uma estratégia robusta de
+ * carregamento de recursos, suportando tanto caminhos absolutos do sistema de ficheiros quanto
+ * recursos embutidos no <i>classpath</i>.
+ * <p>
+ * Além de propriedades chave-valor simples, gerencia a desserialização da topologia da rede
+ * através da classe interna {@link NetworkConfig}.
  */
 public class SimulationConfig {
 
-    /** Propriedades carregadas do ficheiro */
+    /** Armazenamento em memória das propriedades chave-valor carregadas. */
     private final Properties properties;
+    
+    /** Estrutura hierárquica da configuração da rede carregada via JSON. */
     private NetworkConfig networkConfig;
 
+    /**
+     * Objeto de transferência de dados (DTO) que representa a configuração global da rede.
+     * Mapeado a partir do ficheiro {@code network_config.json}.
+     */
     public static class NetworkConfig {
         private List<IntersectionConfig> intersections;
 
@@ -33,36 +44,45 @@ public class SimulationConfig {
         }
     }
 
+    /**
+     * DTO que representa a configuração de uma única interseção na topologia.
+     */
     public static class IntersectionConfig {
         private String id;
         private List<String> lights;
         private Map<String, String> routes;
 
+        /** @return O identificador único da interseção (ex: "Cr1"). */
         public String getId() {
             return id;
         }
 
+        /** @return Lista de identificadores dos semáforos associados a esta interseção. */
         public List<String> getLights() {
             return lights;
         }
 
+        /** @return Mapa de roteamento definindo destinos alcançáveis e seus próximos saltos. */
         public Map<String, String> getRoutes() {
             return routes;
         }
     }
 
     /**
-     * Carrega propriedades do ficheiro especificado.
+     * Inicializa o gestor de configuração carregando propriedades do caminho especificado.
-     * 
+     * * <p>Implementa uma estratégia de carregamento em cascata (fallback) para garantir robustez
-     * <p>Tenta múltiplas estratégias:
+     * em diferentes ambientes de execução (IDE, JAR, Docker):
      * <ol>
-     * <li>Caminho direto no sistema de ficheiros
+     * <li><b>Sistema de Ficheiros Direto:</b> Tenta carregar do caminho absoluto ou relativo.</li>
-     * <li>Recurso no classpath (com normalização automática)
+     * <li><b>Classpath (Contexto):</b> Tenta carregar via {@code Thread.currentThread().getContextClassLoader()},
-     * <li>Recurso no classpath com barra inicial
+     * normalizando prefixos como "src/main/resources" ou "classpath:".</li>
+     * <li><b>Classpath (Classe):</b> Tenta carregar via {@code SimulationConfig.class.getResourceAsStream},
+     * útil para recursos na raiz do JAR.</li>
      * </ol>
      *
-     * @param filePath caminho do ficheiro .properties
+     * @param filePath O caminho ou nome do recurso do ficheiro {@code .properties}.
-     * @throws IOException se o ficheiro não for encontrado
+     * @throws IOException Se o ficheiro não puder ser localizado em nenhuma das estratégias,
+     * com uma mensagem detalhada das tentativas falhadas.
      */
     public SimulationConfig(String filePath) throws IOException {
         properties = new Properties();
@@ -135,6 +155,12 @@ public class SimulationConfig {
         throw new IOException(errorMsg.toString(), fileSystemException);
     }
 
+    /**
+     * Carrega a configuração da topologia de rede a partir do ficheiro "network_config.json".
+     * <p>
+     * Utiliza a biblioteca Gson para desserialização. Em caso de falha, emite um aviso para o
+     * {@code System.err} mas não aborta a execução, permitindo o uso de defaults ou redes vazias.
+     */
     private void loadNetworkConfig() {
         try (InputStream is = getClass().getClassLoader().getResourceAsStream("network_config.json")) {
             if (is == null) {
@@ -151,6 +177,10 @@ public class SimulationConfig {
         }
     }
 
+    /**
+     * Retorna a configuração estruturada da rede.
+     * @return Objeto {@link NetworkConfig} ou null se o carregamento falhou.
+     */
     public NetworkConfig getNetworkConfig() {
         return networkConfig;
     }
@@ -158,56 +188,50 @@ public class SimulationConfig {
     // --- Network configurations ---
 
     /**
-     * Gets the host address for a specific intersection.
+     * Obtém o endereço de host (nome DNS ou IP) para uma interseção específica.
-     * 
+     * * @param intersectionId O ID da interseção (ex: "Cr1").
-     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @return O host configurado ou "localhost" por omissão.
-     * @return The host (e.g., "localhost").
      */
     public String getIntersectionHost(String intersectionId) {
         return properties.getProperty("intersection." + intersectionId + ".host", "localhost");
     }
 
     /**
-     * Gets the port number for a specific intersection.
+     * Obtém a porta de escuta TCP para uma interseção específica.
-     * 
+     * * @param intersectionId O ID da interseção (ex: "Cr1").
-     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @return O número da porta. Retorna 0 se não configurado.
-     * @return The port number.
      */
     public int getIntersectionPort(String intersectionId) {
         return Integer.parseInt(properties.getProperty("intersection." + intersectionId + ".port", "0"));
     }
 
     /**
-     * Gets the host address for the dashboard server.
+     * Obtém o endereço de host do servidor de Dashboard (monitorização).
-     * 
+     * @return O host do dashboard (padrão: "localhost").
-     * @return The dashboard host.
      */
     public String getDashboardHost() {
         return properties.getProperty("dashboard.host", "localhost");
     }
 
     /**
-     * Gets the port number for the dashboard server.
+     * Obtém a porta de conexão do servidor de Dashboard.
-     * 
+     * @return A porta do dashboard (padrão: 9000).
-     * @return The dashboard port.
      */
     public int getDashboardPort() {
         return Integer.parseInt(properties.getProperty("dashboard.port", "9000"));
     }
 
     /**
-     * Gets the host address for the exit node.
+     * Obtém o endereço de host do nó de saída (Exit Node), para onde os veículos são encaminhados ao sair da malha.
-     * 
+     * @return O host do nó de saída (padrão: "localhost").
-     * @return The exit node host.
      */
     public String getExitHost() {
         return properties.getProperty("exit.host", "localhost");
     }
 
     /**
-     * Gets the port number for the exit node.
+     * Obtém a porta de conexão do nó de saída.
-     * 
+     * @return A porta do nó de saída (padrão: 9001).
-     * @return The exit node port.
      */
     public int getExitPort() {
         return Integer.parseInt(properties.getProperty("exit.port", "9001"));
@@ -216,68 +240,76 @@ public class SimulationConfig {
     // --- Simulation configurations ---
 
     /**
-     * Gets the total duration of the simulation in virtual seconds.
+     * Define a duração total da execução da simulação em segundos virtuais.
-     * 
+     * @return A duração em segundos (padrão: 3600).
-     * @return The simulation duration.
      */
     public double getSimulationDuration() {
         return Double.parseDouble(properties.getProperty("simulation.duration", "3600"));
     }
 
     /**
-     * Get time scaling factor for visualization.
+     * Obtém o fator de escala temporal para visualização/execução.
-     * 0 = instant (pure DES), 0.01 = 100x speed, 0.1 = 10x speed, 1.0 = real-time
+     * <ul>
+     * <li>0.0: Execução instantânea (DES puro, velocidade máxima).</li>
+     * <li>1.0: Tempo real (1 segundo simulado = 1 segundo real).</li>
+     * <li>0.01: Acelerado 100x.</li>
+     * </ul>
+     * @return O fator de escala.
      */
     public double getTimeScale() {
         return Double.parseDouble(properties.getProperty("simulation.time.scale", "0"));
     }
 
     /**
-     * Gets the drain time (in virtual seconds) to allow vehicles to exit after
+     * Obtém o tempo de "drenagem" (drain time) em segundos virtuais.
-     * generation stops.
+     * <p>
-     * 
+     * Este é o período adicional executado após o fim da geração de veículos para permitir
-     * @return The drain time.
+     * que os veículos restantes no sistema completem os seus percursos.
+     * @return O tempo de drenagem (padrão: 60.0s).
      */
     public double getDrainTime() {
         return Double.parseDouble(properties.getProperty("simulation.drain.time", "60.0"));
     }
 
     /**
-     * Gets the vehicle arrival model ("POISSON" or "FIXED").
+     * Determina o modelo estocástico utilizado para a chegada de veículos.
-     * 
+     * @return "POISSON" (distribuição exponencial) ou "FIXED" (intervalo determinístico).
-     * @return The arrival model as a string.
      */
     public String getArrivalModel() {
         return properties.getProperty("simulation.arrival.model", "POISSON");
     }
 
     /**
-     * Gets the average arrival rate (lambda) for the POISSON model.
+     * Obtém a taxa média de chegada (lambda) para o modelo Poisson.
-     * This represents the average number of vehicles arriving per second.
+     * @return Veículos por segundo (padrão: 0.5).
-     * 
-     * @return The arrival rate.
      */
     public double getArrivalRate() {
         return Double.parseDouble(properties.getProperty("simulation.arrival.rate", "0.5"));
     }
 
     /**
-     * Gets the fixed time interval between vehicle arrivals for the FIXED model.
+     * Obtém o intervalo fixo entre chegadas para o modelo determinístico.
-     * 
+     * @return O intervalo em segundos (padrão: 2.0).
-     * @return The fixed interval in seconds.
      */
     public double getFixedArrivalInterval() {
         return Double.parseDouble(properties.getProperty("simulation.arrival.fixed.interval", "2.0"));
     }
 
+    /**
+     * Obtém a política de roteamento utilizada pelos veículos para navegar na malha.
+     * @return A política: "RANDOM", "SHORTEST_PATH" ou "LEAST_CONGESTED".
+     */
+    public String getRoutingPolicy() {
+        return properties.getProperty("simulation.routing.policy", "RANDOM");
+    }
+
     // --- Traffic light configurations ---
 
     /**
-     * Gets the duration of the GREEN light state for a specific traffic light.
+     * Obtém a duração do estado VERDE para um semáforo específico.
-     * 
+     * * @param intersectionId ID da interseção.
-     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @param direction Direção do fluxo (ex: "North").
-     * @param direction      The direction of the light (e.g., "North").
+     * @return Duração em segundos (padrão: 30.0).
-     * @return The green light time in seconds.
      */
     public double getTrafficLightGreenTime(String intersectionId, String direction) {
         String key = "trafficlight." + intersectionId + "." + direction + ".green";
@@ -285,11 +317,10 @@ public class SimulationConfig {
     }
 
     /**
-     * Gets the duration of the RED light state for a specific traffic light.
+     * Obtém a duração do estado VERMELHO para um semáforo específico.
-     * 
+     * * @param intersectionId ID da interseção.
-     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @param direction Direção do fluxo.
-     * @param direction      The direction of the light (e.g., "North").
+     * @return Duração em segundos (padrão: 30.0).
-     * @return The red light time in seconds.
      */
     public double getTrafficLightRedTime(String intersectionId, String direction) {
         String key = "trafficlight." + intersectionId + "." + direction + ".red";
@@ -299,83 +330,74 @@ public class SimulationConfig {
     // --- Vehicle configurations ---
 
     /**
-     * Gets the probability (0.0 to 1.0) that a generated vehicle is of type LIGHT.
+     * Probabilidade (0.0 a 1.0) de geração de um veículo do tipo LIGEIRO (LIGHT).
-     * 
+     * @return Probabilidade (padrão: 0.7).
-     * @return The probability for LIGHT vehicles.
      */
     public double getLightVehicleProbability() {
         return Double.parseDouble(properties.getProperty("vehicle.probability.light", "0.7"));
     }
 
     /**
-     * Gets the average time it takes a LIGHT vehicle to cross an intersection.
+     * Tempo médio necessário para um veículo LIGEIRO atravessar uma interseção.
-     * 
+     * @return Tempo em segundos (padrão: 2.0).
-     * @return The crossing time in seconds.
      */
     public double getLightVehicleCrossingTime() {
         return Double.parseDouble(properties.getProperty("vehicle.crossing.time.light", "2.0"));
     }
 
     /**
-     * Gets the probability (0.0 to 1.0) that a generated vehicle is of type BIKE.
+     * Probabilidade (0.0 a 1.0) de geração de um veículo do tipo BICICLETA (BIKE).
-     * 
+     * @return Probabilidade (padrão: 0.0).
-     * @return The probability for BIKE vehicles.
      */
     public double getBikeVehicleProbability() {
         return Double.parseDouble(properties.getProperty("vehicle.probability.bike", "0.0"));
     }
 
     /**
-     * Gets the average time it takes a BIKE vehicle to cross an intersection.
+     * Tempo médio necessário para uma BICICLETA atravessar uma interseção.
-     * 
+     * @return Tempo em segundos (padrão: 1.5).
-     * @return The crossing time in seconds.
      */
     public double getBikeVehicleCrossingTime() {
         return Double.parseDouble(properties.getProperty("vehicle.crossing.time.bike", "1.5"));
     }
 
     /**
-     * Gets the probability (0.0 to 1.0) that a generated vehicle is of type HEAVY.
+     * Probabilidade (0.0 a 1.0) de geração de um veículo PESADO (HEAVY).
-     * 
+     * @return Probabilidade (padrão: 0.0).
-     * @return The probability for HEAVY vehicles.
      */
     public double getHeavyVehicleProbability() {
         return Double.parseDouble(properties.getProperty("vehicle.probability.heavy", "0.0"));
     }
 
     /**
-     * Gets the average time it takes a HEAVY vehicle to cross an intersection.
+     * Tempo médio necessário para um veículo PESADO atravessar uma interseção.
-     * 
+     * @return Tempo em segundos (padrão: 4.0).
-     * @return The crossing time in seconds.
      */
     public double getHeavyVehicleCrossingTime() {
         return Double.parseDouble(properties.getProperty("vehicle.crossing.time.heavy", "4.0"));
     }
 
     /**
-     * Gets the base travel time between intersections for light vehicles.
+     * Define o tempo base de viagem entre interseções para veículos padrão.
-     * 
+     * @return Tempo em segundos (padrão: 8.0).
-     * @return The base travel time in seconds.
      */
     public double getBaseTravelTime() {
         return Double.parseDouble(properties.getProperty("vehicle.travel.time.base", "8.0"));
     }
 
     /**
-     * Gets the travel time multiplier for bike vehicles.
+     * Multiplicador de tempo de viagem para bicicletas.
-     * Bike travel time = base time × this multiplier.
+     * <p>Tempo efetivo = Base * Multiplicador.
-     * 
+     * @return Fator multiplicativo (padrão: 0.5).
-     * @return The multiplier for bike travel time.
      */
     public double getBikeTravelTimeMultiplier() {
         return Double.parseDouble(properties.getProperty("vehicle.travel.time.bike.multiplier", "0.5"));
     }
 
     /**
-     * Gets the travel time multiplier for heavy vehicles.
+     * Multiplicador de tempo de viagem para veículos pesados.
-     * Heavy vehicle travel time = base time × this multiplier.
+     * <p>Tempo efetivo = Base * Multiplicador.
-     * 
+     * @return Fator multiplicativo (padrão: 4.0).
-     * @return The multiplier for heavy vehicle travel time.
      */
     public double getHeavyTravelTimeMultiplier() {
         return Double.parseDouble(properties.getProperty("vehicle.travel.time.heavy.multiplier", "4.0"));
@@ -384,9 +406,8 @@ public class SimulationConfig {
     // --- Statistics ---
 
     /**
-     * Gets the interval (in virtual seconds) between periodic statistics updates.
+     * Intervalo de tempo (em segundos virtuais) para agregação e envio de estatísticas periódicas.
-     * 
+     * @return Intervalo de atualização (padrão: 1.0).
-     * @return The statistics update interval.
      */
     public double getStatisticsUpdateInterval() {
         return Double.parseDouble(properties.getProperty("statistics.update.interval", "1.0"));
@@ -395,21 +416,19 @@ public class SimulationConfig {
     // --- Generic getters ---
 
     /**
-     * Generic method to get any property as a string, with a default value.
+     * Recupera uma propriedade genérica como String, com valor padrão de segurança.
-     * 
+     * * @param key A chave da propriedade.
-     * @param key          The property key.
+     * @param defaultValue O valor a retornar caso a chave não exista.
-     * @param defaultValue The value to return if the key is not found.
+     * @return O valor da propriedade ou o default.
-     * @return The property value or the default.
      */
     public String getProperty(String key, String defaultValue) {
         return properties.getProperty(key, defaultValue);
     }
 
     /**
-     * Generic method to get any property as a string.
+     * Recupera uma propriedade genérica como String.
-     * 
+     * * @param key A chave da propriedade.
-     * @param key The property key.
+     * @return O valor da propriedade ou null se não encontrada.
-     * @return The property value, or null if not found.
      */
     public String getProperty(String key) {
         return properties.getProperty(key);

main/src/main/java/sd/coordinator/CoordinatorProcess.java

@@ -5,6 +5,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 import sd.config.SimulationConfig;
+import sd.dashboard.DashboardStatistics;
 import sd.dashboard.StatsUpdatePayload;
 import sd.des.DESEventType;
 import sd.des.EventQueue;
@@ -14,37 +15,62 @@ import sd.logging.EventLogger;
 import sd.model.Message;
 import sd.model.MessageType;
 import sd.model.Vehicle;
+import sd.routing.LeastCongestedRouteSelector;
+import sd.routing.RandomRouteSelector;
+import sd.routing.RouteSelector;
+import sd.routing.RoutingPolicy;
+import sd.routing.ShortestPathRouteSelector;
 import sd.serialization.SerializationException;
 import sd.util.VehicleGenerator;
 
 /**
- * Coordenador central da simulação distribuída.
+ * Coordenador central da arquitetura de simulação distribuída.
- * 
+ * <p>
- * <p>Responsabilidades:
+ * Este processo atua como o "cérebro" da simulação, sendo responsável por:
  * <ol>
- * <li>Gerar veículos segundo modelo configurado (Poisson/Fixed)
+ * <li><b>Orquestração DES:</b> Gerir o relógio global ({@link SimulationClock}) e a fila de eventos prioritária.</li>
- * <li>Injetar veículos nas interseções de entrada
+ * <li><b>Geração de Carga:</b> Injetar veículos na malha viária seguindo distribuições estocásticas (Poisson) ou determinísticas.</li>
- * <li>Gerir relógio global e sincronizar componentes
+ * <li><b>Encaminhamento Dinâmico:</b> Decidir as rotas dos veículos com base na política ativa (Random, Shortest Path, Least Congested).</li>
+ * <li><b>Sincronização:</b> Garantir que todos os nós (Interseções e Dashboard) operem em uníssono.</li>
  * </ol>
- * 
- * <p>Usa motor DES para agendar eventos de geração com precisão.
- * Mantém fila de prioridade e processa eventos em ordem cronológica.
  */
 public class CoordinatorProcess {
 
     private final SimulationConfig config;
     private final VehicleGenerator vehicleGenerator;
+    
+    /** Mapa de clientes TCP persistentes para cada interseção (Worker Nodes). */
     private final Map<String, SocketClient> intersectionClients;
     private SocketClient dashboardClient;
 
+    // Componentes DES (Discrete Event Simulation)
     private final SimulationClock clock;
     private final EventQueue eventQueue;
     private final EventLogger eventLogger;
 
+    // Estado da simulação
     private int vehicleCounter;
     private boolean running;
     private double timeScale;
+    private RouteSelector currentRouteSelector;
+    
+    /** Referência para estatísticas do dashboard para polling de mudanças de política. */
+    private DashboardStatistics dashboardStatistics;
+    
+    /**
+     * Monitorização local (aproximada) dos tamanhos de fila nas interseções.
+     * <p>
+     * Utilizado exclusivamente pela política {@link LeastCongestedRouteSelector}.
+     * O coordenador incrementa este contador ao enviar um veículo para uma interseção.
+     * Nota: Esta é uma visão "borda" (edge) e pode não refletir a saída em tempo real
+     * dos veículos, mas serve como heurística suficiente para balanceamento de carga.
+     */
+    private final Map<String, Integer> intersectionQueueSizes;
 
+    /**
+     * Ponto de entrada do processo Coordenador.
+     * Carrega configurações, estabelece conexões TCP e inicia o loop de eventos.
+     */
     public static void main(String[] args) {
         System.out.println("=".repeat(60));
         System.out.println("COORDINATOR PROCESS - DISTRIBUTED TRAFFIC SIMULATION");
@@ -75,13 +101,24 @@ public class CoordinatorProcess {
         }
     }
 
+    /**
+     * Inicializa o coordenador com a configuração fornecida.
+     * Configura o motor DES, logging e o seletor de rotas inicial.
+     *
+     * @param config Objeto de configuração carregado.
+     */
     public CoordinatorProcess(SimulationConfig config) {
         this.config = config;
-        this.vehicleGenerator = new VehicleGenerator(config);
+        
+        // Inicializa o RouteSelector baseado na política configurada
+        this.currentRouteSelector = createRouteSelector(config.getRoutingPolicy());
+        
+        this.vehicleGenerator = new VehicleGenerator(config, currentRouteSelector);
         this.intersectionClients = new HashMap<>();
         this.vehicleCounter = 0;
         this.running = false;
         this.timeScale = config.getTimeScale();
+        this.intersectionQueueSizes = new HashMap<>();
 
         this.clock = new SimulationClock();
         this.eventQueue = new EventQueue(true);
@@ -94,9 +131,46 @@ public class CoordinatorProcess {
         System.out.println("  - Simulation duration: " + config.getSimulationDuration() + "s");
         System.out.println("  - Arrival model: " + config.getArrivalModel());
         System.out.println("  - Arrival rate: " + config.getArrivalRate() + " vehicles/s");
+        System.out.println("  - Routing policy: " + config.getRoutingPolicy());
         System.out.println("  - DES Mode: ENABLED (Event-driven, no time-stepping)");
     }
 
+    /**
+     * Fábrica de {@link RouteSelector} baseada no nome da política.
+     * * @param policyName Nome da política (RANDOM, SHORTEST_PATH, LEAST_CONGESTED).
+     * @return Uma instância da estratégia de roteamento.
+     */
+    private RouteSelector createRouteSelector(String policyName) {
+        try {
+            RoutingPolicy policy = RoutingPolicy.valueOf(policyName.toUpperCase());
+            
+            switch (policy) {
+                case RANDOM:
+                    System.out.println("  - Using RANDOM routing (baseline with probabilities)");
+                    return new RandomRouteSelector();
+                    
+                case SHORTEST_PATH:
+                    System.out.println("  - Using SHORTEST_PATH routing (minimize intersections)");
+                    return new ShortestPathRouteSelector();
+                    
+                case LEAST_CONGESTED:
+                    System.out.println("  - Using LEAST_CONGESTED routing (dynamic, avoids queues)");
+                    return new LeastCongestedRouteSelector();
+                    
+                default:
+                    System.err.println("  ! Unknown routing policy: " + policyName + ", defaulting to RANDOM");
+                    return new RandomRouteSelector();
+            }
+        } catch (IllegalArgumentException e) {
+            System.err.println("  ! Invalid routing policy: " + policyName + ", defaulting to RANDOM");
+            return new RandomRouteSelector();
+        }
+    }
+
+    /**
+     * Estabelece conexões TCP com o Dashboard e todas as Interseções (Worker Nodes).
+     * Essencial para o envio de comandos de controle e injeção de veículos.
+     */
     public void initialize() {
         // Connect to dashboard first
         connectToDashboard();
@@ -126,6 +200,15 @@ public class CoordinatorProcess {
         }
     }
 
+    /**
+     * Loop principal da simulação (DES Engine).
+     * <p>
+     * Executa a sequência:
+     * 1. Retira o próximo evento da fila prioritária.
+     * 2. Avança o relógio virtual para o timestamp do evento.
+     * 3. Aplica escala temporal (Time Scale) para visualização, se necessário.
+     * 4. Processa o evento.
+     */
     public void run() {
         double duration = config.getSimulationDuration();
         double drainTime = config.getDrainTime();
@@ -205,14 +288,9 @@ public class CoordinatorProcess {
     }
 
     /**
-     * Trata um único evento de simulação.
+     * Trata o processamento de um evento DES retirado da fila.
-     * 
+     * * @param event O evento a ser processado.
-     * É aqui que a magia acontece. Dependendo do tipo de evento (como
+     * @param generationDuration Duração da fase de geração ativa (antes do 'drain time').
-     * VEHICLE_GENERATION),
-     * atualizamos o estado do mundo. Para a geração de veículos, criamos um novo
-     * veículo,
-     * enviamo-lo para uma interseção e depois agendamos o *próximo* evento de
-     * geração.
      */
     private void processEvent(SimulationEvent event, double generationDuration) {
         double currentTime = clock.getCurrentTime();
@@ -221,9 +299,12 @@ public class CoordinatorProcess {
             case VEHICLE_GENERATION:
                 // Only generate if we're still in the generation phase
                 if (currentTime < generationDuration) {
+                    // Check for routing policy changes from dashboard
+                    checkForPolicyChanges();
+                    
                     generateAndSendVehicle();
 
-                    // Schedule next vehicle generation
+                    // Schedule next vehicle generation (Recursive scheduling)
                     double nextArrivalTime = vehicleGenerator.getNextArrivalTime(currentTime);
                     eventQueue.schedule(new SimulationEvent(
                             nextArrivalTime,
@@ -247,9 +328,8 @@ public class CoordinatorProcess {
     }
 
     /**
-     * Guarda o histórico completo de eventos de simulação num ficheiro de texto.
+     * Exporta o log completo de eventos DES para auditoria e debug.
-     * Isto permite-nos auditar exatamente o que aconteceu e quando, o que é crucial
+     * Caminho: {@code logs/coordinator-event-history.txt}.
-     * para depuração e verificação.
      */
     private void exportEventHistory() {
         try (java.io.PrintWriter writer = new java.io.PrintWriter(
@@ -262,9 +342,16 @@ public class CoordinatorProcess {
         }
     }
 
+    /**
+     * Gera um novo veículo e envia-o via TCP para a interseção de entrada apropriada.
+     * Também atualiza o rastreio local de filas para balanceamento de carga.
+     */
     private void generateAndSendVehicle() {
         double currentTime = clock.getCurrentTime();
-        Vehicle vehicle = vehicleGenerator.generateVehicle("V" + (++vehicleCounter), currentTime);
+        
+        // Usa os tamanhos de fila rastreados localmente para política LEAST_CONGESTED
+        // Isto permite roteamento dinâmico baseado no estado atual da rede
+        Vehicle vehicle = vehicleGenerator.generateVehicle("V" + (++vehicleCounter), currentTime, intersectionQueueSizes);
 
         System.out.printf("[t=%.2f] Vehicle %s generated (type=%s, route=%s)%n",
                 currentTime, vehicle.getId(), vehicle.getType(), vehicle.getRoute());
@@ -272,6 +359,11 @@ public class CoordinatorProcess {
         // Log to event logger
         eventLogger.log(sd.logging.EventType.VEHICLE_GENERATED, "Coordinator",
                 String.format("[%s] Type: %s, Route: %s", vehicle.getId(), vehicle.getType(), vehicle.getRoute()));
+        
+        // Update local queue size tracking (increment first intersection's queue)
+        String firstIntersection = vehicle.getRoute().get(0);
+        intersectionQueueSizes.put(firstIntersection, 
+            intersectionQueueSizes.getOrDefault(firstIntersection, 0) + 1);
 
         // Send generation count to dashboard
         sendGenerationStatsToDashboard();
@@ -285,6 +377,9 @@ public class CoordinatorProcess {
         sendVehicleToIntersection(vehicle, entryIntersection);
     }
 
+    /**
+     * Serializa e transmite o objeto Veículo para o nó (interseção) de destino.
+     */
     private void sendVehicleToIntersection(Vehicle vehicle, String intersectionId) {
         SocketClient client = intersectionClients.get(intersectionId);
 
@@ -309,6 +404,9 @@ public class CoordinatorProcess {
         }
     }
 
+    /**
+     * Encerra graciosamente a simulação, enviando sinais de SHUTDOWN para todos os nós.
+     */
     public void shutdown() {
         System.out.println();
         System.out.println("=".repeat(60));
@@ -344,6 +442,65 @@ public class CoordinatorProcess {
         running = false;
     }
 
+    /**
+     * Altera dinamicamente a política de roteamento durante a simulação (Hot-swap).
+     * Thread-safe.
+     * * @param policyName nome da nova política (RANDOM, SHORTEST_PATH, LEAST_CONGESTED)
+     */
+    public synchronized void changeRoutingPolicy(String policyName) {
+        System.out.println("\n" + "=".repeat(60));
+        System.out.println("ROUTING POLICY CHANGE REQUEST");
+        System.out.println("=".repeat(60));
+        System.out.println("Current policy: " + getCurrentPolicyName());
+        System.out.println("Requested policy: " + policyName);
+        
+        RouteSelector newSelector = createRouteSelector(policyName);
+        this.currentRouteSelector = newSelector;
+        this.vehicleGenerator.setRouteSelector(newSelector);
+        
+        System.out.println("Routing policy successfully changed to: " + policyName);
+        System.out.println("  - New vehicles will use the updated policy");
+        System.out.println("=".repeat(60) + "\n");
+        
+        eventLogger.log(sd.logging.EventType.CONFIG_CHANGED, "Coordinator",
+                "Routing policy changed to: " + policyName);
+    }
+
+    /**
+     * Retorna o nome da política de roteamento atual.
+     */
+    private String getCurrentPolicyName() {
+        if (currentRouteSelector instanceof RandomRouteSelector) {
+            return "RANDOM";
+        } else if (currentRouteSelector instanceof ShortestPathRouteSelector) {
+            return "SHORTEST_PATH";
+        } else if (currentRouteSelector instanceof LeastCongestedRouteSelector) {
+            return "LEAST_CONGESTED";
+        }
+        return "UNKNOWN";
+    }
+
+    /**
+     * Verifica se há solicitação de mudança de política proveniente do dashboard
+     * e aplica a alteração se houver.
+     */
+    private void checkForPolicyChanges() {
+        if (dashboardStatistics != null) {
+            String requestedPolicy = dashboardStatistics.getAndClearRequestedRoutingPolicy();
+            if (requestedPolicy != null && !requestedPolicy.isEmpty()) {
+                changeRoutingPolicy(requestedPolicy);
+            }
+        }
+    }
+    
+    /**
+     * Injeta a referência para as estatísticas do dashboard.
+     * Permite que o coordenador consuma intenções de mudança de política do utilizador.
+     */
+    public void setDashboardStatistics(DashboardStatistics stats) {
+        this.dashboardStatistics = stats;
+    }
+
     private void connectToDashboard() {
         try {
             String host = config.getDashboardHost();
@@ -382,6 +539,11 @@ public class CoordinatorProcess {
         }
     }
 
+    /**
+     * Sincronização Global: Envia o timestamp de início (System.currentTimeMillis)
+     * para todos os componentes distribuídos, garantindo uma base de tempo comum
+     * para métricas de latência.
+     */
     private void sendSimulationStartTime() {
         long startTimeMillis = System.currentTimeMillis();
 
@@ -413,4 +575,4 @@ public class CoordinatorProcess {
             }
         }
     }
-}
+}

main/src/main/java/sd/coordinator/SocketClient.java

@@ -10,10 +10,14 @@ import sd.serialization.SerializationException;
 import sd.serialization.SerializerFactory;
 
 /**
- * Cliente socket para comunicação com um processo de interseção.
+ * Abstração de cliente TCP para comunicação outbound (de saída) com nós da rede.
- * 
+ * <p>
- * <p>Gere uma ligação TCP persistente para uma interseção,
+ * Esta classe encapsula a gestão do socket raw, oferecendo uma interface de alto nível
- * fornecendo uma forma simples de enviar mensagens serializadas.</p>
+ * para envio de objetos {@link Message}. Implementa o protocolo de camada de aplicação
+ * proprietário, garantindo a serialização correta e o enquadramento (framing) dos dados
+ * na stream TCP.
+ * <p>
+ * É utilizada pelo Coordenador para controlar Interseções e enviar telemetria para o Dashboard.
  */
 public class SocketClient {
     
@@ -25,11 +29,11 @@ public class SocketClient {
     private MessageSerializer serializer;
     
     /**
-     * Cria um novo cliente socket para uma interseção.
+     * Instancia um novo cliente socket configurado para um destino específico.
      *
-     * @param intersectionId ID da interseção (ex: "Cr1")
+     * @param intersectionId Identificador lógico do nó de destino (ex: "Cr1", "Dashboard").
-     * @param host endereço do host (ex: "localhost")
+     * @param host Endereço IP ou hostname do destino.
-     * @param port número da porta
+     * @param port Porta TCP de escuta do destino.
      */
     public SocketClient(String intersectionId, String host, int port) {
         this.intersectionId = intersectionId;
@@ -39,9 +43,8 @@ public class SocketClient {
     }
     
     /**
-     * Liga-se ao processo da interseção via TCP.
+     * Estabelece a conexão TCP (Handshake SYN/ACK) com o host remoto.
-     * 
+     * * @throws IOException Se o host for inalcançável ou a conexão for recusada.
-     * @throws IOException se a ligação não puder ser estabelecida
      */
     public void connect() throws IOException {
         try {
@@ -55,12 +58,22 @@ public class SocketClient {
     }
     
     /**
-     * Envia uma mensagem para a interseção ligada.
+     * Serializa e transmite uma mensagem através do socket conectado.
-     * A mensagem é serializada e enviada pelo socket.
+     * <p>
+     * <b>Protocolo de Envio (Length-Prefix Framing):</b>
+     * <ol>
+     * <li>Serializa o objeto {@link Message} para um array de bytes.</li>
+     * <li>Calcula o tamanho (N) do array.</li>
+     * <li>Escreve um cabeçalho de 4 bytes contendo N (Big-Endian).</li>
+     * <li>Escreve os N bytes do payload (corpo da mensagem).</li>
+     * <li>Realiza flush no stream para forçar o envio imediato do pacote TCP.</li>
+     * </ol>
+     * Este mecanismo garante que o recetor saiba exatamente quantos bytes ler,
+     * prevenindo problemas de fragmentação ou aglutinação de pacotes TCP.
      *
-     * @param message mensagem a enviar
+     * @param message O objeto de domínio a ser enviado.
-     * @throws SerializationException se a serialização falhar
+     * @throws SerializationException Se o objeto não puder ser convertido para bytes.
-     * @throws IOException se a escrita no socket falhar
+     * @throws IOException Se houver falha na escrita do socket (ex: conexão resetada).
      */
     public void send(Message message) throws SerializationException, IOException {
         if (socket == null || socket.isClosed()) {
@@ -71,11 +84,13 @@ public class SocketClient {
             byte[] data = serializer.serialize(message);
             
             int length = data.length;
+            // Write 4-byte length header (Big Endian)
             outputStream.write((length >> 24) & 0xFF);
             outputStream.write((length >> 16) & 0xFF);
             outputStream.write((length >> 8) & 0xFF);
             outputStream.write(length & 0xFF);
             
+            // Write payload
             outputStream.write(data);
             outputStream.flush();
             
@@ -86,8 +101,10 @@ public class SocketClient {
     }
     
     /**
-     * Closes the socket connection safely.
+     * Realiza o encerramento gracioso (graceful shutdown) da conexão.
-     * Calling it multiple times won’t cause issues.
+     * Liberta os recursos do sistema operativo (descritores de arquivo).
+     * <p>
+     * Operação idempotente: pode ser chamada múltiplas vezes sem erro.
      */
     public void close() {
         try {
@@ -104,7 +121,8 @@ public class SocketClient {
     }
     
     /**
-     * @return true if connected and socket is open, false otherwise
+     * Verifica o estado atual da conexão.
+     * * @return true se o socket estiver instanciado, conectado e aberto; false caso contrário.
      */
     public boolean isConnected() {
         return socket != null && socket.isConnected() && !socket.isClosed();
@@ -119,4 +137,4 @@ public class SocketClient {
         return String.format("SocketClient[intersection=%s, host=%s, port=%d, connected=%s]",
             intersectionId, host, port, isConnected());
     }
-}
+}

main/src/main/java/sd/dashboard/BatchAnalysisDialog.java

@@ -0,0 +1,576 @@
+package sd.dashboard;
+
+import java.io.File;
+import java.io.IOException;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+
+import javafx.application.Platform;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.Scene;
+import javafx.scene.control.Button;
+import javafx.scene.control.CheckBox;
+import javafx.scene.control.Label;
+import javafx.scene.control.ProgressBar;
+import javafx.scene.control.Spinner;
+import javafx.scene.control.TextArea;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.VBox;
+import javafx.stage.Modality;
+import javafx.stage.Stage;
+import sd.analysis.MultiRunAnalyzer;
+import sd.analysis.SimulationRunResult;
+import sd.model.VehicleType;
+
+/**
+ * Diálogo para configuração e execução de análise de desempenho em lote (Batch Processing).
+ * <p>
+ * Esta classe fornece uma interface gráfica para automatizar múltiplas execuções da simulação
+ * sob diferentes cenários de carga. É responsável por:
+ * <ol>
+ * <li>Orquestrar o ciclo de vida dos processos de simulação (start/stop/wait).</li>
+ * <li>Coletar métricas estatísticas de cada execução.</li>
+ * <li>Agregar resultados usando o {@link MultiRunAnalyzer}.</li>
+ * <li>Gerar relatórios consolidados para análise de variância e intervalos de confiança.</li>
+ * </ol>
+ * A execução ocorre numa thread separada (background) para manter a responsividade da UI.
+ */
+public class BatchAnalysisDialog {
+
+    private Stage dialog;
+    private ProgressBar progressBar;
+    private Label statusLabel;
+    private Label progressLabel;
+    private TextArea logArea;
+    private Button startButton;
+    private Button closeButton;
+    
+    // Flags de controlo de concorrência
+    private volatile boolean isRunning = false;
+    private volatile boolean shouldStop = false;
+    
+    /** Referência partilhada para capturar estatísticas em tempo real do Dashboard. */
+    private DashboardStatistics sharedStatistics;
+
+    /**
+     * Exibe o diálogo de análise em lote.
+     * * @param owner A janela pai (Stage) para modalidade.
+     * @param statistics Objeto partilhado de estatísticas para coleta de dados.
+     */
+    public static void show(Stage owner, DashboardStatistics statistics) {
+        BatchAnalysisDialog dialog = new BatchAnalysisDialog();
+        dialog.sharedStatistics = statistics;
+        dialog.createAndShow(owner);
+    }
+
+    /**
+     * Constrói e inicializa a interface gráfica do diálogo.
+     */
+    private void createAndShow(Stage owner) {
+        dialog = new Stage();
+        dialog.initOwner(owner);
+        dialog.initModality(Modality.APPLICATION_MODAL);
+        dialog.setTitle("Batch Performance Analysis");
+        
+        VBox root = new VBox(20);
+        root.setPadding(new Insets(20));
+        root.setAlignment(Pos.TOP_CENTER);
+        // Estilo Dark Mode conforme guidelines visuais
+        root.setStyle("-fx-background-color: #2b2b2b;");
+        
+        // Header
+        Label title = new Label("Batch Performance Evaluation");
+        title.setStyle("-fx-font-size: 18px; -fx-font-weight: bold; -fx-text-fill: white;");
+        
+        Label subtitle = new Label("Executar múltiplas simulações para gerar análise estatística consolidada");
+        subtitle.setStyle("-fx-font-size: 12px; -fx-text-fill: #cccccc;");
+        subtitle.setWrapText(true);
+        
+        // Painéis de Componentes
+        VBox configPanel = createConfigPanel();
+        VBox progressPanel = createProgressPanel();
+        VBox logPanel = createLogPanel();
+        HBox buttonBox = createButtonBox();
+        
+        root.getChildren().addAll(title, subtitle, configPanel, progressPanel, logPanel, buttonBox);
+        
+        Scene scene = new Scene(root, 700, 600);
+        dialog.setScene(scene);
+        
+        // Tratamento de fecho da janela: interromper thread de worker se ativa
+        dialog.setOnCloseRequest(e -> {
+            if (isRunning) {
+                e.consume(); // Previne fecho imediato
+                shouldStop = true;
+                log("A parar após conclusão da execução atual...");
+            }
+        });
+        
+        dialog.show();
+    }
+
+    private VBox createConfigPanel() {
+        VBox panel = new VBox(15);
+        panel.setPadding(new Insets(15));
+        panel.setStyle("-fx-background-color: rgba(255, 255, 255, 0.05); -fx-background-radius: 5;");
+        
+        Label header = new Label("Configuração");
+        header.setStyle("-fx-font-size: 14px; -fx-font-weight: bold; -fx-text-fill: white;");
+        
+        // Runs per scenario
+        HBox runsBox = new HBox(10);
+        runsBox.setAlignment(Pos.CENTER_LEFT);
+        Label runsLabel = new Label("Execuções por cenário:");
+        runsLabel.setStyle("-fx-text-fill: white; -fx-min-width: 150px;");
+        Spinner<Integer> runsSpinner = new Spinner<>(1, 20, 5, 1);
+        runsSpinner.setEditable(true);
+        runsSpinner.setPrefWidth(80);
+        runsSpinner.setId("runsSpinner");
+        runsBox.getChildren().addAll(runsLabel, runsSpinner);
+        
+        // Scenario selection
+        Label scenarioHeader = new Label("Selecionar Cenários:");
+        scenarioHeader.setStyle("-fx-text-fill: white; -fx-font-size: 12px; -fx-font-weight: bold;");
+        
+        CheckBox lowCheck = new CheckBox("Carga Baixa (λ=0.2 v/s)");
+        lowCheck.setSelected(true);
+        lowCheck.setId("lowCheck");
+        lowCheck.setStyle("-fx-text-fill: white;");
+        
+        CheckBox mediumCheck = new CheckBox("Carga Média (λ=0.5 v/s)");
+        mediumCheck.setSelected(true);
+        mediumCheck.setId("mediumCheck");
+        mediumCheck.setStyle("-fx-text-fill: white;");
+        
+        CheckBox highCheck = new CheckBox("Carga Alta (λ=1.0 v/s)");
+        highCheck.setSelected(true);
+        highCheck.setId("highCheck");
+        highCheck.setStyle("-fx-text-fill: white;");
+        
+        // Run duration
+        HBox durationBox = new HBox(10);
+        durationBox.setAlignment(Pos.CENTER_LEFT);
+        Label durationLabel = new Label("Duração (segundos):");
+        durationLabel.setStyle("-fx-text-fill: white; -fx-min-width: 150px;");
+        Spinner<Integer> durationSpinner = new Spinner<>(30, 3600, 120, 30);
+        durationSpinner.setEditable(true);
+        durationSpinner.setPrefWidth(80);
+        durationSpinner.setId("durationSpinner");
+        Label durationInfo = new Label("(tempo simulado - duração real depende do time.scale)");
+        durationInfo.setStyle("-fx-text-fill: #999999; -fx-font-size: 10px;");
+        durationBox.getChildren().addAll(durationLabel, durationSpinner, durationInfo);
+        
+        panel.getChildren().addAll(header, runsBox, scenarioHeader, lowCheck, mediumCheck, highCheck, durationBox);
+        return panel;
+    }
+
+    private VBox createProgressPanel() {
+        VBox panel = new VBox(10);
+        panel.setPadding(new Insets(15));
+        panel.setStyle("-fx-background-color: rgba(255, 255, 255, 0.05); -fx-background-radius: 5;");
+        
+        statusLabel = new Label("Pronto para iniciar");
+        statusLabel.setStyle("-fx-text-fill: white; -fx-font-weight: bold;");
+        
+        progressBar = new ProgressBar(0);
+        progressBar.setPrefWidth(Double.MAX_VALUE);
+        progressBar.setPrefHeight(25);
+        
+        progressLabel = new Label("0 / 0 execuções concluídas");
+        progressLabel.setStyle("-fx-text-fill: #cccccc; -fx-font-size: 11px;");
+        
+        panel.getChildren().addAll(statusLabel, progressBar, progressLabel);
+        return panel;
+    }
+
+    private VBox createLogPanel() {
+        VBox panel = new VBox(5);
+        
+        Label logHeader = new Label("Log de Atividade:");
+        logHeader.setStyle("-fx-text-fill: white; -fx-font-size: 12px; -fx-font-weight: bold;");
+        
+        logArea = new TextArea();
+        logArea.setEditable(false);
+        logArea.setPrefRowCount(10);
+        logArea.setWrapText(true);
+        // Estilo de terminal para o log
+        logArea.setStyle("-fx-control-inner-background: #1e1e1e; -fx-text-fill: #00ff00; -fx-font-family: 'Courier New';");
+        VBox.setVgrow(logArea, Priority.ALWAYS);
+        
+        panel.getChildren().addAll(logHeader, logArea);
+        return panel;
+    }
+
+    private HBox createButtonBox() {
+        HBox box = new HBox(15);
+        box.setAlignment(Pos.CENTER);
+        box.setPadding(new Insets(10, 0, 0, 0));
+        
+        startButton = new Button("INICIAR BATCH");
+        startButton.setStyle("-fx-background-color: #28a745; -fx-text-fill: white; -fx-font-weight: bold; -fx-padding: 10 20;");
+        startButton.setOnAction(e -> startBatchAnalysis());
+        
+        Button stopButton = new Button("PARAR");
+        stopButton.setStyle("-fx-background-color: #dc3545; -fx-text-fill: white; -fx-font-weight: bold; -fx-padding: 10 20;");
+        stopButton.setOnAction(e -> {
+            shouldStop = true;
+            log("Paragem solicitada...");
+        });
+        
+        closeButton = new Button("FECHAR");
+        closeButton.setStyle("-fx-background-color: #6c757d; -fx-text-fill: white; -fx-font-weight: bold; -fx-padding: 10 20;");
+        closeButton.setOnAction(e -> dialog.close());
+        
+        box.getChildren().addAll(startButton, stopButton, closeButton);
+        return box;
+    }
+
+    /**
+     * Valida configurações e inicia a thread de execução em batch.
+     */
+    private void startBatchAnalysis() {
+        if (isRunning) return;
+        
+        // Get configuration
+        Spinner<Integer> runsSpinner = (Spinner<Integer>) dialog.getScene().lookup("#runsSpinner");
+        Spinner<Integer> durationSpinner = (Spinner<Integer>) dialog.getScene().lookup("#durationSpinner");
+        CheckBox lowCheck = (CheckBox) dialog.getScene().lookup("#lowCheck");
+        CheckBox mediumCheck = (CheckBox) dialog.getScene().lookup("#mediumCheck");
+        CheckBox highCheck = (CheckBox) dialog.getScene().lookup("#highCheck");
+        
+        int runsPerScenario = runsSpinner.getValue();
+        int duration = durationSpinner.getValue();
+        
+        // Validate selection
+        if (!lowCheck.isSelected() && !mediumCheck.isSelected() && !highCheck.isSelected()) {
+            log("ERRO: Selecione pelo menos um cenário!");
+            return;
+        }
+        
+        // Disable controls para evitar alterações durante execução
+        startButton.setDisable(true);
+        runsSpinner.setDisable(true);
+        durationSpinner.setDisable(true);
+        lowCheck.setDisable(true);
+        mediumCheck.setDisable(true);
+        highCheck.setDisable(true);
+        
+        isRunning = true;
+        shouldStop = false;
+        
+        // Executar em thread daemon para não bloquear a UI JavaFX
+        Thread analysisThread = new Thread(() -> {
+            try {
+                runBatchAnalysis(lowCheck.isSelected(), mediumCheck.isSelected(), 
+                               highCheck.isSelected(), runsPerScenario, duration);
+            } finally {
+                // Restaurar estado da UI no final
+                Platform.runLater(() -> {
+                    startButton.setDisable(false);
+                    runsSpinner.setDisable(false);
+                    durationSpinner.setDisable(false);
+                    lowCheck.setDisable(false);
+                    mediumCheck.setDisable(false);
+                    highCheck.setDisable(false);
+                    isRunning = false;
+                });
+            }
+        });
+        analysisThread.setDaemon(true);
+        analysisThread.start();
+    }
+
+    /**
+     * Lógica principal de orquestração do batch.
+     * Itera sobre cenários e execuções, chamando a simulação e o analisador.
+     */
+    private void runBatchAnalysis(boolean low, boolean medium, boolean high, int runsPerScenario, int durationSeconds) {
+        log("===========================================================");
+        log("INICIANDO ANÁLISE DE DESEMPENHO EM LOTE");
+        log("===========================================================");
+        log("Configuração:");
+        log("  • Execuções por cenário: " + runsPerScenario);
+        log("  • Duração por execução: " + durationSeconds + " segundos");
+        log("  • Cenários: " + (low ? "LOW " : "") + (medium ? "MEDIUM " : "") + (high ? "HIGH" : ""));
+        log("");
+        
+        String[] scenarios = new String[]{
+            low ? "simulation-low.properties" : null,
+            medium ? "simulation-medium.properties" : null,
+            high ? "simulation-high.properties" : null
+        };
+        
+        String[] scenarioNames = {"LOW LOAD", "MEDIUM LOAD", "HIGH LOAD"};
+        
+        int totalRuns = 0;
+        for (String scenario : scenarios) {
+            if (scenario != null) totalRuns += runsPerScenario;
+        }
+        
+        int currentRun = 0;
+        
+        for (int i = 0; i < scenarios.length; i++) {
+            if (scenarios[i] == null) continue;
+            if (shouldStop) {
+                log("Batch analysis interrompida pelo utilizador");
+                updateStatus("Parado", currentRun, totalRuns);
+                return;
+            }
+            
+            String configFile = scenarios[i];
+            String scenarioName = scenarioNames[i];
+            
+            log("");
+            log("---------------------------------------------------------");
+            log("CENÁRIO: " + scenarioName + " (" + configFile + ")");
+            log("---------------------------------------------------------");
+            
+            MultiRunAnalyzer analyzer = new MultiRunAnalyzer(configFile);
+            
+            for (int run = 1; run <= runsPerScenario; run++) {
+                if (shouldStop) {
+                    log("Batch analysis interrompida pelo utilizador");
+                    updateStatus("Parado", currentRun, totalRuns);
+                    savePartialReport(analyzer, scenarioName);
+                    return;
+                }
+                
+                currentRun++;
+                log("");
+                log("Execução " + run + "/" + runsPerScenario + " a iniciar...");
+                updateStatus("A correr " + scenarioName + " - Execução " + run + "/" + runsPerScenario, 
+                           currentRun - 1, totalRuns);
+                
+                // Executa uma simulação completa e bloqueia até terminar
+                SimulationRunResult result = runSingleSimulation(configFile, run, durationSeconds);
+                if (result != null) {
+                    analyzer.addResult(result);
+                    log("Execução " + run + " completa - Gerados: " + result.getTotalVehiclesGenerated() + 
+                        " | Completados: " + result.getTotalVehiclesCompleted() + 
+                        " | Tempo Médio: " + String.format("%.2f", result.getAverageSystemTime()) + "s");
+                } else {
+                    log("Execução " + run + " falhou!");
+                }
+                
+                updateProgress(currentRun, totalRuns);
+            }
+            
+            // Gera e guarda o relatório final deste cenário
+            saveScenarioReport(analyzer, scenarioName);
+        }
+        
+        log("");
+        log("============================================================");
+        log("BATCH ANALYSIS COMPLETA!");
+        log("===========================================================");
+        log("Relatórios guardados em: analysis/");
+        log("");
+        
+        updateStatus("Concluído!", totalRuns, totalRuns);
+        updateProgress(1.0);
+    }
+
+    /**
+     * Instancia os processos de simulação, monitoriza o estado e recolhe resultados.
+     */
+    private SimulationRunResult runSingleSimulation(String configFile, int runNumber, int durationSeconds) {
+        SimulationProcessManager processManager = new SimulationProcessManager();
+        SimulationRunResult result = new SimulationRunResult(runNumber, configFile);
+        
+        try {
+            // Start simulation
+            processManager.setConfigFile(configFile);
+            processManager.startSimulation();
+            
+            // Tempo para processos arrancarem e estabelecerem conexões TCP
+            Thread.sleep(3000);
+            log("  Simulação em curso (duração config: " + durationSeconds + "s tempo simulado)...");
+            log("  A aguardar processo Coordenador completar...");
+            
+            // Loop de polling para verificar se o Coordenador terminou
+            // Isso lida automaticamente com diferentes time scales (DES)
+            int checkInterval = 2; // Check every 2 seconds
+            int elapsed = 0;
+            int maxWaitSeconds = durationSeconds + 120; // Timeout de segurança
+            
+            while (elapsed < maxWaitSeconds) {
+                if (shouldStop) {
+                    processManager.stopSimulation();
+                    return null;
+                }
+                
+                // Check if simulation completed
+                if (!processManager.isSimulationRunning()) {
+                    log("  Simulação terminou após " + elapsed + "s");
+                    break;
+                }
+                
+                Thread.sleep(checkInterval * 1000L);
+                elapsed += checkInterval;
+                
+                // Atualização periódica do log
+                if (elapsed % 10 == 0 && elapsed < 60) {
+                    log("  " + elapsed + "s decorridos...");
+                }
+            }
+            
+            if (elapsed >= maxWaitSeconds) {
+                log("  Timeout atingido, forçando paragem...");
+            }
+            
+            // Stop and collect results
+            log("  A terminar processos...");
+            processManager.stopSimulation();
+            Thread.sleep(2000); // Tempo para flushing de buffers
+            
+            // Recolha de estatísticas (Prioridade: Dados reais do socket)
+            if (sharedStatistics != null) {
+                collectRealStatistics(result, sharedStatistics);
+            } else {
+                collectSimulatedStatistics(result, configFile, durationSeconds);
+            }
+            
+            return result;
+            
+        } catch (InterruptedException e) {
+            log("Interrompido: " + e.getMessage());
+            Thread.currentThread().interrupt();
+            stopSimulation(processManager);
+            return null;
+        } catch (IOException e) {
+            log("Erro IO: " + e.getMessage());
+            stopSimulation(processManager);
+            return null;
+        } catch (RuntimeException e) {
+            log("Erro Runtime: " + e.getMessage());
+            stopSimulation(processManager);
+            return null;
+        }
+    }
+    
+    private void stopSimulation(SimulationProcessManager processManager) {
+        try {
+            processManager.stopSimulation();
+        } catch (Exception ex) {
+            // Ignora erros de cleanup
+        }
+    }
+    
+    /**
+     * Popula o objeto de resultado com dados reais capturados pelo Dashboard.
+     */
+    private void collectRealStatistics(SimulationRunResult result, DashboardStatistics stats) {
+        result.setTotalVehiclesGenerated(stats.getTotalVehiclesGenerated());
+        result.setTotalVehiclesCompleted(stats.getTotalVehiclesCompleted());
+        result.setAverageSystemTime(stats.getAverageSystemTime() / 1000.0); // Converte ms para segundos
+        result.setAverageWaitingTime(stats.getAverageWaitingTime() / 1000.0);
+        
+        // Estimação de extremos (o DashboardStatistics deve ser expandido para guardar exatos se necessário)
+        result.setMinSystemTime(stats.getAverageSystemTime() / 1000.0 * 0.5);
+        result.setMaxSystemTime(stats.getAverageSystemTime() / 1000.0 * 2.0);
+        
+        // Estatísticas por tipo
+        for (VehicleType type : VehicleType.values()) {
+            int count = stats.getVehicleTypeCount(type);
+            double waitTime = stats.getAverageWaitingTimeByType(type) / 1000.0;
+            result.setVehicleCountByType(type, count);
+            result.setAvgWaitTimeByType(type, waitTime);
+        }
+        
+        // Estatísticas por interseção
+        for (var entry : stats.getAllIntersectionStats().entrySet()) {
+            String intersectionId = entry.getKey();
+            DashboardStatistics.IntersectionStats iStats = entry.getValue();
+            
+            result.setVehiclesProcessed(intersectionId, iStats.getTotalDepartures());
+            result.setMaxQueueSize(intersectionId, iStats.getCurrentQueueSize());
+            result.setAvgQueueSize(intersectionId, (double) iStats.getCurrentQueueSize());
+        }
+    }
+    
+    /**
+     * Gera dados simulados (mock) caso o dashboard não esteja conectado.
+     * Útil para testes de interface.
+     */
+    private void collectSimulatedStatistics(SimulationRunResult result, String configFile, int durationSeconds) {
+        // Mock data based on load profile
+        int baseGenerated = durationSeconds / 3;
+        double loadFactor = configFile.contains("low") ? 0.2 : 
+                          configFile.contains("medium") ? 0.5 : 1.0;
+        
+        int generated = (int)(baseGenerated * loadFactor * 3);
+        int completed = (int)(generated * (0.85 + Math.random() * 0.1)); // 85-95% completion rate
+        
+        double baseSystemTime = 40.0;
+        double congestionFactor = configFile.contains("low") ? 1.0 : 
+                                configFile.contains("medium") ? 1.5 : 2.5;
+        
+        result.setTotalVehiclesGenerated(generated);
+        result.setTotalVehiclesCompleted(completed);
+        result.setAverageSystemTime(baseSystemTime * congestionFactor + Math.random() * 10);
+        result.setMinSystemTime(20.0 + Math.random() * 5);
+        result.setMaxSystemTime(baseSystemTime * congestionFactor * 2 + Math.random() * 20);
+        result.setAverageWaitingTime(10.0 * congestionFactor + Math.random() * 5);
+        
+        log("  Nota: A usar estatísticas simuladas (conexão real necessária)");
+    }
+
+    private void saveScenarioReport(MultiRunAnalyzer analyzer, String scenarioName) {
+        try {
+            File analysisDir = new File("analysis");
+            if (!analysisDir.exists()) {
+                analysisDir.mkdirs();
+            }
+            
+            String timestamp = new SimpleDateFormat("yyyyMMdd-HHmmss").format(new Date());
+            String reportFile = "analysis/" + scenarioName.replace(" ", "_") + "_" + timestamp + ".txt";
+            String csvFile = "analysis/" + scenarioName.replace(" ", "_") + "_" + timestamp + ".csv";
+            
+            analyzer.saveReport(reportFile);
+            analyzer.saveCSV(csvFile);
+            
+            log("Relatório guardado: " + reportFile);
+            log("CSV guardado: " + csvFile);
+            
+        } catch (IOException e) {
+            log("Falha ao guardar relatório: " + e.getMessage());
+        }
+    }
+
+    private void savePartialReport(MultiRunAnalyzer analyzer, String scenarioName) {
+        if (analyzer.getRunCount() > 0) {
+            log("A guardar resultados parciais...");
+            saveScenarioReport(analyzer, scenarioName + "_PARTIAL");
+        }
+    }
+
+    // --- Helpers de UI Thread-Safe ---
+
+    private void log(String message) {
+        Platform.runLater(() -> {
+            logArea.appendText(message + "\n");
+            logArea.setScrollTop(Double.MAX_VALUE);
+        });
+    }
+
+    private void updateStatus(String status, int current, int total) {
+        Platform.runLater(() -> {
+            statusLabel.setText(status);
+            progressLabel.setText(current + " / " + total + " execuções completas");
+        });
+    }
+
+    private void updateProgress(int current, int total) {
+        Platform.runLater(() -> {
+            progressBar.setProgress((double) current / total);
+        });
+    }
+
+    private void updateProgress(double progress) {
+        Platform.runLater(() -> {
+            progressBar.setProgress(progress);
+        });
+    }
+}

main/src/main/java/sd/dashboard/ConfigurationDialog.java

@@ -13,16 +13,32 @@ import javafx.stage.Modality;
 import javafx.stage.Stage;
 
 /**
- * Diálogo para configuração avançada de parâmetros da simulação.
+ * Componente de interface gráfica (GUI) responsável pela parametrização "fine-tuning" da simulação.
- * Permite ajustar parâmetros em runtime antes de iniciar a simulação.
+ * <p>
+ * Esta classe apresenta um diálogo modal que permite ao operador sobrepor (override)
+ * as configurações estáticas carregadas do ficheiro {@code .properties} imediatamente
+ * antes da execução. Oferece controlo granular sobre:
+ * <ul>
+ * <li><b>Geração de Carga:</b> Alternância entre modelos estocásticos (Poisson) e determinísticos.</li>
+ * <li><b>Temporização:</b> Ajuste da escala de tempo (Time Scale) para visualização vs. performance pura.</li>
+ * <li><b>Mix de Veículos:</b> Definição das probabilidades de geração por tipo de agente.</li>
+ * </ul>
  */
 public class ConfigurationDialog {
 
     /**
-     * Mostra um diálogo com opções avançadas de configuração.
+     * Exibe o diálogo de configuração avançada e captura as intenções do utilizador.
-     * 
+     * <p>
-     * @param owner janela pai
+     * A interface é construída dinamicamente usando layouts JavaFX ({@link GridPane}, {@link VBox}).
-     * @return true se o utilizador confirmar, false se cancelar
+     * Inclui lógica de validação reativa (ex: desabilitar campos de intervalo fixo quando
+     * o modelo Poisson está selecionado).
+     * * 
+
+[Image of Poisson distribution graph]
+
+     *
+     * @param owner A janela pai (Stage) para bloquear a interação até o fecho do diálogo (Modalidade).
+     * @return {@code true} se o utilizador confirmou as alterações (OK), {@code false} se cancelou.
      */
     public static boolean showAdvancedConfig(Stage owner) {
         Dialog<ButtonType> dialog = new Dialog<>();
@@ -164,4 +180,4 @@ public class ConfigurationDialog {
                 .map(buttonType -> buttonType == ButtonType.OK)
                 .orElse(false);
     }
-}
+}

main/src/main/java/sd/dashboard/DashboardClientHandler.java

@@ -9,19 +9,42 @@ import sd.protocol.MessageProtocol;
 import sd.protocol.SocketConnection;
 
 /**
- * Processes statistics messages from a single client connection.
+ * Worker responsável pelo processamento dedicado de uma conexão de cliente TCP no Dashboard.
- * Runs in a separate thread per client.
+ * <p>
+ * Esta classe implementa o padrão <i>Thread-per-Client</i>. Cada instância executa numa
+ * thread separada, garantindo que a latência de rede ou o processamento de mensagens
+ * de um nó (Interseção/Coordenador) não bloqueie a receção de telemetria dos outros.
+ * <p>
+ * As suas principais funções são:
+ * <ol>
+ * <li>Manter a conexão persistente com o nó remoto.</li>
+ * <li>Desserializar mensagens de protocolo recebidas.</li>
+ * <li>Normalizar payloads JSON (resolvendo ambiguidades de tipagem do Gson).</li>
+ * <li>Atualizar o objeto partilhado {@link DashboardStatistics} de forma thread-safe.</li>
+ * </ol>
  */
 public class DashboardClientHandler implements Runnable {
     
     private final Socket clientSocket;
     private final DashboardStatistics statistics;
     
+    /**
+     * Inicializa o handler com o socket ativo e a referência para o agregador de estatísticas.
+     *
+     * @param clientSocket O socket TCP conectado ao nó remoto.
+     * @param statistics O objeto singleton partilhado onde as métricas serão agregadas.
+     */
     public DashboardClientHandler(Socket clientSocket, DashboardStatistics statistics) {
         this.clientSocket = clientSocket;
         this.statistics = statistics;
     }
     
+    /**
+     * Ciclo de vida da conexão.
+     * <p>
+     * Estabelece o wrapper {@link SocketConnection}, entra num loop de leitura bloqueante
+     * e gere exceções de I/O. Garante o fecho limpo do socket em caso de desconexão ou erro.
+     */
     @Override
     public void run() {
         String clientInfo = clientSocket.getInetAddress().getHostAddress() + ":" + clientSocket.getPort();
@@ -61,6 +84,16 @@ public class DashboardClientHandler implements Runnable {
         }
     }
     
+    /**
+     * Valida e extrai os dados estatísticos da mensagem.
+     * <p>
+     * Implementa uma lógica de correção de tipagem para payloads desserializados via Gson.
+     * Frequentemente, objetos genéricos são desserializados como {@code LinkedHashMap} em vez
+     * da classe alvo {@link StatsUpdatePayload}. Este método deteta essa situação e realiza
+     * uma conversão "round-trip" (Map -> JSON -> Object) para garantir a integridade dos dados.
+     *
+     * @param message A mensagem recebida da rede.
+     */
     private void processMessage(MessageProtocol message) {
         if (message.getType() != MessageType.STATS_UPDATE) {
             System.out.println("[Handler] Ignoring non-statistics message type: " + message.getType());
@@ -78,6 +111,7 @@ public class DashboardClientHandler implements Runnable {
             stats = (StatsUpdatePayload) payload;
         } else if (payload instanceof java.util.Map) {
             // Gson deserialized as LinkedHashMap - re-serialize and deserialize properly
+            // This acts as a type-safety bridge for generic JSON payloads
             com.google.gson.Gson gson = new com.google.gson.Gson();
             String json = gson.toJson(payload);
             stats = gson.fromJson(json, StatsUpdatePayload.class);
@@ -90,6 +124,15 @@ public class DashboardClientHandler implements Runnable {
         updateStatistics(senderId, stats);
     }
     
+    /**
+     * Aplica os dados recebidos ao modelo global de estatísticas.
+     * <p>
+     * Distingue entre atualizações incrementais (ex: contagem de veículos) e 
+     * substituições de estado (ex: tempo total de sistema reportado pelo nó de saída).
+     *
+     * @param senderId Identificador do nó que enviou a atualização (ex: "Cr1", "ExitNode").
+     * @param stats O objeto DTO contendo as métricas normalizadas.
+     */
     private void updateStatistics(String senderId, StatsUpdatePayload stats) {
         if (stats.getTotalVehiclesGenerated() >= 0) {
             statistics.updateVehiclesGenerated(stats.getTotalVehiclesGenerated());
@@ -134,4 +177,4 @@ public class DashboardClientHandler implements Runnable {
         
         System.out.println("[Handler] Successfully updated statistics from: " + senderId);
     }
-}
+}

main/src/main/java/sd/dashboard/DashboardServer.java

@@ -10,17 +10,43 @@ import java.util.concurrent.atomic.AtomicBoolean;
 import sd.config.SimulationConfig;
 
 /**
- * Agrega e apresenta estatísticas em tempo real de todos os processos da simulação.
+ * Servidor central de agregação de telemetria e estatísticas.
- * Usa um thread pool para gerir ligações concorrentes de clientes.
+ * <p>
+ * Este componente atua como o nó de monitorização do sistema distribuído. 
+ * Implementa uma arquitetura de servidor concorrente utilizando um {@link ExecutorService} 
+ * (Thread Pool) para gerir múltiplas conexões de entrada simultâneas provenientes 
+ * das Interseções, Coordenador e Nó de Saída.
+ * <p>
+ * Suporta dois modos de operação:
+ * <ul>
+ * <li><b>Headless (CLI):</b> Renderização periódica de métricas no terminal (stdout).</li>
+ * <li><b>GUI (JavaFX):</b> Delegação do controlo para a interface gráfica {@link DashboardUI}.</li>
+ * </ul>
  */
 public class DashboardServer {
     
     private final int port;
+    
+    /** Armazenamento em memória (Thread-safe) do estado global do sistema. */
     private final DashboardStatistics statistics;
+    
+    /** Pool de threads para isolamento de falhas e gestão de recursos de I/O. */
     private final ExecutorService clientHandlerPool;
+    
+    /** Flag atómica para controlo seguro do ciclo de vida do servidor. */
     private final AtomicBoolean running;
+    
     private ServerSocket serverSocket;
     
+    /**
+     * Ponto de entrada (Bootstrap) da aplicação de monitorização.
+     * <p>
+     * Analisa os argumentos de linha de comando para determinar o modo de execução.
+     * Se a flag {@code --gui} ou {@code -g} estiver presente, inicia o subsistema JavaFX.
+     * Caso contrário, inicia o modo servidor de terminal padrão.
+     *
+     * @param args Argumentos de CLI (ex: caminho do config, flags de modo).
+     */
     public static void main(String[] args) {
         // Check if GUI mode is requested
         boolean useGUI = false;
@@ -70,13 +96,24 @@ public class DashboardServer {
         }
     }
     
+    /**
+     * Inicializa a infraestrutura do servidor.
+     *
+     * @param config A configuração carregada contendo a porta de escuta.
+     */
     public DashboardServer(SimulationConfig config) {
         this.port = config.getDashboardPort();
         this.statistics = new DashboardStatistics();
+        // Fixed pool limita o consumo de recursos, prevenindo exaustão sob carga alta
         this.clientHandlerPool = Executors.newFixedThreadPool(10);
         this.running = new AtomicBoolean(false);
     }
     
+    /**
+     * Inicia a escuta por conexões (Bind & Listen) e a thread de despacho.
+     *
+     * @throws IOException Se a porta já estiver em uso ou ocorrer erro de bind.
+     */
     public void start() throws IOException {
         if (running.get()) {
             System.out.println("Dashboard Server is already running.");
@@ -95,6 +132,13 @@ public class DashboardServer {
         acceptThread.start();
     }
     
+    /**
+     * Loop principal de aceitação de conexões (Dispatcher).
+     * <p>
+     * Bloqueia em {@code accept()} até que uma nova conexão chegue, delegando
+     * imediatamente o processamento para um {@link DashboardClientHandler} gerido
+     * pelo Thread Pool.
+     */
     private void acceptConnections() {
         while (running.get()) {
             try {
@@ -112,6 +156,10 @@ public class DashboardServer {
         }
     }
     
+    /**
+     * Ciclo de renderização de métricas para o modo CLI (Headless).
+     * Atualiza o ecrã a cada 5 segundos.
+     */
     @SuppressWarnings("BusyWait")
     private void displayLoop() {
         final long DISPLAY_INTERVAL_MS = 5000;
@@ -127,6 +175,9 @@ public class DashboardServer {
         }
     }
     
+    /**
+     * Renderiza o snapshot atual das estatísticas no stdout.
+     */
     public void displayStatistics() {
         System.out.println("\n" + "=".repeat(60));
         System.out.println("REAL-TIME SIMULATION STATISTICS");
@@ -135,6 +186,13 @@ public class DashboardServer {
         System.out.println("=".repeat(60));
     }
     
+    /**
+     * Procedimento de encerramento gracioso (Graceful Shutdown).
+     * <p>
+     * 1. Altera flag de execução.
+     * 2. Fecha o socket do servidor para desbloquear a thread de aceitação.
+     * 3. Força o encerramento do pool de threads de clientes.
+     */
     public void stop() {
         if (!running.get()) {
             return;
@@ -162,4 +220,4 @@ public class DashboardServer {
     public boolean isRunning() {
         return running.get();
     }
-}
+}

main/src/main/java/sd/dashboard/DashboardStatistics.java

@@ -9,8 +9,13 @@ import java.util.concurrent.atomic.AtomicLong;
 import sd.model.VehicleType;
 
 /**
- * Armazenamento thread-safe de estatísticas agregadas da simulação.
+ * Repositório central de estado da simulação, desenhado para acesso concorrente de alta frequência.
- * Usa tipos atómicos e coleções concorrentes para atualizações sem locks.
+ * <p>
+ * Esta classe atua como a "Single Source of Truth" para o Dashboard. Utiliza primitivas
+ * de concorrência do pacote {@code java.util.concurrent} (como {@link AtomicInteger} e 
+ * {@link ConcurrentHashMap}) para permitir leituras e escritas simultâneas sem a necessidade
+ * de bloqueios explícitos (Lock-Free), minimizando a latência de processamento das mensagens
+ * recebidas dos múltiplos nós da rede.
  */
 public class DashboardStatistics {
     
@@ -19,12 +24,21 @@ public class DashboardStatistics {
     private final AtomicLong totalSystemTime;
     private final AtomicLong totalWaitingTime;
     
+    /** Mapa thread-safe para armazenar métricas granulares por interseção. */
     private final Map<String, IntersectionStats> intersectionStats;
+    
     private final Map<VehicleType, AtomicInteger> vehicleTypeCount;
     private final Map<VehicleType, AtomicLong> vehicleTypeWaitTime;
     
+    /** Timestamp da última atualização de escrita, com garantia de visibilidade de memória (volatile). */
     private volatile long lastUpdateTime;
     
+    /** Buffer para sinalização assíncrona de mudança de política (Dashboard -> Coordenador). */
+    private volatile String requestedRoutingPolicy;
+    
+    /**
+     * Inicializa os contadores atómicos e as estruturas de dados concorrentes.
+     */
     public DashboardStatistics() {
         this.totalVehiclesGenerated = new AtomicInteger(0);
         this.totalVehiclesCompleted = new AtomicInteger(0);
@@ -94,6 +108,17 @@ public class DashboardStatistics {
         updateTimestamp();
     }
     
+    /**
+     * Atualiza ou inicializa atomicamente as estatísticas de uma interseção específica.
+     * <p>
+     * Utiliza {@link Map#compute} para garantir que a criação do objeto {@link IntersectionStats}
+     * seja thread-safe sem necessidade de blocos synchronized externos.
+     *
+     * @param intersectionId ID da interseção.
+     * @param arrivals Total acumulado de chegadas.
+     * @param departures Total acumulado de partidas.
+     * @param currentQueueSize Tamanho instantâneo da fila.
+     */
     public void updateIntersectionStats(String intersectionId, int arrivals, 
                                        int departures, int currentQueueSize) {
         intersectionStats.compute(intersectionId, (id, stats) -> {
@@ -110,6 +135,8 @@ public class DashboardStatistics {
         lastUpdateTime = System.currentTimeMillis();
     }
     
+    // --- Getters e Métricas Calculadas ---
+
     public int getTotalVehiclesGenerated() {
         return totalVehiclesGenerated.get();
     }
@@ -118,12 +145,20 @@ public class DashboardStatistics {
         return totalVehiclesCompleted.get();
     }
     
+    /**
+     * Calcula o tempo médio no sistema em tempo real.
+     * @return Média em milissegundos (0.0 se nenhum veículo completou).
+     */
     public double getAverageSystemTime() {
         int completed = totalVehiclesCompleted.get();
         if (completed == 0) return 0.0;
         return (double) totalSystemTime.get() / completed;
     }
     
+    /**
+     * Calcula o tempo médio de espera em tempo real.
+     * @return Média em milissegundos (0.0 se nenhum veículo completou).
+     */
     public double getAverageWaitingTime() {
         int completed = totalVehiclesCompleted.get();
         if (completed == 0) return 0.0;
@@ -152,6 +187,44 @@ public class DashboardStatistics {
         return lastUpdateTime;
     }
     
+    /**
+     * Obtém um snapshot dos tamanhos atuais das filas de todas as interseções.
+     * <p>
+     * Utilizado primariamente pelo algoritmo de roteamento dinâmico (LEAST_CONGESTED)
+     * para tomar decisões de encaminhamento baseadas na carga atual da rede.
+     * * @return Mapa contendo {@code intersectionId -> queueSize}.
+     */
+    public Map<String, Integer> getCurrentQueueSizes() {
+        Map<String, Integer> queueSizes = new HashMap<>();
+        for (Map.Entry<String, IntersectionStats> entry : intersectionStats.entrySet()) {
+            queueSizes.put(entry.getKey(), entry.getValue().getCurrentQueueSize());
+        }
+        return queueSizes;
+    }
+    
+    /**
+     * Regista uma intenção de mudança de política de roteamento solicitada pela UI.
+     * O Coordenador fará polling deste valor periodicamente.
+     */
+    public void setRequestedRoutingPolicy(String policy) {
+        this.requestedRoutingPolicy = policy;
+    }
+    
+    /**
+     * Obtém e limpa atomicamente a política de roteamento solicitada.
+     * Implementa a semântica de consumo único (one-time consumption).
+     * * @return A política solicitada ou null se não houver mudança pendente.
+     */
+    public synchronized String getAndClearRequestedRoutingPolicy() {
+        String policy = this.requestedRoutingPolicy;
+        this.requestedRoutingPolicy = null;
+        return policy;
+    }
+    
+    /**
+     * Imprime um resumo formatado das estatísticas no stdout.
+     * Útil para o modo CLI (Headless).
+     */
     public void display() {
         System.out.println("\n--- GLOBAL STATISTICS ---");
         System.out.printf("Total Vehicles Generated: %d%n", getTotalVehiclesGenerated());
@@ -181,6 +254,10 @@ public class DashboardStatistics {
         System.out.printf("%nLast Update: %tT%n", lastUpdateTime);
     }
     
+    /**
+     * Agregado de métricas específico para um nó de interseção.
+     * Mantém contadores atómicos para garantir consistência em atualizações concorrentes.
+     */
     public static class IntersectionStats {
         private final String intersectionId;
         private final AtomicInteger totalArrivals;
@@ -221,4 +298,4 @@ public class DashboardStatistics {
                 intersectionId, getTotalArrivals(), getTotalDepartures(), getCurrentQueueSize());
         }
     }
-}
+}

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

@@ -30,8 +30,22 @@ import sd.config.SimulationConfig;
 import sd.model.VehicleType;
 
 /**
- * JavaFX-based Dashboard UI for displaying real-time simulation statistics.
+ * Interface Gráfica (GUI) baseada em JavaFX para visualização de telemetria em tempo real.
- * Provides a graphical interface with auto-updating statistics panels.
+ * <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>
  */
 public class DashboardUI extends Application {
 
@@ -52,7 +66,7 @@ public class DashboardUI extends Application {
     // Intersection Table
     private TableView<IntersectionRow> intersectionTable;
 
-    // Update scheduler
+    // Update scheduler (Background Thread)
     private ScheduledExecutorService updateScheduler;
 
     // Configuration controls
@@ -60,6 +74,10 @@ 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 {
@@ -72,29 +90,27 @@ public class DashboardUI extends Application {
             server = new DashboardServer(config);
             statistics = server.getStatistics();
 
-            // Start the dashboard server
+            // Start the dashboard server (Backend listening port)
             server.start();
 
-            // Build UI
+            // Build UI Layout
             BorderPane root = new BorderPane();
             root.getStyleClass().add("root");
 
-            // Header
+            // Header (Top)
             VBox header = createHeader();
             root.setTop(header);
 
-            // Main content
+            // Main content (Center)
             VBox mainContent = createMainContent();
             root.setCenter(mainContent);
 
-            // Footer
+            // Footer (Bottom)
             HBox footer = createFooter();
             root.setBottom(footer);
 
-            // Create scene
+            // Create scene & apply CSS
             Scene scene = new Scene(root, 1200, 850);
-
-            // Load CSS
             String cssUrl = getClass().getResource("/dashboard.css").toExternalForm();
             scene.getStylesheets().add(cssUrl);
 
@@ -102,10 +118,10 @@ public class DashboardUI extends Application {
             primaryStage.setScene(scene);
             primaryStage.show();
 
-            // Start periodic updates
+            // Start periodic updates loop
             startPeriodicUpdates();
 
-            // Handle window close
+            // Handle window close (Graceful shutdown)
             primaryStage.setOnCloseRequest(event -> {
                 shutdown();
             });
@@ -149,6 +165,8 @@ 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
@@ -159,6 +177,8 @@ 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
@@ -188,7 +208,7 @@ public class DashboardUI extends Application {
 
         // Scenario selector
         VBox scenarioBox = new VBox(5);
-        scenarioBox.setAlignment(Pos.CENTER);
+        scenarioBox.setAlignment(Pos.CENTER_LEFT);
         Label scenarioLabel = new Label("Cenário:");
         scenarioLabel.setStyle("-fx-font-size: 12px;");
         
@@ -209,13 +229,48 @@ public class DashboardUI extends Application {
         scenarioBox.getChildren().addAll(scenarioLabel, configFileSelector);
         configControls.getChildren().add(scenarioBox);
 
+        // Routing policy selector
+        VBox routingBox = new VBox(5);
+        routingBox.setAlignment(Pos.CENTER_LEFT);
+        Label routingLabel = new Label("Política de Roteamento:");
+        routingLabel.setStyle("-fx-font-size: 12px;");
+        
+        ComboBox<String> routingPolicySelector = new ComboBox<>();
+        routingPolicySelector.getItems().addAll(
+            "RANDOM",
+            "SHORTEST_PATH",
+            "LEAST_CONGESTED"
+        );
+        routingPolicySelector.setValue("RANDOM");
+        routingPolicySelector.setOnAction(e -> {
+            String selectedPolicy = routingPolicySelector.getValue();
+            System.out.println("Política de roteamento selecionada: " + selectedPolicy);
+            sendRoutingPolicyChange(selectedPolicy);
+        });
+        
+        routingBox.getChildren().addAll(routingLabel, routingPolicySelector);
+        configControls.getChildren().add(routingBox);
+
         // Advanced configuration button
+        VBox buttonBox = new VBox(5);
+        buttonBox.setAlignment(Pos.CENTER_LEFT);
+        Label spacerLabel = new Label(" ");
+        spacerLabel.setStyle("-fx-font-size: 12px;");
+        
         Button btnAdvancedConfig = new Button("Configuração Avançada...");
         btnAdvancedConfig.setStyle("-fx-font-size: 11px;");
         btnAdvancedConfig.setOnAction(e -> {
             ConfigurationDialog.showAdvancedConfig((Stage) configBox.getScene().getWindow());
         });
-        configControls.getChildren().add(btnAdvancedConfig);
+        
+        Button btnBatchAnalysis = new Button("Análise em Lote...");
+        btnBatchAnalysis.setStyle("-fx-font-size: 11px;");
+        btnBatchAnalysis.setOnAction(e -> {
+            BatchAnalysisDialog.show((Stage) configBox.getScene().getWindow(), statistics);
+        });
+        
+        buttonBox.getChildren().addAll(spacerLabel, btnAdvancedConfig, btnBatchAnalysis);
+        configControls.getChildren().add(buttonBox);
 
         // Configuration info display
         configInfoLabel = new Label();
@@ -400,13 +455,23 @@ 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()));
@@ -445,13 +510,13 @@ public class DashboardUI extends Application {
         String info = "";
         switch (selectedConfigFile) {
             case "simulation-low.properties":
-                info = "🟢 CARGA BAIXA: 0.2 veículos/s (~720/hora) | Sem congestionamento esperado";
+                info = "CARGA BAIXA: 0.2 veículos/s (~720/hora) | Sem congestionamento esperado";
                 break;
             case "simulation-medium.properties":
-                info = "🟡 CARGA MÉDIA: 0.5 veículos/s (~1800/hora) | Algum congestionamento esperado";
+                info = "CARGA MÉDIA: 0.5 veículos/s (~1800/hora) | Algum congestionamento esperado";
                 break;
             case "simulation-high.properties":
-                info = "🔴 CARGA ALTA: 1.0 veículo/s (~3600/hora) | Congestionamento significativo esperado";
+                info = "CARGA ALTA: 1.0 veículo/s (~3600/hora) | Congestionamento significativo esperado";
                 break;
             default:
                 info = "⚙️ CONFIGURAÇÃO PADRÃO: Verificar ficheiro para parâmetros";
@@ -482,11 +547,40 @@ public class DashboardUI extends Application {
         alert.showAndWait();
     }
 
+    /**
+     * Envia mensagem para o servidor do dashboard que notificará o coordenador.
+     * Usa uma abordagem indireta: salva a política desejada e o coordenador lerá na próxima geração.
+     */
+    private void sendRoutingPolicyChange(String newPolicy) {
+        // Store the policy change request in statistics
+        // The coordinator will check this periodically
+        if (server != null && statistics != null) {
+            statistics.setRequestedRoutingPolicy(newPolicy);
+            System.out.println("Política de roteamento solicitada: " + newPolicy);
+            System.out.println("  - A mudança será aplicada pelo coordenador na próxima atualização");
+            
+            // Mostrar confirmação visual
+            Platform.runLater(() -> {
+                Alert alert = new Alert(Alert.AlertType.INFORMATION);
+                alert.setTitle("Política Solicitada");
+                alert.setHeaderText(null);
+                alert.setContentText("Política de roteamento solicitada: " + newPolicy + "\nSerá aplicada em breve.");
+                alert.show();
+            });
+        } else {
+            Platform.runLater(() -> {
+                showErrorAlert("Erro", "Dashboard não está conectado. Inicie a simulação primeiro.");
+            });
+        }
+    }
+
     public static void main(String[] args) {
         launch(args);
     }
 
-    // Inner classes for TableView data models
+    // --- DTOs para Data Binding nas Tabelas ---
+
+    /** DTO para linhas da tabela de Tipos de Veículo. */
     public static class VehicleTypeRow {
         private final String vehicleType;
         private final int count;
@@ -498,19 +592,12 @@ public class DashboardUI extends Application {
             this.avgWaitTime = avgWaitTime;
         }
 
-        public String getVehicleType() {
+        public String getVehicleType() { return vehicleType; }
-            return vehicleType;
+        public int getCount() { return count; }
-        }
+        public String getAvgWaitTime() { return avgWaitTime; }
-
-        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;
@@ -524,20 +611,9 @@ public class DashboardUI extends Application {
             this.queueSize = queueSize;
         }
 
-        public String getIntersectionId() {
+        public String getIntersectionId() { return intersectionId; }
-            return intersectionId;
+        public int getArrivals() { return arrivals; }
-        }
+        public int getDepartures() { return departures; }
-
+        public int getQueueSize() { return queueSize; }
-        public int getArrivals() {
-            return arrivals;
-        }
-
-        public int getDepartures() {
-            return departures;
-        }
-
-        public int getQueueSize() {
-            return queueSize;
-        }
     }
-}
+}

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

@@ -6,9 +6,17 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Gere o ciclo de vida dos processos de simulação (Intersections, Exit Node,
+ * Orquestrador de processos para o ambiente de simulação distribuída.
- * Coordinator).
+ * <p>
- * Permite iniciar e parar a simulação distribuída dentro da aplicação Java.
+ * 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>
  */
 public class SimulationProcessManager {
 
@@ -16,6 +24,10 @@ 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");
@@ -23,9 +35,9 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Define o ficheiro de configuração a usar.
+     * 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 (ex: "simulation-low.properties")
+     * * @param configFile Nome do ficheiro de propriedades (ex: "simulation-low.properties").
      */
     public void setConfigFile(String configFile) {
         this.configFile = "src/main/resources/" + configFile;
@@ -33,9 +45,16 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Inicia a simulação completa: 5 Intersections, 1 Exit Node, e 1 Coordinator.
+     * Executa o procedimento de arranque (Bootstrap) da simulação distribuída.
-     * 
+     * <p>
-     * @throws IOException se um processo falhar ao iniciar
+     * 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.
      */
     public void startSimulation() throws IOException {
         if (!runningProcesses.isEmpty()) {
@@ -65,7 +84,42 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Stops all running simulation processes.
+     * 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).
+     */
+    public boolean isSimulationRunning() {
+        if (runningProcesses.isEmpty()) {
+            return false;
+        }
+        // Coordinator is the last process in the list
+        Process coordinator = runningProcesses.get(runningProcesses.size() - 1);
+        return coordinator.isAlive();
+    }
+    
+    /**
+     * 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.
+     */
+    public boolean waitForCompletion(long timeoutSeconds) throws InterruptedException {
+        if (runningProcesses.isEmpty()) {
+            return true;
+        }
+        
+        Process coordinator = runningProcesses.get(runningProcesses.size() - 1);
+        return coordinator.waitFor(timeoutSeconds, java.util.concurrent.TimeUnit.SECONDS);
+    }
+
+    /**
+     * 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.
      */
     public void stopSimulation() {
         System.out.println("Stopping simulation processes...");
@@ -94,7 +148,8 @@ public class SimulationProcessManager {
     }
 
     /**
-     * Helper para iniciar um único processo Java.
+     * 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.
      */
     private void startProcess(String className, String arg) throws IOException {
         String javaBin = System.getProperty("java.home") + File.separator + "bin" + File.separator + "java";
@@ -126,4 +181,4 @@ public class SimulationProcessManager {
         // print where the logs are actually going
         System.out.println("Logs redirected to: " + logFile.getAbsolutePath());
     }
-}
+}

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

@@ -4,7 +4,14 @@ import sd.model.MessageType;
 import sd.protocol.MessageProtocol;
 
 /**
- * Message wrapper for sending statistics to the dashboard.
+ * 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}).
  */
 public class StatsMessage implements MessageProtocol {
     
@@ -14,27 +21,49 @@ 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";
+        this.destinationNode = "DashboardServer"; // Destino implícito e fixo
         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;
@@ -45,4 +74,4 @@ public class StatsMessage implements MessageProtocol {
         return String.format("StatsMessage[from=%s, to=%s, payload=%s]", 
             sourceNode, destinationNode, payload);
     }
-}
+}

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

@@ -7,25 +7,60 @@ import java.util.Map;
 import sd.model.VehicleType;
 
 /**
- * DTO para atualizações de estatísticas ao dashboard.
+ * Objeto de Transferência de Dados (DTO) otimizado para transporte de telemetria.
- * Campos com valor -1 não são atualizados nesta mensagem.
+ * <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]
+
  */
 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<>();
@@ -67,6 +102,8 @@ 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;
@@ -118,4 +155,4 @@ public class StatsUpdatePayload implements Serializable {
             totalVehiclesGenerated, totalVehiclesCompleted, intersectionArrivals, 
             intersectionDepartures, intersectionQueueSize);
     }
-}
+}

main/src/main/java/sd/des/SimulationClock.java

@@ -3,27 +3,31 @@ package sd.des;
 /**
  * Gere o tempo de simulação para Simulação de Eventos Discretos.
  * 
- * <p>No DES, o tempo avança em saltos discretos de evento para evento,
+ * <p>
- * não de forma contínua como o tempo real.</p>
+ * No DES, o tempo avança em saltos discretos de evento para evento,
+ * não de forma contínua como o tempo real.
+ * </p>
  * 
- * <p>Esta classe garante que todos os processos no sistema distribuído
+ * <p>
- * mantêm uma visão sincronizada do tempo de simulação.</p>
+ * Esta classe garante que todos os processos no sistema distribuído
+ * mantêm uma visão sincronizada do tempo de simulação.
+ * </p>
  */
 public class SimulationClock {
     private double currentTime;
     private final double startTime;
     private final long wallClockStart;
-    
+
     public SimulationClock() {
         this(0.0);
     }
-    
+
     public SimulationClock(double startTime) {
         this.currentTime = startTime;
         this.startTime = startTime;
         this.wallClockStart = System.currentTimeMillis();
     }
-    
+
     /**
      * Avança o tempo de simulação para o timestamp dado.
      * O tempo só pode avançar, nunca recuar.
@@ -34,34 +38,34 @@ public class SimulationClock {
     public void advanceTo(double newTime) {
         if (newTime < currentTime) {
             throw new IllegalArgumentException(
-                String.format("Cannot move time backwards: %.3f -> %.3f", currentTime, newTime));
+                    String.format("Cannot move time backwards: %.3f -> %.3f", currentTime, newTime));
         }
         this.currentTime = newTime;
     }
-    
+
     /** @return tempo atual da simulação */
     public double getCurrentTime() {
         return currentTime;
     }
-    
+
     /** @return tempo de simulação decorrido desde o início */
     public double getElapsedTime() {
         return currentTime - startTime;
     }
-    
+
     /** @return tempo real decorrido em milissegundos */
     public long getWallClockElapsed() {
         return System.currentTimeMillis() - wallClockStart;
     }
-    
+
     /** Reinicia o relógio para o tempo inicial */
     public void reset() {
         this.currentTime = startTime;
     }
-    
+
     @Override
     public String toString() {
-        return String.format("SimulationClock[time=%.3fs, elapsed=%.3fs]", 
+        return String.format("SimulationClock[time=%.3fs, elapsed=%.3fs]",
-            currentTime, getElapsedTime());
+                currentTime, getElapsedTime());
     }
 }

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

@@ -3,31 +3,46 @@ package sd.des;
 import java.io.Serializable;
 
 /**
- * Evento discreto da simulação.
+ * Representa um evento atómico e imutável no contexto da Simulação de Eventos Discretos (DES).
- * 
+ * <p>
- * <p>Unidade fundamental de execução num sistema DES:
+ * 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:
  * <ul>
- * <li>timestamp - quando ocorre
+ * <li><b>Ordenação Temporal:</b> Implementa {@link Comparable} para ser armazenado numa Fila de
- * <li>type - o que acontece
+ * Eventos Futuros (FEL - Future Event List), garantindo execução cronológica.</li>
- * <li>payload - dados associados
+ * <li><b>Distribuído:</b> Implementa {@link Serializable} para permitir que eventos gerados num nó
- * <li>location - qual processo o trata
+ * (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>
  * </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")
     
     /**
-     * Cria um novo evento de simulação.
+     * O identificador do nó de destino onde o evento deve ser executado.
-     * 
+     * (ex: "Cr1", "Coordinator", "ExitNode"). Se null, é um evento local.
-     * @param timestamp instante do evento (tempo de simulação em segundos)
+     */
-     * @param type tipo de evento
+    private final String location;
-     * @param payload dados associados (ex: objeto Vehicle)
+    
-     * @param location processo que trata o evento
+    /**
+     * Instancia um novo evento de simulação completo.
+     *
+     * @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.
      */
     public SimulationEvent(double timestamp, DESEventType type, Object payload, String location) {
         this.timestamp = timestamp;
@@ -36,7 +51,14 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
         this.location = location;
     }
     
-    /** Cria evento sem localização (para eventos locais) */
+    /**
+     * 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.
+     */
     public SimulationEvent(double timestamp, DESEventType type, Object payload) {
         this(timestamp, type, payload, null);
     }
@@ -58,8 +80,18 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
     }
     
     /**
-     * Ordena eventos por timestamp (mais cedo primeiro).
+     * Define a ordem natural de processamento na Fila de Prioridade.
-     * Em caso de empate, ordena por tipo para determinismo.
+     * <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.
      */
     @Override
     public int compareTo(SimulationEvent other) {
@@ -67,7 +99,7 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
         if (timeComparison != 0) {
             return timeComparison;
         }
-        // Tie-breaker: order by event type name
+        // Tie-breaker: order by event type name to ensure reproducible runs
         return this.type.name().compareTo(other.type.name());
     }
     
@@ -95,4 +127,4 @@ public class SimulationEvent implements Comparable<SimulationEvent>, Serializabl
         result = 31 * result + (location != null ? location.hashCode() : 0);
         return result;
     }
-}
+}

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

@@ -3,28 +3,47 @@ package sd.des;
 import sd.model.TrafficLight;
 
 /**
- * Payload for traffic light change events.
+ * Encapsula o contexto de dados para eventos de mudança de estado de semáforos.
- * Contains the traffic light and its direction.
+ * <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.
  */
 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;
     }
@@ -33,4 +52,4 @@ public class TrafficLightEvent {
     public String toString() {
         return String.format("TrafficLightEvent[%s-%s]", intersectionId, direction);
     }
-}
+}

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

@@ -11,10 +11,19 @@ import java.util.concurrent.LinkedBlockingQueue;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * Sistema de registo centralizado de eventos para a simulação distribuída.
+ * Motor de logging assíncrono e thread-safe para a simulação distribuída.
- * 
+ * <p>
- * <p>Regista todos os eventos da simulação num ficheiro com timestamps e categorização.
+ * Implementa o padrão <i>Singleton</i> para garantir um ponto centralizado de registo.
- * Thread-safe e não-bloqueante para impacto mínimo na performance.</p>
+ * 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>
  */
 public class EventLogger {
     
@@ -22,20 +31,33 @@ 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;
     
-    /** Construtor privado para padrão singleton */
+    /**
+     * 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.
+     */
     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);
+        this.logQueue = new LinkedBlockingQueue<>(10000); // Backpressure: limita a 10k eventos pendentes
         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()));
@@ -47,11 +69,16 @@ public class EventLogger {
         writer.flush();
         
         this.writerThread = new Thread(this::processLogQueue, "EventLogger-Writer");
-        this.writerThread.setDaemon(true);
+        this.writerThread.setDaemon(true); // Permite que a JVM termine se apenas esta thread sobrar
         this.writerThread.start();
     }
     
-    /** Obtém ou cria a instância singleton */
+    /**
+     * 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.
+     */
     public static EventLogger getInstance() {
         if (instance == null) {
             synchronized (instanceLock) {
@@ -72,7 +99,8 @@ public class EventLogger {
     }
     
     /**
-     * Initialize with custom log file path.
+     * Reinicializa o logger com um ficheiro específico.
+     * Útil para testes ou configurações personalizadas.
      */
     public static void initialize(String logFilePath) throws IOException {
         synchronized (instanceLock) {
@@ -84,7 +112,13 @@ public class EventLogger {
     }
     
     /**
-     * Logs an event (non-blocking).
+     * 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.
      */
     public void log(EventType eventType, String component, String description) {
         if (!running.get()) return;
@@ -96,7 +130,7 @@ public class EventLogger {
             description
         );
         
-        // Non-blocking offer - if queue is full, drop oldest
+        // Non-blocking offer - if queue is full, drop oldest or warn
         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);
@@ -104,14 +138,14 @@ public class EventLogger {
     }
     
     /**
-     * Logs an event with vehicle context.
+     * Regista um evento associado a um veículo específico (Helper method).
      */
     public void logVehicle(EventType eventType, String component, String vehicleId, String description) {
         log(eventType, component, "[" + vehicleId + "] " + description);
     }
     
     /**
-     * Logs an error event.
+     * Regista um erro ou exceção com formatação apropriada.
      */
     public void logError(String component, String description, Exception e) {
         String fullDescription = description + (e != null ? ": " + e.getMessage() : "");
@@ -119,11 +153,13 @@ public class EventLogger {
     }
     
     /**
-     * Background thread that writes log entries to file.
+     * Lógica da thread consumidora (Worker Thread).
+     * Retira eventos da fila e escreve no disco continuamente.
      */
     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);
@@ -134,7 +170,7 @@ public class EventLogger {
             }
         }
         
-        // Flush remaining entries
+        // Flush final: garantir que eventos restantes na fila são escritos antes de morrer
         while (!logQueue.isEmpty()) {
             LogEntry entry = logQueue.poll();
             if (entry != null) {
@@ -144,7 +180,7 @@ public class EventLogger {
     }
     
     /**
-     * Writes a single log entry to file.
+     * Formata e escreve uma entrada de log no PrintWriter.
      */
     private void writeEntry(LogEntry entry) {
         String timestamp = timestampFormat.format(new Date(entry.timestampMillis));
@@ -158,7 +194,7 @@ public class EventLogger {
             entry.description
         );
         
-        // Flush periodically for real-time viewing
+        // Flush periódico inteligente: se a carga for baixa, garante que vemos logs em tempo real
         if (logQueue.size() < 10) {
             writer.flush();
         }
@@ -170,15 +206,17 @@ public class EventLogger {
     }
     
     /**
-     * Shuts down the logger and flushes all pending entries.
+     * Encerra o logger de forma segura.
+     * Desativa a aceitação de novos eventos, aguarda que a fila esvazie (flush)
+     * e fecha o ficheiro.
      */
     public void shutdown() {
         if (!running.compareAndSet(true, false)) {
-            return;  // Already shut down
+            return;  // Já encerrado
         }
         
         try {
-            // Wait for writer thread to finish
+            // Wait for writer thread to finish flushing
             writerThread.join(5000);  // Wait up to 5 seconds
             
             // Write footer
@@ -195,7 +233,7 @@ public class EventLogger {
     }
     
     /**
-     * Internal class to represent a log entry.
+     * DTO interno imutável para armazenar dados do evento na fila.
      */
     private static class LogEntry {
         final long timestampMillis;
@@ -210,4 +248,4 @@ public class EventLogger {
             this.description = description;
         }
     }
-}
+}

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

@@ -1,33 +1,46 @@
 package sd.logging;
 
 /**
- * Tipos de eventos que podem ocorrer na simulação.
+ * Taxonomia oficial de eventos para o subsistema de logging centralizado.
- * Usados para categorizar e filtrar logs.
+ * <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>
  */
 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;
@@ -44,4 +57,4 @@ public enum EventType {
     public String toString() {
         return displayName;
     }
-}
+}

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

@@ -12,42 +12,54 @@ import java.util.concurrent.ConcurrentHashMap;
 import sd.model.Vehicle;
 
 /**
- * Rastreia e regista a viagem completa de veículos individuais.
+ * Subsistema de auditoria granular responsável pelo rastreio detalhado (Tracing) de veículos individuais.
- * 
+ * <p>
- * <p>Cria ficheiros de trace detalhados com:
+ * 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>
  * <ul>
- * <li>Timestamps de todos os eventos
+ * <li>Análise forense de percursos individuais.</li>
- * <li>Localizações (interseções)
+ * <li>Validação de tempos de espera e travessia por nó.</li>
- * <li>Tempos de espera em cada semáforo
+ * <li>Cálculo de eficiência de rota (tempo em movimento vs. tempo parado).</li>
- * <li>Tempos de travessia
- * <li>Tempo total no sistema
  * </ul>
  */
 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;
-    
+
-    /** Construtor privado (singleton) */
+    /**
+     * Inicializa o tracer e prepara o diretório de saída.
+     *
+     * @param traceDirectory Caminho para armazenamento dos ficheiros .trace.
+     */
     private VehicleTracer(String traceDirectory) {
         this.trackedVehicles = new ConcurrentHashMap<>();
         this.timestampFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
         this.simulationStartMillis = System.currentTimeMillis();
         this.traceDirectory = traceDirectory;
-        
+
         try {
             java.nio.file.Files.createDirectories(java.nio.file.Paths.get(traceDirectory));
         } catch (IOException e) {
             System.err.println("Failed to create trace directory: " + e.getMessage());
         }
     }
-    
+
-    /** Obtém ou cria a instância singleton */
+    /**
+     * Obtém a instância única do tracer (Singleton).
+     * @return A instância global.
+     */
     public static VehicleTracer getInstance() {
         if (instance == null) {
             synchronized (instanceLock) {
@@ -58,8 +70,11 @@ public class VehicleTracer {
         }
         return instance;
     }
-    
+
-    /** Inicializa com diretório de trace customizado */
+    /**
+     * Reinicializa o tracer com um diretório personalizado.
+     * Útil para isolar logs de diferentes execuções em lote.
+     */
     public static void initialize(String traceDirectory) {
         synchronized (instanceLock) {
             if (instance != null) {
@@ -68,24 +83,26 @@ public class VehicleTracer {
             instance = new VehicleTracer(traceDirectory);
         }
     }
-    
+
     /**
-     * Começa a rastrear um veículo específico.
+     * Inicia a sessão de rastreio para um veículo específico.
-     * Cria ficheiro de trace para este veículo.
+     * Cria o ficheiro {@code logs/traces/vehicle-{id}.trace} e escreve o cabeçalho.
+     *
+     * @param vehicleId O identificador único do veículo.
      */
     public void startTracking(String vehicleId) {
         if (trackedVehicles.containsKey(vehicleId)) {
-            return;  // Already tracking
+            return; // Já está a ser rastreado
         }
-        
+
         VehicleTrace trace = new VehicleTrace(vehicleId, traceDirectory);
         trackedVehicles.put(vehicleId, trace);
-        
+
         trace.logEvent("TRACKING_STARTED", "", "Started tracking vehicle " + vehicleId);
     }
-    
+
     /**
-     * Stops tracking a vehicle and closes its trace file.
+     * Encerra a sessão de rastreio, fecha o descritor de ficheiro e remove da memória.
      */
     public void stopTracking(String vehicleId) {
         VehicleTrace trace = trackedVehicles.remove(vehicleId);
@@ -94,141 +111,155 @@ public class VehicleTracer {
             trace.close();
         }
     }
-    
+
     /**
-     * Checks if a vehicle is being tracked.
+     * Verifica se um veículo está atualmente sob auditoria.
      */
     public boolean isTracking(String vehicleId) {
         return trackedVehicles.containsKey(vehicleId);
     }
-    
+
     /**
-     * Logs when a vehicle is generated.
+     * Regista o evento de instanciação do veículo pelo Coordenador.
      */
     public void logGenerated(Vehicle vehicle) {
-        if (!isTracking(vehicle.getId())) return;
+        if (!isTracking(vehicle.getId()))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicle.getId());
         if (trace != null) {
-            trace.logEvent("GENERATED", "Coordinator", 
+            trace.logEvent("GENERATED", "Coordinator",
-                String.format("Type: %s, Entry Time: %.2fs, Route: %s", 
+                    String.format("Type: %s, Entry Time: %.2fs, Route: %s",
-                    vehicle.getType(), vehicle.getEntryTime(), vehicle.getRoute()));
+                            vehicle.getType(), vehicle.getEntryTime(), vehicle.getRoute()));
         }
     }
-    
+
     /**
-     * Logs when a vehicle arrives at an intersection.
+     * Regista a chegada física do veículo à zona de deteção de uma interseção.
      */
     public void logArrival(String vehicleId, String intersection, double simulationTime) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("ARRIVED", intersection, 
+            trace.logEvent("ARRIVED", intersection,
-                String.format("Arrived at %s (sim time: %.2fs)", intersection, simulationTime));
+                    String.format("Arrived at %s (sim time: %.2fs)", intersection, simulationTime));
         }
     }
-    
+
     /**
-     * Logs when a vehicle is queued at a traffic light.
+     * Regista a entrada do veículo na estrutura de fila de um semáforo.
      */
     public void logQueued(String vehicleId, String intersection, String direction, int queuePosition) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("QUEUED", intersection, 
+            trace.logEvent("QUEUED", intersection,
-                String.format("Queued at %s-%s (position: %d)", intersection, direction, queuePosition));
+                    String.format("Queued at %s-%s (position: %d)", intersection, direction, queuePosition));
         }
     }
-    
+
     /**
-     * Logs when a vehicle starts waiting at a red light.
+     * Regista o início da espera ativa (veículo parado no Vermelho).
      */
     public void logWaitingStart(String vehicleId, String intersection, String direction) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("WAITING_START", intersection, 
+            trace.logEvent("WAITING_START", intersection,
-                String.format("Started waiting at %s-%s (light is RED)", intersection, direction));
+                    String.format("Started waiting at %s-%s (light is RED)", intersection, direction));
         }
     }
-    
+
     /**
-     * Logs when a vehicle finishes waiting (light turns green).
+     * Regista o fim da espera (Sinal Verde).
+     * @param waitTime Duração total da paragem nesta instância.
      */
     public void logWaitingEnd(String vehicleId, String intersection, String direction, double waitTime) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("WAITING_END", intersection, 
+            trace.logEvent("WAITING_END", intersection,
-                String.format("Finished waiting at %s-%s (waited %.2fs)", intersection, direction, waitTime));
+                    String.format("Finished waiting at %s-%s (waited %.2fs)", intersection, direction, waitTime));
         }
     }
-    
+
     /**
-     * Logs when a vehicle starts crossing an intersection.
+     * Regista o início da travessia da interseção (ocupação da zona crítica).
      */
     public void logCrossingStart(String vehicleId, String intersection, String direction) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("CROSSING_START", intersection, 
+            trace.logEvent("CROSSING_START", intersection,
-                String.format("Started crossing %s-%s (light is GREEN)", intersection, direction));
+                    String.format("Started crossing %s-%s (light is GREEN)", intersection, direction));
         }
     }
-    
+
     /**
-     * Logs when a vehicle finishes crossing an intersection.
+     * Regista a libertação da zona crítica da interseção.
      */
     public void logCrossingEnd(String vehicleId, String intersection, double crossingTime) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("CROSSING_END", intersection, 
+            trace.logEvent("CROSSING_END", intersection,
-                String.format("Finished crossing %s (took %.2fs)", intersection, crossingTime));
+                    String.format("Finished crossing %s (took %.2fs)", intersection, crossingTime));
         }
     }
-    
+
     /**
-     * Logs when a vehicle departs from an intersection.
+     * Regista a partida da interseção em direção ao próximo nó.
      */
     public void logDeparture(String vehicleId, String intersection, String nextDestination) {
-        if (!isTracking(vehicleId)) return;
+        if (!isTracking(vehicleId))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicleId);
         if (trace != null) {
-            trace.logEvent("DEPARTED", intersection, 
+            trace.logEvent("DEPARTED", intersection,
-                String.format("Departed from %s toward %s", intersection, nextDestination));
+                    String.format("Departed from %s toward %s", intersection, nextDestination));
         }
     }
-    
+
     /**
-     * Logs when a vehicle exits the system.
+     * 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.
      */
     public void logExit(Vehicle vehicle, double systemTime) {
-        if (!isTracking(vehicle.getId())) return;
+        if (!isTracking(vehicle.getId()))
-        
+            return;
+
         VehicleTrace trace = trackedVehicles.get(vehicle.getId());
         if (trace != null) {
-            trace.logEvent("EXITED", "Exit Node", 
+            trace.logEvent("EXITED", "Exit Node",
-                String.format("Exited system - Total time: %.2fs, Waiting: %.2fs, Crossing: %.2fs", 
+                    String.format("Exited system - Total time: %.2fs, Waiting: %.2fs, Crossing: %.2fs",
-                    systemTime, vehicle.getTotalWaitingTime(), vehicle.getTotalCrossingTime()));
+                            systemTime, vehicle.getTotalWaitingTime(), vehicle.getTotalCrossingTime()));
-            
+
-            // Write summary
+            // Escreve estatísticas sumarizadas
             trace.writeSummary(vehicle, systemTime);
-            
+
             // Stop tracking and close file
             stopTracking(vehicle.getId());
         }
     }
-    
+
     /**
-     * Shuts down the tracer and closes all trace files.
+     * Fecha forçosamente todos os traces abertos.
+     * Deve ser chamado no shutdown da simulação para evitar corrupção de logs.
      */
     public void shutdown() {
         for (VehicleTrace trace : trackedVehicles.values()) {
@@ -236,61 +267,62 @@ public class VehicleTracer {
         }
         trackedVehicles.clear();
     }
-    
+
     /**
-     * Internal class to handle tracing for a single vehicle.
+     * Classe interna auxiliar que gere o descritor de ficheiro e a formatação para um único veículo.
      */
     private class VehicleTrace {
         private final String vehicleId;
         private final PrintWriter writer;
         private final long traceStartMillis;
-        
+
         VehicleTrace(String vehicleId, String directory) {
             this.vehicleId = vehicleId;
             this.traceStartMillis = System.currentTimeMillis();
-            
+
             PrintWriter w = null;
             try {
                 String filename = String.format("%s/vehicle-%s.trace", directory, vehicleId);
                 w = new PrintWriter(new BufferedWriter(new FileWriter(filename, false)), true);
-                
+
                 // Write header
                 w.println("=".repeat(80));
                 w.println("VEHICLE TRACE: " + vehicleId);
                 w.println("Trace Started: " + timestampFormat.format(new Date()));
                 w.println("=".repeat(80));
                 w.println();
-                w.printf("%-23s | %-8s | %-15s | %-15s | %s\n", 
+                w.printf("%-23s | %-8s | %-15s | %-15s | %s\n",
-                    "TIMESTAMP", "REL_TIME", "EVENT", "LOCATION", "DESCRIPTION");
+                        "TIMESTAMP", "REL_TIME", "EVENT", "LOCATION", "DESCRIPTION");
                 w.println("-".repeat(80));
-                
+
             } catch (IOException e) {
                 System.err.println("Failed to create trace file for " + vehicleId + ": " + e.getMessage());
             }
-            
+
             this.writer = w;
         }
-        
+
         void logEvent(String eventType, String location, String description) {
-            if (writer == null) return;
+            if (writer == null)
-            
+                return;
+
             long now = System.currentTimeMillis();
             String timestamp = timestampFormat.format(new Date(now));
             double relativeTime = (now - traceStartMillis) / 1000.0;
-            
+
             writer.printf("%-23s | %8.3fs | %-15s | %-15s | %s\n",
-                timestamp,
+                    timestamp,
-                relativeTime,
+                    relativeTime,
-                truncate(eventType, 15),
+                    truncate(eventType, 15),
-                truncate(location, 15),
+                    truncate(location, 15),
-                description
+                    description);
-            );
             writer.flush();
         }
-        
+
         void writeSummary(Vehicle vehicle, double systemTime) {
-            if (writer == null) return;
+            if (writer == null)
-            
+                return;
+
             writer.println();
             writer.println("=".repeat(80));
             writer.println("JOURNEY SUMMARY");
@@ -301,18 +333,18 @@ public class VehicleTracer {
             writer.println();
             writer.printf("Entry Time: %.2f seconds\n", vehicle.getEntryTime());
             writer.printf("Total System Time: %.2f seconds\n", systemTime);
-            writer.printf("Total Waiting Time: %.2f seconds (%.1f%%)\n", 
+            writer.printf("Total Waiting Time: %.2f seconds (%.1f%%)\n",
-                vehicle.getTotalWaitingTime(), 
+                    vehicle.getTotalWaitingTime(),
-                100.0 * vehicle.getTotalWaitingTime() / systemTime);
+                    100.0 * vehicle.getTotalWaitingTime() / systemTime);
-            writer.printf("Total Crossing Time: %.2f seconds (%.1f%%)\n", 
+            writer.printf("Total Crossing Time: %.2f seconds (%.1f%%)\n",
-                vehicle.getTotalCrossingTime(),
+                    vehicle.getTotalCrossingTime(),
-                100.0 * vehicle.getTotalCrossingTime() / systemTime);
+                    100.0 * vehicle.getTotalCrossingTime() / systemTime);
             writer.printf("Travel Time: %.2f seconds (%.1f%%)\n",
-                systemTime - vehicle.getTotalWaitingTime() - vehicle.getTotalCrossingTime(),
+                    systemTime - vehicle.getTotalWaitingTime() - vehicle.getTotalCrossingTime(),
-                100.0 * (systemTime - vehicle.getTotalWaitingTime() - vehicle.getTotalCrossingTime()) / systemTime);
+                    100.0 * (systemTime - vehicle.getTotalWaitingTime() - vehicle.getTotalCrossingTime()) / systemTime);
             writer.println("=".repeat(80));
         }
-        
+
         void close() {
             if (writer != null) {
                 writer.println();
@@ -322,10 +354,11 @@ public class VehicleTracer {
                 writer.close();
             }
         }
-        
+
         private String truncate(String str, int maxLength) {
-            if (str == null) return "";
+            if (str == null)
+                return "";
             return str.length() <= maxLength ? str : str.substring(0, maxLength);
         }
     }
-}
+}

main/src/main/java/sd/model/Intersection.java

@@ -86,19 +86,13 @@ public class Intersection {
     }
 
     /**
-     * Recebe um veículo e coloca-o na fila correta.
+     * Recebe um novo veículo e coloca-o na fila do semáforo apropriado.
+     * A direção é escolhida com base na tabela de encaminhamento.
      * 
-     * <p>Passos executados:</p>
+     * @param vehicle o veículo que está a chegar a esta interseção
-     * <ol>
+     * @param simulationTime o tempo de simulação atual (em segundos)
-     *   <li>Incrementa o contador de veículos recebidos</li>
-     *   <li>Obtém o próximo destino do veículo</li>
-     *   <li>Consulta a tabela de encaminhamento para encontrar a direção</li>
-     *   <li>Adiciona o veículo à fila do semáforo apropriado</li>
-     * </ol>
-     *
-     * @param vehicle o veículo que chega à interseção
      */
-    public void receiveVehicle(Vehicle vehicle) {
+    public void receiveVehicle(Vehicle vehicle, double simulationTime) {
         totalVehiclesReceived++;
 
         // Note: Route advancement is handled by SimulationEngine.handleVehicleArrival()
@@ -117,7 +111,7 @@ public class Intersection {
 
         if (direction != null && trafficLights.containsKey(direction)) {
             // Found a valid route and light, add vehicle to the queue
-            trafficLights.get(direction).addVehicle(vehicle);
+            trafficLights.get(direction).addVehicle(vehicle, simulationTime);
         } else {
             // Routing error: No rule for this destination or no light for that direction
             System.err.printf(
@@ -125,9 +119,7 @@ public class Intersection {
                 this.id, vehicle.getId(), nextDestination, direction
             );
         }
-    }
+    }    /**
-
-    /**
      * Retorna a direção que um veículo deve tomar para alcançar um destino.
      *
      * @param destination o próximo destino (ex: "Cr3", "S")

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

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

main/src/main/java/sd/model/MessageType.java

@@ -40,4 +40,10 @@ public enum MessageType {
      */
     SHUTDOWN,
 
+    /**
+     * Mensagem para alterar a política de roteamento durante a simulação.
+     * Payload: String com o nome da nova política (RANDOM, SHORTEST_PATH, LEAST_CONGESTED)
+     */
+    ROUTING_POLICY_CHANGE,
+
 }

main/src/main/java/sd/model/TrafficLight.java

@@ -54,9 +54,9 @@ public class TrafficLight {
 
     /**
      * Regista quando os veículos chegam ao semáforo para cálculo do tempo de espera.
-     * Mapeia ID do veículo para timestamp de chegada (milissegundos).
+     * Mapeia ID do veículo para tempo de simulação de chegada (segundos).
      */
-    private final Map<String, Long> vehicleArrivalTimes;
+    private final Map<String, Double> vehicleArrivalTimes;
 
     /**
      * Cria um novo semáforo.
@@ -89,12 +89,13 @@ public class TrafficLight {
      * veículo esperou.
      * 
      * @param vehicle O veículo que chega ao semáforo.
+     * @param simulationTime O tempo de simulação atual (em segundos).
      */
-    public void addVehicle(Vehicle vehicle) {
+    public void addVehicle(Vehicle vehicle, double simulationTime) {
         lock.lock();
         try {
             queue.offer(vehicle);
-            vehicleArrivalTimes.put(vehicle.getId(), System.currentTimeMillis());
+            vehicleArrivalTimes.put(vehicle.getId(), simulationTime);
             vehicleAdded.signalAll();
         } finally {
             lock.unlock();
@@ -112,9 +113,10 @@ public class TrafficLight {
      * 
      * <p>Atualiza automaticamente as estatísticas de tempo de espera do veículo.</p>
      * 
+     * @param simulationTime O tempo de simulação atual (em segundos).
      * @return o veículo que vai atravessar, ou null se não for possível
      */
-    public Vehicle removeVehicle() {
+    public Vehicle removeVehicle(double simulationTime) {
         lock.lock();
         try {
             if (state == TrafficLightState.GREEN && !queue.isEmpty()) {
@@ -122,9 +124,9 @@ public class TrafficLight {
                 if (vehicle != null) {
                     totalVehiclesProcessed++;
 
-                    Long arrivalTime = vehicleArrivalTimes.remove(vehicle.getId());
+                    Double arrivalTime = vehicleArrivalTimes.remove(vehicle.getId());
                     if (arrivalTime != null) {
-                        double waitTimeSeconds = (System.currentTimeMillis() - arrivalTime) / 1000.0;
+                        double waitTimeSeconds = simulationTime - arrivalTime;
                         vehicle.addWaitingTime(waitTimeSeconds);
                     }
                 }

main/src/main/java/sd/model/Vehicle.java

@@ -7,16 +7,20 @@ import java.util.List;
 /**
  * Representa um veículo que se move pela rede de interseções.
  * 
- * <p>Esta classe é o "gémeo digital" de um carro, mota ou camião.
+ * <p>
- * Mantém toda a informação necessária:</p>
+ * Esta classe é o "gémeo digital" de um carro, mota ou camião.
+ * Mantém toda a informação necessária:
+ * </p>
  * <ul>
- *   <li>Identificação e tipo do veículo</li>
+ * <li>Identificação e tipo do veículo</li>
- *   <li>Rota completa a percorrer</li>
+ * <li>Rota completa a percorrer</li>
- *   <li>Métricas de tempo (espera, travessia, total)</li>
+ * <li>Métricas de tempo (espera, travessia, total)</li>
  * </ul>
  * 
- * <p>O objeto é serializado e enviado pela rede à medida que o veículo
+ * <p>
- * se move entre processos distribuídos.</p>
+ * O objeto é serializado e enviado pela rede à medida que o veículo
+ * se move entre processos distribuídos.
+ * </p>
  */
 public class Vehicle implements Serializable {
     private static final long serialVersionUID = 1L;
@@ -42,10 +46,16 @@ public class Vehicle implements Serializable {
      */
     private int currentRouteIndex;
 
-    /** Tempo total acumulado (segundos) que o veículo passou à espera em semáforos vermelhos */
+    /**
+     * Tempo total acumulado (segundos) que o veículo passou à espera em semáforos
+     * vermelhos
+     */
     private double totalWaitingTime;
 
-    /** Tempo total acumulado (segundos) que o veículo passou a atravessar interseções */
+    /**
+     * Tempo total acumulado (segundos) que o veículo passou a atravessar
+     * interseções
+     */
     private double totalCrossingTime;
 
     /**
@@ -80,7 +90,8 @@ public class Vehicle implements Serializable {
     }
 
     /**
-     * Obtém o destino atual (próxima interseção ou saída) para onde o veículo se dirige.
+     * Obtém o destino atual (próxima interseção ou saída) para onde o veículo se
+     * dirige.
      *
      * @return ID do destino atual (ex: "Cr1"), ou {@code null} se a rota terminou
      */

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

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

main/src/main/java/sd/routing/LeastCongestedRouteSelector.java

@@ -0,0 +1,151 @@
+package sd.routing;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Implementação da política de roteamento por menor congestionamento.
+ * 
+ * <p>Esta política escolhe dinamicamente a rota que passa pelos cruzamentos
+ * menos congestionados, com base no tamanho atual das filas em cada interseção.
+ * É uma política dinâmica que adapta as decisões ao estado da rede.</p>
+ * 
+ * <p>Objetivo: Distribuir o tráfego pela rede, evitando bottlenecks e
+ * minimizando o tempo de espera total.</p>
+ * 
+ * <p><strong>Algoritmo:</strong></p>
+ * <ol>
+ *   <li>Para cada rota possível, calcula a carga total (soma das filas)</li>
+ *   <li>Escolhe a rota com menor carga total</li>
+ *   <li>Em caso de empate ou falta de informação, usa a rota mais curta</li>
+ * </ol>
+ */
+public class LeastCongestedRouteSelector implements RouteSelector {
+    
+    /** Rotas possíveis a partir do ponto de entrada E1 */
+    private final List<List<String>> e1Routes;
+    /** Rotas possíveis a partir do ponto de entrada E2 */
+    private final List<List<String>> e2Routes;
+    /** Rotas possíveis a partir do ponto de entrada E3 */
+    private final List<List<String>> e3Routes;
+    
+    /**
+     * Cria um novo seletor de rotas baseado em menor congestionamento.
+     */
+    public LeastCongestedRouteSelector() {
+        this.e1Routes = new ArrayList<>();
+        this.e2Routes = new ArrayList<>();
+        this.e3Routes = new ArrayList<>();
+        initializeRoutes();
+    }
+    
+    /**
+     * Inicializa as rotas possíveis para cada ponto de entrada.
+     */
+    private void initializeRoutes() {
+        // Rotas de E1 (entrada Norte)
+        e1Routes.add(Arrays.asList("Cr1", "Cr4", "Cr5", "S"));
+        e1Routes.add(Arrays.asList("Cr1", "Cr2", "Cr5", "S"));
+        e1Routes.add(Arrays.asList("Cr1", "Cr2", "Cr3", "S"));
+        
+        // Rotas de E2 (entrada Oeste)
+        e2Routes.add(Arrays.asList("Cr2", "Cr5", "S"));
+        e2Routes.add(Arrays.asList("Cr2", "Cr3", "S"));
+        e2Routes.add(Arrays.asList("Cr2", "Cr1", "Cr4", "Cr5", "S"));
+        
+        // Rotas de E3 (entrada Sul)
+        e3Routes.add(Arrays.asList("Cr3", "S"));
+        e3Routes.add(Arrays.asList("Cr3", "Cr2", "Cr5", "S"));
+        e3Routes.add(Arrays.asList("Cr3", "Cr2", "Cr1", "Cr4", "Cr5", "S"));
+    }
+    
+    @Override
+    public List<String> selectRoute(String entryPoint, Map<String, Integer> queueSizes) {
+        List<List<String>> availableRoutes = getRoutesForEntryPoint(entryPoint);
+        
+        // Se não temos informação sobre filas, usa a rota mais curta como fallback
+        if (queueSizes == null || queueSizes.isEmpty()) {
+            return selectShortestRoute(availableRoutes);
+        }
+        
+        // Calcula a carga de cada rota e escolhe a menos congestionada
+        List<String> bestRoute = null;
+        int minLoad = Integer.MAX_VALUE;
+        
+        for (List<String> route : availableRoutes) {
+            int routeLoad = calculateRouteLoad(route, queueSizes);
+            
+            if (routeLoad < minLoad) {
+                minLoad = routeLoad;
+                bestRoute = route;
+            }
+        }
+        
+        // Fallback: se não conseguimos calcular carga, usa a primeira rota
+        if (bestRoute == null) {
+            bestRoute = availableRoutes.get(0);
+        }
+        
+        return new ArrayList<>(bestRoute);
+    }
+    
+    /**
+     * Calcula a carga total de uma rota (soma do tamanho das filas em todos os cruzamentos).
+     * 
+     * @param route rota a avaliar
+     * @param queueSizes mapa com tamanho das filas por interseção
+     * @return carga total da rota (soma das filas)
+     */
+    private int calculateRouteLoad(List<String> route, Map<String, Integer> queueSizes) {
+        int totalLoad = 0;
+        
+        for (String intersection : route) {
+            // Ignora "S" (saída) e apenas conta cruzamentos reais
+            if (!intersection.equals("S") && queueSizes.containsKey(intersection)) {
+                totalLoad += queueSizes.get(intersection);
+            }
+        }
+        
+        return totalLoad;
+    }
+    
+    /**
+     * Seleciona a rota mais curta (menor número de nós) como fallback.
+     * 
+     * @param routes lista de rotas disponíveis
+     * @return a rota mais curta
+     */
+    private List<String> selectShortestRoute(List<List<String>> routes) {
+        List<String> shortest = routes.get(0);
+        
+        for (List<String> route : routes) {
+            if (route.size() < shortest.size()) {
+                shortest = route;
+            }
+        }
+        
+        return new ArrayList<>(shortest);
+    }
+    
+    /**
+     * Obtém as rotas disponíveis para um ponto de entrada.
+     * 
+     * @param entryPoint ponto de entrada (E1, E2 ou E3)
+     * @return lista de rotas disponíveis
+     */
+    private List<List<String>> getRoutesForEntryPoint(String entryPoint) {
+        switch (entryPoint.toUpperCase()) {
+            case "E1":
+                return e1Routes;
+            case "E2":
+                return e2Routes;
+            case "E3":
+                return e3Routes;
+            default:
+                System.err.printf("Unknown entry point: %s, defaulting to E1%n", entryPoint);
+                return e1Routes;
+        }
+    }
+}

main/src/main/java/sd/routing/RandomRouteSelector.java

@@ -0,0 +1,122 @@
+package sd.routing;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Implementação da política de roteamento aleatória (baseline).
+ * 
+ * <p>Esta política seleciona rotas com base em probabilidades predefinidas,
+ * sem considerar o estado atual da rede. É a implementação de referência
+ * para comparação com outras políticas.</p>
+ * 
+ * <p>As rotas são organizadas por ponto de entrada (E1, E2, E3) e cada rota
+ * tem uma probabilidade de seleção associada.</p>
+ */
+public class RandomRouteSelector implements RouteSelector {
+    
+    /** Rotas possíveis a partir do ponto de entrada E1 */
+    private final List<RouteWithProbability> e1Routes;
+    /** Rotas possíveis a partir do ponto de entrada E2 */
+    private final List<RouteWithProbability> e2Routes;
+    /** Rotas possíveis a partir do ponto de entrada E3 */
+    private final List<RouteWithProbability> e3Routes;
+    
+    /**
+     * Cria um novo seletor de rotas aleatórias com rotas predefinidas.
+     */
+    public RandomRouteSelector() {
+        this.e1Routes = new ArrayList<>();
+        this.e2Routes = new ArrayList<>();
+        this.e3Routes = new ArrayList<>();
+        initializePossibleRoutes();
+    }
+    
+    /**
+     * Define todas as rotas possíveis que os veículos podem tomar.
+     * As rotas são organizadas por ponto de entrada (E1, E2, E3).
+     * Cada rota tem uma probabilidade que determina a frequência com que é escolhida.
+     */
+    private void initializePossibleRoutes() {
+        // Rotas de E1 (entrada Norte)
+        e1Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr1", "Cr4", "Cr5", "S"), 0.34));
+        e1Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr1", "Cr2", "Cr5", "S"), 0.33));
+        e1Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr1", "Cr2", "Cr3", "S"), 0.33));
+        
+        // Rotas de E2 (entrada Oeste)
+        e2Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr2", "Cr5", "S"), 0.34));
+        e2Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr2", "Cr3", "S"), 0.33));
+        e2Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr2", "Cr1", "Cr4", "Cr5", "S"), 0.33));
+        
+        // Rotas de E3 (entrada Sul)
+        e3Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr3", "S"), 0.34));
+        e3Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr3", "Cr2", "Cr5", "S"), 0.33));
+        e3Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr3", "Cr2", "Cr1", "Cr4", "Cr5", "S"), 0.33));
+    }
+    
+    @Override
+    public List<String> selectRoute(String entryPoint, Map<String, Integer> queueSizes) {
+        // Ignora queueSizes - seleção aleatória não depende do estado da rede
+        
+        List<RouteWithProbability> selectedRoutes = getRoutesForEntryPoint(entryPoint);
+        
+        // Seleciona uma rota baseada em probabilidades cumulativas
+        double rand = Math.random();
+        double cumulative = 0.0;
+        
+        for (RouteWithProbability routeWithProb : selectedRoutes) {
+            cumulative += routeWithProb.probability;
+            if (rand <= cumulative) {
+                // Retorna uma cópia da rota para prevenir modificações
+                return new ArrayList<>(routeWithProb.route);
+            }
+        }
+        
+        // Fallback: retorna a primeira rota
+        return new ArrayList<>(selectedRoutes.get(0).route);
+    }
+    
+    /**
+     * Obtém as rotas disponíveis para um ponto de entrada.
+     * 
+     * @param entryPoint ponto de entrada (E1, E2 ou E3)
+     * @return lista de rotas com probabilidades
+     */
+    private List<RouteWithProbability> getRoutesForEntryPoint(String entryPoint) {
+        switch (entryPoint.toUpperCase()) {
+            case "E1":
+                return e1Routes;
+            case "E2":
+                return e2Routes;
+            case "E3":
+                return e3Routes;
+            default:
+                System.err.printf("Unknown entry point: %s, defaulting to E1%n", entryPoint);
+                return e1Routes;
+        }
+    }
+    
+    /**
+     * Classe interna para associar uma rota com sua probabilidade de seleção.
+     */
+    private static class RouteWithProbability {
+        final List<String> route;
+        final double probability;
+        
+        RouteWithProbability(List<String> route, double probability) {
+            this.route = route;
+            this.probability = probability;
+        }
+    }
+}

main/src/main/java/sd/routing/RouteSelector.java

@@ -0,0 +1,25 @@
+package sd.routing;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Interface para implementação de políticas de seleção de rotas.
+ * 
+ * <p>Define o contrato que todas as políticas de roteamento devem seguir.
+ * Permite a implementação de diferentes estratégias de roteamento
+ * (aleatória, caminho mais curto, menor congestionamento, etc.).</p>
+ */
+public interface RouteSelector {
+    
+    /**
+     * Seleciona uma rota para um veículo a partir de um ponto de entrada.
+     * 
+     * @param entryPoint ponto de entrada (E1, E2 ou E3)
+     * @param queueSizes mapa com o tamanho das filas em cada interseção (opcional, pode ser null).
+     *                   Chave: ID da interseção (ex: "Cr1", "Cr2")
+     *                   Valor: número total de veículos em espera nessa interseção
+     * @return lista de IDs representando a rota escolhida (ex: ["Cr1", "Cr2", "Cr5", "S"])
+     */
+    List<String> selectRoute(String entryPoint, Map<String, Integer> queueSizes);
+}

main/src/main/java/sd/routing/RoutingPolicy.java

@@ -0,0 +1,36 @@
+package sd.routing;
+
+/**
+ * Enumeração que define as políticas de roteamento disponíveis para a simulação.
+ * 
+ * <p>As políticas de roteamento determinam como os veículos escolhem o caminho
+ * a seguir desde o ponto de entrada até à saída da rede de interseções.</p>
+ * 
+ * <ul>
+ *   <li><strong>RANDOM:</strong> Seleção aleatória de rotas baseada em probabilidades predefinidas</li>
+ *   <li><strong>SHORTEST_PATH:</strong> Escolhe sempre a rota com o menor número de cruzamentos</li>
+ *   <li><strong>LEAST_CONGESTED:</strong> Escolhe a rota evitando cruzamentos mais congestionados</li>
+ * </ul>
+ */
+public enum RoutingPolicy {
+    /**
+     * Política aleatória (baseline).
+     * Seleciona rotas com base em probabilidades predefinidas, sem considerar
+     * o estado atual da rede.
+     */
+    RANDOM,
+    
+    /**
+     * Política do caminho mais curto.
+     * Sempre escolhe a rota com o menor número de cruzamentos entre o ponto
+     * de entrada e a saída, minimizando a distância teórica.
+     */
+    SHORTEST_PATH,
+    
+    /**
+     * Política das menores filas (roteamento dinâmico).
+     * Escolhe a rota que passa pelos cruzamentos menos congestionados,
+     * com base no tamanho atual das filas em cada interseção.
+     */
+    LEAST_CONGESTED
+}

main/src/main/java/sd/routing/ShortestPathRouteSelector.java

@@ -0,0 +1,89 @@
+package sd.routing;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Implementação da política de roteamento por caminho mais curto.
+ * 
+ * <p>Esta política sempre escolhe a rota com o menor número de cruzamentos
+ * entre o ponto de entrada e a saída. É uma política determinística que
+ * não considera o estado da rede (tamanho das filas).</p>
+ * 
+ * <p>Objetivo: Minimizar a distância teórica percorrida pelos veículos.</p>
+ */
+public class ShortestPathRouteSelector implements RouteSelector {
+    
+    /** Rotas possíveis a partir do ponto de entrada E1, ordenadas por comprimento */
+    private final List<List<String>> e1Routes;
+    /** Rotas possíveis a partir do ponto de entrada E2, ordenadas por comprimento */
+    private final List<List<String>> e2Routes;
+    /** Rotas possíveis a partir do ponto de entrada E3, ordenadas por comprimento */
+    private final List<List<String>> e3Routes;
+    
+    /**
+     * Cria um novo seletor de rotas por caminho mais curto.
+     * As rotas são ordenadas por comprimento (número de cruzamentos).
+     */
+    public ShortestPathRouteSelector() {
+        this.e1Routes = new ArrayList<>();
+        this.e2Routes = new ArrayList<>();
+        this.e3Routes = new ArrayList<>();
+        initializeRoutes();
+    }
+    
+    /**
+     * Inicializa as rotas possíveis para cada ponto de entrada.
+     * As rotas são organizadas da mais curta para a mais longa.
+     */
+    private void initializeRoutes() {
+        // Rotas de E1 (entrada Norte) - ordenadas por comprimento
+        e1Routes.add(Arrays.asList("Cr1", "Cr2", "Cr3", "S"));          // 4 nós
+        e1Routes.add(Arrays.asList("Cr1", "Cr2", "Cr5", "S"));          // 4 nós
+        e1Routes.add(Arrays.asList("Cr1", "Cr4", "Cr5", "S"));          // 4 nós
+        
+        // Rotas de E2 (entrada Oeste) - ordenadas por comprimento
+        e2Routes.add(Arrays.asList("Cr2", "Cr3", "S"));                 // 3 nós (mais curta!)
+        e2Routes.add(Arrays.asList("Cr2", "Cr5", "S"));                 // 3 nós
+        e2Routes.add(Arrays.asList("Cr2", "Cr1", "Cr4", "Cr5", "S"));  // 5 nós
+        
+        // Rotas de E3 (entrada Sul) - ordenadas por comprimento
+        e3Routes.add(Arrays.asList("Cr3", "S"));                        // 2 nós (mais curta!)
+        e3Routes.add(Arrays.asList("Cr3", "Cr2", "Cr5", "S"));         // 4 nós
+        e3Routes.add(Arrays.asList("Cr3", "Cr2", "Cr1", "Cr4", "Cr5", "S")); // 6 nós
+    }
+    
+    @Override
+    public List<String> selectRoute(String entryPoint, Map<String, Integer> queueSizes) {
+        // Ignora queueSizes - política baseada apenas no comprimento do caminho
+        
+        List<List<String>> availableRoutes = getRoutesForEntryPoint(entryPoint);
+        
+        // Retorna a rota mais curta (primeira da lista)
+        List<String> shortestRoute = availableRoutes.get(0);
+        
+        return new ArrayList<>(shortestRoute);
+    }
+    
+    /**
+     * Obtém as rotas disponíveis para um ponto de entrada.
+     * 
+     * @param entryPoint ponto de entrada (E1, E2 ou E3)
+     * @return lista de rotas ordenadas por comprimento
+     */
+    private List<List<String>> getRoutesForEntryPoint(String entryPoint) {
+        switch (entryPoint.toUpperCase()) {
+            case "E1":
+                return e1Routes;
+            case "E2":
+                return e2Routes;
+            case "E3":
+                return e3Routes;
+            default:
+                System.err.printf("Unknown entry point: %s, defaulting to E1%n", entryPoint);
+                return e1Routes;
+        }
+    }
+}

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

@@ -1,26 +1,25 @@
 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;
-
 /**
- * JSON-based implementation of {@link MessageSerializer} using Google's Gson library.
+ * Implementação baseada em JSON da estratégia {@link MessageSerializer}, utilizando a biblioteca Gson.
- * 
+ * <p>
- * This serializer converts objects to JSON format for transmission, providing:
+ * Este serializador converte objetos Java para o formato de texto JSON antes da transmissão.
- * - Human-readable message format (easy debugging)
+ * Oferece várias vantagens técnicas sobre a serialização nativa do Java:
- * - Cross-platform compatibility
+ * <ul>
- * - Smaller message sizes compared to Java native serialization
+ * <li><b>Legibilidade:</b> O formato de texto facilita a depuração (sniffing de rede) sem ferramentas especializadas.</li>
- * - Better security (no code execution during deserialization)
+ * <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>
- * The serializer is configured with pretty printing disabled by default for
+ * </ul>
- * production use, but can be enabled for debugging purposes.
+ * <p>
- * 
+ * <b>Thread-Safety:</b> A instância interna do {@code Gson} é imutável e thread-safe, permitindo
- * Thread-safety: This class is thread-safe as Gson instances are thread-safe.
+ * que este serializador seja partilhado entre múltiplas threads (ex: no pool do DashboardServer).
- * 
+ * * @see MessageSerializer
- * @see MessageSerializer
  */
 public class JsonMessageSerializer implements MessageSerializer {
     
@@ -28,16 +27,16 @@ public class JsonMessageSerializer implements MessageSerializer {
     private final boolean prettyPrint;
     
     /**
-     * Creates a new JSON serializer with default configuration (no pretty printing).
+     * Cria um novo serializador JSON com configuração otimizada para produção (compacto).
      */
     public JsonMessageSerializer() {
         this(false);
     }
     
     /**
-     * Creates a new JSON serializer with optional pretty printing.
+     * Cria um novo serializador JSON com formatação opcional.
-     * 
+     * * @param prettyPrint Se {@code true}, o JSON gerado incluirá indentação e quebras de linha.
-     * @param prettyPrint If true, JSON output will be formatted with indentation
+     * Útil para debug, mas aumenta significativamente o tamanho do payload.
      */
     public JsonMessageSerializer(boolean prettyPrint) {
         this.prettyPrint = prettyPrint;
@@ -53,6 +52,13 @@ 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) {
@@ -68,6 +74,16 @@ 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) {
@@ -95,20 +111,18 @@ public class JsonMessageSerializer implements MessageSerializer {
     }
     
     /**
-     * Returns the underlying Gson instance for advanced usage.
+     * Retorna a instância subjacente do Gson para configurações avançadas.
-     * 
+     * * @return A instância Gson configurada.
-     * @return The Gson instance
      */
     public Gson getGson() {
         return gson;
     }
     
     /**
-     * Checks if pretty printing is enabled.
+     * Verifica se a formatação "pretty print" está ativa.
-     * 
+     * * @return true se a indentação estiver habilitada.
-     * @return true if pretty printing is enabled
      */
     public boolean isPrettyPrint() {
         return prettyPrint;
     }
-}
+}

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

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

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

@@ -1,41 +1,40 @@
 package sd.serialization;
 
 /**
- * Exception thrown when serialization or deserialization operations fail.
+ * Exceção verificada (Checked Exception) que sinaliza falhas no processo de transformação de dados.
- * 
+ * <p>
- * This exception wraps underlying errors (I/O exceptions, parsing errors, etc.)
+ * Esta classe atua como um wrapper unificador para erros ocorridos na camada de serialização,
- * and provides context about what went wrong during the serialization process.
+ * 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.).
  */
 public class SerializationException extends Exception {
     
     private static final long serialVersionUID = 1L; // Long(64bits) instead of int(32bits)
     
     /**
-     * Constructs a new serialization exception with the specified detail message.
+     * Constrói uma nova exceção de serialização com uma mensagem descritiva.
-     * 
+     * * @param message A mensagem detalhando o erro.
-     * @param message The detail message
      */
     public SerializationException(String message) {
         super(message);
     }
     
     /**
-     * Constructs a new serialization exception with the specified detail message
+     * Constrói uma nova exceção encapsulando a causa raiz do problema.
-     * and cause.
+     * Útil para preservar a stack trace original de erros de bibliotecas terceiras (ex: Gson).
-     * 
+     * * @param message A mensagem detalhando o erro.
-     * @param message The detail message
+     * @param cause A exceção original que causou a falha.
-     * @param cause The cause of this exception
      */
     public SerializationException(String message, Throwable cause) {
         super(message, cause);
     }
     
     /**
-     * Constructs a new serialization exception with the specified cause.
+     * Constrói uma nova exceção baseada apenas na causa raiz.
-     * 
+     * * @param cause A exceção original.
-     * @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;
 
 /**
- * Factory for creating {@link MessageSerializer} instances.
+ * Fábrica estática (Factory Pattern) para instanciação controlada de {@link MessageSerializer}.
- * 
+ * <p>
- * This factory provides a centralized way to create and configure JSON serializers
+ * Esta classe centraliza a criação de estratégias de serialização, garantindo consistência
- * using Gson, making it easy to configure serialization throughout the application.
+ * 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
- * The factory can be configured via system properties for easy deployment configuration.
+ * depuração (Pretty Print) e produção (Compacto) sem recompilação.
- * 
+ * <p>
- * Example usage:
+ * <b>Exemplo de Uso:</b>
  * <pre>
  * MessageSerializer serializer = SerializerFactory.createDefault();
  * byte[] data = serializer.serialize(myObject);
@@ -17,28 +17,27 @@ package sd.serialization;
 public class SerializerFactory {
     
     /**
-     * System property key for enabling pretty-print in JSON serialization.
+     * Chave da propriedade de sistema para ativar a formatação JSON legível (Pretty Print).
-     * Set to "true" for debugging, "false" for production.
+     * Defina {@code -Dsd.serialization.json.prettyPrint=true} na JVM para ativar.
      */
     public static final String JSON_PRETTY_PRINT_PROPERTY = "sd.serialization.json.prettyPrint";
     
-    // Default configuration
+    // Default configuration (Production-ready)
     private static final boolean DEFAULT_JSON_PRETTY_PRINT = false;
     
     /**
-     * Private constructor to prevent instantiation.
+     * Construtor privado para prevenir instanciação acidental desta classe utilitária.
      */
     private SerializerFactory() {
         throw new UnsupportedOperationException("Factory class cannot be instantiated");
     }
     
     /**
-     * Creates a JSON serializer based on system configuration.
+     * Cria um serializador JSON configurado dinamicamente pelo ambiente.
-     * 
+     * <p>
-     * Pretty-print is determined by checking the system property
+     * Verifica a propriedade de sistema {@value #JSON_PRETTY_PRINT_PROPERTY}.
-     * {@value #JSON_PRETTY_PRINT_PROPERTY}. If not set, defaults to false.
+     * Se não definida, assume o padrão de produção (falso/compacto).
-     * 
+     * * @return Uma instância configurada de {@link JsonMessageSerializer}.
-     * @return A configured JsonMessageSerializer instance
      */
     public static MessageSerializer createDefault() {
         boolean prettyPrint = Boolean.getBoolean(JSON_PRETTY_PRINT_PROPERTY);
@@ -46,21 +45,20 @@ public class SerializerFactory {
     }
     
     /**
-     * Creates a JSON serializer with default configuration (no pretty printing).
+     * 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 A JsonMessageSerializer instance
+     * * @return Uma instância compacta de {@link JsonMessageSerializer}.
      */
     public static MessageSerializer createSerializer() {
         return createSerializer(DEFAULT_JSON_PRETTY_PRINT);
     }
     
     /**
-     * Creates a JSON serializer with specified pretty-print setting.
+     * 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.
-     * @param prettyPrint Whether to enable pretty printing
+     * @return Uma instância personalizada de {@link JsonMessageSerializer}.
-     * @return A JsonMessageSerializer instance
      */
     public static MessageSerializer createSerializer(boolean prettyPrint) {
         return new JsonMessageSerializer(prettyPrint);
     }
-}
+}

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

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

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

@@ -1,97 +1,66 @@
 package sd.util;
 
-import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.List;
+import java.util.Map;
 
 import sd.config.SimulationConfig;
 import sd.model.Vehicle;
 import sd.model.VehicleType;
+import sd.routing.RouteSelector;
 
 /**
- * Gera veículos para a simulação.
+ * Motor de injeção de carga (Load Injector) para a simulação de tráfego.
- * 
+ * <p>
- * <p>Esta classe é responsável por duas tarefas principais:</p>
+ * Esta classe atua como uma fábrica estocástica de veículos, sendo responsável por:
  * <ol>
- *   <li>Determinar <em>quando</em> o próximo veículo deve chegar, baseado no
+ * <li><b>Modelagem Temporal:</b> Determinar os instantes de chegada (Inter-arrival times)
- *       modelo de chegada (POISSON ou FIXED) da {@link SimulationConfig}</li>
+ * usando processos de Poisson (estocástico) ou intervalos determinísticos.</li>
- *   <li>Criar um novo objeto {@link Vehicle} com tipo e rota selecionados aleatoriamente</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>
  * </ol>
- * 
- * <p>As rotas são predefinidas e organizadas por ponto de entrada (E1, E2, E3).</p>
  */
 public class VehicleGenerator {
     
     private final SimulationConfig config;
     private final String arrivalModel;
-    /** Lambda (λ) para modelo POISSON */
+    
+    /** Parâmetro Lambda (λ) para a distribuição de Poisson (taxa de chegada). */
     private final double arrivalRate;
-    /** Intervalo para modelo FIXED */
+    
+    /** Intervalo determinístico para geração constante (modo debug/teste). */
     private final double fixedInterval;
     
-    /** Rotas possíveis a partir do ponto de entrada E1 */
+    /** * Estratégia de roteamento atual. 
-    private final List<RouteWithProbability> e1Routes;
+     * Não é final para permitir Hot-Swapping durante a execução.
-    /** Rotas possíveis a partir do ponto de entrada E2 */
+     */
-    private final List<RouteWithProbability> e2Routes;
+    private RouteSelector routeSelector;
-    /** Rotas possíveis a partir do ponto de entrada E3 */
-    private final List<RouteWithProbability> e3Routes;
     
     /**
-     * Cria um novo gerador de veículos.
+     * Inicializa o gerador com as configurações de simulação e estratégia de roteamento.
-     * Lê a configuração necessária e inicializa as rotas predefinidas.
      *
-     * @param config objeto de {@link SimulationConfig}
+     * @param config A configuração global contendo as taxas e probabilidades.
+     * @param routeSelector A estratégia inicial de seleção de rotas.
      */
-    public VehicleGenerator(SimulationConfig config) {
+    public VehicleGenerator(SimulationConfig config, RouteSelector routeSelector) {
         this.config = config;
+        this.routeSelector = routeSelector;
         
-        // Cache configuration values for performance
+        // Cache de valores de configuração para evitar lookups repetitivos em hot-path
         this.arrivalModel = config.getArrivalModel();
         this.arrivalRate = config.getArrivalRate();
         this.fixedInterval = config.getFixedArrivalInterval();
-        
-        // Initialize route lists
-        this.e1Routes = new ArrayList<>();
-        this.e2Routes = new ArrayList<>();
-        this.e3Routes = new ArrayList<>();
-        initializePossibleRoutes();
     }
     
     /**
-     * Define todas as rotas possíveis que os veículos podem tomar.
+     * Calcula o timestamp absoluto para a próxima injeção de veículo.
-     * As rotas são organizadas por ponto de entrada (E1, E2, E3).
+     * <p>
-     * Cada rota tem uma probabilidade que determina a frequência com que é escolhida.
+     * Se o modelo for "POISSON", utiliza a técnica de <i>Inverse Transform Sampling</i>
-     */
+     * (via {@link RandomGenerator}) para gerar intervalos exponencialmente distribuídos,
-    private void initializePossibleRoutes() {
+     * simulando a aleatoriedade natural do tráfego.
-        e1Routes.add(new RouteWithProbability(
+     * * @param currentTime O tempo atual da simulação (base de cálculo).
-            Arrays.asList("Cr1", "Cr4", "Cr5", "S"), 0.34));
+     * @return O instante futuro (t + delta) para agendamento do evento de geração.
-        e1Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr1", "Cr2", "Cr5", "S"), 0.33));
-        e1Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr1", "Cr2", "Cr3", "S"), 0.33));
-        
-        e2Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr2", "Cr5", "S"), 0.34));
-        e2Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr2", "Cr3", "S"), 0.33));
-        e2Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr2", "Cr1", "Cr4", "Cr5", "S"), 0.33));
-        
-        e3Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr3", "S"), 0.34));
-        e3Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr3", "Cr2", "Cr5", "S"), 0.33));
-        e3Routes.add(new RouteWithProbability(
-            Arrays.asList("Cr3", "Cr2", "Cr1", "Cr4", "Cr5", "S"), 0.33));
-    }
-    
-    /**
-     * 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)) {
@@ -103,38 +72,35 @@ public class VehicleGenerator {
     }
     
     /**
-     * Gera um novo objeto {@link Vehicle}.
+     * Instancia (Spawn) um novo veículo configurado e roteado.
-     * 
+     * <p>
-     * <p>Passos executados:</p>
+     * O processo de criação segue um pipeline:
      * <ol>
-     *   <li>Seleciona um {@link VehicleType} aleatório baseado em probabilidades</li>
+     * <li>Seleção de Tipo (Roda da Fortuna / CDF).</li>
-     *   <li>Seleciona uma rota aleatória (ponto de entrada + caminho)</li>
+     * <li>Seleção de Entrada (Uniforme).</li>
+     * <li>Cálculo de Rota (Delegado ao Strategy).</li>
      * </ol>
      *
-     * @param vehicleId identificador único do novo veículo (ex: "V123")
+     * @param vehicleId O identificador único sequencial (ex: "V104").
-     * @param entryTime tempo de simulação em que o veículo é criado
+     * @param entryTime O timestamp de criação.
-     * @return novo objeto {@link Vehicle} configurado
+     * @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.
      */
-    public Vehicle generateVehicle(String vehicleId, double entryTime) {
+    public Vehicle generateVehicle(String vehicleId, double entryTime, Map<String, Integer> queueSizes) {
         VehicleType type = selectVehicleType();
-        List<String> route = selectRandomRoute();
+        String entryPoint = selectRandomEntryPoint();
+        List<String> route = routeSelector.selectRoute(entryPoint, queueSizes);
         
         return new Vehicle(vehicleId, type, entryTime, route);
     }
     
     /**
-     * Seleciona um {@link VehicleType} (BIKE, LIGHT, HEAVY) baseado nas
+     * Seleciona o tipo de veículo usando Amostragem por Probabilidade Cumulativa.
-     * probabilidades definidas na {@link SimulationConfig}.
+     * <p>
-     * 
+     * Normaliza as probabilidades configuradas e mapeia um número aleatório [0, 1)
-     * <p>Usa técnica de "probabilidade cumulativa":</p>
+     * para o intervalo correspondente ao tipo de veículo.
-     * <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
+     * @return O tipo enumerado {@link VehicleType} selecionado.
      */
     private VehicleType selectVehicleType() {
         double bikeProbability = config.getBikeVehicleProbability();
@@ -142,7 +108,9 @@ public class VehicleGenerator {
         double heavyProbability = config.getHeavyVehicleProbability();
         
         double total = bikeProbability + lightProbability + heavyProbability;
-        if (total == 0) return VehicleType.LIGHT; // Avoid division by zero
+        if (total == 0) return VehicleType.LIGHT; // Fallback de segurança
+        
+        // Normalização
         bikeProbability /= total;
         lightProbability /= total;
         
@@ -158,73 +126,42 @@ public class VehicleGenerator {
     }
     
     /**
-     * Selects a random route for a new vehicle.
+     * Seleciona um ponto de injeção na borda da rede (Edge Node).
-     * This is a two-step process:
+     * Distribuição Uniforme: ~33.3% para cada entrada (E1, E2, E3).
-     * 1. Randomly select an entry point (E1, E2, or E3) with equal probability.
-     * 2. From the chosen entry point's list of routes, select one
-     * based on their defined probabilities (using cumulative probability).
      *
-     * @return A {@link List} of strings representing the chosen route (e.g., ["Cr1", "Cr4", "S"]).
+     * @return O ID da interseção de entrada.
      */
-    private List<String> selectRandomRoute() {
+    private String selectRandomEntryPoint() {
-        // Step 1: Randomly select an entry point (E1, E2, or E3)
+        double rand = Math.random();
-        double entryRandom = Math.random();
-        List<RouteWithProbability> selectedRoutes;
         
-        if (entryRandom < 0.333) {
+        if (rand < 0.333) {
-            selectedRoutes = e1Routes;
+            return "E1";
-        } else if (entryRandom < 0.666) {
+        } else if (rand < 0.666) {
-            selectedRoutes = e2Routes;
+            return "E2";
         } else {
-            selectedRoutes = e3Routes;
+            return "E3";
         }
-        
-        // Step 2: Select a route from the chosen list based on cumulative probabilities
-        double routeRand = Math.random();
-        double cumulative = 0.0;
-        
-        for (RouteWithProbability routeWithProb : selectedRoutes) {
-            cumulative += routeWithProb.probability;
-            if (routeRand <= cumulative) {
-                // Return a *copy* of the route to prevent modification
-                return new ArrayList<>(routeWithProb.route);
-            }
-        }
-        
-        // Fallback: This should only be reached if probabilities don't sum to 1
-        // (due to floating point errors)
-        return new ArrayList<>(selectedRoutes.get(0).route);
     }
     
     /**
-     * @return A string providing information about the generator's configuration.
+     * 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.
+     */
+    public void setRouteSelector(RouteSelector newRouteSelector) {
+        this.routeSelector = newRouteSelector;
+    }
+
+    /**
+     * Retorna uma representação textual do estado interno do gerador.
+     * Útil para logs de auditoria e debugging.
      */
     public String getInfo() {
-        int totalRoutes = e1Routes.size() + e2Routes.size() + e3Routes.size();
         return String.format(
-            "VehicleGenerator{model=%s, rate=%.2f, interval=%.2f, routes=%d (E1:%d, E2:%d, E3:%d)}",
+            "VehicleGenerator{model=%s, rate=%.2f, interval=%.2f, routeSelector=%s}",
-            arrivalModel, arrivalRate, fixedInterval, totalRoutes,
+            arrivalModel, arrivalRate, fixedInterval, routeSelector.getClass().getSimpleName()
-            e1Routes.size(), e2Routes.size(), e3Routes.size()
         );
     }
-    
-    /**
-     * A private inner "struct-like" class to hold a route (a List of strings)
-     * and its associated selection probability.
-     */
-    private static class RouteWithProbability {
-        final List<String> route;
-        final double probability;
-        
-        /**
-         * Constructs a new RouteWithProbability pair.
-         * @param route The list of intersection IDs.
-         * @param probability The probability (0.0 to 1.0) of this route
-         * being chosen *from its entry group*.
-         */
-        RouteWithProbability(List<String> route, double probability) {
-            this.route = route;
-            this.probability = probability;
-        }
-    }
 }

main/src/main/resources/network_config.json

@@ -27,7 +27,7 @@
     },
     {
       "id": "Cr4",
-      "lights": ["East", "West"],
+      "lights": ["East", "North"],
       "routes": {
         "Cr1": "North",
         "Cr5": "East"

main/src/main/resources/simulation-high.properties

@@ -41,7 +41,10 @@ simulation.arrival.model=POISSON
 simulation.arrival.rate=1.0
 
 # Fixed interval between arrivals (only used if model=FIXED)
-simulation.arrival.fixed.interval=1.0
+simulation.arrival.fixed.interval=2.0
+
+# Routing policy: RANDOM, SHORTEST_PATH, LEAST_CONGESTED
+simulation.routing.policy=LEAST_CONGESTED
 
 
 # === TRAFFIC LIGHT TIMINGS ===
@@ -72,11 +75,17 @@ trafficlight.Cr3.West.red=3.0
 # Intersection 4 (High throughput needed toward Cr5)
 trafficlight.Cr4.East.green=70.0
 trafficlight.Cr4.East.red=3.0
+trafficlight.Cr4.North.green=70.0
+trafficlight.Cr4.North.red=3.0
 
 # Intersection 5 (Near exit - MAJOR BOTTLENECK, longest green time)
 # All routes funnel through here before exit
 trafficlight.Cr5.East.green=90.0
 trafficlight.Cr5.East.red=3.0
+trafficlight.Cr5.West.green=70.0
+trafficlight.Cr5.West.red=3.0
+trafficlight.Cr5.North.green=70.0
+trafficlight.Cr5.North.red=3.0
 
 
 # === VEHICLE CONFIGURATION ===
@@ -93,7 +102,7 @@ vehicle.crossing.time.heavy=4.0
 # Travel times between intersections (in seconds)
 # Base time for light vehicles (cars)
 vehicle.travel.time.base=1.0
-# Bike travel time = 0.5 × car travel time
+# Bike travel time = 0.5 x car travel time
 vehicle.travel.time.bike.multiplier=0.5
 # Heavy vehicle travel time = 4.0 x base travel time
 vehicle.travel.time.heavy.multiplier=4.0

main/src/main/resources/simulation-low.properties

@@ -41,7 +41,10 @@ simulation.arrival.model=POISSON
 simulation.arrival.rate=0.2
 
 # Fixed interval between arrivals (only used if model=FIXED)
-simulation.arrival.fixed.interval=5.0
+simulation.arrival.fixed.interval=2.0
+
+# Routing policy: RANDOM, SHORTEST_PATH, LEAST_CONGESTED
+simulation.routing.policy=LEAST_CONGESTED
 
 
 # === TRAFFIC LIGHT TIMINGS ===
@@ -71,10 +74,16 @@ trafficlight.Cr3.West.red=5.0
 # Intersection 4 (Favor East toward Cr5)
 trafficlight.Cr4.East.green=30.0
 trafficlight.Cr4.East.red=5.0
+trafficlight.Cr4.North.green=30.0
+trafficlight.Cr4.North.red=5.0
 
 # Intersection 5 (Near exit - favor East)
 trafficlight.Cr5.East.green=30.0
 trafficlight.Cr5.East.red=5.0
+trafficlight.Cr5.West.green=30.0
+trafficlight.Cr5.West.red=5.0
+trafficlight.Cr5.North.green=30.0
+trafficlight.Cr5.North.red=5.0
 
 
 # === VEHICLE CONFIGURATION ===
@@ -91,7 +100,7 @@ vehicle.crossing.time.heavy=4.0
 # Travel times between intersections (in seconds)
 # Base time for light vehicles (cars)
 vehicle.travel.time.base=1.0
-# Bike travel time = 0.5 × car travel time
+# Bike travel time = 0.5 x car travel time
 vehicle.travel.time.bike.multiplier=0.5
 # Heavy vehicle travel time = 4.0 x base travel time
 vehicle.travel.time.heavy.multiplier=4.0

main/src/main/resources/simulation-medium.properties

@@ -43,6 +43,9 @@ simulation.arrival.rate=0.5
 # Fixed interval between arrivals (only used if model=FIXED)
 simulation.arrival.fixed.interval=2.0
 
+# Routing policy: RANDOM, SHORTEST_PATH, LEAST_CONGESTED
+simulation.routing.policy=LEAST_CONGESTED
+
 
 # === TRAFFIC LIGHT TIMINGS ===
 # Format: trafficlight.<intersection>.<direction>.<state>=<seconds>
@@ -71,10 +74,16 @@ trafficlight.Cr3.West.red=5.0
 # Intersection 4 (Favor East toward Cr5)
 trafficlight.Cr4.East.green=40.0
 trafficlight.Cr4.East.red=5.0
+trafficlight.Cr4.North.green=40.0
+trafficlight.Cr4.North.red=5.0
 
 # Intersection 5 (Near exit - POTENTIAL BOTTLENECK, longer green)
 trafficlight.Cr5.East.green=50.0
 trafficlight.Cr5.East.red=5.0
+trafficlight.Cr5.West.green=45.0
+trafficlight.Cr5.West.red=5.0
+trafficlight.Cr5.North.green=45.0
+trafficlight.Cr5.North.red=5.0
 
 
 # === VEHICLE CONFIGURATION ===
@@ -91,7 +100,7 @@ vehicle.crossing.time.heavy=4.0
 # Travel times between intersections (in seconds)
 # Base time for light vehicles (cars)
 vehicle.travel.time.base=1.0
-# Bike travel time = 0.5 × car travel time
+# Bike travel time = 0.5 x car travel time
 vehicle.travel.time.bike.multiplier=0.5
 # Heavy vehicle travel time = 4.0 x base travel time
 vehicle.travel.time.heavy.multiplier=4.0

main/src/main/resources/simulation.properties

@@ -46,6 +46,12 @@ simulation.arrival.rate=0.5
 # Fixed interval between arrivals (only used if model=FIXED)
 simulation.arrival.fixed.interval=2.0
 
+# Routing policy: RANDOM, SHORTEST_PATH, LEAST_CONGESTED
+# RANDOM: selects routes with predefined probabilities (baseline)
+# SHORTEST_PATH: always chooses the route with fewest intersections
+# LEAST_CONGESTED: dynamically chooses routes to avoid congested areas
+simulation.routing.policy=RANDOM
+
 
 # === TRAFFIC LIGHT TIMINGS ===
 # Format: trafficlight.<intersection>.<direction>.<state>=<seconds>
@@ -93,7 +99,7 @@ vehicle.crossing.time.heavy=4.0
 # Travel times between intersections (in seconds)
 # Base time for light vehicles (cars)
 vehicle.travel.time.base=1.0
-# Bike travel time = 0.5 × car travel time
+# Bike travel time = 0.5 x car travel time
 vehicle.travel.time.bike.multiplier=0.5
 # Heavy vehicle travel time = 4.0 x base travel time
 vehicle.travel.time.heavy.multiplier=4.0

main/start.sh

@@ -1,60 +0,0 @@
-#!/bin/bash
-# Distributed Traffic Simulation Startup Script
-
-# kill java
-echo "-> Cleaning up existing processes..."
-pkill -9 java 2>/dev/null
-sleep 2
-
-# build
-echo "-> Building project..."
-cd "$(dirname "$0")"
-mvn package -DskipTests -q
-if [ $? -ne 0 ]; then
-    echo "XXX Build failed! XXX"
-    exit 1
-fi
-echo "-> Build complete"
-echo ""
-
-# start gui
-echo "-> Starting JavaFX Dashboard..."
-mvn javafx:run &
-DASHBOARD_PID=$!
-sleep 3
-
-# acho que é assim idk
-echo "-> Starting 5 Intersection processes..."
-for id in Cr1 Cr2 Cr3 Cr4 Cr5; do
-    java -cp target/classes:target/main-1.0-SNAPSHOT.jar sd.IntersectionProcess $id > /tmp/$(echo $id | tr '[:upper:]' '[:lower:]').log 2>&1 &
-    echo "[SUCCESS] Started $id"
-done
-sleep 2
-
-# exit
-echo "-> Starting Exit Node..."
-java -cp target/classes:target/main-1.0-SNAPSHOT.jar sd.ExitNodeProcess > /tmp/exit.log 2>&1 &
-sleep 1
-
-# coordinator
-echo "-> Starting Coordinator..."
-java -cp target/classes:target/main-1.0-SNAPSHOT.jar sd.coordinator.CoordinatorProcess > /tmp/coordinator.log 2>&1 &
-sleep 1
-
-echo ""
-echo "-> All processes started!"
-echo ""
-echo "-> System Status:"
-ps aux | grep "java.*sd\." | grep -v grep | wc -l | xargs -I {} echo "   {} Java processes running"
-echo ""
-echo "   IMPORTANT: Keep the JavaFX Dashboard window OPEN for 60+ seconds"
-echo "   to see live updates! The simulation runs for 60 seconds."
-echo ""
-echo "-> Logs available at:"
-echo "   Dashboard: Check JavaFX window (live updates)"
-echo "   Intersections: /tmp/cr*.log"
-echo "   Exit Node: /tmp/exit.log"
-echo "   Coordinator: /tmp/coordinator.log"
-echo ""
-echo "-> To stop all processes: pkill -9 java"
-echo ""