Single Source of Truth
Creating my app and website completely consumes me. I’m not just talking about the time I actually spend coding, but the constant storm in my brain. I try to anticipate all possible problems and prevent them before they even arise. I’m talking here not only about purely programming problems, but also architectural, organizational, or business ones. DlaPolakow.app will be a service built from many smaller microservices. For example, wydarzenia.dlapolakow.app. Each of them will be independent and each will have its own terms and conditions, for example. And here a potential problem arises. Where to put it? Should it be at wydarzenia.dlapolakow.app/terms? Or maybe a dedicated page, regulaminy.dlapolakow.app, and redirect the user there? What if I need these terms and conditions in a prompt, for example, for AI to check the user’s content compliance with the terms? And what if I want to display these terms in the mobile app? My first thought was simply to create a copy of the content and paste it in those several places. But this solution makes no sense, because every time the document content changes, it means it must be updated everywhere. With a few, it might pass, but with a dozen or so, it’s already a problem. I shared this concern with AI. And this is exactly why I’m excited about this like a kid. It suggested creating a single source of truth. It sounds mystical, but the solution is brilliant. Let me explain. I created a separate page, faq.dlapolakow.app (faq or any other dedicated subdomain). Every document, of course, has its own slug, e.g., /polityka-prywatności (privacy-policy). This sounds quite “ordinary,” plus I mentioned this earlier in the text that I had already thought about it. The content here is embedded on the page for the user. So where is the power? In the fact that every /slug has an added API. And in this way, /slug/json returns exactly the same content in API format. And from the API, I can load data anywhere else and format it as needed. And so, instead of redirecting the user from wydarzenia.dlapolakow.app/ to faq.dlapolakow.app/polityka-prywatnosci, I simply import the content via the API and display it on the original page. This content is always up-to-date, and that is its greatest power.
Additionally, I decided to extend the content itself with markdown and custom tags. Thanks to this, the code that imports the content can also load identical formatting (or ignore it). The custom tags I use are[section][/section]
[list][/list]
[code][/code]
[mermaid][/mermaid].
Each of these elements can also have an id= parameter, and in the list itself there is also [item id=""].
The concept of SSoT (Single Source of Truth) is brilliant. Not my idea, unfortunately. And it solves a large number of problems. An example? Say you have an classifieds service. You want AI to automatically check if the content complies with the terms and conditions. The prompt – roughly – will look like this: “Check if the content complies with the terms and conditions. <Here> are the terms, and <here> is the content“. And the terms will always be current, even if you don’t update the prompt.
The CMS for managing the FAQ is being written from scratch with the help of—you guessed it—AI. I also added versioning for every document. Each document, in addition to the slug, has its own ID consisting of 8 alphanumeric characters. The risk of repetition is practically zero. The latest version is always displayed on the /slug page, and all previous versions automatically move to /slug/history.
Why markdown and not full JSON then? JSON is brilliant BECAUSE it is very heavily structured. But for text content, flexibility is key. Code uses data in JSON format. And text can be used by both code and humans. Here, I was aiming for a flexible structure. That’s why markdown. What’s more, the text can be cleaned of markdown. And in the case of JSON, removing a certain element can create problems.