# marceloanje/otimizador-rotas-foodservice architecture

> Architecture diagram of the GitHub repository marceloanje/otimizador-rotas-foodservice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marceloanje/otimizador-rotas-foodservice
- Repository: https://github.com/marceloanje/otimizador-rotas-foodservice

## Overview

1. **Visão geral da arquitetura**  
   Este repositório é um protótipo de otimização de rotas para food-service, focado no VRP com janelas de tempo. A aplicação é organizada como um pipeline: dados de pedidos entram, passam por geoprocessamento para virar instância do problema, e então são avaliados por um conjunto de algoritmos exatos/meta-heurísticos.

2. **Ponto de entrada e orquestração**  
   O fluxo principal parece ser iniciado por `src/main.py`, com apoio de `src/comparador.py` para executar e comparar métodos. A configuração global fica em `src/config.py` e `src/config_experimento.py`, que provavelmente controlam parâmetros de ambiente, execução e experimento.

3. **Dados e insumos do problema**  
   O repositório já inclui dados de exemplo em `src/dados/`, como `pedidos_pequeno.csv` e `matriz_distancias.csv`. Esses arquivos representam, respectivamente, a demanda/pedidos e a matriz de custos/distâncias usada pelos algoritmos.

4. **Camada de geoprocessamento**  
   O pacote `src/geoprocessamento/` é a fronteira entre dados “crus” e a instância otimizada.  
   - `geocodificador.py`: indica transformação de endereços em coordenadas.  
   - `preprocessamento.py`: prepara dados para o solver, incluindo limpeza e montagem da instância.  
   - `integracao_osrm.py`: integra com o OSRM para obter distâncias reais por malha viária.

5. **Dependência externa crítica: OSRM local**  
   O README deixa claro que existe um serviço externo opcional/estratégico: um servidor OSRM rodando localmente via Docker. Ele é usado para construir a matriz de distâncias reais. Se o OSRM estiver indisponível, o sistema faz fallback para distância euclidiana. Isso é um boundary importante do desenho: o núcleo do otimizador não depende diretamente da internet, mas pode usar um serviço local para enriquecer os custos.

6. **Modelo de domínio do VRP**  
   O pacote `src/modelos/` concentra a representação formal do problema e da solução.  
   - `instancia.py`: encapsula os dados do caso de teste.  
   - `representacao.py`: define como uma solução é codificada internamente.  
   - `solucao.py`: guarda a solução final, custo e métricas.  
   - `objetivo_config.py`: define os pesos/regras da função objetivo e restrições.

7. **Geração de soluções e operadores auxiliares**  
   `src/utilitarios/` contém as rotinas reutilizáveis que alimentam os algoritmos.  
   - `construtivas.py`: gera soluções iniciais viáveis.  
   - `local_search.py`: aplica refinamento local sobre rotas.  
   - `simulacao_rota.py`: avalia a execução de uma rota, provavelmente verificando tempo/janelas/custos.  
   - `graficos_experimento.py`: produz visualizações e comparações dos resultados.

8. **Algoritmos de otimização comparados**  
   Em `src/algoritmos/` estão as estratégias principais do projeto:  
   - `busca_tabu.py`  
   - `colonia_formigas.py`  
   - `enxame_particulas.py`  
   - `solver_referencia.py`  
   Esse conjunto sugere uma arquitetura de comparação entre um baseline/referência e três meta-heurísticas. Os algoritmos devem consumir a mesma instância e função objetivo para permitir comparação justa.

9. **Fluxo de dados entre camadas**  
   O fluxo típico é: arquivos CSV → geoprocessamento/preprocessamento → `Instancia` → codificação da solução → algoritmo de busca → avaliação em `Solucao`/função objetivo → comparação e gráficos. A matriz de distâncias é um artefato central no meio desse fluxo, pois liga os dados geográficos ao custo de otimização.

10. **Saída analítica e experimento**  
   O projeto não parece ser um sistema transacional; ele é orientado a experimento. Os principais produtos de saída são soluções de rota, métricas de qualidade e comparações entre algoritmos, possivelmente com gráficos e relatórios gerados por `comparador.py` e `utilitarios/graficos_experimento.py`.

