00 · Apertura: la semilla

Una semilla de baobab puede pasar años en la tierra seca esperando la lluvia. Este módulo es la buena espera: preparar el suelo antes de cavar.

Cómo estudiar

1. Lee de afuera hacia adentro. Primero lo que la persona ve (el sitio, la CLI), después la API, después los servicios y por último el disco. Cada capa explica la de abajo.
2. Lee con un test abierto al lado. La suite de testes/ no usa pytest: cada archivo es un script que monta una galaxia de verdad en una carpeta temporal y comprueba un comportamiento. El docstring al inicio de cada test cuenta la historia del bug que evita. Es la mejor documentación del proyecto.
3. Los comentarios son largos a propósito. Casi toda decisión extraña tiene un párrafo que explica el bug real que la motivó. Antes de "simplificar" algo, lee el comentario.
4. Estudia en ronda. Al final de cada módulo hay preguntas para conversar. El código comunitario se aprende mejor en grupo.

Preparar el entorno

# 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      # opcionales, para medios/sync

bbx criar-galaxia "Galaxia de Estudio"   # crea mucua, territorio y admin
bbx api                                  # http://127.0.0.1:8000/docs

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

La contraseña del admin creado queda en ~/.baobaxia/credenciais.yaml.

Correr los tests

bash testes/rodar_suite.sh          # todo (≈ 5 min)
python3 testes/test_merge_bbx.py    # un solo archivo

Los tests no necesitan FastAPI, git-annex ni red: testes/_fake_fastapi.py permite importar las rutas como funciones comunes, y un FakeSankofaBackend cambia git-annex por git puro. Sin faster-whisper y tesseract, cuatro casos de test_enriquecimento_whisper.py fallan — es lo esperado.

En el front: npm run check (svelte-check) y npm run build.

Prácticas

1. Levanta la API y abre /docs. Encuentra tres rutas que no piden autenticación. ¿Por qué cada una puede ser pública?
2. Entra con el admin (bbx login --usuario <admin>), crea un saber (bbx publicar foto.jpg --titulo "Prueba") y abre su carpeta en ~/.baobaxia/galaxias/. ¿Qué hay dentro de saber.bbx?
3. Corre testes/test_quem_e_desambiguacao.py y lee su docstring. ¿Qué problema de gente de verdad resuelve?

Para conversar

• ¿Qué cambia para quien programa cuando la mucua está en una escuela de quilombo, sin técnico cerca, y no en un data center?