Reference
Quick reference for config setup, supported storage patterns, permissions, file types, limits, and glossary terms.
Setup storage
| Area | Source of truth |
|---|---|
| Install auth secret | BASEBUDDY_AUTH_SECRET |
| Local users and sessions | selected BaseBuddy app-data backend |
| Projects and members | selected BaseBuddy app-data backend |
| Permissions and author scopes | selected BaseBuddy app-data backend |
| Mapping and mapping revisions | selected BaseBuddy app-data backend |
| Sidebar layout | selected BaseBuddy app-data backend |
| Invitations | selected BaseBuddy app-data backend |
| Default app-data backend | basebuddy-data/basebuddy.config.json |
| Optional app-data backend | BASEBUDDY_APP_STATE_BACKEND=supabase-same-project or supabase-split-project |
| Content Postgres URL | BASEBUDDY_CONTENT_DATABASE_URL |
| Optional Supabase storage values | BASEBUDDY_SUPABASE_URL, BASEBUDDY_SUPABASE_PUBLISHABLE_KEY, BASEBUDDY_SUPABASE_SECRET_KEY |
| Optional public branding | NEXT_PUBLIC_BASEBUDDY_APP_NAME, NEXT_PUBLIC_BASEBUDDY_DOCS_URL, NEXT_PUBLIC_BASEBUDDY_SUPPORT_URL |
Configuration explains how these groups work, and How to configure production setup is the deployment checklist.
App data storage options compares basebuddy-data/, a separate Supabase/Postgres database, and the same database as your content.
Supported relation patterns
| Pattern | Typical use |
|---|---|
| Foreign key | One author or one category |
| Join table | Many tags or categories |
| Helper row | One metadata row per post |
| JSON path | Nested metadata or SEO values |
| Array value | List stored in one column |
| Value-match relation | Stored slug or code points at target row |
Mapping fields and relations explains these relation shapes in the editor, including author scopes and large relation search.
Common field families
| Family | Default behavior |
|---|---|
| Text and long text | Text input, textarea, or rich editor overlay |
| Numbers | Number or decimal input |
| Boolean | Toggle |
| Enum | Dropdown from allowed values |
| Date and datetime | Date/time input |
| JSON and XML | Structured editor or code editor when safe |
| Arrays | Repeatable editor or mapped item editor |
| Relations | Single or multi selector |
| Media and files | Picker connected to mapped storage |
| Geometry, ranges, composites, and network types | Structured controls when the contract is known; read-only when unsafe |
| Generated/system values | Read-only by default |
Storage contract and UI is the canonical product explanation for how these field families become controls.
Unsupported or read-only patterns
Fields default to read-only when the value is generated, view-derived, trigger-managed, a system identifier, an unknown composite, an opaque binary value without upload support, or a polymorphic relation without an explicit discriminator contract.
Use How to fix a field showing as read-only before trying to force a risky field writable.
File and media types
| Library | Accepted types |
|---|---|
| Media | avif, gif, jpeg, jpg, png, webp |
| Documents | doc, docx, pdf, rtf, txt, md |
| Spreadsheets | csv, xls, xlsx |
| Presentations | ppt, pptx |
| Data | json, xml |
| Archives | zip, gz, tar |
Media and files covers storage behavior, while Caps and rate limits lists upload sizes, batch sizes, and request limits.
Glossary
| Term | Meaning |
|---|---|
| Config data | BaseBuddy-owned setup data like projects, members, invites, roles, and mappings |
| Content data | Your app's existing posts, authors, taxonomy, media, and file records |
| Mapping | Saved contract that tells BaseBuddy how to read and write content |
| Storage contract | Field-level description of source, type, shape, editability, and patch mode |
| Semantic role | Optional meaning like title, content, slug, status, or published date |
| Dirty field | A field the user actually changed in the editor |
| Explicit action | A deliberate workflow action like Publish, Unpublish, or Archive |
For a narrative version of these terms, start with Core concepts and How BaseBuddy works.
Public API note
BaseBuddy's editor talks to internal app APIs. Treat those routes as implementation details unless a future release explicitly documents a public API.
CLI note
Use the CLI reference for setup, diagnostics, config-backed project administration, mapping/sidebar JSON imports, and storage mapping metadata. The CLI is the supported automation surface for agents; direct config-file edits should be emergency repair only.
FAQ
| Question | Answer |
|---|---|
| Does BaseBuddy create my content schema? | No. It maps your existing schema. |
| Does opening a post write to my database? | No. Opening content is a read-only path. |
| Does Save rewrite every mapped field? | No. Save only sends and writes the fields you changed. |
| Can I use one install for multiple projects? | Yes. One install can manage many mapped projects. |
| Can app state and content live separately? | Yes. Use BASEBUDDY_APP_STATE_BACKEND=supabase-split-project; editable content still uses the content database env value. |
| Are storage credentials saved in project rows? | No. Storage credentials live in environment variables. |
The safest first production check is still task-based: How to safely edit your first post.