In this text we're going to take a close look under the Matrix. We're going to find the exact place where your consciousness is located and start hacking on it until you become someone else.
Just kidding.
Welcome to a jolly journey through Journaly! The idea of this post is to give you a first taste of how the platform you're (hopefully) using everyday looks like from a technical point of view.
First of all: I am not part of the Journaly team, so everything I'll say is just my very superficial take on very concrete things. It most certainly won't be fully correct. I only had the epiphany that led me to write this article today, so please don't expect an utterly thorough coverage of the technicalities. But I assume most of the readers won't, so we're fine.
Let's get started!
I'm going to talk about the badge that most of you'll already have gotten by now. I refer to the badge of having written ten posts in Journaly. If you are anything like me, you'll by now have undoubtedly asked yourself: Where does that come from?
Well, obviously it comes from having written at least ten posts. But that's not what I mean. What I mean is: Where does it technically come from? Where are the nitty gritty details behind that functionality? How does it work under the hood? Where does that information come from?
In short: Where is the code?
This won't be a programming crash course or anything. It will just be a very fast round around the corner. We'll get straight to the core. I mean the code.
Journaly is (obviously) a web application. The source code of what all of us are using right now is hosted on GitHub. Journaly seems to be mostly written in TypeScript (I had no idea, that's a nice thing to know!) and uses a relational database called PostgreSQL. This database contains all our posts, the users (us!), the comments we write to each other, the likes (the hearts) we give us, absolutely every type of information that comes from the users. Yes, that's what a database is for, of course. The visual aspects of the web application (what all of you see and use in the browser) are written in a framework called React.
Let's go a little bit deeper.
There is another layer on top of the SQL database, which is called Prisma. I don't know much (i.e. anything) about web development with JavaScript, but as a working Java programmer I can reasonably understand what the components of Journaly are and what they're good for. Prisma seems to be mostly an Object Relational Mapping (ORM) on top of the PostgreSQL database.
And what does that mean?
It means that you interact with the database in a certain way. Instead of writing in the SQL language of the database (SQL statements), you do that in your programming language of choice, i.e. in this case TypeScript. Without technicalities, this just means that your life working with the database is easier. The central idea of an ORM tool is the mapping it provides: It is a sort of bridge between the database world and the code world.
And why do I talk about that?
Because the badges can be found here!
This file lists (declares) all sorts of types (kinds of information) that the Journaly database knows about. Well, not really the database, but how Prisma sees it and exposes it to the TypeScript code. Without understanding anything about programming, one can get a very precise idea as to what the database contains. The names are really very readable (good job, Journaly team!) and the structure seems to be quite transparent (the relations between the different types of information are mostly intuitively understandable).
For example, there are easily identifiable concepts such as Post, Comment or User. What are those? Well, they are the posts, the comments and the users. These and other concepts are declared in form of types.
The badges are thus declared in the enumeration (enum) BadgeType. We can see that there are currently badges for alpha and beta users (like Linda) and for users who wrote ten posts or more. I was personally curious about what comes next, and now I know it: Authors get another badge at the respectable amount of 100 posts. And the heroes who work on Journaly itself get another one as code contributors.
Okay, now we know what kinds of badges are there. But I want to know more. Where is the code that rewards users with the badge of 10 posts? In other words: Where is the badge assigned?
Without getting too much into details, the easier part of the code is here. One can read this SQL statement in plain English: "select the badge type of ten posts and the user ID from all posts where the count is larger or equal than ten". Or more tersely: Gimme my badge!
The part of the code that takes care of sending a notification email to every user with a new badge is here. More concretely, the name sendNewBadgeEmail should be already quite descriptive. It tells exactly what it does: It sends an email notification because of a new badge. The mentioned Promise has nothing to do with promising you a new badge (that's something you have to earn!) but with the way the email is sent (in parallel, or better said, concurrently).
That's it. Quite nice, right?
Oh my, this is amazing! How did you find this? And could you change anything, if you wanted to? This wasn't only super interesting, but also so well written, I really enjoyed reading :) (and of course I have a million questions)
Then ask! Thank you, Caro! It's really awesome that Journaly-the-running-webapp AND the code is fully and openly accessible. Yes, you can download the source code, inspect it, change it and you even can RUN your own version. You have then an own database and webapp. That's how you work on extending the product with new features and how you fix problems, etc.
I've distributed my questions evenly ;) But if I run my own version, it'd look the same as this own, right? I've never thought about how you add new features or fix problems.
I think so, yes. There seems to be some sort of seeding mechanism for filling the initially empty database with some content, but the webapp should look the same, yes. You could then for example inspect how the blue markings and the delta logic work. That'd be fun.
What's a seeding mechanism? ^^'
I just mean filling the database tables with some dummy content so that you have some initial text. Maybe some Lorem Ipsums or so.
Ah ok, I see :)
@Eduard! This is awesome, but did you know that there would have been an easier way to find out about the badges? The answer is here: https://docs.google.com/spreadsheets/d/1NkyPTvK4DCDtbSyMfhIj3pI8obhbC_CzHZJbyP19uEE/edit (This is the spreadsheet for translating the UI.) Here everyone is welcome to contribute translations of the UI into other languages. You're welcome to add translations or give better translations. @robin originally posted this link underneath this video: https://www.youtube.com/watch?v=HBr-4PHmLBY&t=33s&ab_channel=RobinMacPherson
Wow. Eduard, the way you analysed and described technical aspects of Journaly is quite impressive. On one hand it is on a such general level that anyone can understand it and on the other hand it is detailed enough to be interesting for someone with some technical knowledge. You found a sweet spot. I think I may reconsider reading your posts about physics and mathematics in German :)
Eduard, that was quite brave of you to throw this technical post to the language community. But you did it so well, congrats!
Caro, if you have your own, you can start modifying the code and if you think you solved a problem you can submit your change suggestion. It will then be reviewed and if it's good, included in the main code. Running your own copy however would be not so interesting, because you would have to create a community of your own ;-)
Linda: Yes, I know about the Excel sheet. See my next text ;). I thought it's cool to simply take a look at the code. But you're right, the labels are definitely there. That's where the information comes from :D. In German even thanks to you.
Radek and Erich: Thank you very much!
Erich, it's all hypothetical questions. I'm just trying to wrap my around it, since I don't really know anything about programming etc. So don't worry, I won't start Journaly 2.0 ;)
I liked this post. Very interesting, informative and nice to read as well.
Thank you CloudyDe! I hope you enjoy the second journey as well, though I am a bit less content with the result (I just improvised it this morning).
There also should be a badge for the post with the most comments. I think this one would go to you, Eduard! This specific post has 465 comments, that's insane! :D And the time traveler part 4 even has more than 500 comments.
Linda: :D. That's only the case because I'm in very good company.
Linda, Agree with what you have suggested regarding post with most comments. Very likely that would go to Eduard. And also a badge for a collaborator who has read and commented on most entries, that would go to you LINDA.
Eduard, After opened the Journaly GitHub repository https://github.com/Journaly/journaly I nearly fell off my chair, I saw this line at the top: "robin-macpherson Merge pull request #507 from Journaly/inline-i" I know Robin is very passionate about this Journaly project, but I didn't really he is IN the coalpit everyday working on the code. @robin you have earned my respect.
Haha, LingoBee: You didn't know he works on the code as well? Of course he does, Journaly is his baby. I think he has a Youtube video where he talks about being a polyglot and a programmer, and somewhere (maybe in the same place) he talks about Journaly. In one of the latest videos (the full week thing, where he's also seen learning Catalan, which I found funny :D), he's also in front of the computer working on some Journaly code. // Yes, what you link to is a "Pull Request", which means that in this case he 'merged in' (accepted) the changes from someone else (Ryan aka Lanny) on the code. [BTW your link seems to be the implementation of the first "paid" feature for the upcoming premium accounts, the feature to add inline images within a post. See the third item in the TODO list from https://github.com/Journaly/journaly/pull/507]. Interestingly, the very first public changes (commits) on the project date from February 16, 2020. Which for me means: It's a quite fresh project!
Eduard, It's really good to know the project is progressing into adding new features for premium users. I often wonder why there are two categories of users -- beta and alpha, probably it's for the premium version. Wish the Journaly dev team all the success in lunching this app with a paid version.
@LingoBee: no, alpha and beta are referring to the programming process. There are some users who started to use Journaly as "alpha"-users, that is, when the program still had many errors, and they were ready to help find the source of the problems. Now, all of us are "beta"-users because the software is already very usable, still has some bugs but hasn't all features yet (for example the matching between users according to their interests). At some point, the developpers will declare the version 1.0 and users starting from then on won't get the "beta user" badge.
Erich: I registered last month and I'm no beta user, so I guess it's already considered stable/usable. // Edit: According to https://github.com/Journaly/journaly/blob/master/package.json#L3, we are already at version 2.0.0! And according to https://github.com/Journaly/journaly/blob/613c21ce9b2eac817e5c99193fabbce922b1342b/package.json, by February 6, 2021 it was already version 1.0.0. That's the day I registered, d'oh! xD