Skip to content

Technical Details

Jump to bottom
Daniel Heward-Mills edited this page Sep 27, 2025 · 1 revision

Technical Details

This document provides technical information about SPARQLWorks™ architecture, implementation details, and integration capabilities.

🏗️ Architecture Overview

Client-Side Application

SPARQLWorks is a single-page web application built entirely in the browser:

  • No server component: All processing happens client-side
  • Progressive Web App: Installable and offline-capable
  • Responsive design: Works on desktop, tablet, and mobile
  • Modern browser requirements: ES6+ support required

Technology Stack

Core Technologies

  • Frontend Framework: Vanilla JavaScript (ES6+)
  • Visualization: D3.js v7 (Data-Driven Documents)
  • Styling: Tailwind CSS (Utility-first CSS framework)
  • Code Editor: Ace Editor (Professional code editing)
  • Graph Processing: JSON-LD, RDF/Linked Data

Browser APIs Used

  • Fetch API: HTTP requests to SPARQL endpoints
  • Local Storage: Client-side data persistence
  • URL API: Parameter parsing and manipulation
  • Web Crypto API: PKCE challenge generation for OAuth
  • DOM APIs: Dynamic interface manipulation

🔄 Data Processing Pipeline

1. Query Construction

Basic Mode:

  • User inputs triple patterns in text area
  • Automatic CONSTRUCT query generation
  • Prefix expansion and CURIE handling
  • LIMIT clause management

Advanced Mode:

  • Direct SPARQL input with syntax highlighting
  • Full query validation
  • Custom prefix declarations
  • Complex SPARQL feature support

2. SPARQL Execution

HTTP Request:

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Accept': 'application/ld+json, application/json;q=0.9',
    'Authorization': `Bearer ${token}` // If authenticated
  },
  body: `query=${encodeURIComponent(query)}&format=application/ld+json`
});

Response Processing:

  • JSON-LD format parsing
  • Error handling and user feedback
  • Raw data caching for re-processing

3. Graph Construction

JSON-LD to Graph Conversion:

  • Node creation: IRI, literal, and blank node handling
  • Relationship extraction: Triple to edge conversion
  • Type inference: RDF type and datatype detection
  • Label resolution: Multi-predicate label prioritization

Node Classification:

// Automatic node grouping based on characteristics
function classifyNode(node) {
  if (node['@id']) {
    if (node['@id'].startsWith('_:')) return 'blank';
    return 'iri';
  }
  return 'literal';
}

4. Visualization Rendering

Force-Directed Layout:

  • D3.js simulation with custom forces
  • Real-time position updates
  • Collision detection and resolution
  • Performance optimization for large graphs

Interactive Elements:

  • SVG-based rendering with CSS styling
  • Event handling for user interactions
  • Dynamic updates without full re-renders
  • Accessibility features and keyboard navigation

🎨 D3.js Integration

Force Simulation Configuration

const simulation = d3.forceSimulation()
    .force("link", d3.forceLink()
        .id(d => d.id)
        .distance(180)
        .strength(0.6))
    .force("charge", d3.forceManyBody()
        .strength(-600))
    .force("collision", d3.forceCollide()
        .radius(d => getNodeRadius(d) + 12)
        .iterations(3))
    .force("center", d3.forceCenter(width / 2, height / 2))
    .alphaDecay(0.02)
    .velocityDecay(0.3)
    .on("tick", ticked);

Node Rendering

const node = svg.selectAll(".node")
    .data(nodes)
    .join("circle")
    .attr("class", "node")
    .attr("r", d => getNodeRadius(d))
    .attr("fill", d => color(d.group))
    .call(drag(simulation));

Edge Rendering

const link = svg.selectAll(".link")
    .data(links)
    .join("line")
    .attr("class", "link-path")
    .attr("marker-end", "url(#arrowhead)")
    .attr("marker-start", d => isSymmetricPredicate(d.predicate) ? "url(#arrowhead-start)" : null);

🔐 Authentication Architecture

OAuth 2.0 Implementation

PKCE Flow:

  1. Challenge Generation: Cryptographically secure random challenge
  2. State Protection: CSRF prevention with nonce
  3. Dynamic Registration: Client registration for compatible servers
  4. Token Storage: Secure client-side credential management

Security Features:

  • Code Challenge: SHA-256 hashed verifier
  • State Validation: Prevents authorization code interception
  • HTTPS Enforcement: Secure transport required
  • Token Isolation: Per-origin credential storage

Bearer Token Handling

Simple Authentication:

  • Direct token input and validation
  • Automatic header inclusion
  • Credential persistence
  • Manual token refresh

📊 Performance Optimization

Graph Rendering

Efficient Updates:

  • D3.js enter/update/exit pattern
  • Minimal DOM manipulation
  • Virtual scrolling for large datasets
  • Progressive loading

Memory Management:

  • Automatic cleanup of unused elements
  • Object pooling for frequent updates
  • Garbage collection optimization
  • Browser memory limit awareness

Query Optimization

Client-Side Processing:

  • Parallel label resolution
  • Batched DOM updates
  • Debounced user interactions
  • Lazy evaluation of expensive operations

🌐 Browser Compatibility

