01 · Conceitos: o nome das coisas

Antes de mexer na árvore, aprenda o nome de cada parte dela. No Baobáxia os conceitos têm nome em português, e o código respeita esses nomes.

Tudo é Saber

A ideia mais importante do projeto: existe uma entidade só, o Saber (baobaxia/core/saber.py). Uma foto, um artigo, uma pessoa, uma comunidade, um acervo inteiro — tudo é um Saber com um campo nature diferente.

Por que "mucua" e não "servidor". Em outros projetos, a máquina que guarda e entrega os dados se chama servidor (em inglês, server). A gente não gosta desse nome: ele carrega a ideia de uma máquina que serve, que é posta para trabalhar sem fim — uma relação de exploração. Preferimos uma relação de cuidado: a mucua é o fruto do baobá, que guarda a semente e alimenta; quem a mantém é quem cuida dela (o PAJÉ). No código e na documentação de ferramentas de fora a palavra aparece ("servidor XMPP", hooks.server.ts); no Baobáxia, é mucua.

As natures ficam num registro (baobaxia/natures/__init__.py), e cada uma tem um schema pydantic de validação (natures/schemas.py). Comunidades podem criar natures novas pela 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  «chave git-annex»
        +bool is_local  «só no í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 : relações e membros de coleção

As palavras da rede

• Mucua — o fruto do baobá. Cada instalação é uma mucua, com UUID próprio guardado em ~/.baobaxia/mucua.yaml (infra/mucua_local.py). A mucua é dona de um território-natal e de uma galáxia-padrão.
• Galáxia — um acervo, que é um repositório git + git-annex. Uma mucua guarda várias galáxias; a mesma galáxia vive em várias mucuas.
• Mocambola — a pessoa (de mocambo, quilombo). Tem o mesmo UUID e a mesma chave em toda a rede; o papel é por galáxia.
• Território — o chão que a mucua ancora. Saberes herdam o território da mucua se não disserem outro.
• Link / rota — por onde uma galáxia sincroniza: um remote git (link) ou um caminho de sneakernet (rota).
• Pedido — "eu quero uma cópia deste arquivo": viaja pela rede até alguém que tem o arquivo e o traz de volta.
• Lente / aplicação — um jeito de olhar os mesmos saberes: acervo, blog, mapa, agenda, linha do tempo, histórias (applications/).

Papéis

USER ⊂ PAJÉ ⊂ OXALÁ (constants.ROLE_LEVEL). USER cuida dos próprios saberes; PAJÉ cuida de tudo da sua mucua; OXALÁ administra as galáxias em que tem esse papel. O módulo 05 detalha.

Visibilidade e proteção

Dois eixos que se somam:

• visibility: public | mucua | private (campo do saber);
• data.protecao: publico | acl (só os leitores) | cifrado (só os leitores, e com criptografia de verdade).

E a galáxia pode ter acesso: membros — uma porta antes de todas as outras.

Práticas

1. Abra natures/schemas.py e ache o schema do evento. Quais campos são obrigatórios? Crie um evento pela API /docs e veja a validação recusar um campo errado.
2. Em core/saber.py, compare to_metadata() e to_index_metadata(). Por que is_local não pode ir para o arquivo?
3. Liste as relações em natures/relacoes.py. Quais são simétricas? Qual é o inverso de e_copia_de?

Para conversar

• Por que "tudo é Saber" ajuda uma comunidade a criar coisas novas (uma nature receita, cantiga, planta) sem precisar de programador?
• Quem decide o que é público? A pessoa, a mucua, a galáxia?