Add messaging.
[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.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
31
32 .. _ancestor-descendant-relations:
33
34 Relations between ``Books``, ``Fragments`` and other ``Books``
35 --------------------------------------------------------------
36
37 Obviously, every ``Fragment`` comes from a particular ``Book``. This
38 relation is expressed with the Fragment's ``book`` field.
39
40 The source of parent-child relations between ``Books`` is
41 the ``dc:relation.hasPart`` metadata field, exposed by
42 :py:class:`librarian.dcparser.BookInfo` as ``parts``. This relation
43 and the order of children of one parent is expressed with the child
44 book's ``parent`` and ``parent_number`` fields.
45
46 Additionally, every ``Book`` has a many-to-many relationship `ancestor`,
47 onnecting it to all its ancestors, with reverse relationship called
48 `descendant`.  This relationship is rebuilt after a `Book` is published.