Backend architecture
This page documents the architecture of the PHP backend code of Skosmos. It is meant as an introduction to the codebase and explains the most important components.
The Skosmos PHP backend codebase follows the Model-View-Controller software design pattern. The Model module is responsible for managing all data; it handles the Skosmos configuration, the connections to SPARQL endpoints and external lookup services, and the representation of data in a structure that is easy to handle by the View module. The View module consists of templates that generate HTML code for browsers and other web clients. The Controller module ties together the Model and View; it reacts to user actions, queries the Model for data, passes the data to the View for rendering and returns the result to the user.
The diagram below illustrates the MVC modules and the most important classes within each module. Not all utility classes etc. are included.
The central class in the Model module is called Model. It represents global application state. Global application data (e.g. which vocabularies have been configured and global search over all vocabularies) are accessed directly through the Model object. The individual vocabularies (represented as Vocabulary objects) can be found by getVocabulary and getVocabularies methods. Vocabulary-specific data (e.g. individual concepts or search within a single vocabulary) is accessed through the Vocabulary objects. The Model and Vocabulary classes in turn access the data either from the configuration classes or the SPARQL and Resolver submodules (see below).
Global configuration (usually the first section of the config.ttl file) is handled by the GlobalConfig class. Vocabulary-specific configuration is handled by VocabularyConfig objects.
The Request class represents a single HTTP request originating from the user. It holds all the information about the request, for example the UI and content language, the page type (or REST API method) and any parameters such as concept URI or search string.
Many methods in the Model and Vocabulary classes return instances that are subclasses of DataObject. It functions as a wrapper around an EasyRdf\Resource object, which represents an RDF resource (for example a vocabulary in the configuration file, or a concept in a SKOS vocabulary). The View module never works directly on EasyRdf\Resource objects; instead, the templates access methods in the DataObject classes. The VocabularyDataObject is a subclass of DataObject that also holds a reference to a particular Vocabulary.
The Concept class represents an individual concept within a vocabulary. It contains ConceptProperty objects, which represent individual RDF properties such as skos:broader and skos:definition (with one or more values). The values of a property are represented by the classes ConceptPropertyValue (for RDF resources, e.g. other concepts in the same vocabulary), ConceptPropertyValueLiteral (for RDF literals such as labels, notes and definitions) and ConceptMappingPropertyValue (the values of mapping properties such as skos:closeMatch, which are most likely concepts in another vocabulary).
The SPARQL submodule consists of two classes, GenericSparql and JenaTextSparql. These are used to access the vocabulary data available on the SPARQL endpoint, following the Data Access Object (DAO) design pattern. GenericSparql implements the access methods using generic SPARQL 1.1 facilities. JenaTextSparql is a subclass of GenericSparql that overrides some methods with more efficient implementations that are specific to Apache Jena Fuseki and the jena-text index.
The Resolver submodule is responsible for connecting to external resolution services such as Wikidata, the Library of Congress id.loc.gov service and any generic Linked Data URI lookup services.
The View module consists of Twig templates for generating HTML pages. The main template that generates the overall HTML page structure is called light.twig. It is extended by many templates specific to particular page types. There are also common shared template blocks concept-shared and vocab-shared that other templates include, in subroutine call style.
The Controller module consists of three classes: the abstract base class Controller and its subclasses WebController and RestController, which handle the HTML web user interface and the REST API, respectively. The Controller classes contain methods that correspond to specific user actions.
The scripts index.php and rest.php function as entry points into the PHP application code. index.php is used to bootstrap the HTML user interface (using WebController) while rest.php bootstraps the REST API (using RestController). These scripts map URL patterns to corresponding controller methods and execute them.
A .htaccess file (for Apache) is used to rewrite URLs to these entry point scripts.
The static resources that are part of the frontend live under the resources/ directory. In addition, some frontend libraries (e.g. Bootstrap and jQuery) are managed by Composer and stored under the components directory.
The translation files store the language-specific strings visible in the UI in the traditional gettext format. They are stored under resource/translations/. The *.po files contain the strings in a plain text format that is then compiled to the binary *.mo format for actual use. See Translation for some more details.