Skip to main content
The semantic web package shipping system is built using a microservices architecture with two main services that communicate via REST APIs.

​
Architecture Overview

​
Microservices

​
1. Shipment Service (svc-envio-encomienda)

Port: 8080
Technology: Spring Boot + MySQL + JPA/Hibernate
This service handles all CRUD operations for shipments, clients, and branches (sucursales).
Key Components:
  • Controllers: REST API endpoints
    • EnvioController (svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/web/EnvioController.java:19)
    • ClienteController
    • SucursalController
  • Services: Business logic
    • EnvioServiceImpl (svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/servicios/Impl/EnvioServiceImpl.java:32)
    • Handles state transitions
    • Validates business rules
  • Entities:
    • Envio (svc-envio-encomienda/src/main/java/org/jchilon3mas/springcloud/svc/envio/encomienda/entidades/Envio.java:17)
    • Cliente
    • Encomienda
    • Sucursal
  • Integration Service:
    • IntegracionSemanticaService sends shipment data to semantic service automatically
Configuration: 
# application.properties
spring.application.name=svc-envio-encomienda
server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/bd_envio_encomienda

# Semantic service endpoint
microservicio.semantica.url=http://localhost:8081/api/v1/grafo

​
2. Semantic Service (svc-web-semantica)

Port: 8081
Technology: Spring Boot + Apache Jena + OWL/RDF
This service manages the semantic knowledge graph and provides natural language search capabilities.
Key Components:
  • Controller: SemanticController (svc-web-semantica/src/main/java/org/jchilon3mas/springcloud/svc/web/semantica/svc_web_semantica/controllers/SemanticController.java:14)
  • Services:
    • SemanticService: Manages RDF triples, executes SPARQL queries
    • BusquedaSemanticaService (svc-web-semantica/src/main/java/org/jchilon3mas/springcloud/svc/web/semantica/svc_web_semantica/services/BusquedaSemanticaService.java:18): Translates natural language to SPARQL
  • Ontology: encomiendas.ttl defines the semantic structure
  • Storage: Apache Jena TDB (file-based RDF database)
Configuration: 
# application.properties
spring.application.name=web-semantica
server.port=8081
jena.tdb.directory=tdb_data

​
Data Flow

​
Creating a Shipment

1

Client sends POST request

Request to POST /api/v1/envios with shipment details
2

Controller validates and delegates

EnvioController receives request and calls EnvioServiceImpl.registrarEnvio()
3

Business logic execution

  • Validates client exists
  • Validates origin/destination branches
  • Generates tracking code: ENV-{timestamp}
  • Generates 4-digit delivery password
  • Sets initial state: PENDIENTE
4

Save to MySQL

Entity saved via JPA repository
5

Automatic synchronization

IntegracionSemanticaService.notificarNuevoEnvio() sends shipment data to semantic service:
// From EnvioServiceImpl.java:121
Envio envioGuardado = envioRepository.save(nuevoEnvio);
integracionSemanticaService.notificarNuevoEnvio(envioGuardado);
return mapper.deEnvio(envioGuardado);
6

Convert to RDF triples

Semantic service receives data at POST /api/v1/grafo/sincronizar-envio and creates RDF triples based on the ontology:
<http://www.encomiendas.com/cliente/12345678> a enc:Cliente ;
    enc:tieneNombre "Juan Pérez" ;
    enc:tieneDni "12345678" ;
    enc:realizaEnvio <http://www.encomiendas.com/envio/ENV-1234567890> .

<http://www.encomiendas.com/envio/ENV-1234567890> a enc:Envio ;
    enc:codigoSeguimiento "ENV-1234567890" ;
    enc:tieneEstado "PENDIENTE" ;
    enc:contienePaquete "Laptop Dell XPS 15" ;
    enc:tienePesoKg "2.5"^^xsd:decimal .
7

Store in TDB

RDF triples stored in Apache Jena TDB for querying

​
Semantic Search Query

1

Client sends natural language query

Request to GET /api/v1/grafo/buscar?texto=envios pendientes
2

Natural language processing

BusquedaSemanticaService.procesarLenguajeNatural() (svc-web-semantica/src/main/java/org/jchilon3mas/springcloud/svc/web/semantica/svc_web_semantica/services/BusquedaSemanticaService.java:33) extracts parameters:
  • States: pendiente, en tránsito, entregado, cancelado, disponible
  • Dates: “hoy”, “ayer”, “esta semana”, “DD/MM/YYYY”, date ranges
  • Weight: “entre 2 y 5 kg”, “más de 10 kg”
  • Cities: Lima, Cusco, Arequipa, etc.
  • DNI: 8-digit patterns
  • Phone: 9-digit patterns
  • Tracking codes: ENV-xxxxxxxxxx
  • Vehicle plates: ABC-123 format
3

SPARQL query construction

Constructs SPARQL query based on extracted parameters:
PREFIX enc: <http://www.encomiendas.com/ontologia#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?codigo ?nombreRemitente ?estado ?peso
WHERE {
    ?clienteURI enc:realizaEnvio ?envioURI .
    ?clienteURI enc:tieneNombre ?nombreRemitente .
    ?envioURI enc:tieneEstado ?estado .
    ?envioURI enc:codigoSeguimiento ?codigo .
    OPTIONAL { ?envioURI enc:tienePesoKg ?peso }
    FILTER (?estado = "PENDIENTE") .
}
4

Execute against TDB

SemanticService.ejecutarConsultaSparql() runs query against Apache Jena TDB
5

Return results

Results returned as JSON array of maps with shipment details

​
Communication Patterns

​
Synchronous REST Communication

The shipment service communicates with the semantic service via HTTP: 
@Value("${microservicio.semantica.url}")
private String semanticaUrl;

// HTTP POST to sync shipment data
restTemplate.postForEntity(
    semanticaUrl + "/sincronizar-envio",
    envioSemanticoDTO,
    String.class
);
If the semantic service is down, shipments will still be saved to MySQL but won’t be searchable semantically until synchronized.

​
Manual Synchronization

You can manually sync all shipments: 
curl -X POST http://localhost:8080/api/v1/envios/sincronizar-todos
This is useful for:
  • Initial setup with existing data
  • Recovery after semantic service downtime
  • Testing and development

​
Scalability Considerations

​
Current Architecture

  • Single instance of each service
  • File-based RDF storage (TDB)
  • Synchronous communication

​
Future Improvements

Asynchronous Messaging

Replace REST calls with message queue (RabbitMQ, Kafka) for better decoupling and reliability

Service Discovery

Implement Eureka or Consul for dynamic service registration

API Gateway

Add Spring Cloud Gateway for unified entry point

Distributed TDB

Use Apache Jena Fuseki server for distributed RDF storage

​
Technology Stack

ComponentTechnologyPurpose
FrameworkSpring Boot 3.xMicroservices foundation
DatabaseMySQL 8.0+Relational data storage
ORMJPA/HibernateObject-relational mapping
RDF StoreApache Jena TDBTriple store for semantic data
Query LanguageSPARQLSemantic graph queries
OntologyOWL 2Knowledge representation
HTTP ClientRestTemplateInter-service communication
Build ToolMavenDependency management

​
Next Steps

Semantic Web Concepts

Learn about RDF, OWL, and semantic technologies

Ontology Structure

Explore the encomiendas.ttl ontology

Build docs developers (and LLMs) love

Get started for freeTalk to us