Move vehicle route advancement to intersection arrival

Dev

.github/workflows/maven.yml

@@ -0,0 +1,61 @@
+name: Java CI with Maven
+
+on:
+  push:
+    branches: [ "main" ]
+    tags:
+      - 'v*.*.*'
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up JDK 17
+      uses: actions/setup-java@v4
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+        cache: maven
+
+    - name: Build with Maven
+      run: mvn -B package
+      working-directory: main
+
+    - name: Upload built JAR
+      uses: actions/upload-artifact@v4
+      with:
+        name: package
+        path: main/target/*.jar
+
+    - name: Generate dependency graph
+      run: mvn -B -f main/pom.xml com.github.ferstl:depgraph-maven-plugin:4.0.1:graph
+
+    - name: Upload dependency graph artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: dependency-graph
+        path: main/target/**
+
+  publish-release:
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+
+    steps:
+    - name: Download built JAR
+      uses: actions/download-artifact@v4
+      with:
+        name: package
+        path: main/target/
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        files: main/target/*.jar

.gitignore

@@ -0,0 +1,50 @@
+# Compiled class files
+*.class
+
+# Log files
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.ear
+
+# VS Code settings
+.vscode/
+
+# Eclipse files
+*.pydevproject
+.project
+.classpath
+.cproject
+.settings/
+bin/
+tmp/
+
+# IntelliJ IDEA files
+*.iml
+.idea/
+out/
+
+# Mac system files
+.DS_Store
+
+# Windows system files
+Thumbs.db
+
+# Maven
+target/
+
+# Gradle
+.gradle/
+build/
+
+# Other
+*.swp
+*.pdf

Diagrama de arquitetura - SD.drawio

@@ -0,0 +1,27 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36 Edg/141.0.0.0" version="28.2.7">
+  <diagram name="Página-1" id="B1_hHcevBzWlEwI7FSV6">
+    <mxGraphModel dx="778" dy="476" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="vcp7vux32DhQR4tKQhnF-8" value="Dashboard" style="sketch=0;pointerEvents=1;shadow=0;dashed=0;html=1;strokeColor=#C73500;labelPosition=center;verticalLabelPosition=bottom;verticalAlign=top;align=center;fillColor=#fa6800;shape=mxgraph.mscae.oms.dashboard;fontColor=#000000;" vertex="1" parent="1">
+          <mxGeometry x="389" y="230" width="50" height="41" as="geometry" />
+        </mxCell>
+        <mxCell id="vcp7vux32DhQR4tKQhnF-12" value="Semaforo.java" style="shape=image;html=1;verticalAlign=top;verticalLabelPosition=bottom;labelBackgroundColor=#ffffff;imageAspect=0;aspect=fixed;image=https://icons.diagrams.net/icon-cache1/Strabo-2829/traffic_light-1068.png" vertex="1" parent="1">
+          <mxGeometry x="230" y="350" width="53" height="53" as="geometry" />
+        </mxCell>
+        <mxCell id="vcp7vux32DhQR4tKQhnF-13" value="" style="endArrow=classic;startArrow=classic;html=1;rounded=0;movable=1;resizable=1;rotatable=1;deletable=1;editable=1;locked=0;connectable=1;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="310" y="330" as="sourcePoint" />
+            <mxPoint x="360" y="280" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="vcp7vux32DhQR4tKQhnF-14" value="CruzamentoServer.java" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=1;points=[];movable=1;rotatable=1;deletable=1;editable=1;locked=0;connectable=1;" vertex="1" connectable="0" parent="vcp7vux32DhQR4tKQhnF-13">
+          <mxGeometry x="-0.3933" relative="1" as="geometry">
+            <mxPoint x="25" y="25" as="offset" />
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

README.md

@@ -0,0 +1,620 @@
+# Sistema de Simulação de Tráfego Distribuído
+
+Sistema distribuído de simulação de tráfego.
+---
+
+## Índice
+
+- [Visão Geral](#visão-geral)
+- [Arquitetura](#arquitetura)
+- [Protocolo de Comunicação](#protocolo-de-comunicação)
+- [Estrutura do Projeto](#estrutura-do-projeto)
+- [Instalação e Execução](#instalação-e-execução)
+- [Documentação](#documentação)
+- [Desenvolvimento](#desenvolvimento)
+
+---
+
+## Visão Geral
+
+Este projeto implementa uma simulação distribuída de tráfego veicular numa rede de cruzamentos. O sistema utiliza:
+
+- **Processos independentes** para cada cruzamento
+- **Threads** para controlar os semáforos dentro de cada cruzamento
+- **Comunicação via sockets** para transferência de veículos entre cruzamentos
+- **Simulação de eventos discretos** (DES) para gerir o tempo de simulação
+
+### Características Principais
+
+- Simulação determinística e reproduzível
+- Comunicação assíncrona entre processos
+- Protocolo de mensagens baseado em JSON
+- Dashboard em tempo real (planeado)
+- Estatísticas detalhadas de desempenho
+
+---
+
+## Arquitetura
+
+### Visão Geral do Sistema
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    SISTEMA DISTRIBUÍDO                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌──────────────┐                          ┌──────────────┐     │
+│  │  Coordenador │ ────────────────────────>│  Dashboard   │     │
+│  │  / Gerador   │                          │              │
+│  └──────┬───────┘                          └──────▲───────┘     │
+│         │                                          │             │
+│         │ Gera veículos                    Stats  │             │
+│         │                                          │             │
+│         ▼                                          │             │
+│  ┌─────────────────────────────────────────────────┴──────┐     │
+│  │          Rede de Cruzamentos (Processos)              │     │
+│  │                                                         │     │
+│  │  ┌────┐         ┌────┐         ┌────┐                 │     │
+│  │  │Cr1 │◄───────►│Cr2 │◄───────►│Cr3 │                 │     │
+│  │  └─┬──┘         └─┬──┘         └─┬──┘                 │     │
+│  │    │              │              │                     │     │
+│  │    │         ┌────▼────┐         │                     │     │
+│  │    └────────►│   Cr4   │◄────────┘                     │     │
+│  │              └────┬────┘                               │     │
+│  │                   │                                     │     │
+│  │              ┌────▼────┐                               │     │
+│  │              │   Cr5   │                               │     │
+│  │              └────┬────┘                               │     │
+│  └───────────────────┼─────────────────────────────────────┤     │
+│                      │                                     │     │
+│                      ▼                                     │     │
+│               ┌──────────────┐                            │     │
+│               │  Nó de Saída │                            │     │
+│               │      (S)     │                            │     │
+│               └──────────────┘                            │     │
+│                                                            │     │
+└────────────────────────────────────────────────────────────┘     │
+```
+
+### Componentes
+
+1. **Coordenador/Gerador**: Gera veículos e injeta no sistema
+2. **Cruzamentos (Cr1-Cr5)**: Processos independentes que gerem tráfego local
+3. **Nó de Saída (S)**: Recolhe estatísticas de veículos que saem do sistema
+4. **Dashboard Server**: Agrega e exibe dados em tempo real
+
+---
+
+## Protocolo de Comunicação
+
+### Formato de Serialização: JSON (Gson)
+
+O sistema utiliza JSON como formato de serialização por ser mais rápido, seguro e legível que a serialização em Java.
+
+### Estrutura de Mensagens
+
+Todas as mensagens seguem o formato base:
+
+```json
+{
+  "messageId": "uuid",
+  "type": "MESSAGE_TYPE",
+  "senderId": "sender_id",
+  "destinationId": "destination_id",
+  "timestamp": 1729595234567,
+  "payload": { ... }
+}
+```
+
+### Tipos de Mensagens
+
+#### 1. VEHICLE_TRANSFER
+
+Transfere um veículo entre cruzamentos.
+
+**Estrutura:**
+```json
+{
+  "messageId": "a3c5e7f9-1234-5678-90ab-cdef12345678",
+  "type": "VEHICLE_TRANSFER",
+  "senderId": "Cr1",
+  "destinationId": "Cr2",
+  "timestamp": 1729595234567,
+  "payload": {
+    "id": "V123",
+    "type": "LIGHT",
+    "entryTime": 15.7,
+    "route": ["Cr1", "Cr2", "Cr5", "S"],
+    "currentRouteIndex": 1,
+    "totalWaitingTime": 3.2,
+    "totalCrossingTime": 1.8
+  }
+}
+```
+
+**Fluxo:**
+1. Veículo completa travessia no Cr1
+2. Cr1 serializa mensagem VEHICLE_TRANSFER
+3. Envia para Cr2 via socket
+4. Cr2 desserializa e adiciona veículo à fila
+
+#### 2. STATS_UPDATE
+
+Envia estatísticas de um cruzamento para o Dashboard.
+
+**Estrutura:**
+```json
+{
+  "messageId": "b4d6e8f0-2345-6789-01bc-def123456789",
+  "type": "STATS_UPDATE",
+  "senderId": "Cr3",
+  "destinationId": "Dashboard",
+  "timestamp": 1729595234789,
+  "payload": {
+    "intersectionId": "Cr3",
+    "queueLengths": {
+      "North": 5,
+      "South": 3,
+      "East": 7,
+      "West": 2
+    },
+    "vehiclesProcessed": 142,
+    "averageWaitTime": 4.5,
+    "currentTime": 123.45
+  }
+}
+```
+
+**Frequência:** A cada 10 segundos (configurável)
+
+#### 3. VEHICLE_EXIT
+
+Notifica quando um veículo sai do sistema.
+
+**Estrutura:**
+```json
+{
+  "messageId": "c5e7f9a1-3456-7890-12bc-def123456789",
+  "type": "VEHICLE_EXIT",
+  "senderId": "Cr5",
+  "destinationId": "ExitNode",
+  "timestamp": 1729595234890,
+  "payload": {
+    "id": "V123",
+    "type": "LIGHT",
+    "entryTime": 15.7,
+    "exitTime": 45.2,
+    "totalSystemTime": 29.5,
+    "totalWaitingTime": 8.3,
+    "totalCrossingTime": 4.8,
+    "routeTaken": ["Cr1", "Cr2", "Cr5", "S"]
+  }
+}
+```
+
+#### 4. HEARTBEAT
+
+Mantém a ligação ativa e monitoriza a saúde dos processos.
+
+**Estrutura:**
+```json
+{
+  "messageId": "d6e8f0a2-4567-8901-23cd-ef1234567890",
+  "type": "HEARTBEAT",
+  "senderId": "Cr1",
+  "destinationId": "Coordinator",
+  "timestamp": 1729595235000,
+  "payload": {
+    "status": "RUNNING",
+    "uptime": 120.5,
+    "vehiclesInQueue": 12
+  }
+}
+```
+
+**Frequência:** A cada 5 segundos
+
+#### 5. LIGHT_CHANGE
+
+Notifica mudança de estado de semáforo (para logging/debugging).
+
+**Estrutura:**
+```json
+{
+  "messageId": "e7f9a1b3-5678-9012-34de-f12345678901",
+  "type": "LIGHT_CHANGE",
+  "senderId": "Cr1-North",
+  "destinationId": "Dashboard",
+  "timestamp": 1729595235100,
+  "payload": {
+    "lightId": "Cr1-North",
+    "previousState": "RED",
+    "newState": "GREEN",
+    "queueSize": 5
+  }
+}
+```
+
+### Tipos de Veículos
+
+```json
+{
+  "BIKE": {
+    "probability": 0.20,
+    "crossingTime": 1.5
+  },
+  "LIGHT": {
+    "probability": 0.60,
+    "crossingTime": 2.0
+  },
+  "HEAVY": {
+    "probability": 0.20,
+    "crossingTime": 4.0
+  }
+}
+```
+
+### Estados dos Semáforos
+
+```
+RED    → Veículos aguardam na fila
+GREEN  → Veículos podem atravessar
+```
+
+### Exemplo de Comunicação Completa
+
+```
+Tempo    Processo    Ação                                    Mensagem
+------   ---------   -------------------------------------   ------------------
+15.7s    Gerador     Gera veículo V123                      -
+15.7s    Gerador →   Injeta V123 em Cr1                     VEHICLE_TRANSFER
+18.2s    Cr1         V123 inicia travessia                  -
+20.2s    Cr1         V123 completa travessia                -
+20.2s    Cr1 → Cr2   Transfere V123 para Cr2                VEHICLE_TRANSFER
+23.5s    Cr2         V123 inicia travessia                  -
+25.5s    Cr2         V123 completa travessia                -
+25.5s    Cr2 → Cr5   Transfere V123 para Cr5                VEHICLE_TRANSFER
+28.0s    Cr5         V123 inicia travessia                  -
+30.0s    Cr5         V123 completa travessia                -
+30.0s    Cr5 → Exit  V123 sai do sistema                    VEHICLE_EXIT
+30.0s    Exit → Dash Estatísticas de V123                   STATS_UPDATE
+```
+
+---
+
+## Estrutura do Projeto
+
+```
+Trabalho-Pratico-SD/
+├── README.md                          # Este ficheiro
+├── TODO.md                            # Plano de desenvolvimento
+├── main/
+│   ├── pom.xml                        # Configuração do Maven
+│   ├── docs/
+│   │   ├── README.md                  # Índice da documentação
+│   │   ├── SERIALIZATION_SPECIFICATION.md
+│   │   ├── SERIALIZATION_DECISION.md
+│   │   ├── SERIALIZATION_SUMMARY.md
+│   │   └── SERIALIZATION_ARCHITECTURE.md
+│   ├── src/
+│   │   ├── main/java/sd/
+│   │   │   ├── Entry.java             # Ponto de entrada
+│   │   │   ├── config/
+│   │   │   │   └── SimulationConfig.java
+│   │   │   ├── engine/
+│   │   │   │   └── SimulationEngine.java
+│   │   │   ├── model/
+│   │   │   │   ├── Event.java
+│   │   │   │   ├── EventType.java
+│   │   │   │   ├── Intersection.java
+│   │   │   │   ├── Message.java          # Estrutura de mensagens
+│   │   │   │   ├── MessageType.java      # Tipos de mensagens
+│   │   │   │   ├── TrafficLight.java
+│   │   │   │   ├── Vehicle.java
+│   │   │   │   └── VehicleType.java
+│   │   │   ├── serialization/            # Sistema de serialização
+│   │   │   │   ├── MessageSerializer.java
+│   │   │   │   ├── SerializationException.java
+│   │   │   │   ├── JsonMessageSerializer.java
+│   │   │   │   ├── SerializerFactory.java
+│   │   │   │   ├── SerializationExample.java
+│   │   │   │   └── README.md
+│   │   │   └── util/
+│   │   │       ├── RandomGenerator.java
+│   │   │       ├── StatisticsCollector.java
+│   │   │       └── VehicleGenerator.java
+│   │   └── test/java/
+│   │       ├── SimulationTest.java
+│   │       └── sd/serialization/
+│   │           └── SerializationTest.java
+│   └── target/                        # Ficheiros compilados
+└── .vscode/                           # Configuração do VS Code
+```
+
+---
+
+## Instalação e Execução
+
+### Pré-requisitos
+
+- **Java 17** ou superior
+- **Maven 3.8+**
+- **Git**
+
+### Instalação
+
+```bash
+# Clonar o repositório
+git clone https://github.com/davidalves04/Trabalho-Pratico-SD.git
+cd Trabalho-Pratico-SD/main
+
+# Compilar o projeto
+mvn clean compile
+
+# Executar os testes
+mvn test
+```
+
+### Execução
+
+#### Simulação Básica (Single Process)
+
+```bash
+mvn exec:java -Dexec.mainClass="sd.Entry"
+```
+
+#### Exemplo de Serialização
+
+```bash
+mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample"
+```
+
+#### Configuração
+
+Editar `src/main/resources/simulation.properties`:
+
+```properties
+# Duração da simulação (segundos)
+simulation.duration=60.0
+
+# Modelo de chegada: FIXED ou POISSON
+arrival.model=POISSON
+
+# Taxa de chegada (veículos/segundo)
+arrival.rate=0.5
+
+# Intervalo de atualização de estatísticas (segundos)
+stats.update.interval=10.0
+
+# Distribuição de tipos de veículos
+vehicle.type.bike.probability=0.20
+vehicle.type.light.probability=0.60
+vehicle.type.heavy.probability=0.20
+
+# Tempos de travessia por tipo (segundos)
+vehicle.type.bike.crossing.time=1.5
+vehicle.type.light.crossing.time=2.0
+vehicle.type.heavy.crossing.time=4.0
+```
+
+---
+
+## Documentação
+
+### Documentação de Serialização
+
+A documentação completa sobre o protocolo de serialização está disponível em:
+
+- **[Índice Completo](./main/docs/README.md)** - Navegação da documentação
+- **[Especificação](./main/docs/SERIALIZATION_SPECIFICATION.md)** - Design detalhado
+- **[Guia de Decisão](./main/docs/SERIALIZATION_DECISION.md)** - Porquê JSON?
+- **[Resumo](./main/docs/SERIALIZATION_SUMMARY.md)** - Estado de implementação
+- **[Arquitetura](./main/docs/SERIALIZATION_ARCHITECTURE.md)** - Diagramas visuais
+
+### Guias de Utilização
+
+- **[Serialization README](./main/src/main/java/sd/serialization/README.md)** - Como utilizar os serializers
+
+### Exemplos de Código
+
+```java
+// Criar serializer
+MessageSerializer serializer = SerializerFactory.createDefault();
+
+// Serializar mensagem
+Vehicle vehicle = new Vehicle("V123", VehicleType.LIGHT, 10.5, route);
+Message message = new Message(
+    MessageType.VEHICLE_TRANSFER,
+    "Cr1",
+    "Cr2",
+    vehicle
+);
+byte[] data = serializer.serialize(message);
+
+// Enviar via socket
+outputStream.write(data);
+
+// Receber e desserializar
+byte[] received = inputStream.readAllBytes();
+Message msg = serializer.deserialize(received, Message.class);
+Vehicle v = msg.getPayloadAs(Vehicle.class);
+```
+
+---
+
+## Desenvolvimento
+
+### Estado do Projeto
+
+| Componente | Estado | Notas |
+|------------|--------|-------|
+| Modelo de Dados | Completo | Vehicle, Message, Event, etc. |
+| Simulação DES | Completo | Single-process funcional |
+| Serialização | Completo | JSON e Java implementados |
+| Testes | 14/14 | Suite de serialização |
+| Processos Distribuídos | Planeado | Próxima etapa |
+| Comunicação Sockets | Planeado | Em design |
+| Dashboard | Planeado | UI web |
+
+### Roteiro de Desenvolvimento
+
+#### Fase 1: Fundações (Concluído)
+- Modelação de classes
+- Simulação DES single-process
+- Design de protocolo de serialização
+- Implementação JSON/Java serialization
+- Testes unitários
+
+#### Fase 2: Distribuição (Em Curso)
+- Implementar comunicação via sockets
+- Separar cruzamentos em processos
+- Implementar threads de semáforos
+- Testar comunicação entre processos
+
+#### Fase 3: Dashboard e Monitorização
+- Dashboard server
+- UI web em tempo real
+- Visualização de estatísticas
+- Logs estruturados
+
+#### Fase 4: Optimização e Análise
+- Testes de carga
+- Análise de diferentes políticas
+- Recolha de métricas
+- Relatório final
+
+### Executar Testes
+
+```bash
+# Todos os testes
+mvn test
+
+# Apenas testes de serialização
+mvn test -Dtest=SerializationTest
+
+# Com relatório de cobertura
+mvn test jacoco:report
+```
+
+### Contribuir
+
+1. Fork o projeto
+2. Criar uma branch para a funcionalidade (`git checkout -b feature/MinhaFuncionalidade`)
+3. Commit das alterações (`git commit -m 'Adiciona MinhaFuncionalidade'`)
+4. Push para a branch (`git push origin feature/MinhaFuncionalidade`)
+5. Abrir um Pull Request
+
+---
+
+## Métricas de Desempenho
+
+### Serialização
+
+| Formato | Tamanho | Latência | Throughput |
+|---------|---------|----------|------------|
+| JSON | 300 bytes | 40.79 μs | ~24k msgs/s |
+| Java | 657 bytes | 33.34 μs | ~30k msgs/s |
+
+**Conclusão**: JSON é 54% menor com overhead desprezível (7 μs)
+
+### Simulação
+
+- **Veículos gerados/s**: ~0.5-1.0 (configurável)
+- **Throughput**: ~0.2 veículos/s (saída)
+- **Tempo de execução**: 140ms para 60s de simulação
+- **Overhead**: < 0.25% do tempo simulado
+
+---
+
+## Protocolo de Mensagens - Resumo
+
+### Formato Base
+
+```
++------------------+
+| Message Header   |
+|------------------|
+| messageId        | UUID único
+| type             | Enum MessageType
+| senderId         | ID do processo remetente
+| destinationId    | ID do processo destino (null = broadcast)
+| timestamp        | Tempo de criação (ms)
++------------------+
+| Payload          |
+|------------------|
+| Object           | Dados específicos do tipo de mensagem
++------------------+
+```
+
+### Serialização
+
+- **Formato**: JSON (UTF-8)
+- **Biblioteca**: Gson 2.10.1
+- **Codificação**: UTF-8
+- **Compressão**: Opcional (gzip)
+
+### Transporte
+
+- **Protocolo**: TCP/IP
+- **Porta base**: 5000+ (configurável)
+- **Timeout**: 30s
+- **Keep-alive**: Heartbeat a cada 5s
+
+---
+
+## Segurança
+
+### Considerações
+
+1. **Validação de Mensagens**
+   - Verificar tipos esperados
+   - Validar intervalos de valores
+   - Rejeitar mensagens malformadas
+
+2. **Autenticação** (Planeado)
+   - Autenticação baseada em token
+   - Whitelist de processos
+
+3. **Encriptação** (Opcional)
+   - TLS/SSL para produção
+   - Não necessário para ambiente de desenvolvimento local
+
+---
+
+## Licença
+
+Este projeto é desenvolvido para fins académicos no âmbito da disciplina de Sistemas Distribuídos (SD) do Instituto Politécnico do Porto.
+
+---
+
+## Equipa
+
+**Instituição**: Instituto Politécnico do Porto  
+**Curso**: Sistemas Distribuídos  
+**Ano Letivo**: 2025-2026 (1º Semestre)
+
+---
+
+## Suporte
+
+Para questões ou problemas:
+
+1. Consultar a [documentação](./main/docs/README.md)
+2. Ver [exemplos de código](./main/src/main/java/sd/serialization/SerializationExample.java)
+3. Executar testes: `mvn test`
+4. Abrir issue no GitHub
+
+---
+
+## Ligações Úteis
+
+- [Documentação do Projeto](./main/docs/README.md)
+- [Plano de Desenvolvimento](./TODO.md)
+- [Especificação de Serialização](./main/docs/SERIALIZATION_SPECIFICATION.md)
+- [Guia de Serialização](./main/src/main/java/sd/serialization/README.md)
+
+---
+
+**Última actualização**: 23 de outubro de 2025  
+**Versão**: 1.0.0  
+**Estado**: Em Desenvolvimento Activo

STEP2_SUMMARY.md

@@ -0,0 +1,134 @@
+# 🏁 Single-Process Prototype — Implementation Summary
+
+**Status:** ✅ Complete
+**Date:** October 22, 2025
+**Branch:** `8-single-process-prototype`
+
+---
+
+## Overview
+
+The single-process prototype implements a **discrete event simulation (DES)** of a 3×3 urban grid with five intersections, realistic vehicle behavior, and fully synchronized traffic lights. Everything runs under one process, laying the groundwork for the distributed architecture in Phase 3.
+
+---
+
+## Core Architecture
+
+### **SimulationEngine**
+
+Drives the DES loop with a priority queue of timestamped events — vehicles, lights, crossings, and periodic stats updates. Handles five intersections (Cr1–Cr5) and six event types.
+
+**Main loop:**
+
+```
+while (events && time < duration):
+    event = nextEvent()
+    time = event.timestamp
+    handle(event)
+```
+
+### **VehicleGenerator**
+
+Spawns vehicles via:
+
+* **Poisson arrivals** (λ = 0.5 veh/s) or fixed intervals
+* **Probabilistic routes** from E1–E3
+* **Type distribution**: 20% BIKE, 60% LIGHT, 20% HEAVY
+
+### **StatisticsCollector**
+
+Tracks system-wide and per-type metrics: throughput, avg. wait, queue sizes, light cycles — updated every 10 s and at simulation end.
+
+---
+
+## Model Highlights
+
+* **Vehicle** – type, route, timings, lifecycle.
+* **Intersection** – routing tables, traffic lights, queues.
+* **TrafficLight** – red/green cycles with FIFO queues.
+* **Event** – timestamped, comparable; 6 types for all DES actions.
+
+---
+
+## Configuration (`simulation.properties`)
+
+```properties
+simulation.duration=60.0
+simulation.arrival.model=POISSON
+simulation.arrival.rate=0.5
+
+vehicle.bike.crossingTime=1.5
+vehicle.light.crossingTime=2.0
+vehicle.heavy.crossingTime=4.0
+
+statistics.update.interval=10.0
+```
+
+**Speed logic:**
+`t_bike = 0.5×t_car`, `t_heavy = 2×t_car`.
+
+---
+
+## Topology
+
+```
+E1→Cr1→Cr4→Cr5→S
+E2→Cr2→Cr5→S
+E3→Cr3→S
+Bi-dir: Cr1↔Cr2, Cr2↔Cr3
+```
+
+---
+
+## Results
+
+**Unit Tests:** 7/7 ✅
+**60-Second Simulation:**
+
+* Generated: 22 vehicles
+* Completed: 5 (22.7%)
+* Avg system time: 15.47 s
+* Throughput: 0.08 veh/s
+* All lights & intersections operational
+
+**Performance:**
+~0.03 s real-time run (≈2000× speed-up), < 50 MB RAM.
+
+---
+
+## Code Structure
+
+```
+sd/
+├── engine/SimulationEngine.java
+├── model/{Vehicle,Intersection,TrafficLight,Event}.java
+├── util/{VehicleGenerator,StatisticsCollector}.java
+└── config/SimulationConfig.java
+```
+
+---
+
+## Key Flow
+
+1. Initialize intersections, lights, first events.
+2. Process events chronologically.
+3. Vehicles follow routes → queue → cross → exit.
+4. Lights toggle, queues drain, stats update.
+5. Print summary and performance metrics.
+
+---
+
+## Next Steps — Phase 3
+
+* Split intersections into independent **processes**.
+* Add **socket-based communication**.
+* Run **traffic lights as threads**.
+* Enable **distributed synchronization** and fault handling.
+
+---
+
+## TL;DR
+
+Solid single-process DES ✅
+Everything’s working — traffic lights, routing, vehicles, stats.
+Ready to go distributed next.

TODO.md

@@ -1,3 +1,26 @@
+## ✅ SINGLE-PROCESS PROTOTYPE - COMPLETED
+
+### Phase 2 Status: DONE ✅
+
+All components for the single-process prototype have been successfully implemented and tested:
+
+- ✅ **SimulationEngine** - Priority queue-based discrete event simulation
+- ✅ **VehicleGenerator** - Poisson and Fixed arrival models
+- ✅ **StatisticsCollector** - Comprehensive metrics tracking
+- ✅ **Entry point** - Main simulation runner
+- ✅ **60s test simulation** - Successfully validated event processing and routing
+
+### Test Results:
+- All 7 unit tests passing
+- 60-second simulation completed successfully
+- Generated 22 vehicles with 5 completing their routes
+- Traffic light state changes working correctly
+- Vehicle routing through intersections validated
+
+---
+
+## NEXT: Distributed Architecture Implementation
+
 ### Compreender os Conceitos Fundamentais
 
 Primeiro, as tecnologias e paradigmas chave necessários para este projeto devem ser totalmente compreendidos.
@@ -16,7 +39,7 @@ Primeiro, as tecnologias e paradigmas chave necessários para este projeto devem
         
     - Uma **lista de eventos** central, frequentemente uma fila de prioridades, será necessária para armazenar eventos futuros, ordenados pelo seu timestamp. O ciclo principal da simulação retira o próximo evento da lista, processa-o e adiciona quaisquer novos eventos que resultem dele.
         
-- **Processo de Poisson:** Para o modelo "mais realista" de chegadas de veículos, é especificado um processo de Poisson. A principal conclusão é que o tempo _entre_ chegadas consecutivas de veículos segue uma **distribuição exponencial**. Em Java, este intervalo pode ser gerado usando `Math.log(1 - Math.random()) / -lambda`, onde `lambda` (λi​) é a taxa de chegada especificada.
+- **Processo de Poisson:** Para o modelo 'mais realista' de chegadas de veículos, é especificado um processo de Poisson. A principal conclusão é que o tempo _entre_ chegadas consecutivas de veículos segue uma **distribuição exponencial**. Em Java, este intervalo pode ser gerado usando `Math.log(1 - Math.random()) / -lambda`, onde `lambda` (λi​) é a taxa de chegada especificada.
     
 
 ---

arquitetura_simplificada.xml

@@ -0,0 +1,172 @@
+<?xml version='1.0' encoding='utf-8'?>
+<mxfile host="app.diagrams.net" agent="Gemini" version="28.2.7">
+  <diagram name="Arquitetura-Sistema-Trafego" id="L-jWkP8vD7q_2fM6N-yC">
+    <mxGraphModel dx="1434" dy="746" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1654" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="E1-process" value="Processo Gerador E1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="140" y="100" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="E2-process" value="Processo Gerador E2" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="430" y="100" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="E3-process" value="Processo Gerador E3" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="720" y="100" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr1-process" value="Processo Cruzamento (Cr1)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;verticalAlign=top;spacingTop=5;" vertex="1" parent="1">
+          <mxGeometry x="140" y="240" width="140" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr1-thread1" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr1-process">
+          <mxGeometry x="20" y="30" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr1-thread2" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr1-process">
+          <mxGeometry x="20" y="65" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr2-process" value="Processo Cruzamento (Cr2)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;verticalAlign=top;spacingTop=5;" vertex="1" parent="1">
+          <mxGeometry x="430" y="240" width="140" height="140" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr2-thread1" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr2-process">
+          <mxGeometry x="20" y="30" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr2-thread2" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr2-process">
+          <mxGeometry x="20" y="65" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr2-thread3" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr2-process">
+          <mxGeometry x="20" y="100" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr3-process" value="Processo Cruzamento (Cr3)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;verticalAlign=top;spacingTop=5;" vertex="1" parent="1">
+          <mxGeometry x="720" y="240" width="140" height="140" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr3-thread1" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr3-process">
+          <mxGeometry x="20" y="30" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr3-thread2" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr3-process">
+          <mxGeometry x="20" y="65" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr3-thread3" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr3-process">
+          <mxGeometry x="20" y="100" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr4-process" value="Processo Cruzamento (Cr4)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;verticalAlign=top;spacingTop=5;" vertex="1" parent="1">
+          <mxGeometry x="140" y="460" width="140" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr4-thread1" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr4-process">
+          <mxGeometry x="20" y="30" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr4-thread-peao" value="Thread Semáforo (Peões)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr4-process">
+          <mxGeometry x="20" y="65" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr5-process" value="Processo Cruzamento (Cr5)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;verticalAlign=top;spacingTop=5;" vertex="1" parent="1">
+          <mxGeometry x="430" y="460" width="140" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr5-thread1" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr5-process">
+          <mxGeometry x="20" y="30" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Cr5-thread2" value="Thread Semáforo" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="Cr5-process">
+          <mxGeometry x="20" y="65" width="100" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="S-process" value="Processo Saída (S)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
+          <mxGeometry x="720" y="460" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="dashboard-server" value="Servidor Dashboard" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="430" y="640" width="140" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-E1-Cr1" value="Fluxo Veículos&lt;br&gt;(Sockets/Middleware)" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;fontSize=10;align=left;verticalAlign=bottom;" edge="1" parent="1" source="E1-process" target="Cr1-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-E2-Cr2" value="Fluxo Veículos&lt;br&gt;(Sockets/Middleware)" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;fontSize=10;align=left;verticalAlign=bottom;" edge="1" parent="1" source="E2-process" target="Cr2-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-E3-Cr3" value="Fluxo Veículos&lt;br&gt;(Sockets/Middleware)" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;fontSize=10;align=left;verticalAlign=bottom;" edge="1" parent="1" source="E3-process" target="Cr3-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-Cr1-Cr4" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr1-process" target="Cr4-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-Cr2-Cr5" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr2-process" target="Cr5-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-Cr4-Cr5" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr4-process" target="Cr5-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-Cr5-S" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr5-process" target="S-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-Cr3-S" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr3-process" target="S-process">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow-Cr1-Cr2" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr1-process" target="Cr2-process">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="280" y="290" />
+              <mxPoint x="430" y="290" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="arrow-Cr2-Cr1" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr2-process" target="Cr1-process">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="430" y="310" />
+              <mxPoint x="280" y="310" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="arrow-Cr2-Cr3" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr2-process" target="Cr3-process">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="570" y="290" />
+              <mxPoint x="720" y="290" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="arrow-Cr3-Cr2" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;" edge="1" parent="1" source="Cr3-process" target="Cr2-process">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="720" y="310" />
+              <mxPoint x="570" y="310" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="stats-Cr1-Dash" value="Envio de Estatísticas" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;dashed=1;strokeColor=#9673a6;fontSize=10;verticalAlign=bottom;" edge="1" parent="1" source="Cr1-process" target="dashboard-server">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="210" y="680" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="stats-Cr2-Dash" value="Envio de Estatísticas" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;dashed=1;strokeColor=#9673a6;fontSize=10;verticalAlign=bottom;" edge="1" parent="1" source="Cr2-process" target="dashboard-server">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="stats-Cr3-Dash" value="Envio de Estatísticas" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;dashed=1;strokeColor=#9673a6;fontSize=10;verticalAlign=bottom;" edge="1" parent="1" source="Cr3-process" target="dashboard-server">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="790" y="680" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="stats-Cr4-Dash" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;dashed=1;strokeColor=#9673a6;" edge="1" parent="1" source="Cr4-process" target="dashboard-server">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="210" y="680" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="stats-Cr5-Dash" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;dashed=1;strokeColor=#9673a6;" edge="1" parent="1" source="Cr5-process" target="dashboard-server">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="stats-S-Dash" value="Estatísticas Globais" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;dashed=1;strokeColor=#9673a6;fontSize=10;verticalAlign=bottom;" edge="1" parent="1" source="S-process" target="dashboard-server">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="790" y="680" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="legend" value="Legenda simplificada (removida tabela)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#999999;" vertex="1" parent="1">
+          </mxCell>
+        <mxCell id="title" value="Diagrama de Arquitetura - Simulador de Tráfego Distribuído" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=18;fontStyle=1" vertex="1" parent="1">
+          <mxGeometry x="290" y="40" width="420" height="30" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

main/pom.xml

@@ -11,6 +11,58 @@
     <properties>
         <maven.compiler.source>17</maven.compiler.source>
         <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
 
+    <dependencies>
+        <!-- JUnit 5 for testing -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>5.10.0</version>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- Gson for JSON serialization -->
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.10.1</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!-- Maven Exec Plugin for running examples -->
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>3.1.0</version>
+                <configuration>
+                    <mainClass>sd.Entry</mainClass>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.5.2</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <transformers>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                                    <mainClass>sd.Entry</mainClass>
+                                </transformer>
+                            </transformers>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
 </project>

main/src/main/java/sd/Entry.java

@@ -1,7 +1,94 @@
 package sd;
 
+import java.io.IOException;
+
+import sd.config.SimulationConfig;
+import sd.engine.SimulationEngine;
+
+/**
+ * Main entry point for the traffic simulation.
+ * * This class is responsible for loading the simulation configuration,
+ * initializing the {@link SimulationEngine}, and starting the simulation run.
+ * It also prints initial configuration details and final execution time.
+ */
 public class Entry {
+    
+    /**
+     * The default path to the simulation configuration file.
+     * This is used if no command-line arguments are provided.
+     */
+    private static final String DEFAULT_CONFIG_FILE = "src/main/resources/simulation.properties";
+    
+    /**
+     * The main method to start the simulation.
+     * * @param args Command-line arguments. If provided, args[0] is expected
+     * to be the path to a custom configuration file.
+     */
     public static void main(String[] args) {
-        System.out.println("Hello, World!");
+        System.out.println("=".repeat(60));
+        System.out.println("TRAFFIC SIMULATION - DISCRETE EVENT SIMULATOR");
+        System.out.println("=".repeat(60));
+        
+        try {
+            // 1. Load configuration
+            String configFile = args.length > 0 ? args[0] : DEFAULT_CONFIG_FILE;
+            System.out.println("Loading configuration from: " + configFile);
+            
+            SimulationConfig config = new SimulationConfig(configFile);
+            
+            // 2. Display configuration
+            displayConfiguration(config);
+            
+            // 3. Create and initialize simulation engine
+            SimulationEngine engine = new SimulationEngine(config);
+            engine.initialize();
+            
+            System.out.println("\n" + "=".repeat(60));
+            
+            // 4. Run simulation
+            long startTime = System.currentTimeMillis();
+            engine.run();
+            long endTime = System.currentTimeMillis();
+            
+            // 5. Display execution time
+            double executionTime = (endTime - startTime) / 1000.0;
+            System.out.println("\nExecution time: " + String.format("%.2f", executionTime) + " seconds");
+            System.out.println("=".repeat(60));
+            
+        } catch (IOException e) {
+            System.err.println("Error loading configuration: " + e.getMessage());
+            e.printStackTrace();
+        } catch (Exception e) {
+            System.err.println("Error during simulation: " + e.getMessage());
+            e.printStackTrace();
+        }
+    }
+    
+    /**
+     * Displays the main configuration parameters to the console.
+     * This provides a summary of the simulation settings before it starts.
+     *
+     * @param config The {@link SimulationConfig} object containing the loaded settings.
+     */
+    private static void displayConfiguration(SimulationConfig config) {
+        System.out.println("\nSIMULATION CONFIGURATION:");
+        System.out.println("  Duration: " + config.getSimulationDuration() + " seconds");
+        System.out.println("  Arrival Model: " + config.getArrivalModel());
+        
+        if ("POISSON".equalsIgnoreCase(config.getArrivalModel())) {
+            System.out.println("  Arrival Rate (λ): " + config.getArrivalRate() + " vehicles/second");
+        } else {
+            System.out.println("  Fixed Interval: " + config.getFixedArrivalInterval() + " seconds");
+        }
+        
+        System.out.println("  Statistics Update Interval: " + config.getStatisticsUpdateInterval() + " seconds");
+        
+        System.out.println("\nVEHICLE TYPES:");
+        System.out.println("  Bike: " + (config.getBikeVehicleProbability() * 100) + "% " +
+                         "(crossing time: " + config.getBikeVehicleCrossingTime() + "s)");
+        System.out.println("  Light: " + (config.getLightVehicleProbability() * 100) + "% " +
+                         "(crossing time: " + config.getLightVehicleCrossingTime() + "s)");
+        System.out.println("  Heavy: " + (config.getHeavyVehicleProbability() * 100) + "% " +
+                         "(crossing time: " + config.getHeavyVehicleCrossingTime() + "s)");
     }
 }

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

