MeAd – Medical Web Advisor

1.1 System Architecture Overview

• mead-conditions-service - REST API and RDF repository for medical conditions. Features parallel enrichment from Wikidata, DBpedia, and WikiDoc API, plus a SPARQL endpoint for direct RDF querying.
• mead-geography-service - REST API and RDF repository for 43 geographic locations including continents, countries, and cities. Each location is linked to Wikidata and DBpedia via schema:sameAs properties.
• mead-ui - React single-page application with React Router for navigation, featuring condition search/filtering, paginated lists, and rich detail views with image carousels.

1.2 Technology Stack

1.3 C4 Architecture Diagrams

The MeAd architecture is documented using the C4 model (Context, Container, Component, Code), which provides different levels of abstraction for understanding the system.

C4 Context Diagram

The context diagram shows the MeAd Medical Web Advisor system in relation to its users and external systems. The primary user (High-school student) accesses the platform via browser. The system interacts with multiple external data sources: Wikidata SPARQL and DBpedia SPARQL for data enrichment, WikiDoc API for medical summaries, and Wikipedia REST API for geographic summaries.

C4 Container Diagram

The container diagram details the main components of the MeAd system:

• mead-ui [React] - User interface, single-page application with views for exploring medical conditions and geographic data.
• mead-conditions-service [Spring Boot] - REST microservice managing medical conditions, providing API for CRUD, Wikidata/DBpedia enrichment, and a local SPARQL endpoint.
• mead-geography-service [Spring Boot] - REST microservice for geographic locations (continents, countries, cities), with the same enrichment and SPARQL capabilities.

All containers communicate via HTTP/JSON, and the backend services query external SPARQL endpoints for additional data.

C4 Component Diagram - Conditions Service

The component diagram for mead-conditions-service shows the internal architecture:

• ConditionsController [Spring MVC] - REST endpoints for listing and condition details.
• SparqlController [Spring MVC] - Local SPARQL endpoint for direct RDF queries.
• HealthController [Spring MVC] - Health check endpoint.
• ConditionService [Service] - Orchestrates enrichment and DTO mapping.
• ConditionsRepository [Repository] - Loads RDF data and caches conditions.
• RdfService [Jena] - Loads Turtle files into the in-memory Dataset.
• WikidataClient [SPARQL client] - Fetches symptoms, risk factors, images from Wikidata.
• DbpediaClient [SPARQL client] - Fetches descriptions, symptoms, images from DBpedia.
• WikidocSnippetLoader [HTTP client] - Fetches overviews, causes, risk factors, and symptoms from the WikiDoc API (wikidoc.org).

C4 Component Diagram - Geography Service

The component diagram for mead-geography-service has a similar structure:

• RegionsController [Spring MVC] - REST endpoints for listing and region details.
• SparqlController [Spring MVC] - Local SPARQL endpoint.
• HealthController [Spring MVC] - Health check endpoint.
• GeographyService [Service] - Orchestrates enrichment and DTO mapping.
• RegionsRepository [Repository] - Loads geographic RDF data.
• RdfService [Jena] - Manages the Apache Jena Dataset.
• WikidataClient [SPARQL client] - Fetches population, density, type, images from Wikidata.
• DbpediaClient [SPARQL client] - Fetches descriptions, population, images from DBpedia.
• WikipediaSummaryLoader [HTTP client] - Loads summaries from Wikipedia REST API.

2.1 Overview of Data Structures

The primary entities in the system are MedicalCondition and Place. Each entity is associated with various attributes that describe its properties and external Linked Data links to Wikidata and DBpedia knowledge bases.

2.2 Conditions Service Data Models

The conditions service uses Java records to represent data at different layers:

Repository Layer: Condition Record

public record Condition(
    String identifier,    // Stable slug: "asthma", "type-2-diabetes"
    String name,          // Display label: "Asthma", "Type 2 diabetes"
    List<String> sameAs   // External URIs: Wikidata, DBpedia links
) {}

API Layer: ConditionSummary (List View)

