Core concepts
Learn the terms BaseBuddy uses for projects, mappings, storage contracts, semantic roles, and field behavior.
Projects
A project is a BaseBuddy workspace for one content schema. It holds the project name, slug, members, permissions, mapping revisions, and editor settings.
The project doesn't own your content tables. It just points at them through the saved mapping.
Use Projects and mappings for the model, and How to create a BaseBuddy project when you are making the first project in the app.
Saved mappings
A mapping is the contract between BaseBuddy and your database. It tells BaseBuddy which table holds content, which fields show up in the editor, which relations exist, and how each value gets read and written.
Auto-detection can suggest a starting mapping, but the saved version is what actually runs at runtime. If your database changes, update the mapping before expecting the editor to reflect those changes.
How mapping works on BaseBuddy walks through the mapping screen as a task, while Mapping fields and relations explains the common field and relation shapes.
Storage contract
The storage contract describes the actual shape of how data is stored:
| Part | What it means |
|---|---|
| Source | Table, column, relation, JSON path, helper row, or storage path |
| Primitive | Direct column, JSON path, array, relation, helper row, or read-only derived value |
| Value kind | Text, number, boolean, date, enum, relation, markdown, JSON, media, file, etc. |
| Cardinality | Single value or list |
| Nullability | Required or nullable |
| Editability | Writable, read-only, or unsupported |
| Patch mode | How BaseBuddy writes the changed value back safely |
The editor renders its controls based on this contract.
Storage contract and UI expands this into the supported placement and value-kind rules.
Semantic roles
Semantic roles describe what a field means in your content workflow. Examples include title, content, slug, status, published date, excerpt, SEO title, and featured image.
They refine behavior but don't replace storage rules. A field mapped as status still has to respect its underlying storage type, write mode, and permission requirements.
That distinction matters most for workflow fields; Publishing workflows explains why status changes require publish permission.
Read-only and unsupported fields
Read-only means BaseBuddy can display the value but won't write to it. Unsupported means it can't safely understand or render the shape.
This is a safety feature, not a bug. Generated columns, trigger-managed fields, view-derived values, or unclear relations that can't be patched safely get flagged honestly rather than pretending they're editable.
When you see this state in the editor, How to fix a field showing as read-only helps you decide whether to fix the mapping or leave the field protected.
The safety rule
Normal Save writes only the fields you changed. Publish, Unpublish, and Archive are explicit actions. BaseBuddy never renames tables, reshapes columns, or converts content into a different storage format just because someone opened a page.
Safe editing model is the deeper reference before production writes.