00 · Opening: the seed

A baobab seed can spend years in dry ground waiting for rain. This module is the good kind of waiting: preparing the ground before digging.

How to study

1. Read from the outside in. First what people see (the website, the CLI), then the API, then the services, and the disk last. Each layer explains the one below it.
2. Read with a test open beside you. The suite in testes/ doesn't use pytest: each file is a script that builds a real galaxy in a temporary folder and checks one behaviour. The docstring at the top of each test tells the story of the bug it prevents. It is the best documentation the project has.
3. The comments are long on purpose. Almost every odd decision has a paragraph explaining the real bug that motivated it. Before "simplifying" something, read the comment.
4. Study in a circle. At the end of each module there are questions to talk about. Community code is best learned in a group.

Setting up the environment

# 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      # optional, for media/sync

bbx criar-galaxia "Study Galaxy"         # creates mucua, territory and admin
bbx api                                  # http://127.0.0.1:8000/docs

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

The password of the admin it creates is in ~/.baobaxia/credenciais.yaml.

Running the tests

bash testes/rodar_suite.sh          # everything (≈ 5 min)
python3 testes/test_merge_bbx.py    # a single file

The tests need neither FastAPI, git-annex nor a network: testes/_fake_fastapi.py lets you import the routes as plain functions, and a FakeSankofaBackend swaps git-annex for plain git. Without faster-whisper and tesseract, four cases of test_enriquecimento_whisper.py fail — that is expected.

On the front: npm run check (svelte-check) and npm run build.

Practice

1. Start the API and open /docs. Find three routes that don't require authentication. Why can each of them be public?
2. Log in as the admin (bbx login --usuario <admin>), create a saber (bbx publicar foto.jpg --titulo "Test") and open its folder in ~/.baobaxia/galaxias/. What is inside saber.bbx?
3. Run testes/test_quem_e_desambiguacao.py and read its docstring. What real-people problem does it solve?

To talk about

• What changes for whoever writes the code when the mucua sits in a quilombo school, with no technician nearby, rather than in a data center?