@@ -0,0 +1,501 @@
+package sd;
+
+import java.io.IOException;
+import java.net.ServerSocket;
+import java.net.Socket;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+import sd.config.SimulationConfig;
+import sd.model.Intersection;
+import sd.model.MessageType;
+import sd.model.TrafficLight;
+import sd.model.TrafficLightState;
+import sd.model.Vehicle;
+import sd.protocol.MessageProtocol;
+import sd.protocol.SocketConnection;
+
+/**
+ * Main class for an Intersection Process in the distributed traffic simulation.
+ * * Each IntersectionProcess runs as an independent Java application (JVM instance)
+ * representing one of the five intersections (Cr1-Cr5) in the network.
+ */
+public class IntersectionProcess {
+
+    private final String intersectionId;
+    
+    private final SimulationConfig config;
+    
+    private final Intersection intersection;
+    
+    private ServerSocket serverSocket;
+    
+    private final Map<String, SocketConnection> outgoingConnections;
+    
+    private final ExecutorService connectionHandlerPool;
+    
+    private final ExecutorService trafficLightPool;
+    
+    private volatile boolean running;   //Quando uma thread escreve um valor volatile, todas as outras
+                                        //threads veem a mudança imediatamente.
+    
+    /**
+     * Constructs a new IntersectionProcess.
+     *
+     * @param intersectionId The ID of this intersection (e.g., "Cr1").
+     * @param configFilePath Path to the simulation.properties file.
+     * @throws IOException If configuration cannot be loaded.
+     */
+    public IntersectionProcess(String intersectionId, String configFilePath) throws IOException {
+        this.intersectionId = intersectionId;
+        this.config = new SimulationConfig(configFilePath);
+        this.intersection = new Intersection(intersectionId);
+        this.outgoingConnections = new HashMap<>();
+        this.connectionHandlerPool = Executors.newCachedThreadPool();
+        this.trafficLightPool = Executors.newFixedThreadPool(4); // Max 4 directions
+        this.running = false;
+        
+        System.out.println("=".repeat(60));
+        System.out.println("INTERSECTION PROCESS: " + intersectionId);
+        System.out.println("=".repeat(60));
+    }
+    
+    public void initialize() {
+        System.out.println("\n[" + intersectionId + "] Initializing intersection...");
+        
+        createTrafficLights();
+        
+        configureRouting();
+        
+        startTrafficLights();
+        
+        System.out.println("[" + intersectionId + "] Initialization complete.");
+    }
+
+    /**
+     * Creates traffic lights for this intersection based on its physical connections.
+     * Each intersection has different number and directions of traffic lights
+     * according to the network topology.
+     */
+    private void createTrafficLights() {
+        System.out.println("\n[" + intersectionId + "] Creating traffic lights...");
+        
+        String[] directions = new String[0];
+        switch (intersectionId) {
+            case "Cr1":
+                directions = new String[]{"East", "South"};
+                break;
+            case "Cr2":
+                directions = new String[]{"West", "East", "South"};
+                break;
+            case "Cr3":
+                directions = new String[]{"West", "South"};
+                break;
+            case "Cr4":
+                directions = new String[]{"East"};
+                break;
+            case "Cr5":
+                directions = new String[]{"East"};
+                break;
+        }
+        
+        for (String direction : directions) {
+            double greenTime = config.getTrafficLightGreenTime(intersectionId, direction);
+            double redTime = config.getTrafficLightRedTime(intersectionId, direction);
+            
+            TrafficLight light = new TrafficLight(
+                intersectionId + "-" + direction,
+                direction,
+                greenTime,
+                redTime
+            );
+            
+            intersection.addTrafficLight(light);
+            System.out.println("  Created traffic light: " + direction + 
+                             " (Green: " + greenTime + "s, Red: " + redTime + "s)");
+        }
+    }
+    
+    private void configureRouting() {
+        System.out.println("\n[" + intersectionId + "] Configuring routing...");
+        
+        switch (intersectionId) {
+            case "Cr1":
+                intersection.configureRoute("Cr2", "East");
+                intersection.configureRoute("Cr4", "South"); 
+                break;
+                
+            case "Cr2":
+                intersection.configureRoute("Cr1", "West");
+                intersection.configureRoute("Cr3", "East");
+                intersection.configureRoute("Cr5", "South");
+                break;
+                
+            case "Cr3":
+                intersection.configureRoute("Cr2", "West");
+                intersection.configureRoute("S", "South");
+                break;
+                
+            case "Cr4":
+                intersection.configureRoute("Cr5", "East");
+                break;
+                
+            case "Cr5":
+                intersection.configureRoute("S", "East");
+                break;
+                
+            default:
+                System.err.println("  Error: unknown intersection ID: " + intersectionId);
+        }
+        
+        System.out.println("  Routing configured.");
+    }
+    
+    /**
+     * Starts all traffic light threads.
+     */
+    private void startTrafficLights() {
+        System.out.println("\n[" + intersectionId + "] Starting traffic light threads...");
+        
+        for (TrafficLight light : intersection.getTrafficLights()) {
+            trafficLightPool.submit(() -> runTrafficLightCycle(light));
+            System.out.println("  Started thread for: " + light.getDirection());
+        }
+    }
+    
+    /**
+     * The main loop for a traffic light thread.
+     * Continuously cycles between GREEN and RED states.
+     *
+     * @param light The traffic light to control.
+     */
+    private void runTrafficLightCycle(TrafficLight light) {
+        System.out.println("[" + light.getId() + "] Traffic light thread started.");
+        
+        while (running) {
+            try {
+                // Green state
+                light.changeState(TrafficLightState.GREEN);
+                System.out.println("[" + light.getId() + "] State: GREEN");
+                
+                // Process vehicles while green
+                processGreenLight(light);
+                
+                // Wait for green duration
+                Thread.sleep((long) (light.getGreenTime() * 1000));
+                
+                // RED state
+                light.changeState(TrafficLightState.RED);
+                System.out.println("[" + light.getId() + "] State: RED");
+                
+                // Wait for red duration
+                Thread.sleep((long) (light.getRedTime() * 1000));
+                
+            } catch (InterruptedException e) {
+                System.out.println("[" + light.getId() + "] Traffic light thread interrupted.");
+                break;
+            }
+        }
+        
+        System.out.println("[" + light.getId() + "] Traffic light thread stopped.");
+    }
+    
+    /**
+     * Processes vehicles when a traffic light is GREEN.
+     * Dequeues vehicles and sends them to their next destination.
+     *
+     * @param light The traffic light that is currently green.
+     */
+    private void processGreenLight(TrafficLight light) {
+        while (light.getState() == TrafficLightState.GREEN && light.getQueueSize() > 0) {
+            Vehicle vehicle = light.removeVehicle();
+            
+            if (vehicle != null) {
+                // Get crossing time based on vehicle type
+                double crossingTime = getCrossingTimeForVehicle(vehicle);
+                
+                // Simulate crossing time
+                try {
+                    Thread.sleep((long) (crossingTime * 1000));
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    break;
+                }
+                
+                // Update vehicle statistics
+                vehicle.addCrossingTime(crossingTime);
+                
+                // Update intersection statistics
+                intersection.incrementVehiclesSent();
+                
+                // Send vehicle to next destination
+                sendVehicleToNextDestination(vehicle);
+            }
+        }
+    }
+    
+    /**
+     * Gets the crossing time for a vehicle based on its type.
+     *
+     * @param vehicle The vehicle.
+     * @return The crossing time in seconds.
+     */
+    private double getCrossingTimeForVehicle(Vehicle vehicle) {
+        switch (vehicle.getType()) {
+            case BIKE:
+                return config.getBikeVehicleCrossingTime();
+            case LIGHT:
+                return config.getLightVehicleCrossingTime();
+            case HEAVY:
+                return config.getHeavyVehicleCrossingTime();
+            default:
+                return config.getLightVehicleCrossingTime();
+        }
+    }
+    
+    /**
+     * Sends a vehicle to its next destination via socket connection.
+     *
+     * @param vehicle The vehicle that has crossed this intersection.
+     */
+    private void sendVehicleToNextDestination(Vehicle vehicle) {
+        String nextDestination = vehicle.getCurrentDestination();
+        
+        try {
+            // Get or create connection to next destination
+            SocketConnection connection = getOrCreateConnection(nextDestination);
+            
+            // Create and send message
+            MessageProtocol message = new VehicleTransferMessage(
+                intersectionId,
+                nextDestination,
+                vehicle
+            );
+            
+            connection.sendMessage(message);
+            
+            System.out.println("[" + intersectionId + "] Sent vehicle " + vehicle.getId() + 
+                             " to " + nextDestination);
+            
+            // 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());
+        }
+    }
+    
+    /**
+     * Gets an existing connection to a destination or creates a new one.
+     *
+     * @param destinationId The ID of the destination node.
+     * @return The SocketConnection to that destination.
+     * @throws IOException If connection cannot be established.
+     * @throws InterruptedException If connection attempt is interrupted.
+     */
+    private synchronized SocketConnection getOrCreateConnection(String destinationId) 
+            throws IOException, InterruptedException {
+        
+        if (!outgoingConnections.containsKey(destinationId)) {
+            String host = getHostForDestination(destinationId);
+            int port = getPortForDestination(destinationId);
+            
+            System.out.println("[" + intersectionId + "] Creating connection to " + 
+                             destinationId + " at " + host + ":" + port);
+            
+            SocketConnection connection = new SocketConnection(host, port);
+            outgoingConnections.put(destinationId, connection);
+        }
+        
+        return outgoingConnections.get(destinationId);
+    }
+    
+    /**
+     * Gets the host address for a destination node from configuration.
+     *
+     * @param destinationId The destination node ID.
+     * @return The host address.
+     */
+    private String getHostForDestination(String destinationId) {
+        if (destinationId.equals("S")) {
+            return config.getExitHost();
+        } else {
+            return config.getIntersectionHost(destinationId);
+        }
+    }
+    
+    /**
+     * Gets the port number for a destination node from configuration.
+     *
+     * @param destinationId The destination node ID.
+     * @return The port number.
+     */
+    private int getPortForDestination(String destinationId) {
+        if (destinationId.equals("S")) {
+            return config.getExitPort();
+        } else {
+            return config.getIntersectionPort(destinationId);
+        }
+    }
+    
+    /**
+     * Starts the server socket and begins accepting incoming connections.
+     * This is the main listening loop of the process.
+     *
+     * @throws IOException If the server socket cannot be created.
+     */
+    public void start() throws IOException {
+        int port = config.getIntersectionPort(intersectionId);
+        serverSocket = new ServerSocket(port);
+        running = true;
+        
+        System.out.println("\n[" + intersectionId + "] Server started on port " + port);
+        System.out.println("[" + intersectionId + "] Waiting for incoming connections...\n");
+        
+        // Main accept loop
+        while (running) {
+            try {
+                Socket clientSocket = serverSocket.accept();
+                
+                // Handle each connection in a separate thread
+                connectionHandlerPool.submit(() -> handleIncomingConnection(clientSocket));
+                
+            } catch (IOException e) {
+                if (running) {
+                    System.err.println("[" + intersectionId + "] Error accepting connection: " + 
+                                     e.getMessage());
+                }
+            }
+        }
+    }
+    
+    /**
+     * Handles an incoming connection from another process.
+     * Continuously listens for vehicle transfer messages.
+     *
+     * @param clientSocket The accepted socket connection.
+     */
+    private void handleIncomingConnection(Socket clientSocket) {
+        try (SocketConnection connection = new SocketConnection(clientSocket)) {
+            
+            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();
+                    
+                    if (message.getType() == MessageType.VEHICLE_TRANSFER) {
+                        Vehicle vehicle = (Vehicle) message.getPayload();
+                        
+                        System.out.println("[" + intersectionId + "] Received vehicle: " + 
+                                         vehicle.getId() + " from " + message.getSourceNode());
+                        
+                        // Add vehicle to appropriate queue
+                        intersection.receiveVehicle(vehicle);
+                    }
+                    
+                } catch (ClassNotFoundException e) {
+                    System.err.println("[" + intersectionId + "] Unknown message type received: " + 
+                                     e.getMessage());
+                }
+            }
+            
+        } catch (IOException e) {
+            if (running) {
+                System.err.println("[" + intersectionId + "] Connection error: " + e.getMessage());
+            }
+        }
+    }
+    
+    /**
+     * Stops the intersection process gracefully.
+     * Shuts down all threads and closes all connections.
+     */
+    public void shutdown() {
+        System.out.println("\n[" + intersectionId + "] Shutting down...");
+        running = false;
+        
+        // Close server socket
+        try {
+            if (serverSocket != null && !serverSocket.isClosed()) {
+                serverSocket.close();
+            }
+        } catch (IOException e) {
+            System.err.println("[" + intersectionId + "] Error closing server socket: " + 
+                             e.getMessage());
+        }
+        
+        // Shutdown thread pools
+        trafficLightPool.shutdown();
+        connectionHandlerPool.shutdown();
+        
+        try {
+            if (!trafficLightPool.awaitTermination(5, TimeUnit.SECONDS)) {
+                trafficLightPool.shutdownNow();
+            }
+            if (!connectionHandlerPool.awaitTermination(5, TimeUnit.SECONDS)) {
+                connectionHandlerPool.shutdownNow();
+            }
+        } catch (InterruptedException e) {
+            trafficLightPool.shutdownNow();
+            connectionHandlerPool.shutdownNow();
+        }
+        
+        // Close all outgoing connections
+        for (Map.Entry<String, SocketConnection> entry : outgoingConnections.entrySet()) {
+            try {
+                entry.getValue().close();
+            } catch (IOException e) {
+                System.err.println("[" + intersectionId + "] Error closing connection to " + 
+                                 entry.getKey() + ": " + e.getMessage());
+            }
+        }
+        
+        System.out.println("[" + intersectionId + "] Shutdown complete.");
+        System.out.println("=".repeat(60));
+    }
+    
+    // --- Inner class for Vehicle Transfer Messages ---
+    
+    /**
+     * Implementation of MessageProtocol for vehicle transfers between processes.
+     */
+    private static class VehicleTransferMessage implements MessageProtocol {
+        private static final long serialVersionUID = 1L;
+        
+        private final String sourceNode;
+        private final String destinationNode;
+        private final Vehicle payload;
+        
+        public VehicleTransferMessage(String sourceNode, String destinationNode, Vehicle vehicle) {
+            this.sourceNode = sourceNode;
+            this.destinationNode = destinationNode;
+            this.payload = vehicle;
+        }
+        
+        @Override
+        public MessageType getType() {
+            return MessageType.VEHICLE_TRANSFER;
+        }
+        
+        @Override
+        public Object getPayload() {
+            return payload;
+        }
+        
+        @Override
+        public String getSourceNode() {
+            return sourceNode;
+        }
+        
+        @Override
+        public String getDestinationNode() {
+            return destinationNode;
+        }
+    }
+}

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

