Relationship between frontend and backend

[jardakotesovec]

If we think about where we would like to be in ~3 years with the admin interface from frontend & backend relationship point of view. Goal I assume is probably to frontend be (for admin) just Vue.js, without additional templates that are server side rendered.

In terms of backend&frontend interaction, I think its either going to be:

1. to make frontend completely independent and get ALL data from API (via rest or graphql). Or
2. leverage Inertia.js and stick with the full stack DX, where you collect all data necessary in the controller for each invididual page. + Having couple of dedicated API endpoints for users to export/import data.

Comparison is quite well captured https://laravel.com/docs/10.x/frontend#using-vue-react .

Since new submission interface is the first use case I am looking into - let use that as example what it could mean in practice.

For this submission listing, there is quite a lot of data needed.

• list of submissions
• data structure for filtering form (as we probably want to keep that server side to be able to extend it)
• list of columns (as that might be dynamic as well)
• relevant translations
• views - their names and ideally also counts
• and there will be probably more to come

To get all the data to the page we could take following routes:

1. Create dedicated API endpoints, for all these different kind of data.

   • Requires making multiple requests on frontend to get them.
   • This will require quite a lot of thinking how to design these API endpoitns to be universally useful.
   • Every breaking change should be carefully documented.
   • If we expose all these endpoints - how much of them would be actually useful to external users?

2. Expose data via graphql

   • Its bit easier to design such api, as you pretty much just adding more and more fields to be available for frontend and than its up to to frontend to pick which fields to use. No need to think as much about how to split it to individual REST endpoints.
   • Graphql itself also brings some additional complexity - especially to make sure that the data are being fetched efficiently and also extending schema in runtime might be challenging
   • Trick with graphql to avoid breaking changes is usually just keep adding new fields, and deprecate some old ones.
     you get convinience of one request from client.. this becomes harder on api side of things.

3. Use Inertia.js and collect all the data in controller needed for submission list + potentially some individual endpoints for some data.

   • This is obviously quickest and easiest as that would be considered as private API and can evolve as the page needs.
   • Does not have added benefit of exposing some of the data via clean API.
   • There potentially could be bit of both. For example for list of submissions, which clearly could be useful also as API could come from own API. There are two options how to approach that
     • Get all the data via Inertia.js with exception of submission and call the /submission endpoint from the browser to get just submissions. Thats closest to where the code base seems to be heading currently - getting some data via template (would be via inertia.js in future) and some via API endpoints.
     • Get all the data via Inertia.js, but reuse same 'submission listing' logic on php side, but just expose it via both standalone endpoint, but also via given controller, so page can get all data from one place, which helps with hydration and also for example to handle query params just on laravel side.

All these approaches are quite reasonable, so its not straightforward to pick one. I think one of the determining factors is how much public API actually would be useful. There are certainly cases which should to be covered via public API, but not sure how many.

[NateWr]

Thanks @jardakotesovec. Of your three options, I would choose the third: leverage intertia.js or similar to keep the routing and controllers server-side, and use a REST API to fetch key data on the page. Here is a little more about why I've come to that view.

1. I believe a strong REST or graphQL API is important for PKP. Aside from the practical uses of the API, it's important to PKP's mission that the software adopts open-ness and interoperability in its design. Our main purpose in scholarly publishing is to break down walled gardens and locked content, and give control back to scholars. Although having an API doesn't guarantee this, it's a precondition of the underlying promise we make with our software.

Our long-term goal is that someone who doesn't know PHP/Vue can build their own app that interacts directly with our API. Some use cases would be: using a static-site generator to build the frontend; integrating third-party typesetting, review, or editorial tools and services; indexing publishing material in third-party services; creating high-level dashboards that aggregate data from several journals. Although we haven't seen much of this done by our community so far, it is important in order to serve more of the high-profile (and well-funded) publications currently captured by the major publishers.

2. Not all "dynamic" data needs to be live data on the client side. For example, the current language, the list of columns, the form with filters, and the views are all things that could require a page refresh to be changed. This wouldn't effect the UX very much because they are changed only infrequently.

3. Relying on lots of API requests to hydrate a page requires a very fast server response. However, in my experience, our community rarely runs servers with fast response times. Also, they are not using CDNs or edge deployments. If someone is in Australia and tries to access a server in Canada or Europe, even with a good internet connection and a fast server, the sheer distances involved produce what feels like a lot of latency these days.

With a distributed deployment like ours -- where everyone runs their own instance of the software -- performance is really, really hard to achieve throughout the community. This is one place where PKP suffers a lot in comparison to our competitors.

4. Going all-in on an API approach will require some heavy refactoring (authentication, translations, plugins), and will move more of the application away from the core competency of most of the team, which is PHP. Using something like inertia.js will help us move on from Smarty in the near future, and that's a big win at a small cost.

[jardakotesovec]

@NateWr Thank you for additional context and any follow-up thoughts are also very much appreciated :-).

After spending some time on the code base and learning more context, there are still two relatively nuanced options where to aim with architecture. And would really appreciate team feedback on that.

I will use submission listing as example, as thats currently what I am most familiar with, but same principles could apply for others as well.

Note that I intend to process query params on the /index.php/publicknowledge/submissions to be able bookmark/share any state of submission listing (certain filter selected, certain view selected).

Option1

• /index.php/publicknowledge/submissions
  Provides the page configuration (columns configuration, filtersForm, list of views)
• /index.php/publicknowledge/api/v1/_submissions (and possibly others like view counts) is fetched from the browser once the submissions page loads with the configuration
• Query params in url would be processed and translated to the api/v1/_submissions endpoint in browser
• In terms of initial load for slow connections, it would take bit more time waiting for api/v1/_submissions.

Option2

• /index.php/publicknowledge/submissions Provides everything, including the submissions and view counts.
• /index.php/publicknowledge/api/v1/_submissions still exists, but it would be called internally from the /submissions endpoint, there are two ways to do it
  • Literally make a call from /submissions endpoint to the api/v1/_submissions endpoint using Http::get('...api/v1/_submissions'),
  • Or to have less runtime overhead - organise the code base that the route is super thin layer and both api/v1/_submissions and /submissions are both calling the same class method to get relevant submissions. Pain here is that some of the mechanisms like auth or validation is done on route level and would need to move lower to be shared & work exactly the same.
• As result the /submissions endpoint would also process the query params on server to fetch correct submissions, so more logic would stay in PHP realm.
• From UX perspective is literarily just less round trips for initial load.

Options2 would basically result in leveraging Inertia.js, which allows for partial reloads, so we would be fetching submissions from the /submissions the whole time, just changing query params. And query params would be handled on PHP side.

The difference is really just initial load difference on very slow connections and where the query params will be handled.

Personally I would be inclined towards option1 for following reasons:

• With option2 we would leverage Inertia.js (which is additional layer to cope with) and encourages certain patterns that we would not adopt anyway (like https://inertiajs.com/forms, where we want to use directly api endpoints).
• If someone has poor connection but regularly deals with editorial interface - lots of actions means additional API calls with noticeable delay, which still would be there. So having bit of delay on initial load I don't think makes that much of the difference, the overall experience will be slow anyway.
• With options2, we would need to make additional considerations about how to call API from inertia.js endpoints.

[asmecher]

Will be thinking about this further, but a quick cautionary note: the submission list is a uniquely complicated part of the system and the challenges you run into there around complexity and volume/variety of data won't be indicative of the rest of the system. Designing a front-end/back-end pattern for the future using this as the model case will definitely ensure it'll handle the most complex cases -- but it won't be typical!