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,