Architecture
Distribution Layer
The distribution layer provides two channels for consuming components:
- MCP — For AI agents (VS Code Copilot, Kiro, Claude Code). Lists components, reads source code, generates examples.
- CLI Tool — For developers.
buildpad init,buildpad add,buildpad bootstrap.
Both tools read from the same registry.json schema — the MCP server bundles it at build time, while the CLI reads it from disk or fetches it remotely at runtime.
Source Layer
The source layer contains all the packages in the monorepo:
| Package | Description |
|---|---|
@buildpad/types | Shared TypeScript type definitions (Field, Collection, Query, etc.) |
@buildpad/services | Services (FieldsService, CollectionsService) + DaaS API config |
@buildpad/hooks | React hooks for auth, permissions, relations, selection, presets |
@buildpad/utils | Field interface mapper, validation, formatting utilities |
@buildpad/ui-interfaces | 40+ field interface components built with Mantine v8 |
@buildpad/ui-form | VForm dynamic form component with permission enforcement |
@buildpad/ui-table | VTable dynamic data table with sorting, selection, drag-drop |
@buildpad/ui-collections | CollectionForm (CRUD wrapper) + CollectionList (paginated table) |
@buildpad/ui-files | FileManager + FileDetail — upload, folders, preview, bulk actions (recipe) |
@buildpad/ui-forms | Visual FormBuilder + DynamicForm runtime — the Dynamic Form Builder module (recipe) |
@buildpad/ui-users | Users/roles/policies admin — RBAC management with a permissions matrix (recipe) |
@buildpad/ui-workflows | Workflow admin — definitions with a state diagram editor, assignments, read-only instances (recipe) |
@buildpad/ui-cron | Cron jobs admin — jobs list with row actions, job editor with a code editor slot, run history with logs (recipe) |
@buildpad/ui-chat | AI chat with a Chocolate Factory agent — docked panel or floating widget (recipe) |
@buildpad/ui-comments | Comments for any record — threads with replies at any depth, formatting, emoji, reactions (recipe) |
UI layers
The UI packages stack by altitude — each tier builds on the one below. The same grouping organizes the Storybook landing page:
| Tier | Packages | Role |
|---|---|---|
| Field Interfaces | ui-interfaces | Schema-mapped primitives — one component per field type |
| Renderers | ui-form (VForm), ui-table (VTable) | Turn a collection schema into a form or table |
| Composition | ui-collections | CollectionForm + CollectionList — data fetching + renderers into CRUD |
| App Modules | ui-files, ui-forms, ui-users, ui-workflows, ui-cron, ui-chat, ui-comments | Full, recipe-backed features (file manager; visual form builder; users/roles/policies admin; workflow admin; cron jobs admin; AI chat; comments) |
Note the distinction inside the form family: VForm (ui-form) renders a form
from a schema, while the Form Builder (ui-forms) is an authoring module that
designs reusable form definitions and renders them at runtime with DynamicForm.
Dependency Flow
types (base)
├─ utils (mapper + validation)
├─ services (CRUD + DaaS)
└─ hooks (auth + relations)
↓ (all feed into)
ui-interfaces (40+ components)
↓
ui-form (VForm) ui-table (VTable)
└──────┬──────────┘
↓
ui-collections (CollectionForm, CollectionList)
├─ ui-files (FileManager — files module)
├─ ui-forms (FormBuilder + DynamicForm — form builder module)
└─ ui-users (Users/Roles/Policies admin — users module)
ui-table (VTable) + hooks
└─ ui-workflows (Workflow definitions, assignments, instances — workflows module)
ui-table (VTable) + ui-interfaces (InputCode) + hooks
└─ ui-cron (Cron jobs list, job editor, run history — cron jobs module)Relational interfaces and the relational UI context
The relational interfaces (ListO2M, ListM2M, ListM2A and its
JunctionItemForm) open dialogs that need components from the tiers above
them — CollectionForm, CollectionList and VForm. They do not import them
(that was an import cycle: ui-form → ui-interfaces → ui-collections → ui-form).
They read them from the relational UI context in @buildpad/services
(@buildpad/services/relational-ui-context):
| Who | Supplies |
|---|---|
CollectionForm | CollectionForm, CollectionList (lazy), FormRenderer: VForm — for every field it renders |
VForm | FormRenderer: VForm |
CollectionsRelationalProvider (ui-collections) | All three, loaded on demand — wrap a page that renders <ListO2M>/<ListM2M>/<ListM2A> or a plain <VForm> with relational fields on its own. The scaffolded authenticated and /content layouts already do. Its built-ins only fill slots no provider above chose |
RelationalUIProvider (services) | Your own components (nested providers merge) |
A component’s components prop | Overrides for that one field |
Without a provider, a relational interface shows an alert and hides the create,
select and edit actions that need the missing component. pnpm graph:check
keeps the package graph free of cycles.
Consumer Layer
Projects consume Buildpad components via the CLI (Copy & Own model) or through AI agents via MCP. Components are copied as source code with imports transformed to local paths.
Testing Layer
Playwright E2E tests use a two-tier strategy:
- Storybook tests — Isolated component tests with mocked data (no auth required)
- DaaS E2E tests — Full integration tests against real DaaS backend with authentication