11. **Testes e validação**  
   Há uma suíte simples em `testes/`, com `teste.py`, indicando validação automatizada das partes principais do pipeline. Isso é importante porque o projeto combina leitura de dados, cálculo de distâncias e heurísticas, onde regressões são fáceis de introduzir.

12. **Leitura arquitetural resumida**  
   Em termos de diagrama, o sistema deve ser visto como quatro blocos principais:  
   **(a)** entrada/preprocessamento de dados,  
   **(b)** modelo de domínio do VRP,  
   **(c)** motores de otimização,  
   **(d)** comparação/visualização de experimentos.  
   O OSRM fica fora do core e atua como serviço de infraestrutura para custos reais de deslocamento.

Main entry points: [`src/comparador.py`](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/comparador.py) (Comparador), [`src/geoprocessamento/preprocessamento.py`](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/preprocessamento.py) (Preprocessamento), [`src/algoritmos/busca_tabu.py`](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/busca_tabu.py) (Tabu search), [`src/modelos/solucao.py`](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/solucao.py) (Solução)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Entrada e dados"]
  node_n5["Pedidos<br/>input data"]
  node_n6["Distâncias<br/>cost matrix"]
  node_n7["Preprocessamento<br/>data prep"]
  node_n8["Geocodificador<br/>geocoding<br/>[geocodificador.py]"]
  node_n9["OSRM integração<br/>routing adapter<br/>[integracao_osrm.py]"]
end

subgraph group_g2["Domínio VRP"]
  node_n10[("Instância<br/>vrp instance<br/>[instancia.py]")]
  node_n11["Representação<br/>solution encoding<br/>[representacao.py]"]
  node_n12[("Solução<br/>solution model<br/>[solucao.py]")]
  node_n13["Objetivo<br/>objective config<br/>[objetivo_config.py]"]
end

subgraph group_g3["Otimização"]
  node_n14["Construtivas<br/>init heuristics<br/>[construtivas.py]"]
  node_n15["Local search<br/>refinement<br/>[local_search.py]"]
  node_n16["Simulador<br/>route evaluator<br/>[simulacao_rota.py]"]
  node_n17{{"Tabu search<br/>metaheuristic<br/>[busca_tabu.py]"}}
  node_n18{{"Ant colony<br/>metaheuristic"}}
  node_n19{{"Particle swarm<br/>metaheuristic"}}
  node_n20{{"Baseline<br/>reference solver"}}
end

subgraph group_g4["Experimentos"]
  node_n1(("Main<br/>entrypoint<br/>[main.py]"))
  node_n2["Comparador<br/>orchestrator<br/>[comparador.py]"]
  node_n3["Config<br/>[config.py]"]
  node_n4["Exp config<br/>experiment config"]
  node_n21["Gráficos<br/>visualization"]
  node_n22(("Testes<br/>validation<br/>[teste.py]"))
end

subgraph group_g5["Infraestrutura externa"]
  node_n23[("OSRM server<br/>external service")]
end

node_n1 -->|"executa"| node_n2
node_n1 -->|"lê"| node_n3
node_n1 -->|"lê"| node_n4
node_n2 -->|"roda"| node_n17
node_n2 -->|"roda"| node_n18
node_n2 -->|"roda"| node_n19
node_n2 -->|"roda"| node_n20
node_n5 -->|"entrada"| node_n7
node_n7 -->|"usa"| node_n8
node_n7 -->|"consulta"| node_n9
node_n8 -->|"coordena"| node_n9
node_n9 -->|"requisições"| node_n23
node_n7 -->|"gera"| node_n6
node_n7 -->|"monta"| node_n10
node_n6 -->|"alimenta"| node_n10
node_n10 -->|"codifica"| node_n11
node_n10 -->|"aplica"| node_n13
node_n14 -->|"cria"| node_n11
node_n15 -->|"refina"| node_n11
node_n16 -->|"avalia"| node_n12
node_n17 -->|"inicia"| node_n14
node_n17 -->|"refina"| node_n15
node_n17 -->|"valida"| node_n16
node_n18 -->|"constrói"| node_n14
node_n18 -->|"avalia"| node_n16
node_n19 -->|"inicia"| node_n14
node_n19 -->|"ajusta"| node_n15
node_n19 -->|"avalia"| node_n16
node_n20 -->|"compara"| node_n16
node_n17 -->|"produz"| node_n12
node_n18 -->|"produz"| node_n12
node_n19 -->|"produz"| node_n12
node_n20 -->|"produz"| node_n12
node_n12 -->|"resultados"| node_n2
node_n2 -->|"gera"| node_n21
node_n22 -->|"verifica"| node_n7
node_n22 -->|"verifica"| node_n17

