5 lessons in building a SaaS application in SilverStripe

In this guest post, Robert Petreski, Technical Lead of Digital360, shares his lessons in building the Document Management System in SilverStripe.

Project background

Earlier this year, our agency took on several web builds. The client was a national group of companies, diversified in several manufacturing industries. The client’s stakeholders had a key challenge that needed addressing: managing the volume of technical documentation across the entire organisation.

Current market solutions were geared towards file managers that are ‘locked away’ from other users and the public. There is very little opportunity for control over who gets access to these documents. To tackle this challenge, we decided to deliver a custom digital solution: a SaaS application built on SilverStripe CMS/Framework.

While SilverStripe is our choice of CMS/Framework for web builds, it is relatively untested when it comes to SaaS applications. Nonetheless, my team and I decided to remain consistent in our development approach and chose SilverStripe as the application’s framework.

We delivered the project, internally called the Document Management System (DMS), in October 2016. By the end of the project, our efforts tested the SilverStripe framework in its ability to:

• Deliver a sustainable Restful API,
• Deliver a sustainable and scalable SaaS platform,
• Bind an external data warehouse into its model architecture.

This post will explain the functions of the DMS application, as well as share some key lessons we learned during our process of research, experimentation and delivery. To see a client application, view our post on the SilverStripe showcase.

Introducing the Document Management System (DMS)

What is it?

The DMS (branded ‘TradeCentre’ for the client) is a SaaS web application that hosts PDF documents. What makes the DMS unique is its subscriber-based system to the end user through a custom-built API or dedicated ‘white label’ site. The application makes the delivery of documents to end-users simple, and centralises the management and publication of these documents to a single administration area.

Application use cases

• A document manager for internal organisation use
• A mechanism for delivering marketing and sales material to customers
• A document subscription service for partners and suppliers

Technical deliverables

• An API-first PHP based application utilising SilverStripe Framework
• A Relational Database Management System based on MySQL for managing the core foundation of the system
• An independent, single page application built in Vue.js that facilitates the administrative and white label portions of the project.
• A noSQL document-based Database Management System, delivered by Elasticsearch, for managing the documents of the system and providing the full text and suggestive searching in the system.

Key features of the DMS application

User roles

• Super Admin – This user is restricted to Digital360 and is responsible for setting up the Organisation and skin management.
• Organisation – The Organisation is a user that owns the entire system and is managed by the Super Admin.
• Administrator –  An Admin has full privileges and typically manages the Subscribers and Authors of the system.
• Subscriber – Subscribers are users that don’t have access to the system to administer anything, but they are set up to manage their white label site, such as provide a unique skin and allocating the documents that can be viewed.
• Author –  Each document has an author. These users get access to restricted folder(s) and can upload documents for their subscribers.

Document admin and management

A key use case of the DMS is as a flexible file manager for the organisation’s internal stakeholders. The owner can assign authors and subscribers to their portion of the system, making the publication and on-going management of documents simple.

This functionality means that the responsibility of documentation can be assigned to individuals, while other staff members can easily access current documents when and where they need them.

Document subscription

There are two ways the end user can access the documentation:

• A white label eco-system –  A subscriber can deploy a branded (or ‘skinned’) version of the application. This can be hosted on a subdomain of the main site. The owner can set customised themes to subscribers. This gives owners the control to set customised public facing system for each subscriber. The owner can also set permissions for subscribers, such as what they can and cannot display on their white label site.
• Customised through the API – The API allows documentation to be access by subscribers. Using the API, documentation can be displayed and accessed on relevant product pages on the main website, or partner sites.

To support subscriptions, the DMS also includes payment gateways that allow subscription-based payments. It also involves a queue system that runs alongside the core system to detect relationship and subscription changes.

Intelligent searching

Search functionality was a key feature of this build and an integral part of the experience for users. We needed the internal search engine to provide intelligent search results and suggestions by analysing the content of the documents, not just simple keyword metadata and tags. This functionality is not available out of the box with SilverStripe Framework, or most frameworks.

