Black Bean Tables — Features & Technology
Black Bean Tables — Features & Technology Reference for product scope, module layout, and stack. Current release: v4.64.0 (schema 3.9.0). Product positioning: Self-hosted Work OS inside WordPress — Monday.com-style boards without an…
Black Bean Tables — Features & Technology
Reference for product scope, module layout, and stack. Current release: v4.64.0 (schema 3.9.0).
Product positioning: Self-hosted Work OS inside WordPress — Monday.com-style boards without an external SaaS dependency.
Related docs: GETTING-STARTED.md · QA-CHECKLIST.md · WORDPRESS-ORG.md
Technology stack#
| Layer | Technology | Role |
|---|---|---|
| Runtime | PHP 8.1+, WordPress 6.0+ | Plugin bootstrap, hooks, capabilities |
| Database | MySQL via $wpdb |
Physical tables + JSON metadata registry |
| Architecture | Module registry (BB_CT_Module_Registry) |
22 pluggable modules via BB_CT_Module_Interface |
| HTTP API | WP REST API | /wp-json/blackbean-tables-schemas/v1/… |
| Admin UI | Tailwind CSS 3.4, PostCSS | tables-admin-shell.css, tables-admin-ct.css |
| Board workspace | Vanilla JS + jQuery | Inline edit, item panel, realtime, inbox |
| Build | Node.js (npm run build) |
Tailwind compile + shell CSS copy |
| Tests | PHP smoke + Playwright | npm run test:all, npm run test:e2e:wp |
| Search (optional) | Meilisearch | Optional backend; local MySQL search by default |
| AI (optional) | Configurable HTTP LLM client | Generate app / schema from natural language |
| Frontend embed | Shortcodes | [blackbean_tables], [blackbean_form] |
Core pattern: Schema-driven — table/column definitions live in a registry → DDL syncs to MySQL → views, forms, automations, and API read the same metadata.
Data layer#
| Feature | Purpose |
|---|---|
Schema registry (wp_bb_table_schemas) |
Stores columns, indexes, relations, UI JSON per logical table |
| DDL sync | Creates/updates real MySQL tables from schema (dbDelta) |
| Row repository | CRUD, pagination, cursor pagination, soft delete |
| Query builder | Filter, sort, search, filter groups (AND / OR) |
| Relations | Linked records across tables |
| Subitems | Child records within a board context |
| Mirror / rollup fields | Reflect or aggregate values from related tables |
| CSV import / export | Bulk data in/out; export capped at 10k rows |
| Core tables | Read-only views of WordPress data (posts, users, terms, etc.) |
Boards & workspace#
| Feature | Purpose |
|---|---|
| Boards (apps) | Workspace unit: multiple tables, views, forms, automations |
| Boards dashboard | Folder grouping, stats, global workspace search |
| Built-in templates | Bookings, CRM, Inventory, Projects — one-click install |
| Blank board | Empty app scaffold |
| Board settings | Icon, description, folder, team, archive/restore, JSON import/export |
| Teams | Light multi-tenancy: members, roles, filter boards by team |
| Onboarding hero | First-run guidance when no boards exist |
Views (all implemented)#
| View | Purpose |
|---|---|
| Grid | Spreadsheet; inline edit, bulk actions, lazy rendering for 200+ rows |
| Kanban | Columns by status/select; drag-and-drop |
| List | Compact single-column list |
| Calendar | Month/week by date; status/assignee badges; bulk on events |
| Timeline | Gantt-style schedule |
| Gallery | Cards with cover image from attachments |
| Chart | Bar / pie / line grouped by field; drill-down |
View extras: Saved filters, personal views, query bar, load-more pagination, per-user column layout.
Field types (24)#
text, number, email, url, phone, password, date, time, datetime, boolean, select, multi_select, tags, json, file, image, color, rating, progress, rich_text, markdown, relation, uuid, user
Field type drives form inputs, grid formatters, and view suggestions (e.g. select → Kanban, date → Calendar).
Forms#
| Feature | Purpose |
|---|---|
| Form builder | Create/edit records inside a board |
| Public forms | Frontend submission via shortcode |
| reCAPTCHA v3 | Spam protection on public forms |
| Rate limiting | Throttle public submissions |
| Submission log | Audit trail for public form posts |
Automations#
Triggers: record_created, record_deleted, field_changed, field_equals, scheduled (hourly/daily)
Actions: send_email, set_field, log, call_webhook, create_record, notify_user (inbox + optional email)
Extras: Nested condition groups (AND within group, OR between groups), delay queue, WP-Cron scheduler.
Workflows & approvals#
| Feature | Purpose |
|---|---|
| Status steps | Ordered workflow (e.g. todo → doing → done) |
| Backward move rules | Block or require approval for backward transitions |
| Approval queue | Managers approve/reject on Workflows screen |
| Workflow history | Transition log in item panel |
| Inbox notifications | Alerts for approval requests and decisions |
Toggle workflow notifications under Board → Integrations.
Permissions & security#
| Feature | Purpose |
|---|---|
| Board roles | Viewer / Editor presets mapped to WP roles |
| Row access | assignee_only — non-managers see only assigned rows |
| Board members | Per-user board membership |
| API keys | REST access with read/write field scopes |
| OAuth apps | OAuth2 with field scope parity |
| REST rate limiting | Request throttling |
| Row access audit | Log API row access |
| CORS origins | Allowed origins for embed/API |
Integrations & API#
| Feature | Purpose |
|---|---|
| REST rows | GET/POST/PATCH/DELETE; filters, cursor, X-Total-Count |
| REST schemas | Table structure over API |
| REST search | Workspace search (boards + records) |
| REST inbox | Notification drawer (REST primary; admin-ajax fallback) |
| REST events (SSE) | Realtime workspace refresh signals |
| GraphQL endpoint | Optional query layer |
| Webhooks | Outbound signed JSON POST |
| Webhook dead-letter | Failed delivery queue + manual retry |
| Webhook delivery log | Delivery history |
Base URL example: /wp-json/blackbean-tables-schemas/v1/schemas/{table}/rows
Notifications & collaboration#
| Feature | Purpose |
|---|---|
| In-app inbox | Header bell + full Inbox admin page |
| Assignee notifier | Notify when assigned to a record |
| Record watchers | Follow records; notify on updates |
| @mentions | Parse mentions in comments |
| Email digest | Scheduled unread inbox summary |
| Inbox preferences | Per-user notification settings |
Comments & activity#
| Feature | Purpose |
|---|---|
| Record comments | Thread on item panel; markdown preview |
| Activity feed | Board change history; SSE live refresh |
| Audit log | Schema/row change logging; export |
Dashboards & formulas#
| Feature | Purpose |
|---|---|
| Dashboard widgets | KPI counters/aggregates at top of board |
| Live refresh | Widgets update on board changes |
| Formulas | Computed columns via expression evaluator |
Search#
| Feature | Purpose |
|---|---|
| Global workspace search | Find boards and records from dashboard |
| Local search | Default MySQL-backed search |
| Meilisearch | Optional backend; highlighted snippets in query bar |
| Saved filters | Persist filter sets per view |
Configure search backend under Settings.
Realtime#
| Feature | Purpose |
|---|---|
| SSE broadcaster | Refresh grid/kanban when data changes |
| Presence | Show who is viewing a board |
| Field lock | Reduce concurrent edit conflicts |
AI & marketplace#
| Feature | Purpose |
|---|---|
| Generate app | AI creates board + tables + views from description |
| AI regen view | Suggest/apply view layout |
| Marketplace | Import/export app JSON between sites |
| Template exporter | Export board as shareable template |
Embed & blocks#
| Feature | Purpose |
|---|---|
[blackbean_tables] |
Embed read-only board on frontend |
[blackbean_form] |
Embed public form |
| Lazy load | Defer embed assets until needed |
| Embed inbox | Notification bell for embedded board members |
Admin screens#
| Screen | Purpose |
|---|---|
| Black Bean Tables | Boards dashboard + templates |
| Board workspace | Views + item detail panel |
| Fields / Relations / Views | Board schema configuration |
| Forms / Automations / Workflows | Builders |
| Dashboards / Formulas / Filters | KPIs and logic |
| Permissions / Settings / Export | Board administration |
| Activity / Webhooks / Integrations | Operations |
| Inbox | Notification management |
| All tables / Browse / Structure | Table-level CRUD (power users) |
| Settings | Meilisearch, seeder, teams |
| AI Generate / Marketplace | Create and share apps |
Admin shell uses a dark header bar, Tailwind components, and Dashicons.
Module registry (22 modules)#
| Module ID | Responsibility |
|---|---|
data |
Row storage, query execution |
fields |
Field types, formatters, relations |
forms |
Form builder, public forms |
query |
Query UI, filter bar |
permissions |
Board/row access |
boards |
Board CRUD, workspace pages |
views |
View renderers (grid, kanban, …) |
templates |
App template install |
automations |
Triggers, actions, scheduler |
formulas |
Computed columns |
dashboards |
KPI widgets |
api |
Webhooks, GraphQL |
workflows |
Status transitions, approvals |
search |
Engine + saved filters |
realtime |
SSE, presence, field lock |
ai |
Generate app / schema |
marketplace |
Import/export apps |
blocks |
Shortcodes, embed |
import |
CSV import/export |
audit |
Audit logging |
comments |
Record comments |
notifications |
Inbox, email, digest |
Extend via bb_tables_register_modules and bb_tables_modules_booted.
Comparison (high level)#
| Capability | Black Bean Tables | Monday.com | Airtable |
|---|---|---|---|
| Hosting | Self-hosted WordPress | SaaS | SaaS |
| Data store | Your MySQL | Vendor cloud | Vendor cloud |
| Custom tables / DDL | Yes (schema sync) | Limited | Yes (bases) |
| Kanban / Grid / Calendar | Yes (7 views) | Yes | Yes |
| Automations | Yes (built-in) | Yes | Yes |
| REST API | Yes (WP REST) | Yes | Yes |
| Workflow approvals | Yes | Yes (paid tiers) | Limited |
| WordPress native auth | Yes | No | No |
| No monthly per-seat (plugin) | Yes* | No | No |
* Plugin is GPL; hosting and optional Meilisearch/AI costs are yours.
Testing & release#
npm run build # CSS assets
npm run test # PHP smoke
npm run test:e2e # Playwright admin smoke
npm run test:all # PHP + smoke E2E
npm run test:e2e:wp # WordPress site smoke (blackbean.test)
Pre-GTM checklist: QA-CHECKLIST.md
One-line summary#
Black Bean Tables turns WordPress into a no-code Work OS: schema-backed MySQL, seven board views, forms, automations, workflow approvals, permissions, REST/OAuth/webhooks, inbox, and realtime — built with PHP 8.1 strict types, WP REST, Tailwind admin UI, and jQuery workspace scripts.