02 · Architettura: l'albero intero

Principi

1. Il file system è la fonte di verità. Ogni saber è un file saber.bbx (YAML + markdown) versionato in git; i binari passano per git-annex. L'indice SQLite è una cache: cancellalo ed esegui bbx reindex.
2. Prima offline. Ogni mucua funziona da sola. La rete è un di più.
3. Una federazione di pari. Non c'è una mucua centrale. Le mucua eseguono lo stesso codice; cambia solo la configurazione.
4. Modulare tramite variabili d'ambiente. BBX_AUTH_MODE attiva la crittografia; BBX_FED_XMPP/BBX_FED_AP attivano la federazione; BBX_ENRIQUECER attiva OCR e Whisper.

Strati del backend

flowchart TB
    subgraph Entradas["Ingressi (rami)"]
        API["api/v3/ — FastAPI<br/>~150 rotte"]
        CLI["cli.py — bbx"]
        BOT["federacao/xmpp_bot.py"]
        TIMERS["timer systemd<br/>bbx sincronizar · bbx enriquecer"]
    end
    subgraph Servicos["services/ — regole di dominio"]
        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/ — operazioni comuni a CLI e bot"]
        OPS["operacoes.py · processamento.py"]
    end
    subgraph Nucleo["core/ — il tronco"]
        SAB["saber.py — modello"]
        REPO["repository.py — SaberRepository"]
        IDX["index.py — GalaxyIndex (SQLite)"]
        REG["registry.py · relation_graph.py"]
    end
    subgraph Infra["infra/ — le radici"]
        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/ — testo · 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

La regola delle dipendenze: dall'alto verso il basso. core/ non importa services/; infra/ non conosce FastAPI. Quando vedi un import tardivo (dentro una funzione), quasi sempre serve a mantenere questa regola senza cicli.

Installazione di una mucua

flowchart LR
    pessoa(["browser"]) -->|":80"| NGINX
    subgraph Maquina["macchina della mucua (pacchetto 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/>ogni 30 min"]
        T2["baobaxia-enriquecer.timer<br/>20 min dopo ogni giro"]
        T3["baobaxia-healthcheck.timer<br/>ogni 2 min"]
        TOR["tor proprio<br/>SOCKS 19050 + servizio .onion"]
        SSHD["sshd<br/>utente 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(["un'altra mucua"]) -->|"git annex sync via SSH"| SSHD
    SSHD --> DADOS
    APIS -.->|"ssh / tor"| outra

Nota: tre processi scrivono nella stessa galassia (l'API, il timer di sync, il timer di arricchimento). Per questo esiste services/trava_galaxia.py — un flock tra processi — e l'indice apre SQLite con un timeout.

Una richiesta, dal clic al disco

sequenceDiagram
    autonumber
    actor P as Persona
    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 /it-IT/saber/ab12cd34
    F->>A: GET /saberes/ab12… (Bearer dal 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) in ogni galassia
    R->>I: get(uuid) — trova rel_path
    R-->>S: Saber (letto da saber.bbx + presenza su disco)
    S->>S: permissions.can(actor, READ, _resource_of(saber))
    S-->>A: to_public_dict(lang) + contesto
    A-->>F: JSON
    F-->>P: HTML

Esercizi

1. Scegli una rotta di api/v3/saberes.py e seguila fino al disco, annotando ogni file e funzione. Confronta con il diagramma di sequenza.
2. Cerca in services/ un import dentro una funzione. Quale ciclo evita?
3. In api/v3/app.py, quali middleware ci sono? Cosa sorveglia infra/vigia_api.py e perché?

Da discutere

• Quali sono i vantaggi e i costi del fatto che la verità sia il disco, e non il database?
• Se una mucua resta un anno senza rete, cosa succede quando torna?