Overview of the EHRI Portal and Admin front-end

Frameworks and technologies

The portal front end is built on the Play framework, as of this writing at version 2.6.10, using the Scala APIs. Like most Play apps it uses SBT as the build tool, which also provides an interactive running and testing environment.

The primary source of data is the Neo4j-based data backend, but the app also uses a number of other data sources including:

  • a PostgreSQL database for storing various non-archival data, including user accounts

  • Google Docs

  • Neo4j directly, via the Cypher HTTP endpoint

General Application Structure and Modules

The application consists of a number of modules, in a somewhat layered manner:

backend

The backend module is the foundation of the app and provides the basic vocabulary for interacting with the backend data service.

core

The core module depends on the backend module and extends it with definitions for the various models, additional services, authentication and authorisation, and plumbing for actions common throughout the app. Notably the core module uses Play's action composition mechanism to make the building blocks for common patterns of data usage, such as CRUD and access control to specific pages and resources. In almost all cases these components leverage the backend's access control and permission mechanisms directly.

There are no actions (or routes) defined directly in the core module itself.

portal

The portal module contains the public user-facing actions and routes.

api

The api module depends on the portal module and contains actions for the various structured data interfaces available under the /api path.

admin

The admin module depends on the portal module and contains provides various actions for administering portal data. Its routes live under the /admin path.

guides

The guides module also depends on the portal module and handles the public and administrative actions available for viewing and managing the EHRI research guides.

Generic Controller Interfaces

See the controllers page.

Model Layer

See the models page.

Ad-hoc Data Querying via Cypher

Occasionally we need to access some niche data and it's much easier just to query the database with Cypher than use the backend web service. This is a bit unpleasant because it breaks the DB abstraction layer but ¯\_(ツ)_/¯.

See the Cypher page for more details.

Testing

We endeavour to write tests (at least integration tests) for all new features.

See the Testing page for more details.

Issues and Technical Debt

Notable bits of technical debt include:

  • Features relating to the Research Guides are no longer developed and essentially deprecated

  • Features related to virtual collections was not finished in the scope of EHRI 1 and not funded in EHRI 2

  • The action composition mechanism is based around extending traits rather than injected components, which is the newer Play Framework style

  • Some of the code related to integrating with Solr, parsing responses/facets etc, could really do with a clean up

  • The handling for assets like LESS files or javascripts could be streamlined, preferably figuring out a way to have all the admin style assets in the portal module, which otherwise doesn't know anything about the admin module

  • The LESS itself could do with streamlining and a careful refactoring (and preferably converting to SASS)

  • Probably a lot else!