Architecture, design and guidelines
System Architecure
Docker Architecture
Two services are created from a single image:
- journals-http-server: Runs the node.js HTTP server (created using express);
- journals-file-monitor-service: Executes
entrto monitor the folder containing the markdown files. If a file is updated, the corresponding journal is rebuilt.
Notice that we have three volumes that are shared by the two services:
| journals-http-server | journals-file-monitor | |
|---|---|---|
| static-pages | The HTTP server serves these files | These can be updated after a build is triggered by entr |
| markdown | The server calls quick-notes that update these files |
entry monitors these files |
| journal-manager-config | The server calls journal-manager to get configuration information |
It calls journal-manager to gather config info |
Project Organization
The project contains two packages (core and cli) and one assets folder.
core
Defines the data models, exceptions and functions to query the data model.
cli
Contains the journal-manager command-line interface.
assets
Set of static files used as templates.
Design
In this project the following designs and patterns were adopted.
Modular Parsers
Children parsers can exchange information with their parents via the set_defaults method. In the
figure above we have some examples with subcommand_help and func parameters. These export the
print help of a subcommand and the function the subcommand triggers.
This architecture has the following advantages:
- Reduce cluttered code by putting the code in the most appropriated module instead of all put all logic in a single file;
- Allows to call modules as independent command-line-interfaces;
Data Model
I opted to have an equivalence between file and memory representation. Each
model class has a corresponding toml file that can be manually modified by
the user.
This approach gives transparency and flexibility to the system configuration. The drawback is that it vulnerable to data corruption and inconsistencies if modified incorrectly.
The equivalence between python dataclasses and toml files is done via the package toml_dataclass
Documentation
CLI documentation and Library documentation
For a CLI alike script, I don't think it make sense to have a documentation for the API. This information should be accessible via the command line with the help commands. For libraries on the other hand, it makes sense to have an API reference style of documentation. Something like the one generated by the sphinx-apidoc.
Guidelines
Naming conventions
I started this project before reading these articles, but I would like to try the approaches below in my next project.