Overview¶

Before setting up hircine it is important to understand its choice of technologies as well as its design goals and core concepts. This will allow you to make an informed decision on whether or not it is the right solution for you.

Technologies¶

hircine consists of two core parts: a Python backend that exposes a GraphQL API and a SvelteKit frontend written in TypeScript that communicates with it. Data is stored in an SQLite database.

Image processing is done using Pillow. hircine uses the BLAKE3 Python bindings to build hashes used for file identification and deduplication.

The web application is designed to be the canonical user interface, but any program may freely use the provided API.

Design goals¶

hircine is designed to organize a large personal collection of comics and make it easily queryable. It provides a set of concepts and tools that allows categorization and classification of comics and comes with a powerful filtering system.

Whilst hircine does have basic support for categories of metadata such as artists or characters, it is mostly concerned with classifying the content of a comic through user-defined namespaces and tags. The primary goal is to find something you are in the mood to read, and not to provide a full archival system where you keep track of the minute details of a comic’s publication or creation.

As such, it is designed to tackle large and diverse collections of comics, manga, or doujin where the story, art, and characters are the primary appeal.

Core concepts¶

Archives¶

hircine reads image files from ZIP archives. Loose image files are not supported. Usually an archive contains a single comic (or chapter), but it may also contain a whole volume - once imported, an archive can be split into multiple comics in the web application.

Comics¶

A comic is a logical grouping of pages (image files) that can be annotated with metadata. Most of the functionality in the web application pertains to organizing, querying, and reading comics.

Comics are created by collating a sequence of pages from a single archive. This sequence is exclusive, meaning that a page may only ever be allocated to a single comic. Not all pages of an archive have to be used.

Metadata¶

A fair chunk of comic metadata is self-explanatory. For example, a comic may be annotated with the date of its publication, the language it is written in, or what kind of censorship is in use. There also exist a number of well-defined categories of metadata that are managed by the user:

Category	Description
Artists	A person involved in the creating of a comic.
Circles	A group of people involved in the publishing or translation of a comic.
Characters	A fictional character portrayed in a comic.
Worlds	A fictional world portrayed in a comic.

Namespaces & Tags¶

Alongside those well-defined categories, hircine supports user-defined namespaces and tags. The latter is a familiar concept: a tag is a simple piece of information that is attached to an object of interest.

Namespaces enhance that concept by introducing a context in which the tag is placed. Let’s say we want to keep track of the gender of a story’s love interest. We may solve this using tags alone, like male love interest or female love interest, but this is quite unwieldy. Namespaces instead allow us to create a male and female namespace and a single tag love interest which can then be combined with either namespace.

hircine requires the use of namespaces when tagging comics. A tag cannot be applied to a comic unless it is paired with a namespace. Such a pairing is called a qualified tag. When filtering, either the namespace or tag is optional: you may decide to exclude comics with any love interest, or filter for comics that only have tags in the female namespace.

Object store¶

hircine keeps all processed images files in a a content-addressable filesystem called the object store. The purpose of the store is twofold: Firstly, if multiple archives contain the same image, it only needs to be stored once in the object store. Secondly, the object store allows the application to used without having to serve potentially large image files.