I am currently in the middle of the community bonding period, so I am familiarizing myself with Fractal’s codebase. And I thought that it would be a good idea to write a blog post about how Fractal works: firstly because it would be good for me to start getting used to write posts on my blog for GSoC; secondly, it would help me greatly in order to understand more accurately the functioning of Fractal.
The Fractal’s codebase is mainly divided in two crates: the first one is “fractal-api” and the second one is “fractal-gtk”.
The fist crate is designed as a library which provides important services to the main program. It gives backend commands to talk with Matrix homeservers, the different actions can be (this list is not exhaustive):
- login, logout or register a user
- get a username, an avatar or other user information
- synchronize the application in order to get new events in a room
- get room members, messages or a room avatar
- send a message
- join or leave a room
- mark as read a message
- set a room name, topic or avatar
- upload a file or picture
- create a new room
- invite someone to a room
- accept or reject an invite
This crate also provides abstractions for Matrix objects such as rooms, users, events and messages. There are also definitions of various errors that can be related to HTTP requests, internal homeserver errors, the cache of the application or the backend itself.
The crate “fractal-gtk” contains the application itself: the source code, the UI files, the icons, the styling and the custom widgets (mainly used in the chat). The “res” directory contains the resources of the application: the XML files describing the user interface, the icons, the CSS defining the style of the UI elements and other metadata of the application. The “src” directory contains the source files of the application. I am going to talk more about the sources. The crate is divided in several modules (I will give a description of what some of them do):
- util
- widgets
- cache
- uibuilder
- app
- static_resources
- passwd
The module “widgets” defines the custom widgets used by Fractal. Here is a list of those widgets:
- MessageBox: represents a message in a room
- RoomBox: represents the room button in the title bar
- MemberBox: the popover with the members of a room
- AutoComplete: the popover displayed when using autocompletion of usernames
- RoomRow: represents a row of the room list in the side bar
- RoomList: the room list in the side bar
- Avatar / AvatarExt: the box in which avatars are shown
The module “cache” manages the local storage of some data between sessions. The module “passwd” manages the secure storage of passwords and tokens.
The module “app” contains the main logic of the application. It is also there that the connection between the UI elements and their handlers is made. There are two additional threads that are spawn by this module which are used by the backend loop and the AppOp loop. AppOp is the structure where a lot of information about the state of the application goes, the operations defined on this structure are the main operations of the program.
We’ve had an overview of most of the mechanisms that allow Fractal to work. I hope that this article allowed you to understand a little bit more about the way Fractal works. If you have any questions about it or suggestions, don’t hesitate to ask.
GSoC 2018 with GNOME 