public record ConditionSummary(
    String id,            // Same as identifier
    String name,          // Human-readable name
    List<String> sameAs   // External knowledge base links
) {}

API Layer: ConditionDetail (Enriched View)

public record ConditionDetail(
    String context,       // "https://schema.org/"
    String id,            // Full URI: "https://mead.example/condition/asthma"
    String type,          // "MedicalCondition"
    String identifier,    // Slug identifier
    String name,          // Display name
    String description,   // From DBpedia/Wikidata (dbo:abstract, schema:description)
    List<String> images,  // Normalized image URLs from P18, dbo:thumbnail, foaf:depiction
    List<String> symptoms,     // From P780 (Wikidata) or dbo:symptom (DBpedia)
    List<String> riskFactors,  // From P5642 (Wikidata) or dbo:medicalCause (DBpedia)
    List<String> sameAs,       // External URIs for linked data traversal
    String wikidocSnippet      // Curated student-friendly summary (50 files)
) {}

Enrichment Records

// From WikidataClient
public record WikidataEnrichment(
    String description,
    List<String> symptoms,
    List<String> riskFactors,
    List<String> images
) {}

// From DbpediaClient
public record DbpediaEnrichment(
    String description,
    List<String> symptoms,
    List<String> riskFactors,
    List<String> images
) {}

2.3 Geography Service Data Models

The geography service manages 43 geographic locations including continents (Europe, Asia, Africa, North America, South America, Antarctica), countries (Romania, Germany, France, Spain, Italy, United States, United Kingdom, Japan, Canada, Australia, China, India, Brazil, Mexico, Egypt, South Korea), and cities (Bucharest, Berlin, Paris, Madrid, Rome, New York City, London, Tokyo, and many more).

Place Records

// Repository layer
public record Region(
    String identifier,           // "romania", "bucharest", "europe"
    String name,                 // "Romania", "Bucharest", "Europe"
    List<String> sameAs          // Wikidata/DBpedia URIs for Linked Data
) {}

// API layer
public record RegionSummary(String id, String name) {}

public record RegionDetail(
    String context,              // "https://schema.org/"
    String id,                   // Full URI: "https://mead.example/region/romania"
    String type,                 // "Place"
    String identifier,           // Slug identifier
    String name,                 // Display name
    List<String> sameAs          // External URIs for linked data traversal
) {}

Example Places in the Dataset

2.4 RDF Model and Apache Jena Integration

Both microservices use Apache Jena with in-memory datasets loaded from Turtle (.ttl) files at startup. Data is stored as RDF triples (subject-predicate-object).

Example (Turtle format):

@prefix schema: <https://schema.org/> .
@prefix condition: <https://mead.example/condition/> .

condition:asthma a schema:MedicalCondition ;
    schema:identifier "asthma" ;
    schema:name "Asthma"@en ;
    schema:sameAs <https://www.wikidata.org/entity/Q35869>, <http://dbpedia.org/resource/Asthma> .

The conditions service has 51 medical conditions, the geography service has 43 locations - each with schema:sameAs links to Wikidata and DBpedia.

2.5 Vocabulary and Taxonomy Choices

The ontology is structured around core concepts using schema.org vocabulary. This choice ensures interoperability with the broader Semantic Web and Linked Data ecosystem, as schema.org is widely adopted by major search engines and linked data applications.

In RDF/OWL terminology, classes define the type of an entity (used with rdf:type or a in Turtle syntax), while properties (also called predicates) define relationships or attributes that connect a subject to a value.

Classes Used

Properties Used

External Vocabulary Mappings

When querying external knowledge bases, the system maps to their vocabularies:

3.1 RESTful API Architecture

The APIs follow REST architectural principles:

• Resource-oriented URLs – Collections and individual resources (e.g., /conditions, /conditions/{id})
• HTTP Methods – GET for retrieval, POST for SPARQL queries
• JSON Responses – All endpoints return JSON with application/json content type
• JSON-LD Compatible – Response objects include context, id, and type fields for semantic web compatibility
• CORS Enabled – Cross-origin requests allowed for frontend integration

