01 · Concetti: il nome delle cose

Prima di mettere mano all'albero, impara il nome di ogni sua parte. In Baobáxia i concetti hanno nomi in portoghese, e il codice rispetta quei nomi.

Tutto è Saber

L'idea più importante del progetto: esiste un'unica entità, il Saber ("sapere", baobaxia/core/saber.py). Una foto, un articolo, una persona, una comunità, un intero archivio — tutto è un Saber con un campo nature diverso.

Perché "mucua" e non "server". Altrove, la macchina che conserva e consegna i dati si chiama server. Quel nome non ci piace: porta l'idea di una macchina che serve, messa a lavorare senza fine — una relazione di sfruttamento. Preferiamo una relazione di cura: la mucua è il frutto del baobab, che custodisce il seme e nutre; chi la mantiene è chi se ne prende cura (il PAJÉ). La parola compare nel codice e nella documentazione di strumenti esterni ("server XMPP", hooks.server.ts); in Baobáxia, è mucua.

Le nature stanno in un registro (baobaxia/natures/__init__.py), e ognuna ha uno schema pydantic di validazione (natures/schemas.py). Le comunità possono creare nature nuove tramite l'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  «chiave git-annex»
        +bool is_local  «solo nell'indice»
        +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 : allegati
    Saber ..> NatureSpec : nature
    Saber ..> Ref : relazioni e membri di collezione

Le parole della rete

• Mucua — il frutto del baobab. Ogni installazione è una mucua, con un UUID proprio salvato in ~/.baobaxia/mucua.yaml (infra/mucua_local.py). La mucua possiede un territorio d'origine e una galassia predefinita.
• Galassia (galaxia) — un archivio, cioè un repository git + git-annex. Una mucua conserva varie galassie; la stessa galassia vive in varie mucua.
• Mocambola — la persona (da mocambo, quilombo). Ha lo stesso UUID e la stessa chiave in tutta la rete; il ruolo è per galassia.
• Territorio — il suolo a cui la mucua è ancorata. I saberes ereditano il territorio della mucua se non ne indicano un altro.
• Link / rotta — la via per cui una galassia si sincronizza: un remote git (link) o un percorso sneakernet (rotta, rota).
• Richiesta (pedido) — "voglio una copia di questo file": viaggia nella rete fino a qualcuno che ha il file e lo riporta indietro.
• Lente / applicazione — un modo di guardare gli stessi saberes: archivio, blog, mappa, agenda, timeline, storie (applications/).

Ruoli

USER ⊂ PAJÉ ⊂ OXALÁ (constants.ROLE_LEVEL). USER cura i propri saberes; PAJÉ cura tutto ciò che è nella sua mucua; OXALÁ amministra le galassie in cui ha quel ruolo. Il modulo 05 entra nei dettagli.

Visibilità e protezione

Due assi che si sommano:

• visibility: public | mucua | private (campo del saber);
• data.protecao: publico | acl (solo i leitores, i lettori) | cifrado (solo i lettori, e con crittografia vera).

E la galassia può avere acesso: membros — una porta prima di tutte le altre.

Esercizi

1. Apri natures/schemas.py e trova lo schema di evento. Quali campi sono obbligatori? Crea un evento tramite l'API /docs e guarda la validazione rifiutare un campo sbagliato.
2. In core/saber.py, confronta to_metadata() e to_index_metadata(). Perché is_local non può finire nel file?
3. Elenca le relazioni in natures/relacoes.py. Quali sono simmetriche? Qual è l'inverso di e_copia_de?

Da discutere

• Perché "tutto è Saber" aiuta una comunità a creare cose nuove (una nature receita (ricetta), cantiga (canto), planta (pianta)) senza bisogno di un programmatore?
• Chi decide cosa è pubblico? La persona, la mucua, la galassia?