The solution we opted for was Elasticsearch, an out-of-the-box solution for a document based management system. The strengths of Elsaticsearch over competing products, such as Apache Solr, was that it had support for PHP. It also handled suggestive searching – a key deliverable – much better than these alternatives.

Key challenges and lessons

Challenge #1 – Roles, responsibilities and Super Admins

We discovered the need for two administration roles, as it became clear we had to separate the management of the entire system from an individual organisation’s portion of the system.

Our solution was the creation of an ‘Admin’ role for the individual organisation, and a ‘Super Admin’ role for the management of the entire DMS system. The Super Admin role would be delegated to the development team at Digital360.

This separation allows the repository owners (such as the client organisation) to manage their portion of the system with a sufficient degree of control – such as managing users, subscribers and documents – while limiting their access to the critical controls of the entire system.

Challenge #2 –  Building and managing components

Our chosen JavaScript framework, Vue.js, is still in its infancy. This means there are no clear guidelines for producing a standardised method for building components. To overcome these challenges, we attempted to pave the way for best practice by testing some approaches ourselves.

First, we tried managing components as ‘smart’ components that run in their own state. This ultimately caused issues as the close coupling with the application restricted its ability to scale.

 We then moved to manage components on a global scale with a global state architecture using Vuex. However, we didn’t want to refactor the entire project. Our approach was to rewrite the core of the system utilising Vuex, then leave less critical components as ‘smart’ components.

Challenge #3 – Working with untested frameworks and APIs

Building Restful APIs is not something that’s new to the SilverStripe open source community. In our project scope, our team did discover one API wrapper that had been developed by the community as a prototype. Unfortunately, due to its infancy and abandonment, we ended up developing our own Restful API within SilverStripe.

There are many frameworks we could have opted for to build the API, such as Laravel. While SilverStripe is our framework of choice, we needed to overcome some unique challenges, such as Director static class workarounds. Eventually, we ended up producing middleware in a controller. Although this isn’t ideal in the long run, it works well for what we need right now.

Challenge #4 – Content strategy and naming conventions

Initial naming conventions for the different types of members caused confusion among stakeholders and internal staff working on the project. The main issue was around ‘authors’ – we discovered that we were often mixing up user roles with entities.

An author is a user that belongs to a company, but an administrator can also belong to a company. We wanted to show that a company had a range of documents, which could be produced by multiple authors. So the company entity was required, but we had not initially factored in this consideration.

We adjusted the naming conventions to make this distinction clear. The current hierarchy is as follows:

• Super Admin
• Organisation
• Company
• Users
• Documents
• Subscribers

Challenge #5 – ‘Jailing’ subscribers

As part of a SaaS design model, we opted to partition organisations within the database system(s). While this solution solved problems around speed and scale, it also introduced another issue around indexing and jailing the data. Jailing enforces users to be confined to an area of the system. By jailing users, the system has control over which users have access to which documents.

However, this issue meant that a user accessing the searching module might see results that are not necessarily that of the subscriber. In other words, it was possible for a subscriber to have access to a document owned by any company in the organisation, not just the company they were grouped under.

Our solution was to fetch the request from Elasticsearch, which holds the documents being searched, then filter that request on the subscriber. Although it’s not the perfect solution due to its inefficiency, it solves our immediate issues.

Final words and future development pipeline

When we started development of the DMS, there was no comparable product – and no precedent to follow. That’s why we chose a lean approach to developing the DMS, focussing our efforts only on developing critical functionality.

The result is the delivery of a lean product that focusses on the client’s needs, and is a perfect platform for learning, iteration and improvement. At this stage in the product roadmap, we are looking to further abstract the responsibilities of the engine and the concerns of each component of the system.  

Our ultimate vision for this product is to provide a premium branded asset that increases the efficiency of our client’s organisation, and improves relationships with their customers and partners.

For more information, please leave a comment below, email me at robert.petreski@digital360.com.au or contact Digital360.