Supported Browsers

  • Chrome: 80+ (recommended)
  • Firefox: 75+
  • Safari: 13+
  • Edge: 80+
  • Mobile browsers: iOS Safari 13+, Chrome Mobile 80+

Required Features

  • ES6 Modules: Modern JavaScript support
  • Fetch API: HTTP request handling
  • Web Crypto API: OAuth security
  • Local Storage: Settings persistence
  • SVG Support: Graph rendering
  • CSS Grid/Flexbox: Layout management

🔌 Integration Capabilities

External Endpoints

SPARQL Protocol:

  • SPARQL 1.1 Query compliance
  • JSON-LD result format
  • CORS-enabled endpoints
  • Authentication support

Endpoint Compatibility:

  • Virtuoso: Full feature support
  • Blazegraph: Standard compliance
  • Jena Fuseki: SPARQL 1.1 support
  • Wikidata: Public endpoint
  • DBpedia: Large dataset support

API Integration

Programmatic Access:

  • URL parameter API for configuration
  • Query sharing and bookmarking
  • State serialization
  • External tool integration

📦 Build and Deployment

Development Setup

Prerequisites:

  • Modern web server (nginx, Apache, etc.)
  • HTTPS support for OAuth
  • CORS configuration for endpoints

Build Process:

  • No compilation required (vanilla JS)
  • CSS processed via Tailwind CDN
  • External dependencies via CDN
  • Self-contained single HTML file

Deployment Options

Static Hosting:

  • GitHub Pages
  • Netlify
  • Vercel
  • Any static web host

Enterprise Deployment:

  • Internal web servers
  • CDN distribution
  • Docker containers
  • Offline installations

🔧 Extensibility

Plugin Architecture

Extension Points:

  • Custom visualization renderers
  • Additional data formats
  • New authentication methods
  • Custom query builders

Customization Options

Theming:

  • CSS variable overrides
  • Custom color schemes
  • Font and typography changes
  • Layout modifications

Functionality:

  • Additional node/edge types
  • Custom force layouts
  • Alternative visualizations
  • Export capabilities

🐛 Debugging and Development

Browser Developer Tools

Console Logging:

  • Query execution details
  • Graph construction metrics
  • Performance timing
  • Error stack traces

Network Monitoring:

  • SPARQL request/response inspection
  • Authentication flow debugging
  • CORS issue identification
  • Performance bottleneck analysis

Debug Features

URL Parameters:

  • ?debug=1: Enables verbose logging
  • ?trace=1: Detailed execution tracing
  • ?perf=1: Performance metrics

Local Storage Keys:

  • sparqlworks.debug: Debug mode toggle
  • sparqlworks.perf: Performance monitoring
  • Various setting persistence keys

📈 Performance Metrics

Graph Size Handling

  • Small (< 100 nodes): Instant rendering
  • Medium (100-1000 nodes): < 2s rendering
  • Large (1000+ nodes): < 5s rendering with optimizations
  • Very Large: Progressive loading and filtering

Memory Usage

  • Base application: ~5MB
  • Per 1000 nodes: ~2MB additional
  • Large graphs: Memory pooling prevents leaks
  • Automatic cleanup: Unused data garbage collected

Network Performance

  • Query execution: Depends on endpoint response time
  • JSON-LD parsing: Linear with result size
  • Graph construction: O(n) with n = triple count
  • Rendering: O(n) with D3.js optimizations

🔒 Security Considerations

Client-Side Security

Data Handling:

  • No sensitive data storage server-side
  • All processing in user's browser
  • Credentials isolated per origin
  • No cross-origin data leakage

Authentication Security:

  • OAuth tokens stored securely
  • PKCE prevents code interception
  • HTTPS required for OAuth
  • Automatic token cleanup

Content Security Policy

Recommended CSP:

default-src 'self';
script-src 'self' https://d3js.org https://cdn.tailwindcss.com https://cdn.jsdelivr.net;
style-src 'self' 'unsafe-inline' https://cdn.tailwindcss.com;
connect-src https: wss:;

📋 API Reference

Global Objects

Window Properties:

  • window.urlFormat: Current IRI opening format
  • window.describeBase: Entity description service URL
  • window.setQueryMode(mode): Change query mode programmatically

Internal APIs

Query Processing:

  • runSparqlConstruct(): Execute current query
  • jsonldToGraph(json): Convert JSON-LD to graph data
  • updateGraph(): Refresh visualization

Authentication:

  • handleOAuthLogin(): Initiate OAuth flow
  • getAccessToken(): Retrieve current token

🤝 Contributing

Development Guidelines

Code Style:

  • ES6+ JavaScript with modules
  • JSDoc comments for functions
  • Consistent naming conventions
  • Error handling best practices

Testing:

  • Cross-browser compatibility testing
  • Endpoint integration testing
  • Performance benchmarking
  • Security auditing

Extension Development

Plugin Interface:

// Example plugin structure
const myPlugin = {
  name: 'My Visualization',
  init: function(app) {
    // Plugin initialization
  },
  render: function(data) {
    // Custom rendering logic
  }
};

← URL Parameters | Next: FAQ →

Clone this wiki locally