@@ -7,94 +7,253 @@ import java.util.Properties;
 
 /**
  * Class to load and manage simulation configurations.
- * Configurations are read from a .properties file.
+ * Configurations are read from a .properties file. This class provides
+ * type-safe getter methods for all expected configuration parameters,
+ * with default values to ensure robustness.
  */
 public class SimulationConfig {
+    
+    /**
+     * Holds all properties loaded from the file.
+     */
     private final Properties properties;
 
+    /**
+     * Constructs a new SimulationConfig object by loading properties
+     * from the specified file path.
+     *
+     * @param filePath The path to the .properties file (e.g., "src/main/resources/simulation.properties").
+     * @throws IOException If the file cannot be found or read.
+     */
     public SimulationConfig(String filePath) throws IOException {
         properties = new Properties();
+        /**Tenta carregar diretamente a partir do sistema de ficheiros, se o ficheiro não existir
+         * (por exemplo quando executado a partir do classpath/jar),
+         * faz fallback para carregar a partir do classpath usando o ClassLoader.
+        */
+        IOException lastException = null; //FIXME: melhorar esta parte para reportar erros de forma mais clara
+
+        try {
             try (InputStream input = new FileInputStream(filePath)) {
                 properties.load(input);
+                return; // carregado com sucesso a partir do caminho fornecido
             }
+        } catch (IOException e) {
+            lastException = e;
+            //tenta carregar a partir do classpath sem prefixos comuns
+            String resourcePath = filePath;
+            //Remove prefixos que apontam para src/main/resources quando presentes
+            resourcePath = resourcePath.replace("src/main/resources/", "").replace("src\\main\\resources\\", "");
+            //Remove prefixo classpath: se fornecido
+            if (resourcePath.startsWith("classpath:")) {
+                resourcePath = resourcePath.substring("classpath:".length());
+                if (resourcePath.startsWith("/")) resourcePath = resourcePath.substring(1);
             }
 
-    // Network configurations
+            InputStream resourceStream = Thread.currentThread().getContextClassLoader().getResourceAsStream(resourcePath);
+            if (resourceStream == null) {
+                //como último recurso, tentar com um leading slash
+                resourceStream = SimulationConfig.class.getResourceAsStream('/' + resourcePath);
+            }
+
+            if (resourceStream != null) {
+                try (InputStream input = resourceStream) {
+                    properties.load(input);
+                    return;
+                }
+            }
+        }
+        if (lastException != null) throw lastException;
+    }
+
+    // --- Network configurations ---
+
+    /**
+     * Gets the host address for a specific intersection.
+     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @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.
+     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @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.
+     * @return The dashboard host.
+     */
     public String getDashboardHost() {
         return properties.getProperty("dashboard.host", "localhost");
     }
 
+    /**
+     * Gets the port number for the dashboard server.
+     * @return The dashboard port.
+     */
     public int getDashboardPort() {
         return Integer.parseInt(properties.getProperty("dashboard.port", "9000"));
     }
 
+    /**
+     * Gets the host address for the exit node.
+     * @return The exit node host.
+     */
     public String getExitHost() {
         return properties.getProperty("exit.host", "localhost");
     }
 
+    /**
+     * Gets the port number for the exit node.
+     * @return The exit node port.
+     */
     public int getExitPort() {
         return Integer.parseInt(properties.getProperty("exit.port", "9001"));
     }
 
-    // Simulation configurations
+    // --- Simulation configurations ---
+
+    /**
+     * Gets the total duration of the simulation in virtual seconds.
+     * @return The simulation duration.
+     */
     public double getSimulationDuration() {
         return Double.parseDouble(properties.getProperty("simulation.duration", "3600.0"));
     }
 
+    /**
+     * Gets the vehicle arrival model ("POISSON" or "FIXED").
+     * @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.
+     * This represents the average number of vehicles arriving per second.
+     * @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.
+     * @return The fixed interval in seconds.
+     */
     public double getFixedArrivalInterval() {
         return Double.parseDouble(properties.getProperty("simulation.arrival.fixed.interval", "2.0"));
     }
 
-    // Traffic light configurations
+    // --- Traffic light configurations ---
+
+    /**
+     * Gets the duration of the GREEN light state for a specific traffic light.
+     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @param direction The direction of the light (e.g., "North").
+     * @return The green light time in seconds.
+     */
     public double getTrafficLightGreenTime(String intersectionId, String direction) {
         String key = "trafficlight." + intersectionId + "." + direction + ".green";
         return Double.parseDouble(properties.getProperty(key, "30.0"));
     }
 
+    /**
+     * Gets the duration of the RED light state for a specific traffic light.
+     * @param intersectionId The ID of the intersection (e.g., "Cr1").
+     * @param direction The direction of the light (e.g., "North").
+     * @return The red light time in seconds.
+     */
     public double getTrafficLightRedTime(String intersectionId, String direction) {
         String key = "trafficlight." + intersectionId + "." + direction + ".red";
         return Double.parseDouble(properties.getProperty(key, "30.0"));
     }
 
-    // Vehicle configurations
+    // --- Vehicle configurations ---
+
+    /**
+     * Gets the probability (0.0 to 1.0) that a generated vehicle is of type LIGHT.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+     * @return The crossing time in seconds.
+     */
     public double getHeavyVehicleCrossingTime() {
         return Double.parseDouble(properties.getProperty("vehicle.crossing.time.heavy", "4.0"));
     }
 
-    // Statistics
+    // --- Statistics ---
+
+    /**
+     * Gets the interval (in virtual seconds) between periodic statistics updates.
+     * @return The statistics update interval.
+     */
     public double getStatisticsUpdateInterval() {
         return Double.parseDouble(properties.getProperty("statistics.update.interval", "10.0"));
     }
 
-    // Generic method to get any property
+    // --- Generic getters ---
+
+    /**
+     * Generic method to get any property as a string, with a default value.
+     * @param key The property key.
+     * @param defaultValue The value to return if the key is not found.
+     * @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.
+     * @param key The property key.
+     * @return The property value, or null if not found.
+     */
     public String getProperty(String key) {
         return properties.getProperty(key);
     }

main/src/main/java/sd/engine/SimulationEngine.java

@@ -0,0 +1,628 @@
+package sd.engine;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.PriorityQueue;
+
+import sd.config.SimulationConfig;
+import sd.model.Event;
+import sd.model.EventType;
+import sd.model.Intersection;
+import sd.model.TrafficLight;
+import sd.model.TrafficLightState;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+import sd.util.StatisticsCollector;
+import sd.util.VehicleGenerator;
+
+/**
+ * Core simulation engine using discrete event simulation (DES).
+ * * This class orchestrates the entire simulation. It maintains a
+ * {@link PriorityQueue} of {@link Event} objects, representing all
+ * scheduled future actions. The engine processes events in strict
+ * chronological order (based on their timestamp).
+ * * It manages the simulation's state, including:
+ * - The current simulation time ({@code currentTime}).
+ * - The collection of all {@link Intersection} objects.
+ * - The {@link VehicleGenerator} for creating new vehicles.
+ * - The {@link StatisticsCollector} for tracking metrics.
+ */
+public class SimulationEngine {
+    
+    /**
+     * Holds all simulation parameters loaded from the properties file.
+     */
+    private final SimulationConfig config;
+    
+    /**
+     * The core of the discrete event simulation. Events are pulled from this
+     * queue in order of their timestamp.
+     */
+    private final PriorityQueue<Event> eventQueue;
+    
+    /**
+     * A map storing all intersections in the simulation, keyed by their ID (e.g., "Cr1").
+     */
+    private final Map<String, Intersection> intersections;
+    
+    /**
+     * Responsible for creating new vehicles according to the configured arrival model.
+     */
+    private final VehicleGenerator vehicleGenerator;
+    
+    /**
+     * Collects and calculates statistics throughout the simulation.
+     */
+    private final StatisticsCollector statisticsCollector;
+    
+    /**
+     * The current time in the simulation (in virtual seconds).
+     * This time advances based on the timestamp of the event being processed.
+     */
+    private double currentTime;
+    
+    /**
+     * A simple counter to generate unique IDs for vehicles.
+     */
+    private int vehicleCounter;
+    
+    /**
+     * Constructs a new SimulationEngine.
+     *
+     * @param config The {@link SimulationConfig} object containing all
+     * simulation parameters.
+     */
+    public SimulationEngine(SimulationConfig config) {
+        this.config = config;
+        this.eventQueue = new PriorityQueue<>();
+        this.intersections = new HashMap<>();
+        this.vehicleGenerator = new VehicleGenerator(config);
+        this.statisticsCollector = new StatisticsCollector(config);
+        this.currentTime = 0.0;
+        this.vehicleCounter = 0;
+    }
+    
+    /**
+     * Initializes the simulation. This involves:
+     * 1. Creating all {@link Intersection} and {@link TrafficLight} objects.
+     * 2. Configuring the routing logic between intersections.
+     * 3. Scheduling the initial events (first traffic light changes,
+     * first vehicle generation, and periodic statistics updates).
+     */
+    public void initialize() {
+        System.out.println("Initializing simulation...");
+        
+        setupIntersections();
+        setupRouting();
+        
+        // Schedule initial events to "bootstrap" the simulation
+        scheduleTrafficLightEvents();
+        scheduleNextVehicleGeneration(0.0);
+        scheduleStatisticsUpdates();
+        
+        System.out.println("Simulation initialized with " + intersections.size() + " intersections");
+    }
+    
+    /**
+     * Creates all intersections defined in the configuration
+     * and adds their corresponding traffic lights.
+     */
+    private void setupIntersections() {
+        String[] intersectionIds = {"Cr1", "Cr2", "Cr3", "Cr4", "Cr5"};
+        // Note: "North" is commented out, so it won't be created.
+        String[] directions = {/*"North",*/ "South", "East", "West"};
+        
+        for (String id : intersectionIds) {
+            Intersection intersection = new Intersection(id);
+            
+            // Add traffic lights for each configured direction
+            for (String direction : directions) {
+                double greenTime = config.getTrafficLightGreenTime(id, direction);
+                double redTime = config.getTrafficLightRedTime(id, direction);
+                
+                TrafficLight light = new TrafficLight(
+                    id + "-" + direction,
+                    direction,
+                    greenTime,
+                    redTime
+                );
+                
+                intersection.addTrafficLight(light);
+            }
+            
+            intersections.put(id, intersection);
+        }
+    }
+    
+    /**
+     * Configures how vehicles should be routed between intersections.
+     * This hardcoded logic defines the "map" of the city.
+     * * For example, `intersections.get("Cr1").configureRoute("Cr2", "East");` means
+     * "at intersection Cr1, any vehicle whose *next* destination is Cr2
+     * should be sent to the 'East' traffic light queue."
+     */
+    private void setupRouting() {
+        // Cr1 routing
+        intersections.get("Cr1").configureRoute("Cr2", "East");
+        intersections.get("Cr1").configureRoute("Cr4", "South");
+        
+        // Cr2 routing
+        intersections.get("Cr2").configureRoute("Cr1", "West");
+        intersections.get("Cr2").configureRoute("Cr3", "East");
+        intersections.get("Cr2").configureRoute("Cr5", "South");
+        
+        // Cr3 routing
+        intersections.get("Cr3").configureRoute("Cr2", "West");
+        intersections.get("Cr3").configureRoute("S", "South"); // "S" is the exit
+        
+        // Cr4 routing
+        //intersections.get("Cr4").configureRoute("Cr1", "North");
+        intersections.get("Cr4").configureRoute("Cr5", "East");
+        
+        // Cr5 routing
+        //intersections.get("Cr5").configureRoute("Cr2", "North");
+        //intersections.get("Cr5").configureRoute("Cr4", "West");
+        intersections.get("Cr5").configureRoute("S", "East"); // "S" is the exit
+    }
+    
+    /**
+     * Schedules the initial {@link EventType#TRAFFIC_LIGHT_CHANGE} event
+     * for every traffic light in the simulation.
+     * A small random delay is added to "stagger" the lights, preventing
+     * all of them from changing at the exact same time at t=0.
+     */
+    private void scheduleTrafficLightEvents() {
+        for (Intersection intersection : intersections.values()) {
+            for (TrafficLight light : intersection.getTrafficLights()) {
+                // Start with lights in RED state, schedule first GREEN change
+                // Stagger the start times slightly to avoid all lights changing at once
+                double staggerDelay = Math.random() * 1.5;
+                scheduleTrafficLightChange(light, intersection.getId(), staggerDelay);
+            }
+        }
+    }
+    
+    /**
+     * Creates and schedules a new {@link EventType#TRAFFIC_LIGHT_CHANGE} event.
+     * The event is scheduled to occur at {@code currentTime + delay}.
+     *
+     * @param light The {@link TrafficLight} that will change state.
+     * @param intersectionId The ID of the intersection where the light is located.
+     * @param delay The time (in seconds) from {@code currentTime} when the change should occur.
+     */
+    private void scheduleTrafficLightChange(TrafficLight light, String intersectionId, double delay) {
+        double changeTime = currentTime + delay;
+        Event event = new Event(changeTime, EventType.TRAFFIC_LIGHT_CHANGE, light, intersectionId);
+        eventQueue.offer(event);
+    }
+    
+    /**
+     * Schedules the next {@link EventType#VEHICLE_GENERATION} event.
+     * The time of the next arrival is determined by the {@link VehicleGenerator}.
+     *
+     * @param baseTime The time from which to calculate the next arrival (usually {@code currentTime}).
+     */
+    private void scheduleNextVehicleGeneration(double baseTime) {
+        // Get the absolute time for the next arrival.
+        double nextArrivalTime = vehicleGenerator.getNextArrivalTime(baseTime);
+        
+        // Only schedule the event if it's within the simulation's total duration.
+        if (nextArrivalTime < config.getSimulationDuration()) {
+            Event event = new Event(nextArrivalTime, EventType.VEHICLE_GENERATION, null, null);
+            eventQueue.offer(event);
+        }
+    }
+    
+    /**
+     * Schedules all periodic {@link EventType#STATISTICS_UPDATE} events
+     * for the entire duration of the simulation.
+     */
+    private void scheduleStatisticsUpdates() {
+        double interval = config.getStatisticsUpdateInterval();
+        double duration = config.getSimulationDuration();
+        
+        for (double time = interval; time < duration; time += interval) {
+            Event event = new Event(time, EventType.STATISTICS_UPDATE, null, null);
+            eventQueue.offer(event);
+        }
+    }
+    
+    /**
+     * Runs the main simulation loop.
+     * The loop continues as long as there are events in the queue and
+     * the {@code currentTime} is less than the total simulation duration.
+     * * In each iteration, it:
+     * 1. Polls the next event from the {@link #eventQueue}.
+     * 2. Advances {@link #currentTime} to the event's timestamp.
+     * 3. Calls {@link #processEvent(Event)} to handle the event.
+     * * After the loop, it prints the final statistics.
+     */
+    public void run() {
+        System.out.println("Starting simulation...");
+        double duration = config.getSimulationDuration();
+        
+        while (!eventQueue.isEmpty() && currentTime < duration) {
+            // Get the next event in chronological order
+            Event event = eventQueue.poll();
+            
+            // Advance simulation time to this event's time
+            currentTime = event.getTimestamp();
+            
+            // Process the event
+            processEvent(event);
+        }
+        
+        System.out.println("\nSimulation completed at t=" + String.format("%.2f", currentTime) + "s");
+        printFinalStatistics();
+    }
+    
+    /**
+     * Main event processing logic.
+     * Delegates the event to the appropriate handler method based on its {@link EventType}.
+     *
+     * @param event The {@link Event} to be processed.
+     */
+    private void processEvent(Event event) {
+        switch (event.getType()) {
+            case VEHICLE_GENERATION -> handleVehicleGeneration();
+                
+            case VEHICLE_ARRIVAL -> handleVehicleArrival(event);
+                
+            case TRAFFIC_LIGHT_CHANGE -> handleTrafficLightChange(event);
+                
+            case CROSSING_START -> handleCrossingStart(event);
+                
+            case CROSSING_END -> handleCrossingEnd(event);
+                
+            case STATISTICS_UPDATE -> handleStatisticsUpdate();
+                
+            default -> System.err.println("Unknown event type: " + event.getType());
+        }
+    }
+    
+    /**
+     * Handles {@link EventType#VEHICLE_GENERATION}.
+     * 1. Creates a new {@link Vehicle} using the {@link #vehicleGenerator}.
+     * 2. Records the generation event with the {@link #statisticsCollector}.
+     * 3. Schedules a {@link EventType#VEHICLE_ARRIVAL} event for the vehicle
+     * at its first destination intersection.
+     * 4. Schedules the *next* {@link EventType#VEHICLE_GENERATION} event.
+     * (Note: This line is commented out in the original, which might be a bug,
+     * as it implies only one vehicle is ever generated. It should likely be active.)
+     */
+    private void handleVehicleGeneration() {
+        Vehicle vehicle = vehicleGenerator.generateVehicle("V" + (++vehicleCounter), currentTime);
+        
+        System.out.printf("[t=%.2f] Vehicle %s generated (type=%s, route=%s)%n",
+            currentTime, vehicle.getId(), vehicle.getType(), vehicle.getRoute());
+        
+        // Register with statistics collector
+        statisticsCollector.recordVehicleGeneration(vehicle, currentTime);
+        
+        // Schedule arrival at first intersection
+        String firstIntersection = vehicle.getCurrentDestination();
+        if (firstIntersection != null && !firstIntersection.equals("S")) {
+            // Assume minimal travel time to first intersection (e.g., 1-3 seconds)
+            double arrivalTime = currentTime + 1.0 + Math.random() * 2.0;
+            Event arrivalEvent = new Event(arrivalTime, EventType.VEHICLE_ARRIVAL, vehicle, firstIntersection);
+            eventQueue.offer(arrivalEvent);
+        }
+        
+        // Schedule next vehicle generation
+        // This was commented out in the original file.
+        // For a continuous simulation, it should be enabled:
+        scheduleNextVehicleGeneration(currentTime);
+    }
+    
+    /**
+     * Handles {@link EventType#VEHICLE_ARRIVAL} at an intersection.
+     * 1. Records the arrival for statistics.
+     * 2. Advances the vehicle's internal route planner to its *next* destination.
+     * 3. If the next destination is the exit ("S") or null,
+     * the vehicle exits the system via {@link #handleVehicleExit(Vehicle)}.
+     * 4. Otherwise, the vehicle is placed in the correct queue at the
+     * current intersection using {@link Intersection#receiveVehicle(Vehicle)}.
+     * 5. Attempts to process the vehicle immediately if its light is green.
+     *
+     * @param event The arrival event, containing the {@link Vehicle} and intersection ID.
+     */
+    private void handleVehicleArrival(Event event) {
+        Vehicle vehicle = (Vehicle) event.getData();
+        String intersectionId = event.getLocation();
+        
+        Intersection intersection = intersections.get(intersectionId);
+        if (intersection == null) {
+            System.err.println("Unknown intersection: " + intersectionId);
+            return;
+        }
+        
+        System.out.printf("[t=%.2f] Vehicle %s arrived at %s%n",
+            currentTime, vehicle.getId(), intersectionId);
+        
+        // Record arrival time (used to calculate waiting time later)
+        statisticsCollector.recordVehicleArrival(vehicle, intersectionId, currentTime);
+        
+        // Advance the vehicle's route to the *next* stop
+        // (it has now arrived at its *current* destination)
+        boolean hasNext = vehicle.advanceRoute();
+        
+        if (!hasNext) {
+            // This was the last stop
+            handleVehicleExit(vehicle);
+            return;
+        }
+        
+        String nextDestination = vehicle.getCurrentDestination();
+        if (nextDestination == null || "S".equals(nextDestination)) {
+            // Next stop is the exit
+            handleVehicleExit(vehicle);
+            return;
+        }
+        
+        // Add vehicle to the appropriate traffic light queue based on its next destination
+        intersection.receiveVehicle(vehicle);
+        
+        // Try to process the vehicle immediately if its light is already green
+        tryProcessVehicle(vehicle, intersection);
+    }
+    
+    /**
+     * Checks if a newly arrived vehicle (or a vehicle in a queue
+     * that just turned green) can start crossing.
+     *
+     * @param vehicle The vehicle to process.
+     * @param intersection The intersection where the vehicle is.
+     */
+    private void tryProcessVehicle(Vehicle vehicle, Intersection intersection) { //FIXME
+        // Find the direction (and light) this vehicle is queued at
+        // This logic is a bit flawed: it just finds the *first* non-empty queue
+        // A better approach would be to get the light from the vehicle's route
+        String direction = intersection.getTrafficLights().stream()
+            .filter(tl -> tl.getQueueSize() > 0)
+            .map(TrafficLight::getDirection)
+            .findFirst()
+            .orElse(null);
+        
+        if (direction != null) {
+            TrafficLight light = intersection.getTrafficLight(direction);
+            // If the light is green and it's the correct one...
+            if (light != null && light.getState() == TrafficLightState.GREEN) {
+                // ...remove the vehicle from the queue (if it's at the front)
+                Vehicle v = light.removeVehicle();
+                if (v != null) {
+                    // ...and schedule its crossing.
+                    scheduleCrossing(v, intersection);
+                }
+            }
+        }
+    }
+    
+    /**
+     * Schedules the crossing for a vehicle that has just been dequeued
+     * from a green light.
+     * 1. Calculates and records the vehicle's waiting time.
+     * 2. Schedules an immediate {@link EventType#CROSSING_START} event.
+     *
+     * @param vehicle The {@link Vehicle} that is crossing.
+     * @param intersection The {@link Intersection} it is crossing.
+     */
+    private void scheduleCrossing(Vehicle vehicle, Intersection intersection) {
+        // Calculate time spent waiting at the red light
+        double waitTime = currentTime - statisticsCollector.getArrivalTime(vehicle);
+        vehicle.addWaitingTime(waitTime);
+        
+        // Schedule crossing start event *now*
+        Event crossingStart = new Event(currentTime, EventType.CROSSING_START, vehicle, intersection.getId());
+        processEvent(crossingStart); // Process immediately
+    }
+    
+    /**
+     * Handles {@link EventType#CROSSING_START}.
+     * 1. Determines the crossing time based on vehicle type.
+     * 2. Schedules a {@link EventType#CROSSING_END} event to occur
+     * at {@code currentTime + crossingTime}.
+     *
+     * @param event The crossing start event.
+     */
+    private void handleCrossingStart(Event event) {
+        Vehicle vehicle = (Vehicle) event.getData();
+        String intersectionId = event.getLocation();
+        
+        double crossingTime = getCrossingTime(vehicle.getType());
+        
+        System.out.printf("[t=%.2f] Vehicle %s started crossing at %s (duration=%.2fs)%n",
+            currentTime, vehicle.getId(), intersectionId, crossingTime);
+        
+        // Schedule the *end* of the crossing
+        double endTime = currentTime + crossingTime;
+        Event crossingEnd = new Event(endTime, EventType.CROSSING_END, vehicle, intersectionId);
+        eventQueue.offer(crossingEnd);
+    }
+    
+    /**
+     * Handles {@link EventType#CROSSING_END}.
+     * 1. Updates intersection and vehicle statistics.
+     * 2. Checks the vehicle's *next* destination.
+     * 3. If the next destination is the exit ("S"), call {@link #handleVehicleExit(Vehicle)}.
+     * 4. Otherwise, schedule a {@link EventType#VEHICLE_ARRIVAL} event at the
+     * *next* intersection, after some travel time.
+     *
+     * @param event The crossing end event.
+     */
+    private void handleCrossingEnd(Event event) {
+        Vehicle vehicle = (Vehicle) event.getData();
+        String intersectionId = event.getLocation();
+        
+        // Update stats
+        Intersection intersection = intersections.get(intersectionId);
+        if (intersection != null) {
+            intersection.incrementVehiclesSent();
+        }
+        
+        double crossingTime = getCrossingTime(vehicle.getType());
+        vehicle.addCrossingTime(crossingTime);
+        
+        System.out.printf("[t=%.2f] Vehicle %s finished crossing at %s%n",
+            currentTime, vehicle.getId(), intersectionId);
+        
+        // Decide what to do next
+        String nextDest = vehicle.getCurrentDestination();
+        if (nextDest != null && !nextDest.equals("S")) {
+            // Route to the *next* intersection
+            // Assume 5-10 seconds travel time between intersections
+            double travelTime = 5.0 + Math.random() * 5.0; 
+            double arrivalTime = currentTime + travelTime;
+            Event arrivalEvent = new Event(arrivalTime, EventType.VEHICLE_ARRIVAL, vehicle, nextDest);
+            eventQueue.offer(arrivalEvent);
+        } else {
+            // Reached the exit
+            handleVehicleExit(vehicle);
+        }
+    }
+    
+    /**
+     * Handles a vehicle exiting the simulation.
+     * Records final statistics for the vehicle.
+     *
+     * @param vehicle The {@link Vehicle} that has completed its route.
+     */
+    private void handleVehicleExit(Vehicle vehicle) {
+        System.out.printf("[t=%.2f] Vehicle %s exited the system (wait=%.2fs, travel=%.2fs)%n",
+            currentTime, vehicle.getId(), 
+            vehicle.getTotalWaitingTime(), 
+            vehicle.getTotalTravelTime(currentTime));
+        
+        // Record the exit for final statistics calculation
+        statisticsCollector.recordVehicleExit(vehicle, currentTime);
+    }
+    
+    /**
+     * Handles {@link EventType#TRAFFIC_LIGHT_CHANGE}.
+     * 1. Toggles the light's state (RED to GREEN or GREEN to RED).
+     * 2. If the light just turned GREEN, call {@link #processGreenLight(TrafficLight, Intersection)}
+     * to process any waiting vehicles.
+     * 3. Schedules the *next* state change for this light based on its
+     * green/red time duration.
+     *
+     * @param event The light change event.
+     */
+    private void handleTrafficLightChange(Event event) {
+        TrafficLight light = (TrafficLight) event.getData();
+        String intersectionId = event.getLocation();
+        
+        // Toggle state
+        TrafficLightState newState = (light.getState() == TrafficLightState.RED) 
+            ? TrafficLightState.GREEN 
+            : TrafficLightState.RED;
+        
+        light.changeState(newState);
+        
+        System.out.printf("[t=%.2f] Traffic light %s changed to %s%n",
+            currentTime, light.getId(), newState);
+        
+        // If changed to GREEN, process waiting vehicles
+        if (newState == TrafficLightState.GREEN) {
+            Intersection intersection = intersections.get(intersectionId);
+            if (intersection != null) {
+                processGreenLight(light, intersection);
+            }
+        }
+        
+        // Schedule the *next* state change for this same light
+        double nextChangeDelay = (newState == TrafficLightState.GREEN) 
+            ? light.getGreenTime() 
+            : light.getRedTime();
+        
+        scheduleTrafficLightChange(light, intersectionId, nextChangeDelay);
+    }
+    
+    /**
+     * Processes vehicles when a light turns green.
+     * It loops as long as the light is green and there are vehicles in the queue,
+     * dequeuing one vehicle at a time and scheduling its crossing.
+     * * *Note*: This is a simplified model. A real simulation would
+     * account for the *time* it takes each vehicle to cross, processing
+     * one vehicle every {@code crossingTime} seconds. This implementation
+     * processes the entire queue "instantaneously" at the moment
+     * the light turns green.
+     *
+     * @param light The {@link TrafficLight} that just turned green.
+     * @param intersection The {@link Intersection} where the light is.
+     */
+    private void processGreenLight(TrafficLight light, Intersection intersection) {
+        // While the light is green and vehicles are waiting...
+        while (light.getState() == TrafficLightState.GREEN && light.getQueueSize() > 0) {
+            Vehicle vehicle = light.removeVehicle();
+            if (vehicle != null) {
+                // Dequeue one vehicle and schedule its crossing
+                scheduleCrossing(vehicle, intersection);
+            }
+        }
+    }
+    
+    /**
+     * Handles {@link EventType#STATISTICS_UPDATE}.
+     * Calls the {@link StatisticsCollector} to print the current
+     * state of the simulation (queue sizes, averages, etc.).
+     */
+    private void handleStatisticsUpdate() {
+        System.out.printf("\n=== Statistics at t=%.2f ===%n", currentTime);
+        statisticsCollector.printCurrentStatistics(intersections, currentTime);
+        System.out.println();
+    }
+    
+    /**
+     * Utility method to get the configured crossing time for a given {@link VehicleType}.
+     *
+     * @param type The type of vehicle.
+     * @return The crossing time in seconds.
+     */
+    private double getCrossingTime(VehicleType type) {
+        return switch (type) {
+            case BIKE -> config.getBikeVehicleCrossingTime();
+            case LIGHT -> config.getLightVehicleCrossingTime();
+            case HEAVY -> config.getHeavyVehicleCrossingTime();
+            default -> 2.0;
+        }; // Default fallback
+    }
+    
+    /**
+     * Prints the final summary of statistics at the end of the simulation.
+     */
+    private void printFinalStatistics() {
+        System.out.println("\n" + "=".repeat(60));
+        System.out.println("FINAL SIMULATION STATISTICS");
+        System.out.println("=".repeat(60));
+        
+        statisticsCollector.printFinalStatistics(intersections, currentTime);
+        
+        System.out.println("=".repeat(60));
+    }
+    
+    // --- Public Getters ---
+
+    /**
+     * Gets the current simulation time.
+     * @return The time in virtual seconds.
+     */
+    public double getCurrentTime() {
+        return currentTime;
+    }
+    
+    /**
+     * Gets a map of all intersections in the simulation.
+     * Returns a copy to prevent external modification.
+     * @return A {@link Map} of intersection IDs to {@link Intersection} objects.
+     */
+    public Map<String, Intersection> getIntersections() {
+        return new HashMap<>(intersections);
+    }
+    
+    /**
+     * Gets the statistics collector instance.
+     * @return The {@link StatisticsCollector}.
+     */
+    public StatisticsCollector getStatisticsCollector() {
+        return statisticsCollector;
+    }
+}

main/src/main/java/sd/model/Event.java

@@ -3,17 +3,52 @@ package sd.model;
 import java.io.Serializable;
 
 /**
- * Represents an event in the discrete event simulation.
- * Events are ordered by timestamp for sequential processing.
+ * Represents a single event in the discrete event simulation.
+ * * An Event is the fundamental unit of action in the simulation. It contains:
+ * - A {@code timestamp} (when the event should occur).
+ * - A {@link EventType} (what kind of event it is).
+ * - Associated {@code data} (e.g., the {@link Vehicle} or {@link TrafficLight} involved).
+ * - An optional {@code location} (e.g., the ID of the {@link Intersection}).
+ * * Events are {@link Comparable}, allowing them to be sorted in a
+ * {@link java.util.PriorityQueue}. The primary sorting key is the
+ * {@code timestamp}. If timestamps are equal, {@code EventType} is used
+ * as a tie-breaker to ensure a consistent, deterministic order.
+ * * Implements {@link Serializable} so events could (in theory) be sent
+ * across a network in a distributed simulation.
  */
 public class Event implements Comparable<Event>, Serializable {
     private static final long serialVersionUID = 1L;
     
-    private final double timestamp;  // Time when the event occurs
-    private final EventType type;
-    private final Object data;  // Data associated with the event (e.g., Vehicle, traffic light id, etc.)
-    private final String location;  // Intersection or location where the event occurs
+    /**
+     * The simulation time (in seconds) when this event is scheduled to occur.
+     */
+    private final double timestamp;
     
+    /**
+     * The type of event (e.g., VEHICLE_ARRIVAL, TRAFFIC_LIGHT_CHANGE).
+     */
+    private final EventType type;
+    
+    /**
+     * The data payload associated with this event.
+     * This could be a {@link Vehicle}, {@link TrafficLight}, or null.
+     */
+    private final Object data;
+    
+    /**
+     * The ID of the location where the event occurs (e.g., "Cr1").
+     * Can be null if the event is not location-specific (like VEHICLE_GENERATION).
+     */
+    private final String location;
+    
+    /**
+     * Constructs a new Event.
+     *
+     * @param timestamp The simulation time when the event occurs.
+     * @param type The {@link EventType} of the event.
+     * @param data The associated data (e.g., a Vehicle object).
+     * @param location The ID of the location (e.g., an Intersection ID).
+     */
     public Event(double timestamp, EventType type, Object data, String location) {
         this.timestamp = timestamp;
         this.type = type;
@@ -21,38 +56,73 @@ public class Event implements Comparable<Event>, Serializable {
         this.location = location;
     }
     
+    /**
+     * Convenience constructor for an Event without a specific location.
+     *
+     * @param timestamp The simulation time when the event occurs.
+     * @param type The {@link EventType} of the event.
+     * @param data The associated data (e.g., a Vehicle object).
+     */
     public Event(double timestamp, EventType type, Object data) {
         this(timestamp, type, data, null);
     }
     
+    /**
+     * Compares this event to another event for ordering.
+     * * Events are ordered primarily by {@link #timestamp} (ascending).
+     * If timestamps are identical, they are ordered by {@link #type} (alphabetical)
+     * to provide a stable, deterministic tie-breaking mechanism.
+     *
+     * @param other The other Event to compare against.
+     * @return A negative integer if this event comes before {@code other},
+     * zero if they are "equal" in sorting (though this is rare),
+     * or a positive integer if this event comes after {@code other}.
+     */
     @Override
     public int compareTo(Event other) {
-        // Sort by timestamp (earlier events have priority)
+        // Primary sort: timestamp (earlier events come first)
         int cmp = Double.compare(this.timestamp, other.timestamp);
         if (cmp == 0) {
-            // If timestamps are equal, sort by event type
+            // Tie-breaker: event type (ensures deterministic order)
             return this.type.compareTo(other.type);
         }
         return cmp;
     }
     
-    // Getters
+    // --- Getters ---
+    
+    /**
+     * @return The simulation time when the event occurs.
+     */
     public double getTimestamp() {
         return timestamp;
     }
     
+    /**
+     * @return The {@link EventType} of the event.
+     */
     public EventType getType() {
         return type;
     }
     
+    /**
+     * @return The data payload (e.g., {@link Vehicle}, {@link TrafficLight}).
+     * The caller must cast this to the expected type.
+     */
     public Object getData() {
         return data;
     }
     
+    /**
+     * @return The location ID (e.g., "Cr1"), or null if not applicable.
+     */
     public String getLocation() {
         return location;
     }
     
+    /**
+     * @return A string representation of the event for logging.
+     */
     @Override
     public String toString() {
         return String.format("Event{t=%.2f, type=%s, loc=%s}", 

main/src/main/java/sd/model/EventType.java

@@ -1,13 +1,45 @@
 package sd.model;
 
 /**
- * Enumeration representing event types in the simulation.
+ * Enumeration representing all possible event types in the discrete event simulation.
+ * These types are used by the {@link sd.engine.SimulationEngine} to determine
+ * how to process a given {@link Event}.
  */
 public enum EventType {
-    VEHICLE_ARRIVAL,           // Vehicle arrives at an intersection
-    TRAFFIC_LIGHT_CHANGE,      // Traffic light changes state (green/red)
-    CROSSING_START,            // Vehicle starts crossing the intersection
-    CROSSING_END,              // Vehicle finishes crossing
-    VEHICLE_GENERATION,        // New vehicle is generated in the system
-    STATISTICS_UPDATE          // Time to send statistics to dashboard
+    
+    /**
+     * Fired when a {@link Vehicle} arrives at an {@link Intersection}.
+     * Data: {@link Vehicle}, Location: Intersection ID
+     */
+    VEHICLE_ARRIVAL,
+    
+    /**
+     * Fired when a {@link TrafficLight} is scheduled to change its state.
+     * Data: {@link TrafficLight}, Location: Intersection ID
+     */
+    TRAFFIC_LIGHT_CHANGE,
+    
+    /**
+     * Fired when a {@link Vehicle} begins to cross an {@link Intersection}.
+     * Data: {@link Vehicle}, Location: Intersection ID
+     */
+    CROSSING_START,
+    
+    /**
+     * Fired when a {@link Vehicle} finishes crossing an {@link Intersection}.
+     * Data: {@link Vehicle}, Location: Intersection ID
+     */
+    CROSSING_END,
+    
+    /**
+     * Fired when a new {@link Vehicle} should be created and added to the system.
+     * Data: null, Location: null
+     */
+    VEHICLE_GENERATION,
+    
+    /**
+     * Fired periodically to trigger the printing or sending of simulation statistics.
+     * Data: null, Location: null
+     */
+    STATISTICS_UPDATE
 }

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

@@ -0,0 +1,255 @@
+package sd.model;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Represents an intersection in the traffic simulation.
+ * * An Intersection acts as a central hub. It does not control logic itself,
+ * but it *owns* and *manages* a set of {@link TrafficLight} objects.
+ * * Its primary responsibilities are:
+ * 1.  Holding a {@link TrafficLight} for each direction ("North", "East", etc.).
+ * 2.  Maintaining a {@code routing} table that maps a vehicle's *next*
+ * destination (e.g., "Cr3") to a specific *direction* at *this*
+ * intersection (e.g., "East").
+ * 3.  Receiving incoming vehicles and placing them in the correct
+ * traffic light's queue based on the routing table.
+ * 4.  Tracking aggregate statistics for all traffic passing through it.
+ */
+public class Intersection {
+
+    // --- Identity and configuration ---
+    
+    /**
+     * Unique identifier for the intersection (e.g., "Cr1", "Cr2").
+     */
+    private final String id;
+    
+    /**
+     * A map holding all traffic lights managed by this intersection.
+     * Key: Direction (String, e.g., "North", "East").
+     * Value: The {@link TrafficLight} object for that direction.
+     */
+    private final Map<String, TrafficLight> trafficLights;
+    
+    /**
+     * The routing table for this intersection.
+     * Key: The *next* destination ID (String, e.g., "Cr3", "S" for exit).
+     * Value: The *direction* (String, e.g., "East") a vehicle must take
+     * at *this* intersection to reach that destination.
+     */
+    private final Map<String, String> routing;
+
+    // --- Statistics ---
+    
+    /**
+     * Total number of vehicles that have been received by this intersection.
+     */
+    private int totalVehiclesReceived;
+    
+    /**
+     * Total number of vehicles that have successfully passed through (sent from) this intersection.
+     */
+    private int totalVehiclesSent;
+    
+    /**
+     * A running average of the waiting time for vehicles at this intersection.
+     * Note: This calculation might be simplified.
+     */
+    private double averageWaitingTime;
+
+    /**
+     * Constructs a new Intersection with a given ID.
+     * Initializes empty maps for traffic lights and routing.
+     *
+     * @param id The unique identifier for this intersection (e.g., "Cr1").
+     */
+    public Intersection(String id) {
+        this.id = id;
+        this.trafficLights = new HashMap<>();
+        this.routing = new HashMap<>();
+        this.totalVehiclesReceived = 0;
+        this.totalVehiclesSent = 0;
+        this.averageWaitingTime = 0.0;
+    }
+
+    /**
+     * Registers a new {@link TrafficLight} with this intersection.
+     * The light is mapped by its direction.
+     *
+     * @param trafficLight The {@link TrafficLight} object to add.
+     */
+    public void addTrafficLight(TrafficLight trafficLight) {
+        trafficLights.put(trafficLight.getDirection(), trafficLight);
+    }
+
+    /**
+     * Defines a routing rule for this intersection.
+     * * This method builds the routing table. For example, calling
+     * {@code configureRoute("Cr3", "East")} means "Any vehicle
+     * arriving here whose next destination is 'Cr3' should be sent to
+     * the 'East' traffic light queue."
+     *
+     * @param nextDestination The ID of the *next* intersection or exit (e.g., "Cr3", "S").
+     * @param direction       The direction (and thus, the traffic light)
+     * at *this* intersection to use (e.g., "East").
+     */
+    public void configureRoute(String nextDestination, String direction) {
+        routing.put(nextDestination, direction);
+    }
+
+    /**
+     * Accepts an incoming vehicle and places it in the correct queue.
+     * * This method:
+     * 1. Increments the {@link #totalVehiclesReceived} counter.
+     * 2. Advances the vehicle's route (since it just arrived here)
+     * 3. Gets the vehicle's *next* destination (from {@link Vehicle#getCurrentDestination()}).
+     * 4. Uses the {@link #routing} map to find the correct *direction* for that destination.
+     * 5. Adds the vehicle to the queue of the {@link TrafficLight} for that direction.
+     *
+     * @param vehicle The {@link Vehicle} arriving at the intersection.
+     */
+    public void receiveVehicle(Vehicle vehicle) {
+        totalVehiclesReceived++;
+
+        // Advance route since vehicle just arrived at this intersection
+        vehicle.advanceRoute();
+        
+        String nextDestination = vehicle.getCurrentDestination();
+        
+        // Check if vehicle reached final destination
+        if (nextDestination == null) {
+            System.out.printf("[%s] Vehicle %s reached final destination%n", 
+                this.id, vehicle.getId());
+            return;
+        }
+        
+        String direction = routing.get(nextDestination);
+
+        if (direction != null && trafficLights.containsKey(direction)) {
+            // Found a valid route and light, add vehicle to the queue
+            trafficLights.get(direction).addVehicle(vehicle);
+        } else {
+            // Routing error: No rule for this destination or no light for that direction
+            System.err.printf(
+                "Routing error at %s: could not place vehicle %s (destination: %s, found direction: %s)%n",
+                this.id, vehicle.getId(), nextDestination, direction
+            );
+        }
+    }
+
+    /**
+     * Returns the traffic light controlling the given direction.
+     *
+     * @param direction The direction (e.g., "North").
+     * @return The {@link TrafficLight} object, or null if no light exists
+     * for that direction.
+     */
+    public TrafficLight getTrafficLight(String direction) {
+        return trafficLights.get(direction);
+    }
+
+    /**
+     * Returns a list of all traffic lights managed by this intersection.
+     *
+     * @return A new {@link List} containing all {@link TrafficLight} objects.
+     */
+    public List<TrafficLight> getTrafficLights() {
+        // Return a copy to prevent external modification of the internal map's values
+        return new ArrayList<>(trafficLights.values());
+    }
+
+    /**
+     * Returns the total number of vehicles currently queued across *all*
+     * traffic lights at this intersection.
+     *
+     * @return The sum of all queue sizes.
+     */
+    public int getTotalQueueSize() {
+        // Uses Java Stream API:
+        // 1. trafficLights.values().stream() - Get a stream of TrafficLight objects
+        // 2. .mapToInt(TrafficLight::getQueueSize) - Convert each light to its queue size (an int)
+        // 3. .sum() - Sum all the integers
+        return trafficLights.values().stream()
+                .mapToInt(TrafficLight::getQueueSize)
+                .sum();
+    }
+
+    // --- Stats and getters ---
+
+    /**
+     * @return The unique ID of this intersection.
+     */
+    public String getId() {
+        return id;
+    }
+
+    /**
+     * @return The total number of vehicles that have arrived at this intersection.
+     */
+    public int getTotalVehiclesReceived() {
+        return totalVehiclesReceived;
+    }
+
+    /**
+     * @return The total number of vehicles that have successfully
+     * departed from this intersection.
+     */
+    public int getTotalVehiclesSent() {
+        return totalVehiclesSent;
+    }
+
+    /**
+     * Increments the counter for vehicles that have successfully departed.
+     * This is typically called by the {@link sd.engine.SimulationEngine}
+     * after a vehicle finishes crossing.
+     */
+    public void incrementVehiclesSent() {
+        totalVehiclesSent++;
+    }
+
+    /**
+     * @return The running average of vehicle waiting time at this intersection.
+     */
+    public double getAverageWaitingTime() {
+        return averageWaitingTime;
+    }
+
+    /**
+     * Updates the running average waiting time with a new sample (a new
+     * vehicle's wait time).
+     * * Uses an incremental/weighted average formula:
+     * NewAvg = (OldAvg * (N-1) + NewValue) / N
+     * where N is the total number of vehicles sent.
+     *
+     * @param newTime The waiting time (in seconds) of the vehicle that just
+     * departed.
+     */
+    public void updateAverageWaitingTime(double newTime) {
+        // Avoid division by zero if this is called before any vehicle is sent
+        if (totalVehiclesSent > 0) {
+            averageWaitingTime = (averageWaitingTime * (totalVehiclesSent - 1) + newTime)
+                               / totalVehiclesSent;
+        } else if (totalVehiclesSent == 1) {
+             // This is the first vehicle
+            averageWaitingTime = newTime;
+        }
+    }
+
+    /**
+     * @return A string summary of the intersection's current state.
+     */
+    @Override
+    public String toString() {
+        return String.format(
+            "Intersection{id='%s', lights=%d, queues=%d, received=%d, sent=%d}",
+            id,
+            trafficLights.size(),
+            getTotalQueueSize(),
+            totalVehiclesReceived,
+            totalVehiclesSent
+        );
+    }
+}

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

@@ -0,0 +1,142 @@
+package sd.model;
+
+import java.io.Serializable;
+import java.util.UUID;
+
+/**
+ * Represents a message exchanged between processes in the distributed simulation.
+ * Each message has a unique ID, a type, a sender, a destination, and a payload.
+ * This class implements {@link Serializable} to allow transmission over the network.
+ */
+public class Message implements Serializable {
+    
+    private static final long serialVersionUID = 1L;
+    
+    /**
+     * Unique identifier for this message.
+     */
+    private final String messageId;
+    
+    /**
+     * The type of this message (e.g., VEHICLE_TRANSFER, STATS_UPDATE).
+     */
+    private final MessageType type;
+    
+    /**
+     * Identifier of the process that sent this message.
+     */
+    private final String senderId;
+    
+    /**
+     * Identifier of the destination process. Can be null for broadcast messages.
+     */
+    private final String destinationId;
+    
+    /**
+     * The actual data being transmitted. Type depends on the message type.
+     */
+    private final Object payload;
+    
+    /**
+     * Timestamp when this message was created (simulation time or real time).
+     */
+    private final long timestamp;
+    
+    /**
+     * Creates a new message with all parameters.
+     *
+     * @param type The message type
+     * @param senderId The ID of the sending process
+     * @param destinationId The ID of the destination process (null for broadcast)
+     * @param payload The message payload
+     * @param timestamp The timestamp of message creation
+     */
+    public Message(MessageType type, String senderId, String destinationId, 
+                   Object payload, long timestamp) {
+        this.messageId = UUID.randomUUID().toString();
+        this.type = type;
+        this.senderId = senderId;
+        this.destinationId = destinationId;
+        this.payload = payload;
+        this.timestamp = timestamp;
+    }
+    
+    /**
+     * Creates a new message with current system time as timestamp.
+     *
+     * @param type The message type
+     * @param senderId The ID of the sending process
+     * @param destinationId The ID of the destination process
+     * @param payload The message payload
+     */
+    public Message(MessageType type, String senderId, String destinationId, Object payload) {
+        this(type, senderId, destinationId, payload, System.currentTimeMillis());
+    }
+    
+    /**
+     * Creates a broadcast message (no specific destination).
+     *
+     * @param type The message type
+     * @param senderId The ID of the sending process
+     * @param payload The message payload
+     */
+    public Message(MessageType type, String senderId, Object payload) {
+        this(type, senderId, null, payload, System.currentTimeMillis());
+    }
+    
+    //Getters
+    
+    public String getMessageId() {
+        return messageId;
+    }
+    
+    public MessageType getType() {
+        return type;
+    }
+    
+    public String getSenderId() {
+        return senderId;
+    }
+    
+    public String getDestinationId() {
+        return destinationId;
+    }
+    
+    public Object getPayload() {
+        return payload;
+    }
+    
+    public long getTimestamp() {
+        return timestamp;
+    }
+    
+    /**
+     * Checks if this is a broadcast message (no specific destination).
+     *
+     * @return true if destinationId is null, false otherwise
+     */
+    public boolean isBroadcast() {
+        return destinationId == null;
+    }
+    
+    /**
+     * Gets the payload cast to a specific type.
+     * Use with caution and ensure type safety.
+     *
+     * @param <T> The expected payload type
+     * @return The payload cast to type T
+     * @throws ClassCastException if the payload is not of type T
+     */
+    @SuppressWarnings("unchecked")
+    public <T> T getPayloadAs(Class<T> clazz) {
+        return (T) payload;
+    }
+    
+    @Override
+    public String toString() {
+        return String.format("Message[id=%s, type=%s, from=%s, to=%s, timestamp=%d]",
+                           messageId, type, senderId, 
+                           destinationId != null ? destinationId : "BROADCAST",
+                           timestamp);
+    }
+}

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

@@ -0,0 +1,81 @@
+package sd.model;
+
+/**
+ * Enumeration representing all possible message types for distributed communication.
+ * These types are used for inter-process communication between different components
+ * of the distributed traffic simulation system.
+ */
+public enum MessageType {
+    
+    /**
+     * Message to transfer a vehicle between intersections or processes.
+     * Payload: Vehicle object with current state
+     */
+    VEHICLE_TRANSFER,
+    
+    /**
+     * Message to update statistics across the distributed system.
+     * Payload: Statistics data (waiting times, queue sizes, etc.)
+     */
+    STATS_UPDATE,
+    
+    /**
+     * Message to synchronize traffic light states between processes.
+     * Payload: TrafficLight state and timing information
+     */
+    TRAFFIC_LIGHT_SYNC,
+    
+    /**
+     * Heartbeat message to check if a process is alive.
+     * Payload: Process ID and timestamp
+     */
+    HEARTBEAT,
+    
+    /**
+     * Request to join the distributed simulation.
+     * Payload: Process information and capabilities
+     */
+    JOIN_REQUEST,
+    
+    /**
+     * Response to a join request.
+     * Payload: Acceptance status and configuration
+     */
+    JOIN_RESPONSE,
+    
+    /**
+     * Message to notify about a new vehicle generation.
+     * Payload: Vehicle generation parameters
+     */
+    VEHICLE_SPAWN,
+    
+    /**
+     * Message to request the current state of an intersection.
+     * Payload: Intersection ID
+     */
+    STATE_REQUEST,
+    
+    /**
+     * Response containing the current state of an intersection.
+     * Payload: Complete intersection state
+     */
+    STATE_RESPONSE,
+    
+    /**
+     * Message to signal shutdown of a process.
+     * Payload: Process ID and reason
+     */
+    SHUTDOWN,
+    
+    /**
+     * Acknowledgment message for reliable communication.
+     * Payload: Message ID being acknowledged
+     */
+    ACK,
+    
+    /**
+     * Error message to report problems in the distributed system.
+     * Payload: Error description and context
+     */
+    ERROR
+}

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

@@ -0,0 +1,315 @@
+package sd.model;
+
+import java.util.LinkedList;
+import java.util.Queue;
+import java.util.concurrent.locks.Condition;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * Represents a single traffic light controlling one direction at an intersection.
+ * * Each light maintains its own queue of {@link Vehicle} objects and
+ * alternates between {@link TrafficLightState#GREEN} and
+ * {@link TrafficLightState#RED} states.
+ * * This class is designed to be thread-safe for a potential concurrent
+ * simulation (though the current engine {@link sd.engine.SimulationEngine}
+ * is single-threaded). It uses a {@link ReentrantLock} to protect its
+ * internal state (the queue and the light state) from simultaneous access.
+ * * The {@link Condition} variables ({@code vehicleAdded}, {@code lightGreen})
+ * are included for a concurrent model where:
+ * - A "vehicle" thread might wait on {@code lightGreen} until the light changes.
+ * - A "controller" thread might wait on {@code vehicleAdded} to know when to
+ * process a queue.
+ * (Note: These Conditions are *not* used by the current discrete-event engine).
+ */
+public class TrafficLight {
+
+    // --- Identity and configuration ---
+    
+    /**
+     * Unique identifier for the light (e.g., "Cr1-N").
+     */
+    private final String id;
+    
+    /**
+     * The direction this light controls (e.g., "North", "South").
+     */
+    private final String direction;
+    
+    /**
+     * The current state of the light (GREEN or RED).
+     */
+    private TrafficLightState state;
+
+    // --- Vehicle management ---
+    
+    /**
+     * The queue of vehicles waiting at this light.
+     * {@link LinkedList} is used as it's a standard {@link Queue} implementation.
+     */
+    private final Queue<Vehicle> queue;
+
+    // --- Synchronization primitives (for thread-safety) ---
+    
+    /**
+     * A lock to protect all mutable state ({@link #queue} and {@link #state})
+     * from concurrent access. Any method reading or writing these fields
+     * *must* acquire this lock first.
+     */
+    private final Lock lock;
+    
+    /**
+     * A condition variable for a potential concurrent model.
+     * It could be used to signal threads (e.g., a controller) that
+     * a new vehicle has been added to the queue.
+     * (Not used in the current discrete-event engine).
+     */
+    private final Condition vehicleAdded;
+    
+    /**
+     * A condition variable for a potential concurrent model.
+     * It could be used to signal waiting vehicle threads that the
+     * light has just turned GREEN.
+     * (Not used in the current discrete-event engine).
+     */
+    private final Condition lightGreen;
+
+    // --- Timing configuration ---
+    
+    /**
+     * The duration (in seconds) this light stays GREEN.
+     */
+    private double greenTime;
+    
+    /**
+     * The duration (in seconds) this light stays RED.
+     */
+    private double redTime;
+
+    // --- Statistics ---
+    
+    /**
+     * Counter for the total number of vehicles that have
+     * been dequeued (processed) by this light.
+     */
+    private int totalVehiclesProcessed;
+
+    /**
+     * Constructs a new TrafficLight.
+     *
+     * @param id The unique ID (e.g., "Cr1-N").
+     * @param direction The direction (e.g., "North").
+     * @param greenTime The duration of the GREEN state in seconds.
+     * @param redTime The duration of the RED state in seconds.
+     */
+    public TrafficLight(String id, String direction, double greenTime, double redTime) {
+        this.id = id;
+        this.direction = direction;
+        this.state = TrafficLightState.RED; // All lights start RED
+        this.queue = new LinkedList<>();
+
+        // Initialize synchronization objects
+        this.lock = new ReentrantLock();
+        this.vehicleAdded = lock.newCondition();
+        this.lightGreen = lock.newCondition();
+
+        this.greenTime = greenTime;
+        this.redTime = redTime;
+        this.totalVehiclesProcessed = 0;
+    }
+
+    /**
+     * Adds a vehicle to the *end* of the waiting queue.
+     * This method is thread-safe.
+     *
+     * @param vehicle The {@link Vehicle} to add.
+     */
+    public void addVehicle(Vehicle vehicle) {
+        lock.lock(); // Acquire the lock
+        try {
+            queue.offer(vehicle); // Add vehicle to queue
+            vehicleAdded.signalAll(); // Signal (for concurrent models)
+        } finally {
+            lock.unlock(); // Always release the lock
+        }
+    }
+
+    /**
+     * Removes and returns the {@link Vehicle} from the *front* of the queue.
+     * * This only succeeds if:
+     * 1. The light's state is {@link TrafficLightState#GREEN}.
+     * 2. The queue is not empty.
+     * * If these conditions are not met, it returns {@code null}.
+     * This method is thread-safe.
+     *
+     * @return The {@link Vehicle} at the front of the queue, or {@code null}
+     * if the light is RED or the queue is empty.
+     */
+    public Vehicle removeVehicle() {
+        lock.lock(); // Acquire the lock
+        try {
+            if (state == TrafficLightState.GREEN && !queue.isEmpty()) {
+                Vehicle vehicle = queue.poll(); // Remove vehicle from queue
+                if (vehicle != null) {
+                    totalVehiclesProcessed++;
+                }
+                return vehicle;
+            }
+            return null; // Light is RED or queue is empty
+        } finally {
+            lock.unlock(); // Always release the lock
+        }
+    }
+
+    /**
+     * Changes the light’s state (e.g., RED -> GREEN).
+     * If the new state is GREEN, it signals any waiting threads
+     * (for a potential concurrent model).
+     * This method is thread-safe.
+     *
+     * @param newState The {@link TrafficLightState} to set.
+     */
+    public void changeState(TrafficLightState newState) {
+        lock.lock(); // Acquire the lock
+        try {
+            this.state = newState;
+            if (newState == TrafficLightState.GREEN) {
+                lightGreen.signalAll(); // Signal (for concurrent models)
+            }
+        } finally {
+            lock.unlock(); // Always release the lock
+        }
+    }
+
+    /**
+     * Returns how many vehicles are currently in the queue.
+     * This method is thread-safe.
+     * * @return The size of the queue.
+     */
+    public int getQueueSize() {
+        lock.lock(); // Acquire the lock
+        try {
+            return queue.size();
+        } finally {
+            lock.unlock(); // Always release the lock
+        }
+    }
+
+    /**
+     * Checks whether the queue is empty.
+     * This method is thread-safe.
+     *
+     * @return {@code true} if the queue has no vehicles, {@code false} otherwise.
+     */
+    public boolean isQueueEmpty() {
+        lock.lock(); // Acquire the lock
+        try {
+            return queue.isEmpty();
+        } finally {
+            lock.unlock(); // Always release the lock
+        }
+    }
+
+    // --- Getters & Setters ---
+
+    /**
+     * @return The unique ID of this light (e.g., "Cr1-N").
+     */
+    public String getId() {
+        return id;
+    }
+
+    /**
+     * @return The direction this light controls (e.g., "North").
+     */
+    public String getDirection() {
+        return direction;
+    }
+
+    /**
+     * Gets the current state of the light (GREEN or RED).
+     * This method is thread-safe.
+     *
+     * @return The current {@link TrafficLightState}.
+     */
+    public TrafficLightState getState() {
+        lock.lock(); // Acquire the lock
+        try {
+            return state;
+        } finally {
+            lock.unlock(); // Always release the lock
+        }
+    }
+
+    /**
+     * @return The configured GREEN light duration in seconds.
+     */
+    public double getGreenTime() {
+        return greenTime;
+    }
+
+    /**
+     * Sets the GREEN light duration.
+     * @param greenTime The new duration in seconds.
+     */
+    public void setGreenTime(double greenTime) {
+        this.greenTime = greenTime;
+    }
+
+    /**
+     * @return The configured RED light duration in seconds.
+     */
+    public double getRedTime() {
+        return redTime;
+    }
+
+    /**
+     * Sets the RED light duration.
+     * @param redTime The new duration in seconds.
+     */
+    public void setRedTime(double redTime) {
+        this.redTime = redTime;
+    }
+
+    /**
+     * @return The total number of vehicles processed (dequeued) by this light.
+     */
+    public int getTotalVehiclesProcessed() {
+        // Note: This read is not locked, assuming it's okay
+        // for it to be "eventually consistent" for stats.
+        // For strict accuracy, it should also be locked.
+        return totalVehiclesProcessed;
+    }
+
+    /**
+     * @return The {@link Lock} object for advanced synchronization.
+     */
+    public Lock getLock() {
+        return lock;
+    }
+
+    /**
+     * @return The {@link Condition} for vehicle additions.
+     */
+    public Condition getVehicleAdded() {
+        return vehicleAdded;
+    }
+
+    /**
+     * @return The {@link Condition} for the light turning green.
+     */
+    public Condition getLightGreen() {
+        return lightGreen;
+    }
+
+    /**
+     * @return A string summary of the light's current state.
+     */
+    @Override
+    public String toString() {
+        return String.format(
+            "TrafficLight{id='%s', direction='%s', state=%s, queueSize=%d}",
+            id, direction, getState(), getQueueSize() // Use getters for thread-safety
+        );
+    }
+}

main/src/main/java/sd/model/TrafficLightState.java

@@ -1,9 +1,17 @@
 package sd.model;
 
 /**
- * Enumeration representing the state of a traffic light.
+ * Enumeration representing the two possible states of a {@link TrafficLight}.
  */
 public enum TrafficLightState {
-    GREEN,      // Allows passage
-    RED         // Blocks passage
+    
+    /**
+     * The light is GREEN, allowing vehicles to pass (be dequeued).
+     */
+    GREEN,
+    
+    /**
+     * The light is RED, blocking vehicles (they remain in the queue).
+     */
+    RED
 }

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

@@ -0,0 +1,218 @@
+package sd.model;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Represents a single vehicle moving through the simulation.
+ *
+ * This class is a data object that holds the state of a vehicle, including:
+ * - Its unique ID, type, and entry time.
+ * - Its complete, pre-determined {@code route} (a list of intersection IDs).
+ * - Its current position in the route ({@code currentRouteIndex}).
+ * - Metrics for total time spent waiting at red lights and time spent crossing.
+ * * This object is passed around the simulation, primarily inside {@link Event}
+ * payloads and stored in {@link TrafficLight} queues.
+ * * Implements {@link Serializable} so it can be sent between processes
+ * or nodes (e.g., over a socket in a distributed version of the simulation).
+ */
+public class Vehicle implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    // --- Identity and configuration ---
+    
+    /**
+     * Unique identifier for the vehicle (e.g., "V1", "V2").
+     */
+    private final String id;
+    
+    /**
+     * The type of vehicle (BIKE, LIGHT, HEAVY).
+     */
+    private final VehicleType type;
+    
+    /**
+     * The simulation time (in seconds) when the vehicle was generated.
+     */
+    private final double entryTime;
+    
+    /**
+     * The complete, ordered list of destinations (intersection IDs and the
+     * final exit "S"). Example: ["Cr1", "Cr3", "S"].
+     */
+    private final List<String> route;
+    
+    /**
+     * An index that tracks the vehicle's progress along its {@link #route}.
+     * {@code route.get(currentRouteIndex)} is the vehicle's *current*
+     * destination (i.e., the one it is traveling *towards* or *arriving at*).
+     */
+    private int currentRouteIndex;
+
+    // --- Metrics ---
+    
+    /**
+     * The total accumulated time (in seconds) this vehicle has spent
+     * waiting at red lights.
+     */
+    private double totalWaitingTime;
+    
+    /**
+     * The total accumulated time (in seconds) this vehicle has spent
+     * actively crossing intersections.
+     */
+    private double totalCrossingTime;
+
+    /**
+     * Constructs a new Vehicle.
+     *
+     * @param id The unique ID for the vehicle.
+     * @param type The {@link VehicleType}.
+     * @param entryTime The simulation time when the vehicle is created.
+     * @param route The complete list of destination IDs (e.t., ["Cr1", "Cr2", "S"]).
+     */
+    public Vehicle(String id, VehicleType type, double entryTime, List<String> route) {
+        this.id = id;
+        this.type = type;
+        this.entryTime = entryTime;
+        // Create a copy of the route list to ensure immutability
+        this.route = new ArrayList<>(route);
+        this.currentRouteIndex = 0; // Starts at the first destination
+        this.totalWaitingTime = 0.0;
+        this.totalCrossingTime = 0.0;
+    }
+
+    /**
+     * Advances the vehicle to the next stop in its route by
+     * incrementing the {@link #currentRouteIndex}.
+     * * This is typically called *after* a vehicle *arrives* at an intersection,
+     * to set its *next* destination before it is queued.
+     *
+     * @return {@code true} if there is still at least one more destination
+     * in the route, {@code false} if the vehicle has passed its
+     * final destination.
+     */
+    public boolean advanceRoute() {
+        currentRouteIndex++;
+        return currentRouteIndex < route.size();
+    }
+
+    /**
+     * Gets the current destination (the next intersection or exit) that
+     * the vehicle is heading towards.
+     *
+     * @return The ID of the current destination (e.g., "Cr1"), or
+     * {@code null} if the route is complete.
+     */
+    public String getCurrentDestination() {
+        return (currentRouteIndex < route.size()) ? route.get(currentRouteIndex) : null;
+    }
+
+    /**
+     * Checks if the vehicle has completed its entire route.
+     *
+     * @return {@code true} if the route index is at or past the end
+     * of the route list, {@code false} otherwise.
+     */
+    public boolean hasReachedEnd() {
+        return currentRouteIndex >= route.size();
+    }
+
+    // --- Getters and metrics management ---
+
+    /**
+     * @return The vehicle's unique ID.
+     */
+    public String getId() {
+        return id;
+    }
+
+    /**
+     * @return The vehicle's {@link VehicleType}.
+     */
+    public VehicleType getType() {
+        return type;
+    }
+
+    /**
+     * @return The simulation time when the vehicle entered the system.
+     */
+    public double getEntryTime() {
+        return entryTime;
+    }
+
+    /**
+     * @return A *copy* of the vehicle's complete route.
+     */
+    public List<String> getRoute() {
+        // Return a copy to prevent external modification
+        return new ArrayList<>(route);
+    }
+
+    /**
+     * @return The current index pointing to the vehicle's destination in its route list.
+     */
+    public int getCurrentRouteIndex() {
+        return currentRouteIndex;
+    }
+
+    /**
+     * @return The total accumulated waiting time in seconds.
+     */
+    public double getTotalWaitingTime() {
+        return totalWaitingTime;
+    }
+
+    /**
+     * Adds a duration to the vehicle's total waiting time.
+     * This is called by the simulation engine when a vehicle
+     * starts crossing an intersection.
+     *
+     * @param time The duration (in seconds) to add.
+     */
+    public void addWaitingTime(double time) {
+        totalWaitingTime += time;
+    }
+
+    /**
+     * @return The total accumulated crossing time in seconds.
+     */
+    public double getTotalCrossingTime() {
+        return totalCrossingTime;
+    }
+
+    /**
+     * Adds a duration to the vehicle's total crossing time.
+     * This is called by the simulation engine when a vehicle
+     * finishes crossing an intersection.
+     *
+     * @param time The duration (in seconds) to add.
+     */
+    public void addCrossingTime(double time) {
+        totalCrossingTime += time;
+    }
+
+    /**
+     * Calculates the vehicle's total time spent in the system so far.
+     * This is a "live" calculation.
+     *
+     * @param currentTime The current simulation time.
+     * @return The total elapsed time (in seconds) since the vehicle
+     * was generated ({@code currentTime - entryTime}).
+     */
+    public double getTotalTravelTime(double currentTime) {
+        return currentTime - entryTime;
+    }
+
+    /**
+     * @return A string summary of the vehicle's current state.
+     */
+    @Override
+    public String toString() {
+        return String.format(
+            "Vehicle{id='%s', type=%s, next='%s', route=%s}",
+            id, type, getCurrentDestination(), route
+        );
+    }
+}

main/src/main/java/sd/model/VehicleType.java

@@ -1,10 +1,27 @@
 package sd.model;
 
 /**
- * Enumeration representing vehicle types in the simulation.
+ * Enumeration representing the different types of vehicles in the simulation.
+ * Each type can have different properties, such as crossing time
+ * and generation probability, defined in {@link sd.config.SimulationConfig}.
  */
 public enum VehicleType {
-    BIKE,  // Motorcycle
-    LIGHT,      // Light vehicle (car)
-    HEAVY       // Heavy vehicle (truck, bus)
+    
+    /**
+     * A bike or motorcycle.
+     * Typically has a short crossing time.
+     */
+    BIKE,
+    
+    /**
+     * A standard light vehicle, such as a car.
+     * This is usually the most common type.
+     */
+    LIGHT,
+    
+    /**
+     * A heavy vehicle, such as a truck or bus.
+     * Typically has a long crossing time.
+     */
+    HEAVY
 }

main/src/main/java/sd/protocol/MessageProtocol.java

@@ -0,0 +1,41 @@
+package sd.protocol;
+
+import java.io.Serializable;
+import sd.model.MessageType; // Assuming MessageType is in sd.model or sd.protocol
+
+/**
+ * Interface defining the contract for all messages exchanged in the simulator.
+ * Ensures that any message can be identified and routed.
+ * * This interface extends Serializable to allow objects that implement it
+ * to be sent over Sockets (ObjectOutputStream).
+ *
+ */
+public interface MessageProtocol extends Serializable {
+
+    /**
+     * Returns the type of the message, indicating its purpose.
+     * @return The MessageType (e.g., VEHICLE_TRANSFER, STATS_UPDATE).
+     */
+    MessageType getType();
+
+    /**
+     * Returns the data object (payload) that this message carries.
+     * The type of object will depend on the MessageType.
+     * * - If getType() == VEHICLE_TRANSFER, the payload will be a {@link sd.model.Vehicle} object.
+     * - If getType() == STATS_UPDATE, the payload will be a statistics object.
+     * * @return The data object (payload), which must also be Serializable.
+     */
+    Object getPayload();
+
+    /**
+     * Returns the ID of the node (Process) that sent this message.
+     * @return String (e.g., "Cr1", "Cr5", "S").
+     */
+    String getSourceNode();
+
+    /**
+     * Returns the ID of the destination node (Process) for this message.
+     * @return String (e.g., "Cr2", "DashboardServer").
+     */
+    String getDestinationNode();
+}

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

@@ -0,0 +1,183 @@
+package sd.protocol; 
+
+import java.io.Closeable;
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.net.ConnectException;
+import java.net.Socket;
+import java.net.SocketTimeoutException;
+import java.net.UnknownHostException;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Wrapper class that simplifies communication via Sockets.
+ * Includes connection retry logic for robustness.
+ */
+public class SocketConnection implements Closeable {
+
+    private final Socket socket;
+    private final ObjectOutputStream outputStream;
+    private final ObjectInputStream inputStream;
+
+    // --- Configuration for Retry Logic ---
+    /** Maximum number of connection attempts. */
+    private static final int MAX_RETRIES = 5; 
+    /** Delay between retry attempts in milliseconds. */
+    private static final long RETRY_DELAY_MS = 1000; 
+
+    /**
+     * Constructor for the "Client" (who initiates the connection).
+     * Tries to connect to a process that is already listening (Server).
+     * Includes retry logic in case of initial connection failure.
+     *
+     * @param host The host address (e.g., "localhost" from your simulation.properties)
+     * @param port The port (e.g., 8001 from your simulation.properties)
+     * @throws IOException If connection fails after all retries.
+     * @throws UnknownHostException If the host is not found (this error usually doesn't need retry).
+     * @throws InterruptedException If the thread is interrupted while waiting between retries.
+     */
+    public SocketConnection(String host, int port) throws IOException, UnknownHostException, InterruptedException {
+        Socket tempSocket = null;
+        IOException lastException = null;
+
+        System.out.printf("[SocketConnection] Attempting to connect to %s:%d...%n", host, port);
+
+        // --- Retry Loop ---
+        for (int attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                // Try to establish the connection
+                tempSocket = new Socket(host, port);
+
+                // If successful, break out of the retry loop
+                System.out.printf("[SocketConnection] Connected successfully on attempt %d.%n", attempt);
+                lastException = null; // Clear last error on success
+                break;
+
+            } catch (ConnectException | SocketTimeoutException e) {
+                // These are common errors indicating the server might not be ready.
+                lastException = e;
+                System.out.printf("[SocketConnection] Attempt %d/%d failed: %s. Retrying in %d ms...%n",
+                        attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS);
+
+                if (attempt < MAX_RETRIES) {
+                    // Wait before the next attempt
+                    TimeUnit.MILLISECONDS.sleep(RETRY_DELAY_MS);
+                }
+            } catch (IOException e) {
+                // Other IOExceptions might be more permanent, but we retry anyway.
+                 lastException = e;
+                 System.out.printf("[SocketConnection] Attempt %d/%d failed with IOException: %s. Retrying in %d ms...%n",
+                        attempt, MAX_RETRIES, e.getMessage(), RETRY_DELAY_MS);
+                 if (attempt < MAX_RETRIES) {
+                     TimeUnit.MILLISECONDS.sleep(RETRY_DELAY_MS);
+                 }
+            }
+        } // --- End of Retry Loop ---
+
+        // If after all retries tempSocket is still null, it means connection failed permanently.
+        if (tempSocket == null) {
+            System.err.printf("[SocketConnection] Failed to connect to %s:%d after %d attempts.%n", host, port, MAX_RETRIES);
+            if (lastException != null) {
+                 throw lastException; // Throw the last exception encountered
+            } else {
+                 // Should not happen if loop ran, but as a fallback
+                 throw new IOException("Failed to connect after " + MAX_RETRIES + " attempts, reason unknown.");
+            }
+        }
+
+        // If connection was successful, assign to final variable and create streams
+        this.socket = tempSocket;
+        try {
+            // IMPORTANT: The order is crucial. OutputStream first.
+            this.outputStream = new ObjectOutputStream(socket.getOutputStream());
+            this.inputStream = new ObjectInputStream(socket.getInputStream());
+        } catch (IOException e) {
+             // If stream creation fails even after successful socket connection, clean up.
+             System.err.println("[SocketConnection] Failed to create streams after connection: " + e.getMessage());
+             try { socket.close(); } catch (IOException closeEx) { /* ignore */ }
+             throw e; // Re-throw the stream creation exception
+        }
+    }
+
+
+    /**
+     * Constructor for the "Server" (who accepts the connection).
+     * Receives a Socket that has already been accepted by a ServerSocket.
+     * No retry logic needed here as the connection is already established.
+     *
+     * @param acceptedSocket The Socket returned by serverSocket.accept().
+     * @throws IOException If stream creation fails.
+     */
+    public SocketConnection(Socket acceptedSocket) throws IOException {
+        this.socket = acceptedSocket;
+
+        // IMPORTANT: The order is crucial. OutputStream first.
+        this.outputStream = new ObjectOutputStream(socket.getOutputStream());
+        this.inputStream = new ObjectInputStream(socket.getInputStream());
+        System.out.printf("[SocketConnection] Connection accepted from %s:%d.%n",
+            acceptedSocket.getInetAddress().getHostAddress(), acceptedSocket.getPort());
+    }
+
+    /**
+     * Sends (serializes) a MessageProtocol object over the socket.
+     *
+     * @param message The "envelope" (which contains the Vehicle) to be sent.
+     * @throws IOException If writing to the stream fails or socket is not connected.
+     */
+    public void sendMessage(MessageProtocol message) throws IOException {
+        if (!isConnected()) {
+            throw new IOException("Socket is not connected.");
+        }
+        synchronized (outputStream) {
+            outputStream.writeObject(message);
+            outputStream.flush(); // Ensures the message is sent immediately.
+        }
+    }
+
+    /**
+     * Tries to read (deserialize) a MessageProtocol object from the socket.
+     * This call is "blocked" until an object is received.
+     *
+     * @return The "envelope" (MessageProtocol) that was received.
+     * @throws IOException If the connection is lost, the stream is corrupted, or socket is not connected.
+     * @throws ClassNotFoundException If the received object is unknown.
+     */
+    public MessageProtocol receiveMessage() throws IOException, ClassNotFoundException {
+       if (!isConnected()) {
+            throw new IOException("Socket is not connected.");
+        }
+        synchronized (inputStream) {
+            return (MessageProtocol) inputStream.readObject();
+        }
+    }
+
+    /**
+     * Closes the socket and all streams (Input and Output).
+     * It is called automatically if you use 'try-with-resources'.
+     */
+    @Override
+    public void close() throws IOException {
+         System.out.printf("[SocketConnection] Closing connection to %s:%d.%n",
+            socket != null ? socket.getInetAddress().getHostAddress() : "N/A",
+            socket != null ? socket.getPort() : -1);
+        try {
+            if (inputStream != null) inputStream.close();
+        } catch (IOException e) { /* ignore */ }
+
+        try {
+            if (outputStream != null) outputStream.close();
+        } catch (IOException e) { /* ignore */ }
+
+        if (socket != null && !socket.isClosed()) {
+            socket.close();
+        }
+    }
+
+    /**
+     * @return true if the socket is still connected and not closed.
+     */
+    public boolean isConnected() {
+        return socket != null && socket.isConnected() && !socket.isClosed();
+    }
+}

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

@@ -0,0 +1,114 @@
+package sd.serialization;
+
+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.
+ * 
+ * This serializer converts objects to JSON format for transmission, providing:
+ * - Human-readable message format (easy debugging)
+ * - Cross-platform compatibility
+ * - Smaller message sizes compared to Java native serialization
+ * - Better security (no code execution during deserialization)
+ * 
+ * The serializer is configured with pretty printing disabled by default for
+ * production use, but can be enabled for debugging purposes.
+ * 
+ * Thread-safety: This class is thread-safe as Gson instances are thread-safe.
+ * 
+ * @see MessageSerializer
+ */
+public class JsonMessageSerializer implements MessageSerializer {
+    
+    private final Gson gson;
+    private final boolean prettyPrint;
+    
+    /**
+     * Creates a new JSON serializer with default configuration (no pretty printing).
+     */
+    public JsonMessageSerializer() {
+        this(false);
+    }
+    
+    /**
+     * Creates a new JSON serializer with optional pretty printing.
+     * 
+     * @param prettyPrint If true, JSON output will be formatted with indentation
+     */
+    public JsonMessageSerializer(boolean prettyPrint) {
+        this.prettyPrint = prettyPrint;
+        GsonBuilder builder = new GsonBuilder();
+        
+        if (prettyPrint) {
+            builder.setPrettyPrinting();
+        }
+        
+        // Register custom type adapters here if needed
+        // builder.registerTypeAdapter(Vehicle.class, new VehicleAdapter());
+        
+        this.gson = builder.create();
+    }
+    
+    @Override
+    public byte[] serialize(Object object) throws SerializationException {
+        if (object == null) {
+            throw new IllegalArgumentException("Cannot serialize null object");
+        }
+        
+        try {
+            String json = gson.toJson(object);
+            return json.getBytes(StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            throw new SerializationException(
+                "Failed to serialize object of type " + object.getClass().getName(), e);
+        }
+    }
+    
+    @Override
+    public <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException {
+        if (data == null) {
+            throw new IllegalArgumentException("Cannot deserialize null data");
+        }
+        if (clazz == null) {
+            throw new IllegalArgumentException("Class type cannot be null");
+        }
+        
+        try {
+            String json = new String(data, StandardCharsets.UTF_8);
+            return gson.fromJson(json, clazz);
+        } catch (JsonSyntaxException e) {
+            throw new SerializationException(
+                "Failed to parse JSON for type " + clazz.getName(), e);
+        } catch (Exception e) {
+            throw new SerializationException(
+                "Failed to deserialize object of type " + clazz.getName(), e);
+        }
+    }
+    
+    @Override
+    public String getName() {
+        return "JSON (Gson)";
+    }
+    
+    /**
+     * Returns the underlying Gson instance for advanced usage.
+     * 
+     * @return The Gson instance
+     */
+    public Gson getGson() {
+        return gson;
+    }
+    
+    /**
+     * Checks if pretty printing is enabled.
+     * 
+     * @return true if pretty printing is enabled
+     */
+    public boolean isPrettyPrint() {
+        return prettyPrint;
+    }
+}

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

@@ -0,0 +1,48 @@
+package sd.serialization;
+
+/**
+ * Interface for serializing and deserializing objects for network transmission.
+ * 
+ * This interface provides a common abstraction for different serialization strategies
+ * allowing the system to switch between implementations without changing the communication layer.
+ * 
+ * Implementations must ensure:
+ * - Thread-safety if used in concurrent contexts
+ * - Proper exception handling with meaningful error messages
+ * - Preservation of object state during round-trip serialization
+ * 
+ * @see JsonMessageSerializer
+ */
+public interface MessageSerializer {
+    
+    /**
+     * Serializes an object into a byte array for transmission.
+     * 
+     * @param object The object to serialize (must not be null)
+     * @return A byte array containing the serialized representation
+     * @throws SerializationException If serialization fails
+     * @throws IllegalArgumentException If object is null
+     */
+    byte[] serialize(Object object) throws SerializationException;
+    
+    /**
+     * Deserializes a byte array back into an object of the specified type.
+     * 
+     * @param <T> The expected type of the deserialized object
+     * @param data The byte array containing serialized data (must not be null)
+     * @param clazz The class of the expected object type (must not be null)
+     * @return The deserialized object
+     * @throws SerializationException If deserialization fails
+     * @throws IllegalArgumentException If data or clazz is null
+     */
+    <T> T deserialize(byte[] data, Class<T> clazz) throws SerializationException;
+    
+    /**
+     * Gets the name of this serialization strategy (e.g., "JSON", "Java Native").
+     * Useful for logging and debugging.
+     * 
+     * @return The serializer name
+     */
+    String getName();
+    
+}

main/src/main/java/sd/serialization/SerializationExample.java

@@ -0,0 +1,134 @@
+package sd.serialization;
+
+import sd.model.Message;
+import sd.model.MessageType;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Demonstration of JSON serialization usage in the traffic simulation system.
+ * 
+ * This class shows practical examples of how to use JSON (Gson) serialization
+ * for network communication between simulation processes.
+ */
+public class SerializationExample {
+    
+    public static void main(String[] args) {
+        System.out.println("=== JSON Serialization Example ===\n");
+        
+        // Create a sample vehicle
+        List<String> route = Arrays.asList("Cr1", "Cr2", "Cr5", "S");
+        Vehicle vehicle = new Vehicle("V001", VehicleType.LIGHT, 10.5, route);
+        vehicle.addWaitingTime(2.3);
+        vehicle.addCrossingTime(1.2);
+        
+        // Create a message containing the vehicle
+        Message message = new Message(
+            MessageType.VEHICLE_TRANSFER,
+            "Cr1",
+            "Cr2",
+            vehicle
+        );
+        
+        // ===== JSON Serialization =====
+        demonstrateJsonSerialization(message);
+        
+        // ===== Factory Usage =====
+        demonstrateFactoryUsage(message);
+        
+        // ===== Performance Test =====
+        performanceTest(message);
+    }
+    
+    private static void demonstrateJsonSerialization(Message message) {
+        System.out.println("--- JSON Serialization ---");
+        
+        try {
+            // Create JSON serializer with pretty printing for readability
+            MessageSerializer serializer = new JsonMessageSerializer(true);
+            
+            // Serialize to bytes
+            byte[] data = serializer.serialize(message);
+            
+            // Display the JSON
+            String json = new String(data);
+            System.out.println("Serialized JSON (" + data.length + " bytes):");
+            System.out.println(json);
+            
+            // Deserialize back
+            Message deserialized = serializer.deserialize(data, Message.class);
+            System.out.println("\nDeserialized: " + deserialized);
+            System.out.println("✓ JSON serialization successful\n");
+            
+        } catch (SerializationException e) {
+            System.err.println("❌ JSON serialization failed: " + e.getMessage());
+        }
+    }
+    
+    private static void demonstrateFactoryUsage(Message message) {
+        System.out.println("--- Using SerializerFactory ---");
+        
+        try {
+            // Get default serializer (JSON)
+            MessageSerializer serializer = SerializerFactory.createDefault();
+            System.out.println("Default serializer: " + serializer.getName());
+            
+            // Use it
+            byte[] data = serializer.serialize(message);
+            Message deserialized = serializer.deserialize(data, Message.class);
+            
+            System.out.println("Message type: " + deserialized.getType());
+            System.out.println("From: " + deserialized.getSenderId() + 
+                             " → To: " + deserialized.getDestinationId());
+            System.out.println("✓ Factory usage successful\n");
+            
+        } catch (SerializationException e) {
+            System.err.println("❌ Factory usage failed: " + e.getMessage());
+        }
+    }
+    
+    private static void performanceTest(Message message) {
+        System.out.println("--- Performance Test ---");
+        
+        int iterations = 1000;
+        
+        try {
+            MessageSerializer compactSerializer = new JsonMessageSerializer(false);
+            MessageSerializer prettySerializer = new JsonMessageSerializer(true);
+            
+            // Warm up
+            for (int i = 0; i < 100; i++) {
+                compactSerializer.serialize(message);
+            }
+            
+            // Test compact JSON
+            long compactStart = System.nanoTime();
+            byte[] compactData = null;
+            for (int i = 0; i < iterations; i++) {
+                compactData = compactSerializer.serialize(message);
+            }
+            long compactTime = System.nanoTime() - compactStart;
+            
+            // Test pretty JSON
+            byte[] prettyData = prettySerializer.serialize(message);
+            
+            // Results
+            System.out.println("Iterations: " + iterations);
+            System.out.println("\nJSON Compact:");
+            System.out.println("  Size: " + compactData.length + " bytes");
+            System.out.println("  Time: " + (compactTime / 1_000_000.0) + " ms total");
+            System.out.println("  Avg:  " + (compactTime / iterations / 1_000.0) + " μs/operation");
+            
+            System.out.println("\nJSON Pretty-Print:");
+            System.out.println("  Size: " + prettyData.length + " bytes");
+            System.out.println("  Size increase: " + 
+                String.format("%.1f%%", ((double)prettyData.length / compactData.length - 1) * 100));
+            
+        } catch (SerializationException e) {
+            System.err.println("❌ Performance test failed: " + e.getMessage());
+        }
+    }
+}

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

@@ -0,0 +1,41 @@
+package sd.serialization;
+
+/**
+ * Exception thrown when serialization or deserialization operations fail.
+ * 
+ * This exception wraps underlying errors (I/O exceptions, parsing errors, etc.)
+ * and provides context about what went wrong during the serialization process.
+ */
+public class SerializationException extends Exception {
+    
+    private static final long serialVersionUID = 1L; // Long(64bits) instead of int(32bits)
+    
+    /**
+     * Constructs a new serialization exception with the specified detail message.
+     * 
+     * @param message The detail message
+     */
+    public SerializationException(String message) {
+        super(message);
+    }
+    
+    /**
+     * Constructs a new serialization exception with the specified detail message
+     * and cause.
+     * 
+     * @param message The detail message
+     * @param cause The cause of this exception
+     */
+    public SerializationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+    
+    /**
+     * Constructs a new serialization exception with the specified cause.
+     * 
+     * @param cause The cause of this exception
+     */
+    public SerializationException(Throwable cause) {
+        super(cause);
+    }
+}

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

@@ -0,0 +1,66 @@
+package sd.serialization;
+
+/**
+ * Factory for creating {@link MessageSerializer} instances.
+ * 
+ * This factory provides a centralized way to create and configure JSON serializers
+ * using Gson, making it easy to configure serialization throughout the application.
+ * 
+ * The factory can be configured via system properties for easy deployment configuration.
+ * 
+ * Example usage:
+ * <pre>
+ * MessageSerializer serializer = SerializerFactory.createDefault();
+ * byte[] data = serializer.serialize(myObject);
+ * </pre>
+ */
+public class SerializerFactory {
+    
+    /**
+     * System property key for enabling pretty-print in JSON serialization.
+     * Set to "true" for debugging, "false" for production.
+     */
+    public static final String JSON_PRETTY_PRINT_PROPERTY = "sd.serialization.json.prettyPrint";
+    
+    // Default configuration
+    private static final boolean DEFAULT_JSON_PRETTY_PRINT = false;
+    
+    /**
+     * Private constructor to prevent instantiation.
+     */
+    private SerializerFactory() {
+        throw new UnsupportedOperationException("Factory class cannot be instantiated");
+    }
+    
+    /**
+     * Creates a JSON serializer based on system configuration.
+     * 
+     * Pretty-print is determined by checking the system property
+     * {@value #JSON_PRETTY_PRINT_PROPERTY}. If not set, defaults to false.
+     * 
+     * @return A configured JsonMessageSerializer instance
+     */
+    public static MessageSerializer createDefault() {
+        boolean prettyPrint = Boolean.getBoolean(JSON_PRETTY_PRINT_PROPERTY);
+        return new JsonMessageSerializer(prettyPrint);
+    }
+    
+    /**
+     * Creates a JSON serializer with default configuration (no pretty printing).
+     * 
+     * @return A JsonMessageSerializer instance
+     */
+    public static MessageSerializer createSerializer() {
+        return createSerializer(DEFAULT_JSON_PRETTY_PRINT);
+    }
+    
+    /**
+     * Creates a JSON serializer with specified pretty-print setting.
+     * 
+     * @param prettyPrint Whether to enable pretty printing
+     * @return A JsonMessageSerializer instance
+     */
+    public static MessageSerializer createSerializer(boolean prettyPrint) {
+        return new JsonMessageSerializer(prettyPrint);
+    }
+}

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

@@ -0,0 +1,103 @@
+package sd.util;
+
+import java.util.Random;
+
+/**
+ * Utility class for generating random values used throughout the simulation.
+ * * Provides static methods for:
+ * - Generating exponentially distributed intervals (for Poisson processes).
+ * - Generating random integers and doubles in a range.
+ * - Making decisions based on probability.
+ * - Choosing random elements from an array.
+ * * It uses a single, static {@link Random} instance.
+ */
+public class RandomGenerator {
+
+    /**
+     * The single, shared Random instance for the entire simulation.
+     */
+    private static final Random random = new Random();
+
+    /**
+     * Returns a random time interval that follows an exponential distribution.
+     * * This is a key component for modeling a Poisson process, where the
+     * *inter-arrival times* (time between events) are exponentially distributed.
+     * The formula used is the inverse transform sampling method:
+     * {@code Time = -ln(1 - U) / λ}
+     * where U is a uniform random number [0, 1) and λ (lambda) is the
+     * average arrival rate.
+     *
+     * @param lambda The average arrival rate (λ) (e.g., 0.5 vehicles per second).
+     * @return The time interval (in seconds) until the next arrival.
+     */
+    public static double generateExponentialInterval(double lambda) {
+        // Math.log is the natural logarithm (ln)
+        // random.nextDouble() returns a value in [0.0, 1.0)
+        return Math.log(1 - random.nextDouble()) / -lambda;
+    }
+
+    /**
+     * Returns a random integer between {@code min} and {@code max}, inclusive.
+     *
+     * @param min The minimum possible value.
+     * @param max The maximum possible value.
+     * @return A random integer in the range [min, max].
+     */
+    public static int generateRandomInt(int min, int max) {
+        // random.nextInt(N) returns a value from 0 to N-1
+        // (max - min + 1) is the total number of integers in the range
+        // + min offsets the range
+        return random.nextInt(max - min + 1) + min;
+    }
+
+    /**
+     * Returns a random double between {@code min} (inclusive) and {@code max} (exclusive).
+     *
+     * @param min The minimum possible value.
+     * @param max The maximum possible value.
+     * @return A random double in the range [min, max).
+     */
+    public static double generateRandomDouble(double min, double max) {
+        return min + (max - min) * random.nextDouble();
+    }
+
+    /**
+     * Returns {@code true} with a given probability.
+     * * This is useful for making weighted decisions. For example,
+     * {@code occursWithProbability(0.3)} will return {@code true}
+     * approximately 30% of the time.
+     *
+     * @param probability A value between 0.0 (never) and 1.0 (always).
+     * @return {@code true} or {@code false}, based on the probability.
+     */
+    public static boolean occursWithProbability(double probability) {
+        return random.nextDouble() < probability;
+    }
+
+    /**
+     * Picks a random element from the given array.
+     *
+     * @param <T> The generic type of the array.
+     * @param array The array to choose from.
+     * @return A randomly selected element from the array.
+     * @throws IllegalArgumentException if the array is null or empty.
+     */
+    public static <T> T chooseRandom(T[] array) {
+        if (array == null || array.length == 0) {
+            throw new IllegalArgumentException("Array cannot be null or empty.");
+        }
+        return array[random.nextInt(array.length)];
+    }
+
+    /**
+     * Sets the seed of the shared random number generator.
+     * This is extremely useful for debugging and testing, as it allows
+     * the simulation to be run multiple times with the *exact same*
+     * sequence of "random" events, making the results reproducible.
+     *
+     * @param seed The seed to use.
+     */
+    public static void setSeed(long seed) {
+        random.setSeed(seed);
+    }
+}

main/src/main/java/sd/util/StatisticsCollector.java

@@ -0,0 +1,379 @@
+package sd.util;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import sd.config.SimulationConfig;
+import sd.model.Intersection;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+
+/**
+ * Collects, manages, and reports statistics throughout the simulation.
+ * * This class acts as the central bookkeeper for simulation metrics. It tracks:
+ * - Overall system statistics (total vehicles, completion time, wait time).
+ * - Per-vehicle-type statistics (counts, average wait time by type).
+ * - Per-intersection statistics (arrivals, departures).
+ * * It also maintains "in-flight" data, such as the arrival time of a
+ * vehicle at its *current* intersection, which is necessary to
+ * calculate waiting time when the vehicle later departs.
+ */
+public class StatisticsCollector {
+    
+    // --- Vehicle tracking (for in-flight vehicles) ---
+    
+    /**
+     * Tracks the simulation time when a vehicle arrives at its *current* intersection.
+     * This is used later to calculate waiting time (Depart_Time - Arrive_Time).
+     * Key: Vehicle ID (String)
+     * Value: Arrival Time (Double)
+     */
+    private final Map<String, Double> vehicleArrivalTimes;
+    
+    /**
+     * Tracks the sequence of intersections a vehicle has visited.
+     * Key: Vehicle ID (String)
+     * Value: List of Intersection IDs (String)
+     */
+    private final Map<String, List<String>> vehicleIntersectionHistory;
+    
+    // --- Overall system statistics ---
+    
+    /** Total number of vehicles created by the {@link VehicleGenerator}. */
+    private int totalVehiclesGenerated;
+    
+    /** Total number of vehicles that have reached their final destination ("S"). */
+    private int totalVehiclesCompleted;
+    
+    /** The sum of all *completed* vehicles' total travel times. Used for averaging. */
+    private double totalSystemTime;
+    
+    /** The sum of all *completed* vehicles' total waiting times. Used for averaging. */
+    private double totalWaitingTime;
+    
+    // --- Per-vehicle-type statistics ---
+    
+    /**
+     * Tracks the total number of vehicles generated, broken down by type.
+     * Key: {@link VehicleType}
+     * Value: Count (Integer)
+     */
+    private final Map<VehicleType, Integer> vehicleTypeCount;
+    
+    /**
+     * Tracks the total waiting time, broken down by vehicle type.
+     * Key: {@link VehicleType}
+     * Value: Total Wait Time (Double)
+     */
+    private final Map<VehicleType, Double> vehicleTypeWaitTime;
+    
+    // --- Per-intersection statistics ---
+    
+    /**
+     * A map to hold statistics objects for each intersection.
+     * Key: Intersection ID (String)
+     * Value: {@link IntersectionStats} object
+     */
+    private final Map<String, IntersectionStats> intersectionStats;
+    
+    /**
+     * Constructs a new StatisticsCollector.
+     * Initializes all maps and counters.
+     *
+     * @param config The {@link SimulationConfig} (not currently used, but
+     * could be for configuration-dependent stats).
+     */
+    public StatisticsCollector(SimulationConfig config) {
+        this.vehicleArrivalTimes = new HashMap<>();
+        this.vehicleIntersectionHistory = new HashMap<>();
+        this.totalVehiclesGenerated = 0;
+        this.totalVehiclesCompleted = 0;
+        this.totalSystemTime = 0.0;
+        this.totalWaitingTime = 0.0;
+        this.vehicleTypeCount = new HashMap<>();
+        this.vehicleTypeWaitTime = new HashMap<>();
+        this.intersectionStats = new HashMap<>();
+        
+        // Initialize vehicle type counters to 0
+        for (VehicleType type : VehicleType.values()) {
+            vehicleTypeCount.put(type, 0);
+            vehicleTypeWaitTime.put(type, 0.0);
+        }
+    }
+    
+    /**
+     * Records that a new vehicle has been generated.
+     * This is called by the {@link sd.engine.SimulationEngine}
+     * during a {@code VEHICLE_GENERATION} event.
+     *
+     * @param vehicle The {@link Vehicle} that was just created.
+     * @param currentTime The simulation time of the event.
+     */
+    public void recordVehicleGeneration(Vehicle vehicle, double currentTime) {
+        totalVehiclesGenerated++;
+        
+        // Track by vehicle type
+        VehicleType type = vehicle.getType();
+        vehicleTypeCount.put(type, vehicleTypeCount.get(type) + 1);
+        
+        // Initialize history tracking for this vehicle
+        vehicleIntersectionHistory.put(vehicle.getId(), new ArrayList<>());
+    }
+    
+    /**
+     * Records that a vehicle has arrived at an intersection queue.
+     * This is called by the {@link sd.engine.SimulationEngine}
+     * during a {@code VEHICLE_ARRIVAL} event.
+     *
+     * @param vehicle The {@link Vehicle} that arrived.
+     * @param intersectionId The ID of the intersection it arrived at.
+     * @param currentTime The simulation time of the arrival.
+     */
+    public void recordVehicleArrival(Vehicle vehicle, String intersectionId, double currentTime) {
+        // Store arrival time - this is the "start waiting" time
+        vehicleArrivalTimes.put(vehicle.getId(), currentTime);
+        
+        // Track intersection history
+        List<String> history = vehicleIntersectionHistory.get(vehicle.getId());
+        if (history != null) {
+            history.add(intersectionId);
+        }
+        
+        // Update per-intersection statistics
+        getOrCreateIntersectionStats(intersectionId).recordArrival();
+    }
+    
+    /**
+     * Records that a vehicle has completed its route and exited the system.
+     * This is where final metrics for the vehicle are aggregated.
+     * This is called by the {@link sd.engine.SimulationEngine}
+     * when a vehicle reaches destination "S".
+     *
+     * @param vehicle The {@link Vehicle} that is exiting.
+     * @param currentTime The simulation time of the exit.
+     */
+    public void recordVehicleExit(Vehicle vehicle, double currentTime) {
+        totalVehiclesCompleted++;
+        
+        // Calculate and aggregate total system time
+        double systemTime = vehicle.getTotalTravelTime(currentTime);
+        totalSystemTime += systemTime;
+        
+        // Aggregate waiting time
+        double waitTime = vehicle.getTotalWaitingTime();
+        totalWaitingTime += waitTime;
+        
+        // Aggregate waiting time by vehicle type
+        VehicleType type = vehicle.getType();
+        vehicleTypeWaitTime.put(type, vehicleTypeWaitTime.get(type) + waitTime);
+        
+        // Clean up tracking maps to save memory
+        vehicleArrivalTimes.remove(vehicle.getId());
+        vehicleIntersectionHistory.remove(vehicle.getId());
+    }
+    
+    /**
+     * Gets the time a vehicle arrived at its *current* intersection.
+     * This is used by the {@link sd.engine.SimulationEngine} to calculate
+     * wait time just before the vehicle crosses.
+     *
+     * @param vehicle The {@link Vehicle} to check.
+     * @return The arrival time, or 0.0 if not found.
+     */
+    public double getArrivalTime(Vehicle vehicle) {
+        return vehicleArrivalTimes.getOrDefault(vehicle.getId(), 0.0);
+    }
+    
+    /**
+     * Prints a "snapshot" of the current simulation statistics.
+     * This is called periodically by the {@link sd.engine.SimulationEngine}
+     * during a {@code STATISTICS_UPDATE} event.
+     *
+     * @param intersections A map of all intersections (to get queue data).
+     * @param currentTime The current simulation time.
+     */
+    public void printCurrentStatistics(Map<String, Intersection> intersections, double currentTime) {
+        System.out.printf("--- Statistics at t=%.2f ---%n", currentTime);
+        System.out.printf("Vehicles: Generated=%d, Completed=%d, In-System=%d%n",
+            totalVehiclesGenerated,
+            totalVehiclesCompleted,
+            totalVehiclesGenerated - totalVehiclesCompleted);
+        
+        if (totalVehiclesCompleted > 0) {
+            System.out.printf("Average System Time (so far): %.2fs%n", totalSystemTime / totalVehiclesCompleted);
+            System.out.printf("Average Waiting Time (so far): %.2fs%n", totalWaitingTime / totalVehiclesCompleted);
+        }
+        
+        // Print per-intersection queue sizes
+        System.out.println("\nIntersection Queues:");
+        for (Map.Entry<String, Intersection> entry : intersections.entrySet()) {
+            String id = entry.getKey();
+            Intersection intersection = entry.getValue();
+            System.out.printf("  %s: Queue=%d, Received=%d, Sent=%d%n",
+                id,
+                intersection.getTotalQueueSize(),
+                intersection.getTotalVehiclesReceived(),
+                intersection.getTotalVehiclesSent());
+        }
+    }
+    
+    /**
+     * Prints the final simulation summary statistics at the end of the run.
+     *
+     * @param intersections A map of all intersections.
+     * @param currentTime The final simulation time.
+     */
+    public void printFinalStatistics(Map<String, Intersection> intersections, double currentTime) {
+        System.out.println("\n=== SIMULATION SUMMARY ===");
+        System.out.printf("Duration: %.2f seconds%n", currentTime);
+        System.out.printf("Total Vehicles Generated: %d%n", totalVehiclesGenerated);
+        System.out.printf("Total Vehicles Completed: %d%n", totalVehiclesCompleted);
+        System.out.printf("Vehicles Still in System: %d%n", totalVehiclesGenerated - totalVehiclesCompleted);
+        
+        // Overall averages
+        if (totalVehiclesCompleted > 0) {
+            System.out.printf("%nAVERAGE METRICS (for completed vehicles):%n");
+            System.out.printf("  System Time: %.2f seconds%n", totalSystemTime / totalVehiclesCompleted);
+            System.out.printf("  Waiting Time: %.2f seconds%n", totalWaitingTime / totalVehiclesCompleted);
+            System.out.printf("  Throughput: %.2f vehicles/second%n", totalVehiclesCompleted / currentTime);
+        }
+        
+        // Vehicle type breakdown
+        System.out.println("\nVEHICLE TYPE DISTRIBUTION:");
+        for (VehicleType type : VehicleType.values()) {
+            int count = vehicleTypeCount.get(type);
+            if (count > 0) {
+                double percentage = (count * 100.0) / totalVehiclesGenerated;
+                // Calculate avg wait *only* for this type
+                // This assumes all generated vehicles of this type *completed*
+                // A more accurate way would be to track completed vehicle types
+                double avgWait = vehicleTypeWaitTime.get(type) / count; 
+                System.out.printf("  %s: %d (%.1f%%), Avg Wait: %.2fs%n",
+                    type, count, percentage, avgWait);
+            }
+        }
+        
+        // Per-intersection statistics
+        System.out.println("\nINTERSECTION STATISTICS:");
+        for (Map.Entry<String, Intersection> entry : intersections.entrySet()) {
+            String id = entry.getKey();
+            Intersection intersection = entry.getValue();
+            
+            System.out.printf("  %s:%n", id);
+            System.out.printf("    Vehicles Received: %d%n", intersection.getTotalVehiclesReceived());
+            System.out.printf("    Vehicles Sent: %d%n", intersection.getTotalVehiclesSent());
+            System.out.printf("    Final Queue Size: %d%n", intersection.getTotalQueueSize());
+            
+            // Traffic light details
+            intersection.getTrafficLights().forEach(light -> {
+                System.out.printf("      Light %s: State=%s, Queue=%d, Processed=%d%n",
+                    light.getDirection(),
+                    light.getState(),
+                    light.getQueueSize(),
+                    light.getTotalVehiclesProcessed());
+            });
+        }
+        
+        // System health indicators
+        System.out.println("\nSYSTEM HEALTH:");
+        int totalQueuedVehicles = intersections.values().stream()
+            .mapToInt(Intersection::getTotalQueueSize)
+            .sum();
+        System.out.printf("  Total Queued Vehicles (at end): %d%n", totalQueuedVehicles);
+        
+        if (totalVehiclesGenerated > 0) {
+            double completionRate = (totalVehiclesCompleted * 100.0) / totalVehiclesGenerated;
+            System.out.printf("  Completion Rate: %.1f%%%n", completionRate);
+        }
+    }
+    
+    /**
+     * Gets or creates the statistics object for a given intersection.
+     * Uses {@code computeIfAbsent} for efficient, thread-safe-like instantiation.
+     *
+     * @param intersectionId The ID of the intersection.
+     * @return The {@link IntersectionStats} object for that ID.
+     */
+    private IntersectionStats getOrCreateIntersectionStats(String intersectionId) {
+        // If 'intersectionId' is not in the map, create a new IntersectionStats()
+        // and put it in the map, then return it.
+        // Otherwise, just return the one that's already there.
+        return intersectionStats.computeIfAbsent(intersectionId, k -> new IntersectionStats());
+    }
+    
+    /**
+     * Inner class to track per-intersection statistics.
+     * This is a simple data holder.
+     */
+    private static class IntersectionStats {
+        private int totalArrivals;
+        private int totalDepartures;
+        
+        public IntersectionStats() {
+            this.totalArrivals = 0;
+            this.totalDepartures = 0;
+        }
+        
+        public void recordArrival() {
+            totalArrivals++;
+        }
+        
+        public void recordDeparture() {
+            totalDepartures++;
+        }
+        
+        public int getTotalArrivals() {
+            return totalArrivals;
+        }
+        
+        public int getTotalDepartures() {
+            return totalDepartures;
+        }
+    }
+    
+    // --- Public Getters for Final Statistics ---
+    
+    /**
+     * @return Total vehicles generated during the simulation.
+     */
+    public int getTotalVehiclesGenerated() {
+        return totalVehiclesGenerated;
+    }
+    
+    /**
+     * @return Total vehicles that completed their route.
+     */
+    public int getTotalVehiclesCompleted() {
+        return totalVehiclesCompleted;
+    }
+    
+    /**
+     * @return The sum of all travel times for *completed* vehicles.
+     */
+    public double getTotalSystemTime() {
+        return totalSystemTime;
+    }
+    
+    /**
+     * @return The sum of all waiting times for *completed* vehicles.
+     */
+    public double getTotalWaitingTime() {
+        return totalWaitingTime;
+    }
+    
+    /**
+     * @return The average travel time for *completed* vehicles.
+     */
+    public double getAverageSystemTime() {
+        return totalVehiclesCompleted > 0 ? totalSystemTime / totalVehiclesCompleted : 0.0;
+    }
+    
+    /**
+     * @return The average waiting time for *completed* vehicles.
+     */
+    public double getAverageWaitingTime() {
+        return totalVehiclesCompleted > 0 ? totalWaitingTime / totalVehiclesCompleted : 0.0;
+    }
+}

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

@@ -0,0 +1,229 @@
+package sd.util;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import sd.config.SimulationConfig;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+
+/**
+ * Generates vehicles for the simulation.
+ * * This class is responsible for two key tasks:
+ * 1.  Determining *when* the next vehicle should arrive, based on the
+ * arrival model (POISSON or FIXED) from the {@link SimulationConfig}.
+ * 2.  Creating a new {@link Vehicle} object with a randomly selected
+ * type (e.g., BIKE, LIGHT) and a randomly selected route.
+ * * Routes are predefined and organized by entry point (E1, E2, E3).
+ */
+public class VehicleGenerator {
+    
+    private final SimulationConfig config;
+    private final String arrivalModel;
+    private final double arrivalRate;      // Lambda (λ) for POISSON
+    private final double fixedInterval;    // Interval for FIXED
+    
+    // --- Predefined Routes ---
+    // These lists store all possible routes, grouped by where they start.
+    
+    /** Routes starting from entry point E1. */
+    private final List<RouteWithProbability> e1Routes;
+    /** Routes starting from entry point E2. */
+    private final List<RouteWithProbability> e2Routes;
+    /** Routes starting from entry point E3. */
+    private final List<RouteWithProbability> e3Routes;
+    
+    /**
+     * Constructs a new VehicleGenerator.
+     * It reads the necessary configuration and initializes the
+     * predefined routes.
+     *
+     * @param config The {@link SimulationConfig} object.
+     */
+    public VehicleGenerator(SimulationConfig config) {
+        this.config = config;
+        
+        // Cache configuration values for performance
+        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();
+    }
+    
+    /**
+     * Defines all possible routes that vehicles can take, organized by
+     * their entry point (E1, E2, E3). Each route is given a
+     * probability, which determines how often it's chosen.
+     */
+    private void initializePossibleRoutes() {
+        // E1 routes (Starts at Cr1)
+        e1Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr1", "Cr4", "Cr5", "S"), 0.34)); // E1 -> Cr1 -> Cr4 -> Cr5 -> Exit
+        e1Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr1", "Cr2", "Cr5", "S"), 0.33)); // E1 -> Cr1 -> Cr2 -> Cr5 -> Exit
+        e1Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr1", "Cr2", "Cr3", "S"), 0.33)); // E1 -> Cr1 -> Cr2 -> Cr3 -> Exit
+        
+        // E2 routes (Starts at Cr2)
+        e2Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr2", "Cr5", "S"), 0.34)); // E2 -> Cr2 -> Cr5 -> Exit
+        e2Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr2", "Cr3", "S"), 0.33)); // E2 -> Cr2 -> Cr3 -> Exit
+        e2Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr2", "Cr1", "Cr4", "Cr5", "S"), 0.33)); // E2 -> Cr2 -> ... -> Exit
+        
+        // E3 routes (Starts at Cr3)
+        e3Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr3", "S"), 0.34)); // E3 -> Cr3 -> Exit
+        e3Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr3", "Cr2", "Cr5", "S"), 0.33)); // E3 -> Cr3 -> Cr2 -> Cr5 -> Exit
+        e3Routes.add(new RouteWithProbability(
+            Arrays.asList("Cr3", "Cr2", "Cr1", "Cr4", "Cr5", "S"), 0.33)); // E3 -> Cr3 -> ... -> Exit
+    }
+    
+    /**
+     * Calculates the *absolute* time of the next vehicle arrival
+     * based on the configured model.
+     * * @param currentTime The current simulation time, used as the base.
+     * @return The absolute time (e.g., {@code currentTime + interval})
+     * when the next vehicle should be generated.
+     */
+    public double getNextArrivalTime(double currentTime) {
+        if ("POISSON".equalsIgnoreCase(arrivalModel)) {
+            // For a Poisson process, the time *between* arrivals
+            // follows an exponential distribution.
+            double interval = RandomGenerator.generateExponentialInterval(arrivalRate);
+            return currentTime + interval;
+        } else {
+            // For a Fixed model, the interval is constant.
+            return currentTime + fixedInterval;
+        }
+    }
+    
+    /**
+     * Generates a new {@link Vehicle} object.
+     * This involves:
+     * 1. Selecting a random {@link VehicleType} based on probabilities.
+     * 2. Selecting a random route (entry point + path) based on probabilities.
+     *
+     * @param vehicleId The unique identifier for the new vehicle (e.g., "V123").
+     * @param entryTime The simulation time when this vehicle is being created.
+     * @return A new, configured {@link Vehicle} object.
+     */
+    public Vehicle generateVehicle(String vehicleId, double entryTime) {
+        VehicleType type = selectVehicleType();
+        List<String> route = selectRandomRoute();
+        
+        return new Vehicle(vehicleId, type, entryTime, route);
+    }
+    
+    /**
+     * Selects a {@link VehicleType} (BIKE, LIGHT, HEAVY) based on the
+     * probabilities defined in the {@link SimulationConfig}.
+     * * Uses a standard "cumulative probability" technique:
+     * 1. Get a random number {@code rand} from [0, 1).
+     * 2. If {@code rand < P(Bike)}, return BIKE.
+     * 3. Else if {@code rand < P(Bike) + P(Light)}, return LIGHT.
+     * 4. Else, return HEAVY.
+     *
+     * @return The selected {@link VehicleType}.
+     */
+    private VehicleType selectVehicleType() {
+        double bikeProbability = config.getBikeVehicleProbability();
+        double lightProbability = config.getLightVehicleProbability();
+        double heavyProbability = config.getHeavyVehicleProbability();
+        
+        // Normalize probabilities in case they don't sum to exactly 1.0
+        double total = bikeProbability + lightProbability + heavyProbability;
+        if (total == 0) return VehicleType.LIGHT; // Avoid division by zero
+        bikeProbability /= total;
+        lightProbability /= total;
+        
+        double rand = Math.random();
+        
+        if (rand < bikeProbability) {
+            return VehicleType.BIKE;
+        } else if (rand < bikeProbability + lightProbability) {
+            return VehicleType.LIGHT;
+        } else {
+            return VehicleType.HEAVY;
+        }
+    }
+    
+    /**
+     * Selects a random route for a new vehicle.
+     * This is a two-step process:
+     * 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"]).
+     */
+    private List<String> selectRandomRoute() {
+        // Step 1: Randomly select an entry point (E1, E2, or E3)
+        double entryRandom = Math.random();
+        List<RouteWithProbability> selectedRoutes;
+        
+        if (entryRandom < 0.333) {
+            selectedRoutes = e1Routes;
+        } else if (entryRandom < 0.666) {
+            selectedRoutes = e2Routes;
+        } else {
+            selectedRoutes = e3Routes;
+        }
+        
+        // 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.
+     */
+    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)}",
+            arrivalModel, arrivalRate, fixedInterval, totalRoutes,
+            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/simulation.properties

@@ -1,8 +1,13 @@
-# Traffic simulation configuration
-# This file contains all the necessary configurations to run the simulation
+# =========================================================
+# Traffic Simulation Configuration
+# ---------------------------------------------------------
+# All parameters controlling network layout, timing,
+# and simulation behavior.
+# =========================================================
 
-# === NETWORK CONFIGURATIONS ===
-# Intersections
+# === NETWORK CONFIGURATION ===
+
+# Intersections (each with its host and port)
 intersection.Cr1.host=localhost
 intersection.Cr1.port=8001
 intersection.Cr2.host=localhost
@@ -14,30 +19,32 @@ intersection.Cr4.port=8004
 intersection.Cr5.host=localhost
 intersection.Cr5.port=8005
 
-# Exit Node
+# Exit node
 exit.host=localhost
 exit.port=9001
 
-# Dashboard
+# Dashboard server
 dashboard.host=localhost
 dashboard.port=9000
 
-# === SIMULATION CONFIGURATIONS ===
-# Simulation duration in seconds (3600 = 1 hour)
-simulation.duration=3600.0
+
+# === SIMULATION CONFIGURATION ===
+
+# Total duration in seconds (3600 = 1 hour)
+simulation.duration=60.0
 
 # Vehicle arrival model: FIXED or POISSON
 simulation.arrival.model=POISSON
 
-# Arrival rate (λ) for Poisson model (vehicles per second)
+# λ (lambda): average arrival rate (vehicles per second)
 simulation.arrival.rate=0.5
 
-# Fixed interval between arrivals (used if model = FIXED)
+# Fixed interval between arrivals (only used if model=FIXED)
 simulation.arrival.fixed.interval=2.0
 
-# === TRAFFIC LIGHT CONFIGURATIONS ===
-# Times in seconds for each traffic light (green and red)
-# Format: trafficlight.<intersection>.<direction>.<state>
+
+# === TRAFFIC LIGHT TIMINGS ===
+# Format: trafficlight.<intersection>.<direction>.<state>=<seconds>
 
 # Intersection 1
 trafficlight.Cr1.North.green=30.0
@@ -89,15 +96,18 @@ trafficlight.Cr5.East.red=30.0
 trafficlight.Cr5.West.green=30.0
 trafficlight.Cr5.West.red=30.0
 
-# === VEHICLE CONFIGURATIONS ===
-# Probability of generating a light vehicle (0.0 to 1.0)
-# The rest will be heavy vehicles
-vehicle.probability.light=0.7
+# === VEHICLE CONFIGURATION ===
+# Probability distribution for vehicle types (must sum to 1.0)
+vehicle.probability.bike=0.2
+vehicle.probability.light=0.6
+vehicle.probability.heavy=0.2
 
-# Crossing time in seconds
+# Average crossing times (in seconds)
+vehicle.crossing.time.bike=1.5
 vehicle.crossing.time.light=2.0
 vehicle.crossing.time.heavy=4.0
 
-# === STATISTICS CONFIGURATIONS ===
-# Interval to send updates to the dashboard (in seconds)
+# === STATISTICS ===
+
+# Interval between dashboard updates (seconds)
 statistics.update.interval=10.0

main/src/test/java/IntersectionProcessTest.java

@@ -0,0 +1,473 @@
+import java.io.IOException;
+import java.io.ObjectOutputStream;
+import java.net.Socket;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Arrays;
+
+import org.junit.jupiter.api.AfterEach;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.api.io.TempDir;
+
+import sd.IntersectionProcess;
+import sd.model.MessageType;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+
+/**
+ * Tests for IntersectionProcess - covers initialization, traffic lights, 
+ * vehicle transfer and network stuff
+ */
+public class IntersectionProcessTest {
+
+    @TempDir
+    Path tempDir;
+
+    private Path configFile;
+    private IntersectionProcess intersectionProcess;
+
+    // setup test config before each test
+    @BeforeEach
+    public void setUp() throws IOException {
+        // create temp config file
+        configFile = tempDir.resolve("test-simulation.properties");
+        
+        String configContent = """
+                # Test Simulation Configuration
+                
+                # Intersection Network Configuration
+                intersection.Cr1.host=localhost
+                intersection.Cr1.port=18001
+                intersection.Cr2.host=localhost
+                intersection.Cr2.port=18002
+                intersection.Cr3.host=localhost
+                intersection.Cr3.port=18003
+                intersection.Cr4.host=localhost
+                intersection.Cr4.port=18004
+                intersection.Cr5.host=localhost
+                intersection.Cr5.port=18005
+                
+                # Exit Configuration
+                exit.host=localhost
+                exit.port=18099
+                
+                # Dashboard Configuration
+                dashboard.host=localhost
+                dashboard.port=18100
+                
+                # Traffic Light Timing (seconds)
+                trafficLight.Cr1.East.greenTime=5.0
+                trafficLight.Cr1.East.redTime=5.0
+                trafficLight.Cr1.South.greenTime=5.0
+                trafficLight.Cr1.South.redTime=5.0
+                trafficLight.Cr1.West.greenTime=5.0
+                trafficLight.Cr1.West.redTime=5.0
+                
+                trafficLight.Cr2.West.greenTime=4.0
+                trafficLight.Cr2.West.redTime=6.0
+                trafficLight.Cr2.East.greenTime=4.0
+                trafficLight.Cr2.East.redTime=6.0
+                trafficLight.Cr2.South.greenTime=4.0
+                trafficLight.Cr2.South.redTime=6.0
+                
+                trafficLight.Cr3.West.greenTime=3.0
+                trafficLight.Cr3.West.redTime=7.0
+                trafficLight.Cr3.East.greenTime=3.0
+                trafficLight.Cr3.East.redTime=7.0
+                
+                trafficLight.Cr4.East.greenTime=6.0
+                trafficLight.Cr4.East.redTime=4.0
+                
+                trafficLight.Cr5.East.greenTime=5.0
+                trafficLight.Cr5.East.redTime=5.0
+                
+                # Vehicle Crossing Times (seconds)
+                vehicle.bike.crossingTime=2.0
+                vehicle.light.crossingTime=3.0
+                vehicle.heavy.crossingTime=5.0
+                """;
+        
+        Files.writeString(configFile, configContent);
+    }
+
+    // cleanup after tests
+    @AfterEach
+    public void tearDown() {
+        if (intersectionProcess != null) {
+            intersectionProcess.shutdown();
+        }
+    }
+
+    // ==================== Initialization Tests ====================
+
+    @Test
+    public void testConstructor_Success() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        assertNotNull(intersectionProcess);
+    }
+
+    @Test
+    public void testConstructor_InvalidConfig() {
+        Exception exception = assertThrows(IOException.class, () -> {
+            new IntersectionProcess("Cr1", "non-existent-config.properties");
+        });
+        assertNotNull(exception);
+    }
+
+    @Test
+    public void testInitialize_Cr1() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        assertDoesNotThrow(() -> intersectionProcess.initialize());
+    }
+
+    @Test
+    public void testInitialize_Cr2() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr2", configFile.toString());
+        assertDoesNotThrow(() -> intersectionProcess.initialize());
+    }
+
+    @Test
+    public void testInitialize_Cr3() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr3", configFile.toString());
+        assertDoesNotThrow(() -> intersectionProcess.initialize());
+    }
+
+    @Test
+    public void testInitialize_Cr4() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr4", configFile.toString());
+        assertDoesNotThrow(() -> intersectionProcess.initialize());
+    }
+
+    @Test
+    public void testInitialize_Cr5() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr5", configFile.toString());
+        assertDoesNotThrow(() -> intersectionProcess.initialize());
+    }
+
+    // traffic light creation tests
+
+    @Test
+    public void testTrafficLightCreation_Cr1_HasCorrectDirections() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        intersectionProcess.initialize();
+        
+        // cant access private fields but initialization succeds
+        assertNotNull(intersectionProcess);
+    }
+
+    @Test
+    public void testTrafficLightCreation_Cr3_HasCorrectDirections() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr3", configFile.toString());
+        intersectionProcess.initialize();
+        
+        // Cr3 has west and south only
+        assertNotNull(intersectionProcess);
+    }
+
+    @Test
+    public void testTrafficLightCreation_Cr4_HasSingleDirection() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr4", configFile.toString());
+        intersectionProcess.initialize();
+        
+        // Cr4 only has east direction
+        assertNotNull(intersectionProcess);
+    }
+
+    // server startup tests
+
+    @Test
+    @Timeout(5)
+    public void testServerStart_BindsToCorrectPort() throws IOException, InterruptedException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        intersectionProcess.initialize();
+        
+        // start server in seperate thread
+        Thread serverThread = new Thread(() -> {
+            try {
+                intersectionProcess.start();
+            } catch (IOException e) {
+                // expected on shutdown
+            }
+        });
+        serverThread.start();
+        
+        Thread.sleep(500); // wait for server to start
+        
+        // try connecting to check if its running
+        try (Socket clientSocket = new Socket("localhost", 18001)) {
+            assertTrue(clientSocket.isConnected());
+        }
+        
+        intersectionProcess.shutdown();
+        serverThread.join(2000);
+    }
+
+    @Test
+    @Timeout(5)
+    public void testServerStart_MultipleIntersections() throws IOException, InterruptedException {
+        // test 2 intersections on diferent ports
+        IntersectionProcess cr1 = new IntersectionProcess("Cr1", configFile.toString());
+        IntersectionProcess cr2 = new IntersectionProcess("Cr2", configFile.toString());
+        
+        cr1.initialize();
+        cr2.initialize();
+        
+        Thread thread1 = new Thread(() -> {
+            try { cr1.start(); } catch (IOException e) { }
+        });
+        
+        Thread thread2 = new Thread(() -> {
+            try { cr2.start(); } catch (IOException e) { }
+        });
+        
+        thread1.start();
+        thread2.start();
+        
+        Thread.sleep(500);
+        
+        // check both are running
+        try (Socket socket1 = new Socket("localhost", 18001);
+             Socket socket2 = new Socket("localhost", 18002)) {
+            assertTrue(socket1.isConnected());
+            assertTrue(socket2.isConnected());
+        }
+        
+        cr1.shutdown();
+        cr2.shutdown();
+        thread1.join(2000);
+        thread2.join(2000);
+    }
+
+    // vehicle transfer tests
+
+    @Test
+    @Timeout(10)
+    public void testVehicleTransfer_ReceiveVehicle() throws IOException, InterruptedException {
+        // setup reciever intersection
+        intersectionProcess = new IntersectionProcess("Cr2", configFile.toString());
+        intersectionProcess.initialize();
+        
+        Thread serverThread = new Thread(() -> {
+            try {
+                intersectionProcess.start();
+            } catch (IOException e) { }
+        });
+        serverThread.start();
+        
+        Thread.sleep(500);
+        
+        // create test vehicle
+        java.util.List<String> route = Arrays.asList("Cr2", "Cr3", "S");
+        Vehicle vehicle = new Vehicle("V001", VehicleType.LIGHT, 0.0, route);
+        
+        // send vehicle from Cr1 to Cr2
+        try (Socket socket = new Socket("localhost", 18002)) {
+            ObjectOutputStream out = new ObjectOutputStream(socket.getOutputStream());
+            
+            TestVehicleMessage message = new TestVehicleMessage("Cr1", "Cr2", vehicle);
+            out.writeObject(message);
+            out.flush();
+            
+            Thread.sleep(1000); // wait for procesing
+        }
+        
+        intersectionProcess.shutdown();
+        serverThread.join(2000);
+    }
+
+    // routing config tests
+
+    @Test
+    public void testRoutingConfiguration_Cr1() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        intersectionProcess.initialize();
+        
+        // indirect test - if init works routing should be ok
+        assertNotNull(intersectionProcess);
+    }
+
+    @Test
+    public void testRoutingConfiguration_Cr5() throws IOException {
+        intersectionProcess = new IntersectionProcess("Cr5", configFile.toString());
+        intersectionProcess.initialize();
+        
+        // Cr5 routes to exit
+        assertNotNull(intersectionProcess);
+    }
+
+    // shutdown tests
+
+    @Test
+    @Timeout(5)
+    public void testShutdown_GracefulTermination() throws IOException, InterruptedException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        intersectionProcess.initialize();
+        
+        Thread serverThread = new Thread(() -> {
+            try {
+                intersectionProcess.start();
+            } catch (IOException e) { }
+        });
+        serverThread.start();
+        
+        Thread.sleep(500);
+        
+        // shutdown should be fast
+        assertDoesNotThrow(() -> intersectionProcess.shutdown());
+        
+        serverThread.join(2000);
+    }
+
+    @Test
+    @Timeout(5)
+    public void testShutdown_ClosesServerSocket() throws IOException, InterruptedException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        intersectionProcess.initialize();
+        
+        Thread serverThread = new Thread(() -> {
+            try {
+                intersectionProcess.start();
+            } catch (IOException e) { }
+        });
+        serverThread.start();
+        
+        Thread.sleep(500);
+        
+        // verify server running
+        try (Socket socket = new Socket("localhost", 18001)) {
+            assertTrue(socket.isConnected());
+        }
+        
+        intersectionProcess.shutdown();
+        serverThread.join(2000);
+        
+        // after shutdown conection should fail
+        Thread.sleep(500);
+        Exception exception = assertThrows(IOException.class, () -> {
+            Socket socket = new Socket("localhost", 18001);
+            socket.close();
+        });
+        assertNotNull(exception);
+    }
+
+    @Test
+    @Timeout(5)
+    public void testShutdown_StopsTrafficLightThreads() throws IOException, InterruptedException {
+        intersectionProcess = new IntersectionProcess("Cr1", configFile.toString());
+        intersectionProcess.initialize();
+        
+        Thread serverThread = new Thread(() -> {
+            try {
+                intersectionProcess.start();
+            } catch (IOException e) { }
+        });
+        serverThread.start();
+        
+        Thread.sleep(500);
+        
+        int threadCountBefore = Thread.activeCount();
+        
+        intersectionProcess.shutdown();
+        serverThread.join(2000);
+        
+        Thread.sleep(500); // wait for threads to die
+        
+        // thread count should decrese (traffic light threads stop)
+        int threadCountAfter = Thread.activeCount();
+        assertTrue(threadCountAfter <= threadCountBefore);
+    }
+
+    // integration tests
+
+    @Test
+    @Timeout(15)
+    public void testIntegration_TwoIntersectionsVehicleTransfer() throws IOException, InterruptedException {
+        // setup 2 intersections
+        IntersectionProcess cr1 = new IntersectionProcess("Cr1", configFile.toString());
+        IntersectionProcess cr2 = new IntersectionProcess("Cr2", configFile.toString());
+        
+        cr1.initialize();
+        cr2.initialize();
+        
+        // start both
+        Thread thread1 = new Thread(() -> {
+            try { cr1.start(); } catch (IOException e) { }
+        });
+        
+        Thread thread2 = new Thread(() -> {
+            try { cr2.start(); } catch (IOException e) { }
+        });
+        
+        thread1.start();
+        thread2.start();
+        
+        Thread.sleep(1000); // wait for servers
+        
+        // send vehicle to Cr1 that goes to Cr2
+        java.util.List<String> route = Arrays.asList("Cr1", "Cr2", "S");
+        Vehicle vehicle = new Vehicle("V001", VehicleType.LIGHT, 0.0, route);
+        
+        try (Socket socket = new Socket("localhost", 18001)) {
+            ObjectOutputStream out = new ObjectOutputStream(socket.getOutputStream());
+            
+            TestVehicleMessage message = new TestVehicleMessage("Entry", "Cr1", vehicle);
+            out.writeObject(message);
+            out.flush();
+            
+            Thread.sleep(2000); // time for processing
+        }
+        
+        cr1.shutdown();
+        cr2.shutdown();
+        thread1.join(2000);
+        thread2.join(2000);
+    }
+
+    @Test
+    public void testMain_MissingArguments() {
+        // main needs intersection ID as argument
+        // cant test System.exit easily in modern java
+        assertTrue(true, "Main method expects intersection ID as first argument");
+    }
+
+    // helper class for testing vehicle messages
+    private static class TestVehicleMessage implements sd.protocol.MessageProtocol {
+        private static final long serialVersionUID = 1L;
+        
+        private final String sourceNode;
+        private final String destinationNode;
+        private final Vehicle payload;
+        
+        public TestVehicleMessage(String sourceNode, String destinationNode, Vehicle vehicle) {
+            this.sourceNode = sourceNode;
+            this.destinationNode = destinationNode;
+            this.payload = vehicle;
+        }
+        
+        @Override
+        public MessageType getType() {
+            return MessageType.VEHICLE_TRANSFER;
+        }
+        
+        @Override
+        public Object getPayload() {
+            return payload;
+        }
+        
+        @Override
+        public String getSourceNode() {
+            return sourceNode;
+        }
+        
+        @Override
+        public String getDestinationNode() {
+            return destinationNode;
+        }
+    }
+}

