01 · Conceptos: el nombre de las cosas

Antes de tocar el árbol, aprende el nombre de cada una de sus partes. En Baobáxia los conceptos tienen nombre en portugués, y el código respeta esos nombres.

Todo es Saber

La idea más importante del proyecto: existe una sola entidad, el Saber (baobaxia/core/saber.py). Una foto, un artículo, una persona, una comunidad, un acervo entero — todo es un Saber con un campo nature diferente.

Por qué "mucua" y no "servidor". En otros proyectos, la máquina que guarda y entrega los datos se llama servidor. No nos gusta ese nombre: lleva la idea de una máquina que sirve, puesta a trabajar sin fin — una relación de explotación. Preferimos una relación de cuidado: la mucua es el fruto del baobab, que guarda la semilla y alimenta; quien la mantiene es quien la cuida (el PAJÉ). La palabra aparece en el código y en la documentación de herramientas de afuera ("servidor XMPP", hooks.server.ts); en Baobáxia, es mucua.

Las natures están en un registro (baobaxia/natures/__init__.py), y cada una tiene un schema pydantic de validación (natures/schemas.py). Las comunidades pueden crear natures nuevas por la API (POST /natures, services/nature_defs.py).

classDiagram
    direction LR
    class Saber {
        +str uuid
        +str nature
        +str slug
        +str|dict name
        +str galaxia
        +str mucua
        +str creator
        +datetime created
        +datetime updated
        +str signature
        +list~str~ applications
        +str visibility
        +dict data
        +list~ContentRef~ content
        +to_metadata() dict
        +to_index_metadata() dict
        +to_public_dict(lang) dict
    }
    class ContentRef {
        +str filename
        +str mimetype
        +int size
        +str hash  «clave git-annex»
        +bool is_local  «solo en el índice»
        +float duracao
    }
    class NatureSpec {
        +str name
        +str folder
        +bool structural
        +list indexes
        +list default_applications
    }
    class Ref {
        +str galaxia
        +str mucua
        +str saber
    }
    Saber "1" *-- "0..*" ContentRef : anexos
    Saber ..> NatureSpec : nature
    Saber ..> Ref : relaciones y miembros de colección

Las palabras de la red

• Mucua — el fruto del baobab. Cada instalación es una mucua, con UUID propio guardado en ~/.baobaxia/mucua.yaml (infra/mucua_local.py). La mucua es dueña de un territorio natal y de una galaxia por defecto.
• Galaxia — un acervo, que es un repositorio git + git-annex. Una mucua guarda varias galaxias; la misma galaxia vive en varias mucuas.
• Mocambola — la persona (de mocambo, quilombo). Tiene el mismo UUID y la misma clave en toda la red; el rol es por galaxia.
• Territorio — el suelo que la mucua ancla. Los saberes heredan el territorio de la mucua si no dicen otro.
• Enlace / ruta — por donde se sincroniza una galaxia: un remote git (enlace, link) o un camino de sneakernet (ruta, rota).
• Pedido — "quiero una copia de este archivo": viaja por la red hasta alguien que tiene el archivo y lo trae de vuelta.
• Lente / aplicación — una manera de mirar los mismos saberes: acervo, blog, mapa, agenda, línea de tiempo, historias (applications/).

Roles

USER ⊂ PAJÉ ⊂ OXALÁ (constants.ROLE_LEVEL). USER cuida de sus propios saberes; PAJÉ cuida de todo lo de su mucua; OXALÁ administra las galaxias en las que tiene ese rol. El módulo 05 da los detalles.

Visibilidad y protección

Dos ejes que se suman:

• visibility: public | mucua | private (campo del saber);
• data.protecao: publico | acl (solo los leitores, los lectores) | cifrado (solo los lectores, y con criptografía de verdad).

Y la galaxia puede tener acesso: membros — una puerta antes de todas las demás.

Prácticas

1. Abre natures/schemas.py y busca el schema del evento. ¿Qué campos son obligatorios? Crea un evento por la API /docs y mira cómo la validación rechaza un campo equivocado.
2. En core/saber.py, compara to_metadata() y to_index_metadata(). ¿Por qué is_local no puede ir al archivo?
3. Lista las relaciones en natures/relacoes.py. ¿Cuáles son simétricas? ¿Cuál es el inverso de e_copia_de?

Para conversar

• ¿Por qué "todo es Saber" ayuda a una comunidad a crear cosas nuevas (una nature receita (receta), cantiga (canción), planta) sin necesitar un programador?
• ¿Quién decide qué es público? ¿La persona, la mucua, la galaxia?