update librarian
[wolnelektury.git] / doc / architecture.rst
1 Architecture overview
2 =====================
3
4 Catalogue of books
5 ------------------
6
7 Books are kept in the :py:class:`catalogue.models.Book` model.
8
9 Books have fragments, annotated  with themes. Those are kept in the
10 :py:class:`catalogue.models.Fragment` model.
11
12 Both ``Books`` and ``Fragments`` can have ``Tags``, which are
13 :py:class:`catalogue.models.Tag` objects.
14
15 What are ``Tags`` used for?
16 ---------------------------
17
18 Each ``Tag`` objects has a ``category`` field specyfying its meaning.
19 The categories are enumerated in :py:const:`catalogue.models.TAG_CATEGORIES`.
20
21 Tags are used for:
22
23 * Keeping browsable metadata. Each ``Book`` can have any number of tags
24   of categories: ``author``, ``epoch``, ``kind``, ``genre``.
25   Each ``Fragment`` of a book has all of those, 
26   and also a number of ``theme`` tags.
27 * User shelves. A User can put a ``Book`` on a shelf and add some labels
28   by adding a number of ``set`` tags to it. A book put on a shelf without
29   any labels has a Tag with an empty name.
30 * Denoting :ref:`ancestor-descendant-relations` using ``book`` tags. 
31
32
33 .. _ancestor-descendant-relations:
34
35 Relations between ``Books``, ``Fragments`` and other ``Books``
36 --------------------------------------------------------------
37
38 Obviously, every ``Fragment`` comes from a particular ``Book``. This
39 relation is expressed with the Fragment's ``book`` field.
40
41 The source of parent-child relations between ``Books`` is
42 the ``dc:relation.hasPart`` metadata field, exposed by
43 :py:class:`librarian.dcparser.BookInfo` as ``parts``. This relation
44 and the order of children of one parent is expressed with the child
45 book's ``parent`` and ``parent_number`` fields.
46
47 But aside from that, Tags are used for managing those relationships, too.
48
49 Every ``Book`` has a matching `l-tag`. It's a ``Tag`` of category
50 ``book`` and matching slug with an added 'l-' prefix (the prefix
51 is superfluous and we should remove it as some point, as it was only
52 needed when tag slugs had to be unique).
53
54 The `l-tag` of a ``Book`` is used on:
55
56 * all of the book's fragments,
57 * all of the book's descendants,
58 * all of the book's descendants' fragments.
59
60 This is used for:
61
62 * finding fragments of a given theme in books with a given user label,
63 * on a filtered book list (i.e., author's page), for eliminating
64   descendants, if an ancestor is already on the list,
65 * when calculating tag book counts, for eliminating descendants as above,