02 · Arquitetura: a árvore inteira

Princípios

1. O sistema de arquivos é a fonte da verdade. Cada saber é um arquivo saber.bbx (YAML + markdown) versionado no git; binários vão pelo git-annex. O índice SQLite é um cache: apague e rode bbx reindex.
2. Offline primeiro. Cada mucua funciona sozinha. Rede é bônus.
3. Federação de iguais. Não há mucua central. Mucuas rodam o mesmo código; muda só a configuração.
4. Modular por variável de ambiente. BBX_AUTH_MODE liga a criptografia; BBX_FED_XMPP/BBX_FED_AP ligam a federação; BBX_ENRIQUECER liga OCR e Whisper.

Camadas do backend

flowchart TB
    subgraph Entradas["Entradas (galhos)"]
        API["api/v3/ — FastAPI<br/>~150 rotas"]
        CLI["cli.py — bbx"]
        BOT["federacao/xmpp_bot.py"]
        TIMERS["timers systemd<br/>bbx sincronizar · bbx enriquecer"]
    end
    subgraph Servicos["services/ — regras do negócio"]
        SS["SaberService<br/>(saber_service.py)"]
        PERM["permissions · acl · grupos<br/>acesso_galaxia"]
        SYNC["sincronizacao · links<br/>pedidos · propagacao"]
        OUT["copias · restauro · historico<br/>recovery · challenge · jobs"]
    end
    subgraph Pub["publica/ — operações comuns da CLI e do bot"]
        OPS["operacoes.py · processamento.py"]
    end
    subgraph Nucleo["core/ — o tronco"]
        SAB["saber.py — modelo"]
        REPO["repository.py — SaberRepository"]
        IDX["index.py — GalaxyIndex (SQLite)"]
        REG["registry.py · relation_graph.py"]
    end
    subgraph Infra["infra/ — as raízes"]
        STO["storage.py — .bbx"]
        SANK["sankofa.py + sync/ — git-annex"]
        IDT["identity · envelope · jwt"]
        NET["tor_service · farol_lan · ssh_keys"]
    end
    FED["federacao/ — XMPP · ActivityPub"]
    ENR["enriquecimento/ — texto · OCR · Whisper"]
    FS[("disco: ~/.baobaxia/galaxias/*<br/>git + git-annex")]

    API --> SS
    CLI --> OPS --> SS
    BOT --> OPS
    TIMERS --> SYNC
    TIMERS --> ENR
    SS --> PERM
    SS --> SYNC
    SS --> OUT
    SS --> REPO
    FED --> SS
    ENR --> REPO
    REPO --> SAB
    REPO --> IDX
    REPO --> STO
    REPO --> SANK
    SYNC --> SANK
    SYNC --> NET
    PERM --> IDT
    STO --> FS
    SANK --> FS

A regra de dependência: de cima para baixo. core/ não importa services/; infra/ não conhece FastAPI. Quando você ver um import tardio (dentro de função), quase sempre é para manter essa regra sem ciclo.

Implantação de uma mucua

flowchart LR
    pessoa(["navegador"]) -->|":80"| NGINX
    subgraph Maquina["máquina da mucua (pacote baobaxia.deb)"]
        NGINX["nginx<br/>sites-available/baobaxia"]
        FRONT["baobaxia-front<br/>node build/index.js :3000"]
        APIS["baobaxia-api<br/>bbx api :8000"]
        T1["baobaxia-sincronizar.timer<br/>a cada 30 min"]
        T2["baobaxia-enriquecer.timer<br/>20 min após cada rodada"]
        T3["baobaxia-healthcheck.timer<br/>a cada 2 min"]
        TOR["tor próprio<br/>SOCKS 19050 + serviço .onion"]
        SSHD["sshd<br/>usuário baobaxia → git-annex-shell"]
        DADOS[("/var/lib/baobaxia/.baobaxia")]
    end
    NGINX -->|"/"| FRONT
    NGINX -->|"/api/"| APIS
    FRONT -->|"SSR: 127.0.0.1:8000"| APIS
    APIS --> DADOS
    T1 --> DADOS
    T2 --> DADOS
    TOR -->|".onion → :8000"| APIS
    outra(["outra mucua"]) -->|"git annex sync via SSH"| SSHD
    SSHD --> DADOS
    APIS -.->|"ssh / tor"| outra

Repare: três processos escrevem na mesma galáxia (API, timer de sync, timer de enriquecimento). Por isso existe services/trava_galaxia.py — um flock entre processos — e o índice abre o SQLite com timeout.

Uma requisição, do clique ao disco

sequenceDiagram
    autonumber
    actor P as Pessoa
    participant F as Front (SSR)
    participant A as API /api/v3
    participant D as deps.py
    participant S as SaberService
    participant R as SaberRepository
    participant I as GalaxyIndex
    P->>F: GET /pt-BR/saber/ab12cd34
    F->>A: GET /saberes/ab12… (Bearer do cookie)
    A->>D: current_mocambola(token)
    D-->>A: {uuid, role, galaxias, mucua, grupos}
    A->>S: get_saber(uuid, actor)
    S->>R: _find_saber → repo.get(uuid) em cada galáxia
    R->>I: get(uuid) — acha rel_path
    R-->>S: Saber (lido do saber.bbx + presença do disco)
    S->>S: permissions.can(actor, READ, _resource_of(saber))
    S-->>A: to_public_dict(lang) + contexto
    A-->>F: JSON
    F-->>P: HTML

Práticas

1. Escolha uma rota de api/v3/saberes.py e siga até o disco, anotando cada arquivo e função. Compare com o diagrama de sequência.
2. Procure em services/ um import dentro de função. Que ciclo ele evita?
3. Em api/v3/app.py, quais middlewares existem? O que infra/vigia_api.py vigia e por quê?

Para conversar

• Quais são as vantagens e os custos de o disco ser a verdade, e não o banco?
• Se uma mucua fica um ano sem rede, o que acontece quando ela volta?