Developer documentation

This section is for people who change the code or run a deployment.

• Architecture: the services, Django apps and data model, and how requests and background tasks flow.
• Configuration reference: every environment variable.
• White-label deployments: how to give a deployment its own name, look, languages and pages without changing the code.
• Phone sign-in: one-time codes by text message, and how to write a messaging provider.
• Translations: how translators edit and publish the interface in a deployment's languages.
• Usage metrics: the count-only rollups behind the staff usage page, with the exact definition of every metric.

To run the platform locally, start with Getting started. To send a change, read the contributing guide.

Day-to-day commands

All commands run inside the django service.

Task	Command
Start the stack	docker compose up --build
Rebuild the stylesheet as you edit templates	docker compose --profile css up
Run the tests	docker compose run --rm django pytest
Coverage	docker compose run --rm django coverage run -m pytest && docker compose run --rm django coverage report
Lint and format	docker compose run --rm django ruff check . && docker compose run --rm django ruff format .
Create migrations	docker compose run --rm django python manage.py makemigrations
Django shell	docker compose run --rm django python manage.py shell
Admin user	docker compose run --rm django python manage.py createsuperuser

Without Docker you need Python 3.14, uv, PostgreSQL and a Redis-protocol server. Set DATABASE_URL and REDIS_URL, then use uv run pytest, uv run python manage.py runserver, and so on.

Code layout

config/              Django settings, URLs, Celery app, WSGI entry point
  settings/          base.py (shared), local.py, test.py, production.py
baibu/
  core/              platform settings in templates, health check, worker heartbeat
  users/             accounts, profile, consent history, account deletion requests
  submissions/       text contributions and cleaning
  localization/      interface translations: drafts, publishing, loading
  metrics/           count-only usage rollups and the staff usage page
  theme/             Tailwind source (static_src/); builds static/css/dist/styles.css
  templates/         Django templates; allauth/ restyles the sign-in pages
  static/            images, built CSS
compose/django/      Dockerfile and container start scripts
deployment/          a deployment's own templates, translations and static files
docs/                this documentation site (MkDocs)

Further feature apps (chat, staff, notifications, analytics) are added as later stages land; see the roadmap.