# j3ffreyjr/sistema-de-navega-o-urbana architecture

> Architecture diagram of the GitHub repository j3ffreyjr/sistema-de-navega-o-urbana, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/j3ffreyjr/sistema-de-navega-o-urbana
- Repository: https://github.com/j3ffreyjr/sistema-de-navega-o-urbana

## Overview

Urban Nav is a Spring Boot backend that turns Maputo OpenStreetMap data into a weighted road network, exposes route and POI queries, and supports graph exploration. The main request flow is client → route API → coordinate snapping and algorithm → response; graph setup separately parses OSM and builds name lookup. POI parsing and search form a second capability, with BST-backed name queries. BFS/DFS connectivity exploration and trie autocomplete are documented capabilities; their deeper runtime wiring is not fully shown, so uncertain links are omitted. Relationships below rely on the README and sampled source/index references.

Main entry points: [`src/main/java/com/urbanav/urban_nav/api/RouteController.java`](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/api/RouteController.java) (Route API), [`src/main/java/com/urbanav/urban_nav/poi/PoiService.java`](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiService.java) (POI search), [`src/main/java/com/urbanav/urban_nav/graph/Grafo.java`](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/Grafo.java) (Road graph), [`src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java`](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java) (Dijkstra routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_routes["Route API"]
  node_treeapi["Tree API"]
  node_poiapi["POI API<br/>[PoiController.java]"]
end

subgraph group_map["Road network"]
  node_osm["OSM parser<br/>[OsmParser.java]"]
  node_graphservice["Graph service<br/>[GraphService.java]"]
  node_graph[("Road graph<br/>[Grafo.java]")]
  node_graphnode["Graph node<br/>[NoGrafo.java]"]
  node_osmnode["OSM node<br/>[NodeOsm.java]"]
  node_edge["Weighted edge<br/>[Aresta.java]"]
end

subgraph group_routing["Routing and analysis"]
  node_dijkstra["Dijkstra routes<br/>[Dijkstra.java]"]
  node_bfs["BFS exploration<br/>[BFS.java]"]
  node_dfs["DFS connectivity<br/>[DFS.java]"]
end

subgraph group_places["Places and lookup"]
  node_poiparser["POI parser<br/>[PoiParser.java]"]
  node_poiservice["POI search<br/>[PoiService.java]"]
  node_poi["Place records<br/>[Poi.java]"]
  node_trie["Name trie<br/>[Trie.java]"]
end

subgraph group_structures["Data structures"]
  node_bst["POI BST<br/>[ArvoreBST.java]"]
  node_heap["Min heap<br/>[MinHeap.java]"]
  node_list["Linked list<br/>[ListaLigada.java]"]
  node_queue["Queue<br/>[Fila.java]"]
  node_stack["Stack<br/>[Pilha.java]"]
end

node_client(("API client"))

node_client -->|"requests"| node_routes
node_routes -->|"gets graph"| node_graphservice
node_routes -->|"calculates route"| node_dijkstra
node_routes -->|"runs search"| node_bfs
node_routes -->|"runs traversal"| node_dfs
node_routes -->|"searches places"| node_poiservice
node_graphservice -->|"parses map"| node_osm
node_osm -->|"builds graph"| node_graph
node_graphservice -->|"indexes names"| node_trie
node_graph -->|"stores nodes"| node_graphnode
node_graphnode -->|"stores neighbors"| node_edge
node_edge -->|"targets node"| node_osmnode
node_dijkstra -->|"reads network"| node_graph
node_dijkstra -->|"orders frontier"| node_heap
node_dijkstra -->|"returns path"| node_list
node_bfs -->|"explores network"| node_graph
node_bfs -->|"uses frontier"| node_queue
node_dfs -->|"explores network"| node_graph
node_dfs -->|"uses frontier"| node_stack
node_routes -->|"formats path"| node_list
node_client -->|"requests places"| node_poiapi
node_poiapi -->|"queries"| node_poiservice
node_poiservice -->|"loads places"| node_poiparser
node_poiparser -->|"creates records"| node_poi
node_poiservice -->|"searches names"| node_bst
node_poiservice -->|"returns matches"| node_poi
node_bst -->|"indexes records"| node_poi
node_treeapi -->|"queries tree"| node_poiservice
node_trie -->|"uses list"| node_list
node_graph -->|"stores adjacency"| node_list

click node_routes "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/api/RouteController.java"
click node_treeapi "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/api/TreeController.java"
click node_osm "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/parser/OsmParser.java"
click node_graphservice "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/GraphService.java"
click node_graph "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/Grafo.java"
click node_graphnode "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/NoGrafo.java"
click node_osmnode "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/model/NodeOsm.java"
click node_edge "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/model/Aresta.java"
click node_dijkstra "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java"
click node_bfs "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/BFS.java"
click node_dfs "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/DFS.java"
click node_poiapi "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiController.java"
click node_poiparser "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiParser.java"
click node_poiservice "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiService.java"
click node_poi "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/Poi.java"
click node_trie "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/trie/Trie.java"
click node_bst "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/tree/ArvoreBST.java"
click node_heap "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/heap/MinHeap.java"
click node_list "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/structure/ListaLigada.java"
click node_queue "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/structure/Fila.java"
click node_stack "https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/structure/Pilha.java"

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_routes,node_treeapi,node_poiapi,node_client toneBlue
class node_osm,node_graphservice,node_graph,node_graphnode,node_osmnode,node_edge toneAmber
class node_dijkstra,node_bfs,node_dfs toneMint
class node_poiparser,node_poiservice,node_poi,node_trie toneRose
class node_bst,node_heap,node_list,node_queue,node_stack toneIndigo
```

## Components

### REST API

- [Route API](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/api/RouteController.java): `src/main/java/com/urbanav/urban_nav/api/RouteController.java`
- [Tree API](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/api/TreeController.java): `src/main/java/com/urbanav/urban_nav/api/TreeController.java`
- [POI API](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiController.java): `src/main/java/com/urbanav/urban_nav/poi/PoiController.java`

### Road network

- [OSM parser](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/parser/OsmParser.java): `src/main/java/com/urbanav/urban_nav/parser/OsmParser.java`
- [Graph service](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/GraphService.java): `src/main/java/com/urbanav/urban_nav/graph/GraphService.java`
- [Road graph](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/Grafo.java): `src/main/java/com/urbanav/urban_nav/graph/Grafo.java`
- [Graph node](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/graph/NoGrafo.java): `src/main/java/com/urbanav/urban_nav/graph/NoGrafo.java`
- [OSM node](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/model/NodeOsm.java): `src/main/java/com/urbanav/urban_nav/model/NodeOsm.java`
- [Weighted edge](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/model/Aresta.java): `src/main/java/com/urbanav/urban_nav/model/Aresta.java`

### Routing and analysis

- [Dijkstra routes](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java): `src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java`
- [BFS exploration](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/BFS.java): `src/main/java/com/urbanav/urban_nav/algorithm/BFS.java`
- [DFS connectivity](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/algorithm/DFS.java): `src/main/java/com/urbanav/urban_nav/algorithm/DFS.java`

### Places and lookup

- [POI parser](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiParser.java): `src/main/java/com/urbanav/urban_nav/poi/PoiParser.java`
- [POI search](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/PoiService.java): `src/main/java/com/urbanav/urban_nav/poi/PoiService.java`
- [Place records](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/poi/Poi.java): `src/main/java/com/urbanav/urban_nav/poi/Poi.java`
- [Name trie](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/trie/Trie.java): `src/main/java/com/urbanav/urban_nav/trie/Trie.java`

### Data structures

- [POI BST](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/tree/ArvoreBST.java): `src/main/java/com/urbanav/urban_nav/tree/ArvoreBST.java`
- [Min heap](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/heap/MinHeap.java): `src/main/java/com/urbanav/urban_nav/heap/MinHeap.java`
- [Linked list](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/structure/ListaLigada.java): `src/main/java/com/urbanav/urban_nav/structure/ListaLigada.java`
- [Queue](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/structure/Fila.java): `src/main/java/com/urbanav/urban_nav/structure/Fila.java`
- [Stack](https://github.com/j3ffreyjr/sistema-de-navega-o-urbana/blob/main/src/main/java/com/urbanav/urban_nav/structure/Pilha.java): `src/main/java/com/urbanav/urban_nav/structure/Pilha.java`

### Other components

- **API client**

## Connections

- API client → Route API: requests (evidence: `README.md`)
- Route API → Graph service: gets graph (evidence: `src/main/java/com/urbanav/urban_nav/api/RouteController.java`)
- Route API → Dijkstra routes: calculates route (evidence: `src/main/java/com/urbanav/urban_nav/api/RouteController.java`)
- Route API → BFS exploration: runs search (evidence: `src/main/java/com/urbanav/urban_nav/api/RouteController.java`)
- Route API → DFS connectivity: runs traversal (evidence: `src/main/java/com/urbanav/urban_nav/api/RouteController.java`)
- Route API → POI search: searches places (evidence: `src/main/java/com/urbanav/urban_nav/api/RouteController.java`)
- Graph service → OSM parser: parses map (evidence: `src/main/java/com/urbanav/urban_nav/graph/GraphService.java`)
- OSM parser → Road graph: builds graph (evidence: `src/main/java/com/urbanav/urban_nav/parser/OsmParser.java`)
- Graph service → Name trie: indexes names (evidence: `src/main/java/com/urbanav/urban_nav/graph/GraphService.java`)
- Road graph → Graph node: stores nodes (evidence: `src/main/java/com/urbanav/urban_nav/graph/Grafo.java`)
- Graph node → Weighted edge: stores neighbors (evidence: `src/main/java/com/urbanav/urban_nav/graph/NoGrafo.java`)
- Weighted edge → OSM node: targets node (evidence: `src/main/java/com/urbanav/urban_nav/model/Aresta.java`)
- Dijkstra routes → Road graph: reads network (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java`)
- Dijkstra routes → Min heap: orders frontier (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java`)
- Dijkstra routes → Linked list: returns path (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/Dijkstra.java`)
- BFS exploration → Road graph: explores network (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/BFS.java`)
- BFS exploration → Queue: uses frontier (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/BFS.java`)
- DFS connectivity → Road graph: explores network (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/DFS.java`)
- DFS connectivity → Stack: uses frontier (evidence: `src/main/java/com/urbanav/urban_nav/algorithm/DFS.java`)
- Route API → Linked list: formats path (evidence: `src/main/java/com/urbanav/urban_nav/api/RouteController.java`)
- API client → POI API: requests places (evidence: `src/main/java/com/urbanav/urban_nav/poi/PoiController.java`)
- POI API → POI search: queries (evidence: `src/main/java/com/urbanav/urban_nav/poi/PoiController.java`)
- POI search → POI parser: loads places (evidence: `src/main/java/com/urbanav/urban_nav/poi/PoiService.java`)
- POI parser → Place records: creates records (evidence: `src/main/java/com/urbanav/urban_nav/poi/PoiParser.java`)
- POI search → POI BST: searches names (evidence: `src/main/java/com/urbanav/urban_nav/poi/PoiService.java`)
- POI search → Place records: returns matches (evidence: `src/main/java/com/urbanav/urban_nav/poi/PoiService.java`)
- POI BST → Place records: indexes records (evidence: `src/main/java/com/urbanav/urban_nav/tree/ArvoreBST.java`)
- Tree API → POI search: queries tree (evidence: `src/main/java/com/urbanav/urban_nav/api/TreeController.java`)
- Name trie → Linked list: uses list (evidence: `src/main/java/com/urbanav/urban_nav/trie/Trie.java`)
- Road graph → Linked list: stores adjacency (evidence: `src/main/java/com/urbanav/urban_nav/graph/Grafo.java`)
