BraDypUS

Appearance

Is BraDypUS right for your data? ​

A short checklist to decide whether a dataset or a project is worth moving into BraDypUS, written for people and for the assistants (LLMs, agents) that help them. Each section ends with a link to the page that goes deeper.

What BraDypUS is ​

A web application for relational data about things that are described, related and located: archaeological contexts and finds, museum or archive records, bibliographic or prosopographic data, field surveys. You define the tables and fields yourself; the application provides forms, lists, search, import/export, users and permissions, versions of every record, files, maps and print templates on top of them.

  • Free software (AGPL-3.0), self-hosted: your server, your database. No hosted service.
  • PHP API + Vue single-page app; runs on SQLite, MySQL/MariaDB or PostgreSQL, normally from Docker images (requirements).
  • Several independent applications (databases) can live on one installation.

It is a good fit when ​

  • Your data are several tables linked to each other (a context has many finds, a find belongs to a site, a record cites sources), possibly now living in spreadsheets or an Access/FileMaker file.
  • You need a shared database with accounts: people who only read, people who edit, reviewers who see only a slice, and records that must be frozen once published (groups & locks); each group can also have its own record layout (which fields, in which order, the cataloguer, the reviewer or the reader sees), as a convenience only (record layouts).
  • You want controlled vocabularies, validation (not empty, unique, range, regex) and a history of every change with the possibility to restore a previous version (versions).
  • Some records have geometry (points, lines, polygons) to show on a map, or a chronology (also vague: "c4l BCE", "post quem") to put on a timeline (geodata, fuzzy dates).
  • You work with stratigraphy, radiocarbon dates, skeletal inventories, Zotero bibliographies or Pleiades places: these are built in (system plugins).
  • Files (photos, documents) have to be attached to records, in bulk if needed (files, import). A separate frontend or website can ask for them in smaller sizes (thumbnails, previews): you define named presets in the app settings and the images are generated on first request and cached (derived images).

It is probably not the right tool when ​

  • The data are one flat table nobody else edits: a spreadsheet is simpler.
  • You need analytics over very large, append-only data (millions of rows to aggregate): use a data warehouse or a GIS database; BraDypUS can hold the descriptive records next to it.
  • You need a public, hosted website out of the box: BraDypUS is the editing and research database; publishing is done through its API or exports. Note that uploaded files, and their derived sizes, are served without authentication and reachable by sequential id: material that must stay private does not belong there (access control for files is not available yet).
  • You need permissions per field or a workflow engine with notifications: BraDypUS's own permission engine works per table and per row (a rule can use group attributes, e.g. "the records of my site", and pin the value a field may take when records are created or saved), and locks freeze rows; there is nothing finer. A group's record layout chooses which template (fields, order, sections) its members get, but it is a convenience: a field it leaves out is still reachable through the API, search and export; a layout can also show a field read-only or under another label, but only on screen: the server does not know. Hidden columns, rows per role and a draft → review → validated flow can still be had with SQL views and triggers in the database (SQL views as tables), at the price of writing that SQL and of the limits that page lists (tried on MariaDB and PostgreSQL; no notifications). BraDypUS registers such views and knows whether they can be written, but never creates them or writes their SQL: on PostgreSQL and MariaDB a view on one table is writable as it is; on SQLite it is read-only (fine for charts and the API) unless you add INSTEAD OF triggers yourself.
  • You cannot host and back up a small web application.

What your data must look like ​

BraDypUS expectsWhat it means for your data
A table per kind of thingOne sheet or file per entity; mixed sheets must be split first
Primary key id on every tableCreated automatically if missing; your own identifier becomes a normal field
Relations between tablesStored as an id of the other table; a ref: in the DBML (or Config → Relations) creates the foreign key and the linked-records panel on both sides, and a select field "from table" lists the other table's records
Controlled valuesVocabularies (lists) for select / multi_select / combo_select fields
Text, long text, Markdown, date, yes/no, selectThe field types; numbers are stored as text or integer and validated with rules, not as a separate numeric type
Tables that already exist in a databaseThey are registered, not copied: Config → Database objects lists the tables and SQL views the database has and BraDypUS does not know, and activates them. Each needs an id column; a view that can be written needs a creator column too
Geometry as WKT / GeoJSONEnabled per table with the Geodata plugin; GeoJSON is imported onto existing records

Checklist before deciding, answer these about your data:

  1. How many tables, and how are they linked? (Draw it: boxes and arrows.)
  2. Is there a natural identifier per table? Is it unique?
  3. Which columns have a closed list of values?
  4. Are there geometries, uncertain dates, stratigraphic relations, bibliographic references?
  5. Who edits, who only reads, who must see only part of the data?
  6. Do some records have to become read-only once validated?
  7. Must some roles not see some columns, or move records through states (draft → review → validated)? That is possible with SQL views, not with the permission screens: SQL views as tables.
  8. Where do files live, and how are they named so they can be linked to records? Will a frontend or website show the images? Then decide the sizes it needs: they become presets (e.g. thumb, medium) and each is a stable URL per image (derived images).

How much work is a move ​

Typical order, from cheapest to most expensive step:

  1. Describe the schema in DBML (a plain-text format) and import it in one go: tables, labels, vocabularies and foreign keys are created together (DBML import). This is the step an assistant does well.
  2. Import the rows from CSV or JSON, with a mapping from columns to fields and a key field for update-or-insert; the whole import is one transaction, so it either succeeds or changes nothing (import).
  3. Check the result with the schema validator and a few records opened by hand (validation).
  4. Users, groups and print templates, which depend on how you work, not on the data.

For a handful of well-formed tables this is an afternoon; the real cost is almost always cleaning the source data (duplicates, free text that should be a vocabulary, identifiers that are not unique), not BraDypUS itself.

Go deeper ​