# 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](./GETTING-STARTED.md) · [QA-CHECKLIST.md](./QA-CHECKLIST.md) · [WORDPRESS-ORG.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

```bash
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](./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.