Skip to content

Toborverse Data Management

Welcome to the project documentation.

Use the navigation to browse each area:

  • Backend — API and server-side services
  • Frontend — web application
  • Extraction Worker — media and metadata extraction pipeline
  • Database — Postgres schema, RLS, and lifecycle docs
  • General — cross-cutting platform guides

Most sections are placeholders for now. The Database section includes the full database documentation.

Published site: toborliferobotics.github.io/ToborverseDataManagement

Contributing to the docs

Layout

All documentation lives under docs/:

Section Folder
Backend docs/backend/
Frontend docs/frontend/
Extraction Worker docs/extraction-worker/
Database docs/database/
General docs/general/

Every page must be listed in mkdocs.yml under the nav: key.

Adding a page

  1. Create a markdown file in the section folder, e.g. docs/backend/authentication.md.
  2. Register it in mkdocs.yml:
nav:
  - Backend:
      - Overview: backend/index.md
      - Authentication: backend/authentication.md
  1. Preview locally with ./docs.sh serve and open http://127.0.0.1:8000.
  2. Commit the new .md file and the updated mkdocs.yml.

Nested sections are supported — indent entries under a section name to create a submenu.

Database documentation

Database docs live in docs/database/ alongside the other sections. When you change SQL schema or behavior under database/, update the relevant pages:

  • docs/database/DATABASE.md — design rationale and overview
  • docs/database/SCHEMA_REFERENCE.md — developer reference
  • docs/database/EPISODE_CLIP_LIFECYCLE.md — app-side episode/clip flows

Add new database pages directly under docs/database/ and register them in mkdocs.yml.

Git notes

  • Markdown under docs/ is tracked; most other .md files in the repo are gitignored.
  • Do not commit the site/ folder — it is generated by mkdocs build.
  • Install dependencies once: uv pip install -r requirements-docs.txt (uses the parent .venv).

Useful commands

./docs.sh serve    # live preview with auto-reload
./docs.sh build    # static output in site/

Deploying to GitHub Pages

Docs deploy automatically when changes are pushed to dev or main that touch docs/, mkdocs.yml, or requirements-docs.txt. The workflow (.github/workflows/docs.yml) builds the site and publishes it to the gh-pages branch.

One-time repo setup (requires admin access):

  1. Open Settings → Pages on GitHub.
  2. Under Build and deployment, set Source to Deploy from a branch.
  3. Choose branch gh-pages, folder / (root), and save.

After the first successful workflow run, the site is live at:

https://toborliferobotics.github.io/ToborverseDataManagement/

To deploy manually from your machine (requires push access):

./docs.sh gh-deploy --force