click node_n1 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/main.py"
click node_n2 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/comparador.py"
click node_n3 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/config.py"
click node_n4 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/config_experimento.py"
click node_n5 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/dados/pedidos_pequeno.csv"
click node_n6 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/dados/matriz_distancias.csv"
click node_n7 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/preprocessamento.py"
click node_n8 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/geocodificador.py"
click node_n9 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/integracao_osrm.py"
click node_n10 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/instancia.py"
click node_n11 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/representacao.py"
click node_n12 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/solucao.py"
click node_n13 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/objetivo_config.py"
click node_n14 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/construtivas.py"
click node_n15 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/local_search.py"
click node_n16 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/simulacao_rota.py"
click node_n17 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/busca_tabu.py"
click node_n18 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/colonia_formigas.py"
click node_n19 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/enxame_particulas.py"
click node_n20 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/solver_referencia.py"
click node_n21 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/graficos_experimento.py"
click node_n22 "https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/testes/teste.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n5,node_n6,node_n7,node_n8,node_n9 toneBlue
class node_n10,node_n11,node_n12,node_n13 toneAmber
class node_n14,node_n15,node_n16,node_n17,node_n18,node_n19,node_n20 toneMint
class node_n1,node_n2,node_n3,node_n4,node_n21,node_n22 toneRose
class node_n23 toneIndigo
```

## Components

### Entrada e dados

Insumos, preparação e integração geográfica.

- [Pedidos](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/dados/pedidos_pequeno.csv): input data · Dados de pedidos e demanda de exemplo. · `src/dados/pedidos_pequeno.csv`
- [Distâncias](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/dados/matriz_distancias.csv): cost matrix · Matriz de custos/distâncias usada pelos algoritmos. · `src/dados/matriz_distancias.csv`
- [Preprocessamento](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/preprocessamento.py): data prep · Limpeza e montagem da instância do problema. · `src/geoprocessamento/preprocessamento.py`
- [Geocodificador](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/geocodificador.py): geocoding · Transforma endereços em coordenadas. · `src/geoprocessamento/geocodificador.py`
- [OSRM integração](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/geoprocessamento/integracao_osrm.py): routing adapter · Consulta rotas reais e constrói distâncias por rede viária. · `src/geoprocessamento/integracao_osrm.py`

### Domínio VRP

Modelos centrais da instância, solução e objetivo.

- [Instância](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/instancia.py): vrp instance · Encapsula o caso de teste e seus dados estruturados. · `src/modelos/instancia.py`
- [Representação](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/representacao.py): solution encoding · Codificação interna da solução para os algoritmos. · `src/modelos/representacao.py`
- [Solução](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/solucao.py): solution model · Armazena solução final, custo e métricas. · `src/modelos/solucao.py`
- [Objetivo](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/modelos/objetivo_config.py): objective config · Pesos, regras e restrições da função objetivo. · `src/modelos/objetivo_config.py`

### Otimização

Solvers, heurísticas e operadores de busca.

- [Construtivas](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/construtivas.py): init heuristics · Gera soluções iniciais viáveis. · `src/utilitarios/construtivas.py`
- [Local search](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/local_search.py): refinement · Melhora rotas por busca local. · `src/utilitarios/local_search.py`
- [Simulador](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/simulacao_rota.py): route evaluator · Avalia execução de rotas, tempos e janelas. · `src/utilitarios/simulacao_rota.py`
- [Tabu search](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/busca_tabu.py): metaheuristic · Busca tabu para otimização de rotas. · `src/algoritmos/busca_tabu.py`
- [Ant colony](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/colonia_formigas.py): metaheuristic · Colônia de formigas para construção iterativa de rotas. · `src/algoritmos/colonia_formigas.py`
- [Particle swarm](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/enxame_particulas.py): metaheuristic · Enxame de partículas adaptado ao problema de rotas. · `src/algoritmos/enxame_particulas.py`
- [Baseline](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/algoritmos/solver_referencia.py): reference solver · Solver de referência para comparação experimental. · `src/algoritmos/solver_referencia.py`

### Experimentos

Orquestração, comparação e visualização de resultados.

- [Main](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/main.py): entrypoint · Ponto de entrada da aplicação e início do fluxo principal. · `src/main.py`
- [Comparador](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/comparador.py): orchestrator · Executa métodos e compara resultados entre algoritmos. · `src/comparador.py`
- [Config](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/config.py): runtime config · Parâmetros globais de execução e ambiente. · `src/config.py`
- [Exp config](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/config_experimento.py): experiment config · Configuração específica de experimentos e cenários. · `src/config_experimento.py`
- [Gráficos](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/src/utilitarios/graficos_experimento.py): visualization · Gera gráficos e comparações dos experimentos. · `src/utilitarios/graficos_experimento.py`
- [Testes](https://github.com/marceloanje/otimizador-rotas-foodservice/blob/main/testes/teste.py): validation · Validação automatizada do pipeline principal. · `testes/teste.py`

### Infraestrutura externa

Serviço auxiliar de roteamento usado na construção de distâncias.

- **OSRM server**: external service · Serviço local opcional para custos por rede viária.

## Connections

- Main → Comparador: executa · A entrada dispara a comparação de métodos.
- Main → Config: lê · Carrega configuração global.
- Main → Exp config: lê · Carrega parâmetros experimentais.
- Comparador → Tabu search: roda · O comparador executa a busca tabu.
- Comparador → Ant colony: roda · O comparador executa a colônia de formigas.
- Comparador → Particle swarm: roda · O comparador executa o enxame de partículas.
- Comparador → Baseline: roda · O comparador executa o solver de referência.
- Pedidos → Preprocessamento: entrada · Pedidos alimentam o preprocessamento.
- Preprocessamento → Geocodificador: usa · O preprocessamento pode geocodificar endereços.
- Preprocessamento → OSRM integração: consulta · Pode buscar distâncias reais via OSRM.
- Geocodificador → OSRM integração: coordena · Coordenadas alimentam a integração de rotas.
- OSRM integração → OSRM server: requisições · A integração depende do servidor OSRM local.
- Preprocessamento → Distâncias: gera · O preprocessamento produz ou atualiza a matriz de distâncias.
- Preprocessamento → Instância: monta · Transforma dados preparados em instância VRP.
- Distâncias → Instância: alimenta · A matriz de custos compõe a instância.
- Instância → Representação: codifica · A instância é convertida em representação para busca.
- Instância → Objetivo: aplica · A instância usa a configuração do objetivo.
- Construtivas → Representação: cria · Constrói soluções iniciais na representação interna.
- Local search → Representação: refina · A busca local opera sobre a codificação da solução.
- Simulador → Solução: avalia · Simula e mede a qualidade da solução.
- Tabu search → Construtivas: inicia · A busca tabu parte de uma solução construtiva.
- Tabu search → Local search: refina · Usa vizinhança e busca local.
- Tabu search → Simulador: valida · Avalia custo e restrições durante a busca.
- Ant colony → Construtivas: constrói · A colônia usa heurísticas construtivas.
- Ant colony → Simulador: avalia · Pontua rotas com o simulador.
- Particle swarm → Construtivas: inicia · O enxame usa soluções iniciais.
- Particle swarm → Local search: ajusta · Explora melhorias locais nas partículas.
- Particle swarm → Simulador: avalia · Mede desempenho das partículas.
- Baseline → Simulador: compara · O baseline é avaliado pela mesma lógica.
- Tabu search → Solução: produz · A heurística retorna uma solução final.
- Ant colony → Solução: produz · A meta-heurística retorna uma solução final.
- Particle swarm → Solução: produz · A meta-heurística retorna uma solução final.
- Baseline → Solução: produz · O solver de referência retorna uma solução final.
- Solução → Comparador: resultados · Soluções e métricas voltam para comparação.
- Comparador → Gráficos: gera · A comparação alimenta gráficos experimentais.
- Testes → Preprocessamento: verifica · Os testes validam o preprocessamento e o pipeline.
- Testes → Tabu search: verifica · Os testes cobrem o comportamento dos algoritmos.
