Architecture

This document presents Djehooty's architecture and certain technical concepts that are not covered in the user guide. Understanding these concepts is essential for effectively contributing to the project and navigating the source code.

Architecture

TODO

Concepts

Entity

An entity (Entity) is a generic concept that encompasses individuals, events, places, and organizations. It allows the representation of any genealogical or contextual data, to which a unique identifier is assigned.

Layer

The layer (Layer) is a generic concept grouping files, file instances, documents, and selections. It allows the representation of any documentary data, to which a unique identifier is also assigned.

Pointer

The pointer (Pointer) is an internal concept that generalizes the notion of entity and layer. It allows abstract referencing of both entities and layers, thus facilitating the management of links and associations in the application.

Identification

Identification refers to the association between an entity and a layer. For example, it is possible to identify an individual on a document, an individual on a file instance, or a place on a document. This mechanism allows precise linking of contextual or genealogical information to documentary elements, thus enriching the data structure and information retrieval.

Selection

A selection designates a rectangular area defined within a given image.

It is characterized by the coordinates of two points (upper left corner and lower right corner) delimiting the selection rectangle. An index allows specifying, for example, the page in a PDF or the second in a video.

Coordinates are always expressed relative to the original image of the selected file. In case of image rotation, the selection coordinates remain unchanged.

A selection can be modified (coordinate adjustment), but to change the associated file or index, it is necessary to create a new selection.

Thumbnail

A thumbnail is a reduced-resolution image generated from a source file. It is used to provide a quick visual preview of the file content, thus facilitating navigation and selection in the user interface. Thumbnails therefore differ from original files, which retain their initial resolution and quality.

The thumbnail is a square image generated in .webp format to optimize file size. It is stored in the thumbnails folder within the User Directory. Each thumbnail is identified by a UUID.

There are two types of thumbnails:

• File thumbnail: Generated from a file (e.g., an image or the first page of a PDF). It is automatically generated when importing the file into Djehooty.
• Selection thumbnail: Generated from a specific selection within a file (e.g., a closer area around an individual's face, a signature, a text excerpt, a marginal note, etc.). It is generated at the user's initiative and allows highlighting a specific part of a file's content.

A thumbnail is always associated with its source file, so it can be regenerated if necessary. The files_thumbnails table in the database manages this association.

Database model

Djehooty creates a SQLite relational database djehooty.db, local, located in the User Directory folder.

The detailed structure of the database and the base data that are injected during installation can be consulted on the djehooty-backend Git repository.

Table	Description
documents	The documents table represents the basic documentary unit manipulated by users in Djehooty: it groups one or more files (via files_instances) with metadata such as a title, description, etc.
entities	Allows unified referencing of any entity type (individual, event, place, organization) via a unique identifier, thus facilitating polymorphic associations such as identifications on documents.
entities_types	Reference table that defines the entity types allowed in the system (individual, event, place, organization) and serves as a validation constraint for the type_id column of the entities table.
files	Table storing all information about stored files (uuid, media type, sha256, size). The stored data relates to the content of each file.
files_instances	This table represents file instances, i.e., different occurrences of the same file (identified by its SHA-256 hash) with their specific metadata (from the original file system) such as the original filename, modification date, and their position in a document.
files_thumbnails	This association table links a file to its thumbnail by associating the file ID with the corresponding thumbnail ID
identifications	Allows associating an entity (person, event, place, organization) with a layer (document, file instance, file, or selection), for example to identify an individual present in a photo or mentioned in a document.
individuals	List of individuals with their information
layers	Allows unified referencing of any documentary layer type (document, file instance, file, selection) via a unique identifier, thus facilitating polymorphic associations such as entity identifications on these elements.
layers_types	Reference table that defines the documentary layer types allowed in the system (document, file_instance, file, selection) and serves as a validation constraint for the type_id column of the layers table.
selections	The selections table stores the rectangular coordinates (start and end points) defining an area of interest within an image, allowing precise identification of a portion of a visual file.
thumbnails	The thumbnails table stores information about reduced-size images generated to preview files, including their UUID, extension, whether they were resized, and their creation date
users	Djehooty users. By default there is only one for now