Core Concepts

Kommentar has some very simple yet useful concepts. They help me write code better, and hopefully will help you use Kommentar with ease as well.

Host

A Host is the parent of the Comment. A Comment cannot exist by itself. It has to belong to a Host.

Consider these examples:

On a blog site, each blog post is a separate Host.
On GitHub, a PR, issue, or Discussion can be Hosts.
On a site like BlueSky, a post is a Host.
On YouTube, a video is the Host.

Essentially, Comments are scoped to a particular entity. This entity is what I prefer to call a Host.

A Host is identified by a unique identifier called the hostId.

Following the same examples:

On a blog site, the blog post’s slug could be the hostId
On GitHub, the PR number could be the hostId
On BlueSky, the post’s ID could be the hostId
On YouTube, the video’s ID could be the hostId

Like I said earlier, it’s nothing crazy. It’s a very simple entity.

Comment

A Comment is the entity that describes a comment made by a user on a Host.

It’s defined as an object with some properties that allow you to manage them.

type Comment = {
  id: string;
  content: string;
  hostId: string;
  createdAt: Date;
  updatedAt: Date;
  sessionId: string;
  commenter: Commenter;
};

You can look at the actual definition in the code here.

The model of a Comment is simple, and I do not expect it to change much in the future. If there are any changes, I will make sure to keep them backwards compatible.

Commenter

A Commenter is the entity that describes the user who made a Comment.

A Commenter cannot exist on it’s own. It belongs to a Comment.

Kommentar does not require you to authenticate users. As a commenting system that relies on the Host, I did not see the need to handle authentication in the application itself. If you choose to authenticate users, you can do so in your application and inject the user details into the Commenter object.

type Commenter = {
  displayName: string;
  realName: string;
};

You can look at the actual definition in the code here.

Consumer

A Consumer is the entity that consumes the Kommentar API. It can be a web application, a mobile app, or any other service that simply uses the API.

A Consumer is identified by a unique identifier. There is some level of granularity in how much access a particular Consumer has to the API, but it’s nothing too complex.

type Consumer = {
  id: string;
  name: string;
  description: string;
  apiKey: string;
  apiSecret: string;
  allowedHosts: string[] | [];
  isActive: boolean;
  rateLimit: number; // The number of requests allowed per minute
};

You can look at the actual definition in the code here.

Super

A Super is essentially an admin user of the Kommentar application. It bypasses all restrictions and has access to all the data in the application.

Tehcnically speaking, a Super is not a domain entity in Kommentar. It’s more of a user that has superuser privileges in the application.