00 · Abertura: a semente

Uma semente de baobá pode passar anos na terra seca esperando a chuva. Este módulo é a espera boa: preparar o chão antes de cavar.

Como estudar

1. Leia de fora para dentro. Primeiro o que a pessoa vê (o site, a CLI), depois a API, depois os serviços, por último o disco. Cada camada explica a de baixo.
2. Leia com um teste aberto ao lado. A suíte em testes/ não usa pytest: cada arquivo é um script que monta uma galáxia de verdade numa pasta temporária e confere um comportamento. O docstring do topo de cada teste conta a história do bug que ele impede. É a melhor documentação do projeto.
3. Os comentários são longos de propósito. Quase toda decisão estranha tem um parágrafo explicando o bug real que a motivou. Antes de "simplificar" algo, leia o comentário.
4. Estude em roda. No fim de cada módulo há perguntas para conversar. Código comunitário se aprende melhor em grupo.

Montar o ambiente

# backend
cd bbx-v3-back
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt && pip install -e .
sudo apt install git-annex ffmpeg poppler-utils      # opcionais para mídia/sync

bbx criar-galaxia "Galáxia de Estudo"   # cria mucua, território e admin
bbx api                                  # http://127.0.0.1:8000/docs

# frontend (outro terminal)
cd bbx-v3-front
npm ci
npm run dev                              # http://localhost:5173

A senha do admin criado fica em ~/.baobaxia/credenciais.yaml.

Rodar os testes

bash testes/rodar_suite.sh          # tudo (≈ 5 min)
python3 testes/test_merge_bbx.py    # um arquivo só

Os testes não precisam de FastAPI, git-annex nem rede: testes/_fake_fastapi.py deixa importar as rotas como funções comuns, e um FakeSankofaBackend troca o git-annex por git puro. Sem faster-whisper e tesseract, quatro casos de test_enriquecimento_whisper.py falham — é esperado.

No front: npm run check (svelte-check) e npm run build.

Práticas

1. Suba a API e abra /docs. Ache três rotas que não pedem autenticação. Por que cada uma pode ser pública?
2. Entre com o admin (bbx login --usuario <admin>), crie um saber (bbx publicar foto.jpg --titulo "Teste") e abra a pasta dele em ~/.baobaxia/galaxias/. O que tem dentro de saber.bbx?
3. Rode testes/test_quem_e_desambiguacao.py e leia o docstring. Que problema de gente de verdade ele resolve?

Para conversar

• O que muda em quem programa quando a mucua está numa escola de quilombo, sem técnico por perto, e não num data center?