3.2 Conditions Service API

The Conditions Service provides RESTful access to medical condition data. It serves both lightweight summaries for listing/search and enriched details that aggregate data from Wikidata, DBpedia, and WikiDoc API.

Endpoints Overview

Response Models

ConditionSummary

Lightweight representation used in list responses. Contains only essential identification data:

Example:

GET /mead-conditions-service/api/v1/conditions

[
  { "id": "asthma", "name": "Asthma", "sameAs": ["https://www.wikidata.org/entity/Q35869", "http://dbpedia.org/resource/Asthma"] },
  { "id": "type-2-diabetes", "name": "Type 2 diabetes", "sameAs": ["https://www.wikidata.org/entity/Q3025883", "http://dbpedia.org/resource/Type_2_diabetes"] }
  // ... 48 more conditions
]

ConditionDetail

Full representation with enriched data from external sources. Uses schema.org vocabulary for semantic interoperability:

Example:

GET /mead-conditions-service/api/v1/conditions/asthma

{
  "context": "https://schema.org/",
  "id": "https://mead.example/condition/asthma",
  "type": "MedicalCondition",
  "identifier": "asthma",
  "name": "Asthma",
  "description": "long-term disease involving inflamed airways",
  "images": [
    "https://commons.wikimedia.org/wiki/Special:FilePath/Asthma.jpg",
    "https://commons.wikimedia.org/wiki/Special:FilePath/Asthma_attack.png"
  ],
  "symptoms": ["wheeze", "cough", "inflammation", "chest pain"],
  "riskFactors": ["air pollution", "smoking"],
  "sameAs": [
    "https://www.wikidata.org/entity/Q35869",
    "http://dbpedia.org/resource/Asthma"
  ],
  "wikidocSnippet": "Asthma is a long-term condition that affects the airways..."
}

3.3 Geography Service API

The Geography Service provides RESTful access to geographic location data. It serves both lightweight summaries for listing and enriched details that aggregate data from Wikidata, DBpedia, and WikiDoc API.

Endpoints Overview

Response Models

RegionSummary

Lightweight representation used in list responses:

Example:

GET /mead-geography-service/api/v1/regions

[
  { "id": "romania", "name": "Romania", "type": "country", "sameAs": ["https://www.wikidata.org/entity/Q218", "http://dbpedia.org/resource/Romania"] },
  { "id": "bucharest", "name": "Bucharest", "type": "city", "sameAs": ["https://www.wikidata.org/entity/Q19660", "http://dbpedia.org/resource/Bucharest"] },
  { "id": "europe", "name": "Europe", "type": "continent", "sameAs": ["https://www.wikidata.org/entity/Q46", "http://dbpedia.org/resource/Europe"] }
  // ... 40 more regions
]

RegionDetail

Full representation with enriched data from external sources:

Example:

GET /mead-geography-service/api/v1/regions/romania

{
  "context": "https://schema.org/",
  "id": "https://mead.example/region/romania",
  "type": "country",
  "identifier": "romania",
  "name": "Romania",
  "description": "Romania is a country in Southeastern Europe...",
  "populationTotal": "19053815",
  "populationDensity": "80.12",
  "climates": ["humid continental climate", "oceanic climate"],
  "industrialDevelopment": ["automotive industry", "information technology"],
  "culturalFactors": ["Romanian", "Romanians"],
  "images": ["https://commons.wikimedia.org/wiki/Special:FilePath/Romania_location_map.svg"],
  "sameAs": [
    "https://www.wikidata.org/entity/Q218",
    "http://dbpedia.org/resource/Romania"
  ],
  "wikidocSnippet": "Romania is a country located in southeastern Europe..."
}

4.1 Ontology Design Decisions

The knowledge model follows these design principles:

• Schema.org as foundation: Using widely-adopted vocabulary ensures compatibility with search engines and semantic web tools
• Minimal local vocabulary: Only introducing custom URIs where schema.org doesn't provide suitable classes
• Linked Data extensions: Leveraging schema:sameAs to connect to richer external ontologies
• Separation of concerns: Distinct datasets for medical conditions and geographic data

