In this article I will discuss the way Papermerge project repositories are organized and ideas driving those organizational structures.
I need to give appropriate credit to my ignorance – when I started Papermerge project I did not know about GitHub’s Organizations i.e. that you can group related code repositories under one single umbrella or Organization as how GitHub labels this concept. Even if I knew it, what use it would be ? Because all the application was – a pretty simple Django project. Everything just fit perfectly under one repository – https://github.com/ciur/papermerge
Basically at the beginning I was very happy with one single repository. One project, one repository – everything makes perfect sense so far.
Historically speaking https://github.com/ciur/papermerge was very first repository which initially worked perfectly well.
With time however, I was struggling with one serious inconvenience – it became obvious that Papermerge, as any web based application had two somehow separate parts – backend – primary python code and frontend mostly javascript code. As javascript codebase grew more and more – the harder it was to maintain those separate worlds in one repository. Long story short – I decided to move javascript code into its own repository – this is how https://github.com/ciur/papermerge-js repository come to life.
Avoid Monolithic Design
What can be worse then one monolithic application ?
The answer is: two (or three, as in picture) monolithic applications!
In order to avoid monolithic design, I decided to split application into many reusable packages. In fact, Papermerge is based on Django Web Framework which is has built-in the concept of reusable apps in its DNA. In other words, splitting Papermerge project into multiple reusable apps was a piece of cake – this is how … ah, wait – did I mention that in meantime I learned about GitHub’s organizations? Well, in meantime I leaned about Github’s organizations and I created Papermerge Organization. One of the very first projects created under Papermerge org was papermerge-core.
Papermerge Core
Simply put, papermerge-core is a minimal set of Django’s reusable apps which cements the very foundation of everything else in Papermerge ecosystem. You can call it the heart of the project. The most important concepts like Document, Page, Folder, User, Tag and code dealing with those concepts are defined here. The key takeaway point here is that papermerge-core is reusable.
Documentation
Documentation is extremely important. It is so important that it deserves a separate repository (obviously under Papermerge organization). In practical terms, it means that I extracted what previously was under docs folder in very very first repository into a separate documentation repo. By the way, documentation is based on wonderful sphinx-docs open source project. I absolutely love it, it makes writing documentation a breeze.
Frontend Codebase
Frontend monolith (mostly javascript code) was split into many reusable nodejs packages. Basically what was one monolith javascript codebase – was split into following reusable nodejs packages:
- symposium-js – sort of mini frontend framework used across all other packages
- commander-js
- viewer-js
- dual commander
- dialogs-js
- uploader-js
- core-js – bundles all papermerge nodejs packages into one single package
As you can see there are lots of repositories – and their number is growing as I am extracting more and more reusable code. As I mentioned before – the worse of all evils is to keep all codebase into one single monolithic giant structure – I am trying to avoid that pitfall at all costs.
Regardless of how many other repositories will spring under Papermerge umbrella, one of them – the very first one https://github.com/ciur/papermerge will be special – as it was from the very beginning there. This special repository will stay there and will be used as central ticketing system.
https://github.com/ciur/papermerge repository is used for keeping track of issues, announcements and discussions.
Papermerge Blog 