App Hierarchy App → View → Panel → Collection → Thing
The App hierarchy parallels the Site hierarchy:
Site (Public) App (Authenticated) Site App Page View Section Panel Collection Collection Thing Thing
interface App { $type : AppType // 'Admin', 'CRM', 'VibeCode', etc. $id : string // 'https://acme.com/app' name : string shell : Shell // Sidebar + Header + Main views : View [] // Available routes auth : AuthConfig theme : Theme } interface View { $type : ViewType // 'DashboardView', 'ListView', etc. path : string // '/contacts', '/deals/:id' title : string layout : ViewLayout // 'single' | 'column' | 'canvas' | 'vibe' panels : Panel [] } interface Panel { $type : PanelType // 'ListPanel', 'DetailPanel', etc. position : Position // 'main' | 'sidebar' | 'detail' | 'top' | 'bottom' collection ?: Collection content ?: Content } ┌─────────────────────────────────┐ │ main │ └─────────────────────────────────┘ ┌───────────────┬─────────────────┐ 2-column │ sidebar │ main │ └───────────────┴─────────────────┘ ┌─────────┬───────────┬──────────┐ 3-column │ sidebar │ main │ detail │ └─────────┴───────────┴──────────┘ (Can be 2, 3, or N columns as needed)
┌─────────────────────────────────┐ │ top │ ├─────────┬───────────────────────┤ │ sidebar │ main │ ├─────────┴───────────────────────┤ │ bottom │ └─────────────────────────────────┘ ┌─────────┬───────────┬──────────┐ │ chat │ preview │ code │ └─────────┴───────────┴──────────┘ Panel Purpose NavPanelNavigation tree TabsPanelTab navigation BreadcrumbPanelLocation context SidebarPanelCollapsible sidebar
Panel Purpose ListPanelCollection as list TablePanelCollection as table/datagrid CardsPanelCollection as cards KanbanPanelCollection as kanban board CalendarPanelCollection as calendar TimelinePanelCollection as timeline GalleryPanelCollection as image gallery TreePanelCollection as tree/hierarchy
Panel Purpose DetailPanelSingle Thing view FormPanelEdit Thing PreviewPanelLive preview PropertiesPanelEdit properties InspectorPanelObject inspector
Panel Purpose ChatPanelAI conversation CodePanelSource editor (Monaco) EditorPanelRich text (WYSIWYG) FilterPanelSearch & filter controls QueryPanelQuery builder JSONPanelJSON editor MarkdownPanelMarkdown editor
Panel Purpose MetricsPanelKPI display ChartPanelCharts/graphs StatsPanelStatistics WorkflowPanelWorkflow diagram StateMachinePanelState machine view GanttPanelGantt chart GraphPanelNode/edge graph DiagramPanelGeneric diagram
Panel Purpose ArenaPanelBlind A/B comparison (LLM Arena style) DiffPanelSide-by-side diff view ComparePanelFeature/attribute comparison LeaderboardPanelRanked list with scores
Panel Purpose ReviewPanelApprove/reject workflow ReviewThreadLine-by-line comments ChecksPanelValidation/CI status ApprovalPanelMulti-reviewer approval DeliverablePanelDeliverable review view
Panel Purpose BrowserPanelEmbedded browser/iframe TerminalPanelTerminal emulator ComputerPanelComputer use (AI) ConsolePanelConsole output REPLPanelInteractive REPL SandboxPanelCode sandbox
Panel Purpose ContentPanelStatic content/docs ActivityPanelEvent timeline FeedPanelActivity feed LogPanelLog viewer DocumentPanelDocument viewer SignaturePanelE-signature flow
Panel Purpose ThreadPanelConversation thread CommentsPanelComments list NotificationsPanelNotifications
Panel Purpose ToolbarPanelActions bar ActionsPanelQuick actions PalettePanelItem/command picker CommandPanelCommand palette
Panel Purpose CanvasPanelDrag-drop workspace WhiteboardPanelFreeform drawing MapPanelGeographic map FloorplanPanelSpatial layouts
Collections are the data backbone of Apps. Inspired by ReactAdmin's resource model .
interface Collection { $type : string // 'posts', 'users', 'orders' $id : string // Collection identifier // CRUD Views list : ListView // Browse records show : ShowView // View single record edit : EditView // Edit single record create : CreateView // Create new record // Relationships relationships : Relationship [] } Each Collection can have up to 4 standard views:
View Purpose Data Operation ListViewBrowse/filter records getList()ShowViewRead-only record detail getOne()EditViewEdit existing record getOne(), update()CreateViewCreate new record create()
Fields render record properties in read-only views (List, Show):
Field Purpose TextFieldString display NumberFieldNumeric display DateFieldDate/time display BooleanFieldTrue/false display ImageFieldImage preview FileFieldFile download link ChipFieldTag/badge display RichTextFieldHTML content ArrayFieldList of values ReferenceFieldLink to related record ReferenceManyFieldList of related records
Inputs handle record editing in forms (Edit, Create):
Input Purpose TextInputString editing NumberInputNumeric editing DateInputDate picker BooleanInputCheckbox/toggle SelectInputDropdown selection AutocompleteInputSearchable dropdown RadioGroupInputRadio button group CheckboxGroupInputMulti-select checkboxes RichTextInputWYSIWYG editor FileInputFile upload ArrayInputEditable list ReferenceInputRelated record picker ReferenceArrayInputMulti-select related records
Collections relate to each other through references:
┌─────────────┐ ┌─────────────┐ │ Author │────────<│ Book │ │ │ 1 n │ author_id │ └─────────────┘ └─────────────┘ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ User │>───────<│ UserRole │>───────<│ Role │ │ │ n n │ user_id │ n n │ │ │ │ │ role_id │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ Relationship Description Component One-to-One Author → Profile ReferenceOneFieldMany-to-One Book → Author ReferenceFieldOne-to-Many Author → Books ReferenceManyFieldMany-to-Many Users ↔ Roles ReferenceManyToManyField
Display (Fields):
// Show author name for a book < ReferenceField source = "author_id" reference = "authors" > < TextField source = "name" /> </ ReferenceField > // Show all books by an author < ReferenceManyField reference = "books" target = "author_id" > < DataTable > < TextField source = "title" /> </ DataTable > </ ReferenceManyField > Edit (Inputs):
// Select author for a book < ReferenceInput source = "author_id" reference = "authors" > < AutocompleteInput optionText = "name" /> </ ReferenceInput > // Select multiple tags < ReferenceArrayInput source = "tag_ids" reference = "tags" > < CheckboxGroupInput optionText = "name" /> </ ReferenceArrayInput > Collections provide context to descendant components:
CollectionContext ├── RecordContext // Current record data ├── ListContext // List state (pagination, filters, selection) ├── FormContext // Form state (values, validation, dirty) └── ResourceContext // Resource metadata Components access context via hooks:
useRecordContext() - Get current recorduseListContext() - Get list stateuseFormContext() - Get form state
Collections don't fetch data directly. A DataProvider adapts to any API:
interface DataProvider { getList ( resource , params ) : Promise <{ data , total }> getOne ( resource , params ) : Promise <{ data }> getMany ( resource , params ) : Promise <{ data }> getManyReference ( resource , params ) : Promise <{ data , total }> create ( resource , params ) : Promise <{ data }> update ( resource , params ) : Promise <{ data }> updateMany ( resource , params ) : Promise <{ data }> delete ( resource , params ) : Promise <{ data }> deleteMany ( resource , params ) : Promise <{ data }> } This enables:
Backend agnostic - REST, GraphQL, Payload, Supabase, etc.Optimistic updates - UI updates before server confirmsCaching - Automatic query deduplicationOffline support - Local-first with sync
DashboardApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── AnalyticsView (single) │ ├── FilterPanel │ ├── ChartPanel │ └── TablePanel ├── ReportsView (column) │ ├── ListPanel │ └── DetailPanel └── SettingsView DeveloperApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── KeysView (column) │ ├── TablePanel │ └── DetailPanel ├── WebhooksView (column) │ ├── TablePanel │ └── DetailPanel ├── UsageView (single) │ ├── FilterPanel │ ├── ChartPanel │ └── TablePanel ├── LogsView (column) │ ├── TablePanel │ └── DetailPanel ├── DocsView (single) │ └── ContentPanel └── SettingsView AdminApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ActivityPanel │ └── StatsPanel ├── CollectionView (column) [per collection] │ ├── ToolbarPanel │ ├── TablePanel │ └── DetailPanel ├── RecordView (single) │ └── FormPanel ├── CreateView (single) │ └── FormPanel ├── UsersView (column) │ ├── TablePanel │ └── DetailPanel ├── RolesView (column) │ ├── ListPanel │ └── FormPanel └── SettingsView SaaSApp ├── DashboardView (single) │ └── [Product-specific panels] ├── [ProductViews] (varies) ├── TeamView (column) │ ├── TablePanel │ └── DetailPanel ├── InvitesView (single) │ └── TablePanel ├── BillingView (single) │ ├── MetricsPanel │ ├── DetailPanel │ └── TablePanel ├── PlansView (single) │ └── CardsPanel └── SettingsView DataApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── DatasetsView (column) │ ├── CardsPanel │ └── DetailPanel ├── DatasetView (single) │ ├── DetailPanel │ ├── TablePanel (schema) │ ├── TablePanel (preview) │ └── ChartPanel ├── SourcesView (column) │ ├── ListPanel │ └── DetailPanel ├── AccessView (column) │ ├── TablePanel │ └── DetailPanel ├── UsageView (single) │ ├── ChartPanel │ └── TablePanel └── SettingsView HeadlessApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── MCPView (column) │ ├── TabsPanel │ ├── ListPanel │ └── DetailPanel ├── AgentsView (column) │ ├── TablePanel │ └── DetailPanel ├── UsageView (single) │ ├── ChartPanel │ └── TablePanel ├── LogsView (column) │ ├── TablePanel │ └── DetailPanel └── SettingsView CRMApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── ContactsView (column) │ ├── ToolbarPanel │ ├── TablePanel │ └── DetailPanel ├── ContactView (single) │ ├── DetailPanel │ ├── TimelinePanel │ └── ListPanel ├── DealsView (column) │ ├── FilterPanel │ ├── KanbanPanel │ └── DetailPanel ├── DealView (single) │ ├── DetailPanel │ ├── TimelinePanel │ └── ListPanel ├── ActivitiesView (single) │ └── TimelinePanel ├── TasksView (column) │ ├── ListPanel │ └── DetailPanel └── SettingsView BookingApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── CalendarPanel │ └── ListPanel ├── CalendarView (single) │ ├── ToolbarPanel │ └── CalendarPanel ├── BookingsView (column) │ ├── TablePanel │ └── DetailPanel ├── BookingView (single) │ ├── DetailPanel │ ├── DetailPanel (customer) │ └── ActionsPanel ├── AvailabilityView (single) │ ├── CalendarPanel │ └── FormPanel ├── ServicesView (column) │ ├── ListPanel │ └── FormPanel ├── CustomersView (column) │ ├── TablePanel │ └── DetailPanel └── SettingsView SupportApp ├── InboxView (column) │ ├── ToolbarPanel │ ├── ListPanel │ └── DetailPanel ├── TicketView (column) │ ├── ListPanel │ ├── ChatPanel │ └── DetailPanel ├── CustomersView (column) │ ├── TablePanel │ └── DetailPanel ├── KnowledgeBaseView (column) │ ├── NavPanel │ ├── ListPanel │ └── DetailPanel ├── ArticleView (single) │ └── EditorPanel ├── ReportsView (single) │ ├── MetricsPanel │ └── ChartPanel ├── MacrosView (column) │ ├── ListPanel │ └── FormPanel └── SettingsView AgencyApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── KanbanPanel │ └── ActivityPanel ├── ClientsView (column) │ ├── CardsPanel │ └── DetailPanel ├── ClientView (single) │ ├── DetailPanel │ ├── ListPanel (projects) │ └── ListPanel (invoices) ├── ProjectsView (column) │ ├── FilterPanel │ ├── KanbanPanel │ └── DetailPanel ├── ProjectView (single) │ ├── DetailPanel │ ├── TimelinePanel │ ├── ListPanel (tasks) │ └── ListPanel (deliverables) ├── TasksView (column) │ ├── TablePanel │ └── DetailPanel ├── DeliverablesView (column) │ ├── ListPanel │ └── DetailPanel ├── BillingView (single) │ ├── MetricsPanel │ └── TablePanel └── SettingsView OpsApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── StatsPanel │ └── ActivityPanel ├── ClientsView (column) │ ├── TablePanel │ └── DetailPanel ├── ClientView (single) │ ├── DetailPanel │ ├── MetricsPanel │ └── TimelinePanel ├── TasksView (column) │ ├── ToolbarPanel │ ├── TablePanel │ └── DetailPanel ├── IncidentsView (column) │ ├── TablePanel │ └── DetailPanel ├── IncidentView (single) │ ├── DetailPanel │ ├── TimelinePanel │ └── FormPanel ├── RunbooksView (column) │ ├── NavPanel │ ├── ListPanel │ └── ContentPanel ├── SLAsView (column) │ ├── TablePanel │ └── DetailPanel ├── OnCallView (single) │ ├── CalendarPanel │ └── ListPanel ├── ReportsView (single) │ ├── ChartPanel │ └── TablePanel └── SettingsView AgentApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── AgentsView (column) │ ├── CardsPanel │ └── DetailPanel ├── AgentView (single) │ ├── DetailPanel │ ├── ListPanel │ ├── TimelinePanel │ └── MetricsPanel ├── TasksView (column) │ ├── TabsPanel │ ├── ListPanel │ └── DetailPanel ├── TaskView (single) │ ├── DetailPanel │ ├── ChatPanel │ └── DetailPanel (result) ├── ToolsView (column) │ ├── ListPanel │ └── DetailPanel ├── ModelsView (column) │ ├── ListPanel │ └── FormPanel ├── CostsView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── TablePanel ├── LogsView (column) │ ├── TablePanel │ └── DetailPanel └── SettingsView WorkflowApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── WorkflowsView (column) │ ├── CardsPanel │ └── DetailPanel ├── WorkflowView (canvas) │ ├── ToolbarPanel │ ├── PalettePanel │ ├── CanvasPanel │ └── PropertiesPanel ├── RunsView (column) │ ├── TablePanel │ └── DetailPanel ├── RunView (single) │ ├── CanvasPanel │ ├── TimelinePanel │ └── DetailPanel ├── TriggersView (column) │ ├── ListPanel │ └── FormPanel ├── TemplatesView (column) │ ├── CardsPanel │ └── DetailPanel └── SettingsView InfraApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── StatsPanel │ └── ActivityPanel ├── ComputeView (column) │ ├── TablePanel │ └── DetailPanel ├── ServerView (single) │ ├── DetailPanel │ ├── MetricsPanel │ ├── ChartPanel │ └── ActionsPanel ├── StorageView (column) │ ├── TablePanel │ └── DetailPanel ├── NetworkView (column) │ ├── ListPanel │ └── DetailPanel ├── DatabasesView (column) │ ├── TablePanel │ └── DetailPanel ├── SecurityView (column) │ ├── TabsPanel │ ├── ListPanel │ └── DetailPanel ├── MonitoringView (single) │ ├── ChartPanel │ └── TablePanel ├── BillingView (single) │ ├── MetricsPanel │ └── TablePanel └── SettingsView PlatformApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ChartPanel │ └── ActivityPanel ├── AppsView (column) │ ├── CardsPanel │ └── DetailPanel ├── AppView (single) │ ├── DetailPanel │ ├── MetricsPanel │ └── ListPanel ├── DeploysView (column) │ ├── TablePanel │ └── DetailPanel ├── DeployView (single) │ ├── DetailPanel │ ├── TimelinePanel │ └── ContentPanel ├── EnvsView (column) │ ├── ListPanel │ └── FormPanel ├── DomainsView (column) │ ├── TablePanel │ └── FormPanel ├── BuildsView (column) │ ├── TablePanel │ └── DetailPanel ├── LogsView (single) │ ├── FilterPanel │ └── ContentPanel └── SettingsView ClientPortalApp ├── DashboardView (single) │ ├── MetricsPanel │ ├── ActivityPanel │ └── ActionsPanel ├── ProjectsView (column) │ ├── CardsPanel │ └── DetailPanel ├── ProjectView (single) │ ├── DetailPanel │ ├── TimelinePanel │ └── ListPanel ├── InvoicesView (column) │ ├── TablePanel │ └── DetailPanel ├── SupportView (column) │ ├── ListPanel │ └── DetailPanel ├── TicketView (single) │ ├── ChatPanel │ └── DetailPanel ├── DocumentsView (column) │ ├── NavPanel │ ├── ListPanel │ └── DetailPanel └── SettingsView VibeCodeApp ├── EditorView (vibe) │ ├── ChatPanel │ ├── PreviewPanel │ └── CodePanel ├── PagesView (column) │ ├── ListPanel │ └── PreviewPanel ├── ComponentsView (column) │ ├── CardsPanel │ └── DetailPanel ├── AssetsView (single) │ └── CardsPanel ├── ThemeView (single) │ ├── FormPanel │ └── PreviewPanel ├── HistoryView (column) │ ├── TimelinePanel │ └── DetailPanel ├── DeployView (single) │ ├── DetailPanel │ └── ActionsPanel └── SettingsView Every App includes:
View Path Layout DashboardView/single SettingsView/settingssingle ProfileView/profilesingle NotificationsView/notificationscolumn SearchView/searchsingle
Every App has a Shell with:
Shell ├── Sidebar │ ├── Logo │ ├── NavItems (views) │ ├── Collapse toggle │ └── UserMenu ├── Header │ ├── Breadcrumb │ ├── SearchBox │ ├── Notifications │ └── UserAvatar └── Main └── [Current View] Dashboards are composed of widgets - small, focused components that display data.
Widget Purpose KPICardSingle key metric SparklineCardMetric with trend CompareCardMetric vs previous period GoalCardProgress toward goal CountdownCardTime remaining
Widget Purpose LineChartTrend over time BarChartComparisons PieChartDistribution AreaChartVolume over time FunnelChartConversion funnel GaugeChartCurrent vs max HeatmapChartDensity/activity
Widget Purpose DataTablePaginated data LeaderboardTableRanked list ComparisonTableSide-by-side ChangelogTableRecent changes
Widget Purpose StatusCardSystem health UptimeCardService uptime HealthGridMulti-service status IncidentCardActive incidents
Widget Purpose ActivityFeedRecent events NotificationsListUser notifications TaskListPending tasks EventCalendarUpcoming events
Widget Purpose QuickActionsCommon actions ShortcutsNavigation links RecentItemsRecently accessed FavoritesStarred items
Abstract widget categories for common embedded functionality:
Widget Purpose PaymentFormCheckout/payment collection ExpressCheckoutWallet payments (Apple Pay, Google Pay) AddressFormAddress collection PricingTablePlan/pricing display
Widget Purpose UsersManagerTeam member management SecuritySettingsUser security controls OrgSwitcherOrganization/workspace switching LoginButtonSSO/authentication trigger
Widget Purpose IntegrationTemplatesPre-built workflow templates IntegrationDirectoryAvailable integrations browser ConnectorSetupIntegration configuration
Widget Purpose LiveChatReal-time chat support MessengerAsync messaging VideoEmbedVideo player/recorder
Widget Purpose CalendarPickerDate/time selection BookingWidgetAppointment scheduling AvailabilityGridAvailable slots display
Widget Purpose FormEmbedForms/surveys DocumentEmbedDocument viewer DesignEmbedDesign preview
Widget Purpose SignatureCaptureSignature drawing pad DocumentSignerFull e-sign flow SignatureFieldInline signature input SigningStatusSignature request status
Core interactive widgets we provide:
AI-powered chat widget with email capture, typing indicators, and message history.
import { ChatBox, ChatProvider, ChatTrigger } from '@mdxui/widgets' < ChatProvider config = {{ endpoint : '/api/chat' }} > < ChatTrigger /> < ChatBox position = "bottom-right" /> </ ChatProvider > Command palette-style search with keyboard navigation.
import { SearchProvider, SearchTrigger, SearchPalette } from '@mdxui/widgets' < SearchProvider onSearch = {handleSearch} > < SearchTrigger /> { /* ⌘K trigger */ } < SearchPalette /> </ SearchProvider > Monaco-based code editor with preview pane.
import { EditorPanel, EditorProvider } from '@mdxui/widgets' < EditorProvider value = {code} onChange = {setCode} > < EditorPanel mode = "split" /> </ EditorProvider > Multi-step wizard with field components and animations.
import { OnboardingProvider, OnboardingStep } from '@mdxui/widgets' < OnboardingProvider steps = {steps} > < OnboardingStep name = "welcome" /> < OnboardingStep name = "profile" /> < OnboardingStep name = "preferences" /> </ OnboardingProvider > Key patterns that inform our component architecture:
Each entity type has standard CRUD views (List, Show, Edit, Create)
Views compose Panels for layout flexibility
Fields display data, Inputs edit data
DataProvider - Abstracts data fetching (REST, GraphQL, etc.)AuthProvider - Handles authentication/authorizationContext - State flows down, hooks pull up
Components accept children, not giant prop objects
Smart components handle data + rendering
Headless variants expose only logic (hooks)
Collections relate via foreign keys
Reference components auto-fetch related data
Prevents N+1 query problems via aggregation