Namespace Definitions

@prefix schema:    <https://schema.org/> .
@prefix condition: <https://mead.example/condition/> .   # Medical conditions namespace (51 entities)
@prefix region:    <https://mead.example/region/> .      # Geographic locations namespace (43 entities)
@prefix xsd:       <http://www.w3.org/2001/XMLSchema#> . # XML Schema datatypes

Entity URI Patterns

4.2 Knowledge Graph Structure

The system maintains two separate RDF knowledge graphs loaded into Apache Jena datasets:

Conditions Knowledge Graph Statistics

Geography Knowledge Graph Statistics

5.1 Wikidata Knowledge Base Integration

The WikidataClient fetches enriched data from Wikidata's SPARQL endpoint. All queries run in parallel using CompletableFuture for optimal performance.

Data Retrieved

Example SPARQL Query (Symptoms)

SELECT DISTINCT ?symptomLabel WHERE {
  wd:Q35869 wdt:P780 ?symptom .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
} LIMIT 30

5.2 DBpedia Enrichment Strategies

The DbpediaClient fetches Wikipedia-derived data from DBpedia's SPARQL endpoint. It uses fallback chains to maximize data coverage when primary properties are empty.

Data Retrieved with Fallback Strategy

Example SPARQL Query (Images with UNION)

SELECT DISTINCT ?img WHERE {
  { <http://dbpedia.org/resource/Asthma> dbo:thumbnail ?img . }
  UNION { <http://dbpedia.org/resource/Asthma> foaf:depiction ?img . }
  UNION { <http://dbpedia.org/resource/Asthma> schema:image ?img . }
} LIMIT 10

5.3 Non-trivial SPARQL Query Patterns

The system uses advanced SPARQL patterns to maximize data coverage from external knowledge bases.

Query 1: Wikidata Label Service

Fetches symptoms for a condition using Wikidata's built-in label resolution service:

PREFIX wd: <http://www.wikidata.org/entity/>
PREFIX wdt: <http://www.wikidata.org/prop/direct/>
PREFIX wikibase: <http://wikiba.se/ontology#>
PREFIX bd: <http://www.bigdata.com/rdf#>

SELECT DISTINCT ?symptomLabel WHERE {
  wd:Q35869 wdt:P780 ?symptom .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
} LIMIT 30

Pattern: The SERVICE wikibase:label automatically resolves entity URIs to human-readable labels (e.g., Q35869 → "Asthma").

Query 2: UNION for Multiple Image Sources (DBpedia)

Combines multiple image predicates to maximize coverage:

PREFIX dbo: <http://dbpedia.org/ontology/>
PREFIX dbp: <http://dbpedia.org/property/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX schema: <http://schema.org/>

SELECT DISTINCT ?img WHERE {
  { <http://dbpedia.org/resource/Romania> dbo:thumbnail ?img . }
  UNION { <http://dbpedia.org/resource/Romania> foaf:depiction ?img . }
  UNION { <http://dbpedia.org/resource/Romania> schema:image ?img . }
  UNION { <http://dbpedia.org/resource/Romania> dbp:image ?img . }
} LIMIT 10

Pattern: UNION combines results from multiple predicates, ensuring images are found regardless of which property DBpedia uses.

Query 3: Dereferencing with rdfs:label (DBpedia)

Resolves resource URIs to human-readable labels:

PREFIX dbo: <http://dbpedia.org/ontology/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT DISTINCT ?label WHERE {
  <http://dbpedia.org/resource/Romania> dbo:officialLanguage ?langResource .
  ?langResource rdfs:label ?label .
  FILTER(LANG(?label) = "en")
} LIMIT 50

Pattern: When a property points to another resource (not a literal), we follow the link and fetch its rdfs:label for a human-readable name.

5.4 Conformance to Linked Data Principles

MeAd follows Tim Berners-Lee's four Linked Data principles:

Use Cases

Case Study 1: Exploring a Medical Condition

Case Study 2: Exploring Geographic Data