main/src/test/java/SimulationTest.java

@@ -0,0 +1,125 @@
+import java.io.IOException;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import org.junit.jupiter.api.Test;
+
+import sd.config.SimulationConfig;
+import sd.engine.SimulationEngine;
+import sd.model.Event;
+import sd.model.EventType;
+import sd.model.Intersection;
+import sd.model.TrafficLight;
+import sd.model.TrafficLightState;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+import sd.util.StatisticsCollector;
+import sd.util.VehicleGenerator;
+
+/**
+ * Basic tests for the simulation components.
+ */
+class SimulationTest {
+    
+    @Test
+    void testConfigurationLoading() throws IOException {
+        SimulationConfig config = new SimulationConfig("src/main/resources/simulation.properties");
+        
+        assertEquals(60.0, config.getSimulationDuration());
+        assertEquals("POISSON", config.getArrivalModel());
+        assertEquals(0.5, config.getArrivalRate());
+        assertEquals(10.0, config.getStatisticsUpdateInterval());
+    }
+    
+    @Test
+    void testVehicleGeneration() throws IOException {
+        SimulationConfig config = new SimulationConfig("src/main/resources/simulation.properties");
+        VehicleGenerator generator = new VehicleGenerator(config);
+        
+        Vehicle vehicle = generator.generateVehicle("TEST1", 0.0);
+        
+        assertNotNull(vehicle);
+        assertEquals("TEST1", vehicle.getId());
+        assertNotNull(vehicle.getType());
+        assertNotNull(vehicle.getRoute());
+        assertTrue(!vehicle.getRoute().isEmpty());
+    }
+    
+    @Test
+    void testEventOrdering() {
+        Event e1 = new Event(5.0, EventType.VEHICLE_ARRIVAL, null, "Cr1");
+        Event e2 = new Event(3.0, EventType.VEHICLE_ARRIVAL, null, "Cr2");
+        Event e3 = new Event(7.0, EventType.TRAFFIC_LIGHT_CHANGE, null, "Cr1");
+        
+        assertTrue(e2.compareTo(e1) < 0); // e2 should come before e1
+        assertTrue(e1.compareTo(e3) < 0); // e1 should come before e3
+    }
+    
+    @Test
+    void testIntersectionVehicleQueue() {
+        Intersection intersection = new Intersection("TestCr");
+        TrafficLight light = new TrafficLight("TestCr-N", "North", 30.0, 30.0);
+        
+        intersection.addTrafficLight(light);
+        
+        Vehicle v1 = new Vehicle("V1", VehicleType.LIGHT, 0.0, 
+            java.util.Arrays.asList("TestCr", "S"));
+        
+        intersection.configureRoute("S", "North");
+        
+        // Advance route to next destination
+        v1.advanceRoute();
+        
+        intersection.receiveVehicle(v1);
+        
+        assertEquals(1, intersection.getTotalQueueSize());
+        assertEquals(1, intersection.getTotalVehiclesReceived());
+    }
+    
+    @Test
+    void testTrafficLightStateChange() {
+        TrafficLight light = new TrafficLight("Test-Light", "North", 30.0, 30.0);
+        
+        assertEquals(TrafficLightState.RED, light.getState());
+        
+        light.changeState(TrafficLightState.GREEN);
+        assertEquals(TrafficLightState.GREEN, light.getState());
+        
+        light.changeState(TrafficLightState.RED);
+        assertEquals(TrafficLightState.RED, light.getState());
+    }
+    
+    @Test
+    void testSimulationEngineInitialization() throws IOException {
+        SimulationConfig config = new SimulationConfig("src/main/resources/simulation.properties");
+        SimulationEngine engine = new SimulationEngine(config);
+        
+        engine.initialize();
+        
+        assertNotNull(engine.getIntersections());
+        assertEquals(5, engine.getIntersections().size());
+        
+        // Check that intersections have traffic lights
+        for (Intersection intersection : engine.getIntersections().values()) {
+            assertEquals(3, intersection.getTrafficLights().size()); // North, South, East, West
+        }
+    }
+    
+    @Test
+    void testStatisticsCollector() throws IOException {
+        SimulationConfig config = new SimulationConfig("src/main/resources/simulation.properties");
+        StatisticsCollector collector = new StatisticsCollector(config);
+        
+        Vehicle v1 = new Vehicle("V1", VehicleType.LIGHT, 0.0, 
+            java.util.Arrays.asList("Cr1", "Cr2", "S"));
+        
+        collector.recordVehicleGeneration(v1, 0.0);
+        assertEquals(1, collector.getTotalVehiclesGenerated());
+        
+        collector.recordVehicleArrival(v1, "Cr1", 1.0);
+        
+        collector.recordVehicleExit(v1, 10.0);
+        assertEquals(1, collector.getTotalVehiclesCompleted());
+    }
+}

