# BraDypUS

> BraDypUS is free, self-hosted software (AGPL-3.0) for managing relational data in
> the humanities and cultural heritage: archaeology, museums, archives, bibliographies.
> You define tables, fields, vocabularies and relations; it provides forms, search,
> import/export, users/groups/permissions, record versions, files, maps and print
> templates. PHP API + Vue app, on SQLite, MySQL/MariaDB or PostgreSQL, from Docker images.
> Current major version: v5.

Start here to judge whether a dataset is worth moving into BraDypUS, then go deeper
only as far as the task needs.

## Level 1 — decide

- [Is BraDypUS right for your data?](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/evaluate.md): fit checklist, what the data must look like, how much work a migration is (Markdown, ~5 KB)

## Level 2 — build

- [DBML import/export](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/dbml.md): describe a whole schema as text and import it in one step
- [Import data](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/usage/import.md): CSV, JSON, GeoJSON and photo imports, with key-field upsert
- [Creating an application](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/create-app/index.md): web form or command line
- [Field types](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/adding-columns.md), [relations](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/relations.md), [vocabularies](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/vocabularies.md)
- [Files and derived images](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/usage/files.md): photos and documents attached to records; **image presets** (name, width and/or height, fit `cover` = exact crop or `inside`, WebP/JPG, quality) are defined in the app settings (`imagePresets` in `PUT /api/config/app`) and served on demand, cached, at the public URL `/{app}/api/file/{preset}/{id}.{webp|jpg}`: made for a separate frontend or website that needs thumbnails and smaller sizes (`thumb`, 200×200 inside, always exists); a preset can carry a text `watermark` (template with `{{attribution}}`, position, colours, opacity), drawn on derived versions only. Files and derived versions are public and reachable by sequential id: no access control yet
- [Groups, permissions & locks](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/groups.md): who sees and changes which rows (rules can use group attributes via `$GROUP.<name>` and pin the values a create/update may write); freezing published records
- [Record layouts per group](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/record-layouts.md): a group can be given, per table, the templates (record layouts: fields, order, sections, accordions, plugin tables) its members must use; one template = no menu, several = a menu with only those, none = unchanged, admins never restricted (`PUT /api/group/{id}/layouts`, `GET /api/record/{tb}/templates` returns `assigned`/`locked`); **an interface convenience, NOT security**: fields a layout leaves out stay readable through API, search, filters and export, and the group rules remain the only authority; a template field item can carry `label`, `readonly`, `hidden` (screen only: the API still reads and writes those fields when the group rules allow); no inheritance or create-vs-edit layout yet
- [Database objects](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/database-objects.md): register tables and SQL views that already exist in the database (`GET /api/config/db-objects`, `POST …/{name}/activate`), and deactivate, remove from configuration or delete a table; configuration only, never DDL; `id` required
- [SQL views as tables](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/setup/views.md): hidden columns, rows per role and draft → review → validated flows are obtained with SQL views plus triggers, not with the permission screens (tried on MariaDB and PostgreSQL); a registered view is read-only or writable (SQLite: read-only unless the user adds INSTEAD OF triggers, example in the page; PostgreSQL/MariaDB: simple views are writable natively), cannot be altered from BraDypUS, views and triggers are created by the user with the super-admin Run SQL module (`POST /api/free-sql/run`, one statement per call, no DELIMITER), and `POST /api/config/table/{tb}/view-writable` re-reads how it can be written
- Ready-made skill that starts a new application from existing data with an assistant: [skills/bradypus-bootstrap/SKILL.md](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/skills/bradypus-bootstrap/SKILL.md); installable archive: [bradypus-bootstrap.zip](https://docs.bdus.lad-sapienza.it/bradypus-bootstrap.zip)

## Level 3 — reference

- [User guide (HTML)](https://docs.bdus.lad-sapienza.it/guide/): every feature, with screenshots
- [System plugins](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-docs/guide/system-plugins/index.md): geodata, Harris matrix, fuzzy dates, radiocarbon, osteology, Zotero, Pleiades
- [REST API](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/bdus-api/openapi.yaml): OpenAPI 3 contract (the same endpoints the app uses)
- [Developer documentation](https://docs.bdus.lad-sapienza.it/dev/): architecture, database, record lifecycle
- [Changelog](https://raw.githubusercontent.com/lad-sapienza/BraDypUS/v5/CHANGELOG.md)
- Source: https://github.com/lad-sapienza/BraDypUS