PubPub Platform Technical Overview

We are rebuilding PubPub from the ground up, with the aim to make the platform much more flexible. This explainer provides a plain-English overview of the new PubPub, known officially as PubPub Platform, and technically as v7.

The core principle behind v7 is flexibility. We are designing the platform to adapt to any number of uses, including (to name a few) reports, journals, books, preprint servers, conference proceedings, and dataset collections. The platform is in active development, with one use case — overlay review projects — already supported.

v7 is designed to make what each Community publishes — its Pubs — much more flexible. Communities specify the kinds of Pubs they work with, by defining what we call their PubTypes. The idea is that a commissioned report, for example, has a different set of metadata and content requirements than, say, a book review. In v7, each Community can customize what counts as a Pub.

There’s a second, equally important way that v7 is designed for customization. Every Community has its own Workflows, the steps that a raw submission goes through on the path to publication. Every preprint server, for example, has its own moderation process; a journal, likewise, might conduct peer review on research articles, but not invited commentaries. We are designing v7 to let every Community define its own workflows, and to modify those over time.

So v7 is flexible in two key respects: in terms of (1) product (i.e., Pubs) and (2) process (i.e., Workflows). In that sense, v7 builds on PubPub’s original design. The aim, with every iteration, has been to provide Communities with a flexible platform, and then watch as groups use PubPub in unexpected and innovative ways. With v7, we are doubling-down on that original purpose.

Under the hood, we have built v7 on a hub-and-spoke model. There’s the PubPub Core, where its basic operations live. This core is relatively lean, by design. The real power of v7 comes from its spokes, the Community-defined Workflows. The idea is to enable a Community to build its own Workflows — to specify the steps to publication for each its custom PubType. We call these steps Stages, which Communities order in a visual sequence using a drag-and-drop interface. A Workflow is, in effect, a defined sequence of Stages.

Every Stage, in turn, is configurable according to a Community’s needs. The main way that a Community configures a Stage is to assign it one or more Actions — modular applets that do things with Pubs. An Action, for example, might assign a Digital Object Identifier (DOI) to a Pub; another could send an invitation email to a peer reviewer. The point is that Actions act on Pubs to make things happen.

These Actions, in every case, are attached to a Stage. Some Actions, depending on a Community’s preferences, can run automatically, when a Pub enters a new Stage. Others may be triggered manually. The upshot is that Communities can adapt Workflows, at a granular level, to their own goals and procedures.

We can illustrate the flexibility at the heart of v7 with a use case that we have already implemented: the overlay review. The basic idea behind overlay review is to evaluate works that are posted elsewhere — preprints, for example. A Community, with this use case in mind, could define a preprint PubType, and set up a Stage to ingest a preprint’s metadata. Depending on its process, the Community could add a second Stage, to notify the preprint’s authors — to check, for example, for the latest version, or to solicit a potential reply to the reviews.

For the review process itself, the Community would lay out a series of additional Stages, tailored to their preferences: A Prospective Reviewer Stage, for example, powered by an Action that prompts for reviewer details like name and email address. An Invitation Stage would, in turn, issue an email invite, based on a Community-defined template. A series of reminder could be set up, as successive Stages, each assigned its own templated-email Action.

Stages for Decline and Accept, to extend the example, would define what happens when an invited reviewer responds. An Accept could, for example, trigger an email with instructions and a link to a bespoke reviewer form, with details about the preprint. A form submission would, in turn, move the Pub to a new Stage — call it Submitted — with an Action that kicks off another templated email, this time to a designated Community administrator. And so on, until the overlay review Workflow is built out, and ready for active use.

Our core assumption is that no two Communities will want the same Workflow — not in the overlay review case, nor for any others. Each Community will build and adapt Workflows according to their own particular needs. Our plan is to offer a gallery with pre-defined Workflows for the most common use cases — templates that a Community can tweak and customize. In the meantime, we are working with a select group of partner Communities to build out common use cases, with Workflows, Stages, and Actions to match.

We have set up Workflows so that it’s easy to divide up tasks among Community team members. Each Workflow can be exposed to designated members, according to the Community’s settings. As a Pub moves through a Workflow, moreover, Stages can be claimed by a member, or assigned to another. If a Stage is assigned — delegated to an editorial assistant, for example — that member will only see their assigned Stage (unless their permission status grants them broader access).

We built the backend user interface to make working in v7 efficient. We expect that most of a Community’s members will spend the bulk of their time in the Dashboard view. Here members can expose just those items — Pubs, Workflows, Stages, and Actions — that are their responsibility. Much of the set-up work, like adding and modifying Stages, defining Actions and customizing Forms, happens in the other views intended for Community administrators.

The main idea behind v7 is that what counts as a Pub is up to each Community. This principle extends to a Pub’s relationship to other Pubs. In v7, a Pub can “contain” a group of other Pubs. A book, for example, includes its chapter Pubs, just as a journal issue contains its articles. Another way to say this is to call the book and journal issue “parent” Pubs, and the chapter and articles their “children.” The ability to group Pubs together like this is a longstanding PubPub feature; we have called these, up to now, Collections. What’s different in v7 is that such groupings are much more flexible, and can be stacked one on top of the other. Parent-child relationships, in other words, can span multiple generations. Thus a journal, in v7, is itself a Pub. Its children are the volumes, with its children the issues; articles, on this analogy, are the journal Pub’s great-grandchildren.

One benefit of redefining the Pub in this nested way — freeing the Pub from its previous, atomic definition — is that a Community is no longer tethered to a single website. In earlier versions of PubPub, an organization with a journal, a press, and a preprint server had to create three separate Communities. In v7, the Community is the organization. All of its projects — the journal, the press, and the preprint server — are managed from a single backend workspace. We are designing v7 with the aim that even a large operation could manage its reports, series, and journals from one place.

A second benefit of the v7 approach to Pubs is that Communities have radical flexibility to shape Pubs as they like. Earlier versions of PubPub privileged the webpage document, with other kinds of outputs (like PDF or LaTeX) reserved for download. v7, by contrast, is format-agnostic. A preprint server could make the PDF its canonical output, while another — a data repository, for example — could foreground CSV or JSON files. A book publisher, likewise, could feature ePubs, web views, and PDFs side-by-side, without nudging readers toward any format in particular. In each case, for each PubType, a Community will be able to specify what defines the type, including its required metadata.

The Pub-shaping freedom of v7 will extend to where the Pub lives. We expect that many Communities will continue to publish their work on PubPub; we plan to include a core site builder for that purpose. But some Communities with more complex needs may decide to publish elsewhere, or even (in a print-only operation) forego the web altogether. In the future, Actions will enable a Community to publish to other platforms, like WordPress or Squarespace. The idea is that each Community can map its unique vision to a v7 architecture that’s fundamentally pliable.

v7 is being built on the premise that there are as many publishing workflows as there are publishers. Thus the vision for v7 is to work with partners to support a variety of uses cases — from novel takes on established forms like the journal to brand-new modes of knowledge-sharing, as-yet unnamed.