main/src/test/java/sd/serialization/SerializationTest.java

@@ -0,0 +1,140 @@
+package sd.serialization;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import sd.model.Message;
+import sd.model.Vehicle;
+import sd.model.VehicleType;
+
+import java.util.Arrays;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Test suite for JSON serialization.
+ * 
+ * Tests JSON serialization to ensure:
+ * - Correct serialization and deserialization
+ * - Data integrity during round-trip conversion
+ * - Proper error handling
+ */
+class SerializationTest {
+    
+    private MessageSerializer jsonSerializer = new JsonMessageSerializer();
+    
+    private Vehicle testVehicle = new Vehicle("V001", VehicleType.LIGHT, 10.5,
+            Arrays.asList("Cr1", "Cr2", "Cr5", "S"));
+    private Message testMessage = new Message(
+            sd.model.MessageType.VEHICLE_TRANSFER,
+            "Cr1",
+            "Cr2",
+            testVehicle
+    );
+    
+    
+    // ===== JSON Serialization Tests =====
+    
+    @Test
+    @DisplayName("JSON: Should serialize and deserialize Vehicle correctly")
+    void testJsonVehicleRoundTrip() throws SerializationException {
+        // Serialize
+        byte[] data = jsonSerializer.serialize(testVehicle);
+        assertNotNull(data);
+        assertTrue(data.length > 0);
+        
+        // Print JSON for inspection
+        System.out.println("JSON Vehicle:");
+        System.out.println(new String(data));
+        
+        // Deserialize
+        Vehicle deserialized = jsonSerializer.deserialize(data, Vehicle.class);
+        
+        // Verify
+        assertNotNull(deserialized);
+        assertEquals(testVehicle.getId(), deserialized.getId());
+        assertEquals(testVehicle.getType(), deserialized.getType());
+        assertEquals(testVehicle.getEntryTime(), deserialized.getEntryTime());
+        assertEquals(testVehicle.getRoute(), deserialized.getRoute());
+        assertEquals(testVehicle.getTotalWaitingTime(), deserialized.getTotalWaitingTime());
+        assertEquals(testVehicle.getTotalCrossingTime(), deserialized.getTotalCrossingTime());
+    }
+    
+    @Test
+    @DisplayName("JSON: Should serialize and deserialize Message correctly")
+    void testJsonMessageRoundTrip() throws SerializationException {
+        // Serialize
+        byte[] data = jsonSerializer.serialize(testMessage);
+        assertNotNull(data);
+        
+        // Print JSON for inspection
+        System.out.println("\nJSON Message:");
+        System.out.println(new String(data));
+        
+        // Deserialize
+        Message deserialized = jsonSerializer.deserialize(data, Message.class);
+        
+        // Verify
+        assertNotNull(deserialized);
+        assertEquals(testMessage.getType(), deserialized.getType());
+        assertEquals(testMessage.getSenderId(), deserialized.getSenderId());
+        assertEquals(testMessage.getDestinationId(), deserialized.getDestinationId());
+    }
+    
+    @Test
+    @DisplayName("JSON: Should throw exception on null object")
+    void testJsonSerializeNull() {
+        assertThrows(IllegalArgumentException.class, () -> {
+            jsonSerializer.serialize(null);
+        });
+    }
+    
+    @Test
+    @DisplayName("JSON: Should throw exception on null data")
+    void testJsonDeserializeNull() {
+        assertThrows(IllegalArgumentException.class, () -> {
+            jsonSerializer.deserialize(null, Vehicle.class);
+        });
+    }
+    
+    @Test
+    @DisplayName("JSON: Should throw exception on invalid JSON")
+    void testJsonDeserializeInvalid() {
+        byte[] invalidData = "{ invalid json }".getBytes();
+        assertThrows(SerializationException.class, () -> {
+            jsonSerializer.deserialize(invalidData, Vehicle.class);
+        });
+    }
+    
+    @Test
+    @DisplayName("JSON: Should preserve data integrity for complex objects")
+    void testDataIntegrity() throws SerializationException {
+        // Create a more complex vehicle
+        Vehicle vehicle = new Vehicle("V999", VehicleType.HEAVY, 100.5,
+            Arrays.asList("Cr1", "Cr2", "Cr3", "Cr4", "Cr5", "S"));
+        vehicle.addWaitingTime(10.5);
+        vehicle.addWaitingTime(5.3);
+        vehicle.addCrossingTime(2.1);
+        vehicle.advanceRoute();
+        vehicle.advanceRoute();
+        
+        // Serialize and deserialize
+        byte[] jsonData = jsonSerializer.serialize(vehicle);
+        Vehicle deserialized = jsonSerializer.deserialize(jsonData, Vehicle.class);
+        
+        // Verify all fields match
+        assertEquals(vehicle.getId(), deserialized.getId());
+        assertEquals(vehicle.getType(), deserialized.getType());
+        assertEquals(vehicle.getTotalWaitingTime(), deserialized.getTotalWaitingTime());
+        assertEquals(vehicle.getCurrentRouteIndex(), deserialized.getCurrentRouteIndex());
+    }
+    
+    // ===== Factory Tests =====
+    
+    @Test
+    @DisplayName("Factory: Should create JSON serializer by default")
+    void testFactoryDefault() {
+        MessageSerializer serializer = SerializerFactory.createDefault();
+        assertNotNull(serializer);
+        assertEquals("JSON (Gson)", serializer.getName());
+    }
+}