docs(studio): clarify plugin-based architecture - designers are external

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/557f4f83-2ecc-44a8-bf93-d1539ae005e8

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Claude

apps/studio/ROADMAP.md

@@ -6,6 +6,24 @@
 
 ---
 
+## 🏗️ Architectural Principle
+
+**Studio is a plugin platform, not a monolithic IDE.**
+
+- **This project:** Core infrastructure (plugin system, kernel, navigation, testing, routing)
+- **Designer plugins:** Developed in separate repositories as independent Studio plugins
+- **Plugin examples:** Object Designer, View Designer, Flow Designer, etc. are external plugins
+
+This approach ensures:
+- **Modularity:** Each designer is independently developed, tested, and versioned
+- **Maintainability:** Core framework stays lean and focused
+- **Extensibility:** Community can build custom designers without forking Studio
+- **Scalability:** Designers can be loaded on-demand, reducing bundle size
+
+**Reference Implementation:** See `packages/plugins/plugin-*` for plugin development patterns.
+
+---
+
 ## 📊 Current State (v4.0.4)
 
 ### What's Working
@@ -39,82 +57,103 @@
 
 ## 🗺️ Roadmap (2026 Q2-Q4)
 
-### Phase 1: Foundation & Core UX (Q2 2026) — 6 weeks
+### Phase 1: Plugin Infrastructure (Q2 2026) — 6 weeks
 
-**Goal:** Fix critical technical debt and establish solid foundations for future development.
+**Goal:** Build robust plugin infrastructure to support external designer plugins.
 
 | # | Task | Priority | Effort |
 |---|------|----------|--------|
 | 1.1 | **Add URL Router** | 🔴 P0 | 1 week |
-| | Integrate TanStack Router. Map views to URL paths: `/:package/objects/:name`, `/:package/metadata/:type/:name`. Enable browser back/forward. | | |
+| | Integrate TanStack Router. Map views to URL paths: `/:package/objects/:name`, `/:package/metadata/:type/:name`. Enable browser back/forward. Plugin-contributed routes. | | |
 | 1.2 | **Component Testing Setup** | 🔴 P0 | 1 week |
-| | Setup React Testing Library. Write tests for `ObjectDataTable`, `ObjectDataForm`, `AppSidebar`. Target: 30% coverage. | | |
-| 1.3 | **Plugin Sidebar Groups** | 🟡 P1 | 3 days |
-| | Replace hardcoded `PROTOCOL_GROUPS` with plugin-contributed `useSidebarGroups()`. | | |
-| 1.4 | **Data Refresh Fix** | 🟡 P1 | 2 days |
+| | Setup React Testing Library. Write tests for `ObjectDataTable`, `ObjectDataForm`, `AppSidebar`, Plugin system. Target: 30% coverage. | | |
+| 1.3 | **Plugin Sidebar Groups** | 🔴 P0 | 3 days |
+| | Replace hardcoded `PROTOCOL_GROUPS` with plugin-contributed `useSidebarGroups()`. Enable plugins to register sidebar items. | | |
+| 1.4 | **Plugin Hot Reload** | 🟡 P1 | 3 days |
+| | Support plugin hot reload during development. Enable/disable plugins without page refresh. | | |
+| 1.5 | **Data Refresh Fix** | 🟡 P1 | 2 days |
 | | Replace `setTimeout` hack with proper state invalidation / React Query refetch. | | |
-| 1.5 | **Code Cleanup** | 🟢 P2 | 2 days |
+| 1.6 | **Code Cleanup** | 🟢 P2 | 2 days |
 | | Remove stale `types.ts`, empty `app/dashboard/` directory. | | |
-| 1.6 | **Object Field Editor (Basic)** | 🔴 P0 | 2 weeks |
-| | Inline field editing with type picker. Add/remove fields. Basic validation. No drag-drop yet. | | |
+| 1.7 | **Plugin API Documentation** | 🟡 P1 | 3 days |
+| | Document StudioPlugin API, metadataViewers registration, hooks, and best practices. Create plugin starter template. | | |
+
+**Deliverable:** Production-ready plugin infrastructure for external designers.
 
-**Deliverable:** Stable, testable, deep-linkable foundation + basic object editing.
+**Note:** Designer implementations (Object Designer, View Designer, etc.) will be developed as separate plugins in external repositories.
 
 ---
 
-### Phase 2: AI-Enhanced Metadata Editing (Q3 2026) — 8 weeks
+### Phase 2: AI Integration & Developer Tools (Q3 2026) — 6 weeks
 
-**Goal:** Make metadata editing intuitive with AI assistance.
+**Goal:** AI-enhanced developer experience for metadata editing.
 
 | # | Task | Priority | Effort |
 |---|------|----------|--------|
 | 2.1 | **AI Copilot Enhancement** | 🔴 P0 | 2 weeks |
-| | Context-aware AI assistance. Generate fields from natural language. Explain field types. Suggest validations. | | |
-| 2.2 | **Object Designer — Enhanced** | 🔴 P0 | 2 weeks |
-| | Drag-and-drop field reordering. Type-aware property panels. Field grouping. Relationship visualization (basic). | | |
-| 2.3 | **View Designer (Grid Only)** | 🔴 P0 | 2 weeks |
-| | Visual column configurator. Drag-and-drop column reorder. Filter & sort presets. Live preview. | | |
-| 2.4 | **Form Designer (Basic)** | 🟡 P1 | 2 weeks |
-| | Section/column layout editor. Field placement. Widget selection. Preview mode. | | |
+| | Context-aware AI assistance. Plugin-aware code generation. Metadata explanation. Smart suggestions. Integration with designer plugins via API. | | |
+| 2.2 | **Command Palette (Ctrl+K)** | 🔴 P0 | 1 week |
+| | Global command search. Quick navigation. Plugin-contributed commands. AI-powered command suggestions. | | |
+| 2.3 | **Monaco Editor Integration** | 🔴 P0 | 2 weeks |
+| | Raw YAML/JSON/TypeScript editing. Schema-aware autocomplete. Inline Zod validation. Toggle between visual/code modes. Plugin-contributed language support. | | |
+| 2.4 | **Plugin Marketplace UI (Basic)** | 🟡 P1 | 1 week |
+| | Browse available designer plugins. Install/uninstall UI. Plugin metadata display. Version management. | | |
 
-**Deliverable:** AI-assisted object & view design. Better editing UX than JSON.
+**Deliverable:** AI-powered IDE with plugin extensibility.
+
+**Note:** Actual designers (Object Designer, View Designer, Form Designer) are external plugins.
 
 ---
 
-### Phase 3: Developer Productivity (Q4 2026) — 6 weeks
+### Phase 3: Advanced IDE Features (Q4 2026) — 4 weeks
 
-**Goal:** Tools that make developers more productive.
+**Goal:** Professional IDE capabilities.
 
 | # | Task | Priority | Effort |
 |---|------|----------|--------|
-| 3.1 | **Command Palette (Ctrl+K)** | 🔴 P0 | 1 week |
-| | Global command search. Quick navigation. Plugin-contributed commands. | | |
-| 3.2 | **Monaco Editor Integration** | 🔴 P0 | 2 weeks |
-| | Raw YAML/JSON/TypeScript editing. Schema-aware autocomplete. Inline Zod validation. Toggle between visual/code. | | |
-| 3.3 | **Multi-Tab Interface** | 🟡 P1 | 1 week |
-| | Open multiple metadata items. Tab management (close/drag). Unsaved indicators. | | |
-| 3.4 | **Flow Designer (Basic)** | 🟡 P1 | 2 weeks |
-| | Canvas-based node graph (ReactFlow). 5 core node types (start, CRUD, condition, HTTP, end). Basic execution trace. | | |
+| 3.1 | **Multi-Tab Interface** | 🔴 P0 | 1 week |
+| | Open multiple metadata items. Tab management (close/drag/split). Unsaved indicators. Plugin tabs support. | | |
+| 3.2 | **Plugin DevTools** | 🔴 P0 | 1 week |
+| | Plugin inspector. Performance profiling. Error logging. Hot reload status. Debug panel. | | |
+| 3.3 | **Version Control Integration** | 🟡 P1 | 1 week |
+| | Git diff viewer for metadata changes. Commit from Studio. Basic conflict resolution. | | |
+| 3.4 | **Plugin Starter Kit** | 🟡 P1 | 1 week |
+| | CLI scaffolding tool for creating new Studio plugins. Templates for common designer patterns (field editor, canvas, form builder). | | |
+
+**Deliverable:** Complete plugin development environment.
 
-**Deliverable:** Professional IDE experience. Code + visual editing. Basic automation design.
+**Note:** External repositories can now build full-featured designers (Object Designer, Flow Designer, etc.) using the plugin infrastructure.
 
 ---
 
 ## 📅 Simplified Timeline
 
 ```
-2026 Q2  ── Phase 1: Foundation & Core UX        [6 weeks]
+2026 Q2  ── Phase 1: Plugin Infrastructure       [6 weeks]
             ├─ URL Router + Testing
-            └─ Basic Object Field Editor
+            ├─ Plugin Sidebar Groups
+            ├─ Plugin Hot Reload
+            └─ Plugin API Docs
 
-2026 Q3  ── Phase 2: AI-Enhanced Metadata        [8 weeks]
+2026 Q3  ── Phase 2: AI Integration & Tools      [6 weeks]
             ├─ AI Copilot Enhancement
-            ├─ Object Designer (Enhanced)
-            └─ View + Form Designers (Basic)
-
-2026 Q4  ── Phase 3: Developer Productivity      [6 weeks]
-            ├─ Command Palette + Monaco Editor
-            └─ Multi-Tab + Flow Designer (Basic)
+            ├─ Command Palette (Ctrl+K)
+            ├─ Monaco Editor Integration
+            └─ Plugin Marketplace UI
+
+2026 Q4  ── Phase 3: Advanced IDE Features       [4 weeks]
+            ├─ Multi-Tab Interface
+            ├─ Plugin DevTools
+            ├─ Version Control Integration
+            └─ Plugin Starter Kit
+
+External ── Designer Plugins (Separate Repos)
+            ├─ Object Designer Plugin
+            ├─ View Designer Plugin
+            ├─ Form Designer Plugin
+            ├─ Flow Designer Plugin
+            ├─ Dashboard Designer Plugin
+            └─ Community Plugins...
 ```
 
 ---
@@ -170,22 +209,51 @@ export const myPlugin: StudioPlugin = {
 |--------|------------------|---------|---------|---------|
 | Component test coverage | 0% | 30% | 50% | 60% |
 | Deep-linkable views | ❌ | ✅ | ✅ | ✅ |
-| Metadata types with specialized UI | 1 (Object) | 2 (Object + View) | 4 (+ Form + Dashboard) | 6 (+ Flow + Agent) |
-| AI assistance quality (1-5) | 2 (basic chat) | 3 (context-aware) | 4 (generates valid code) | 4+ (multi-step tasks) |
-| Time to edit an object | 5 min (JSON) | 2 min (basic UI) | 1 min (enhanced UI) | 30 sec (AI-assisted) |
+| Plugin API stability (1-5) | 3 (evolving) | 4 (stable) | 5 (production) | 5 (documented) |
+| External plugins supported | 0 | 2-3 | 5-8 | 10+ |
+| AI assistance quality (1-5) | 2 (basic chat) | 3 (context-aware) | 4 (plugin-aware) | 4+ (code generation) |
+| Plugin development time | N/A | 2 weeks | 1 week | 3 days |
 | Developer satisfaction (1-5) | 3 | 3.5 | 4 | 4.5 |
 
 ---
 
-## 🚫 What We're NOT Building (Yet)
+## 🚫 What We're NOT Building in Core Studio
+
+**Core Studio = Plugin Infrastructure Only**
+
+The following are **external plugin responsibilities**, not core framework features:
 
-To stay focused, we're explicitly deferring these items:
+- ❌ Object Designer UI (external plugin)
+- ❌ View Designer UI (external plugin)
+- ❌ Form Designer UI (external plugin)
+- ❌ Flow Designer UI (external plugin)
+- ❌ Dashboard Designer UI (external plugin)
+- ❌ Agent Designer UI (external plugin)
+- ❌ Security/permission UI (external plugin)
+- ❌ Full Airtable Interface parity (external plugins)
+- ❌ Advanced automation designers (external plugins)
+- ❌ Enterprise-specific UI (external plugins)
 
-- ❌ Full Airtable Interface parity (too ambitious)
-- ❌ Complete security/permission UI (low priority)
+**Also Deferred:**
 - ❌ Mobile/responsive mode (desktop-first)
-- ❌ Real-time collaborative editing (complex)
-- ❌ External plugin marketplace (premature)
-- ❌ Advanced automation (approval processes, state machines, ETL)
-- ❌ Complete AI agent designer (service-ai is still MVP)
-- ❌ Enterprise features (audit, compliance, multi-tenant UI)
+- ❌ Real-time collaborative editing (complex, future)
+- ❌ Public plugin marketplace (Phase 3+)
+
+---
+
+## 📦 Example Designer Plugins (External Repos)
+
+These are reference implementations to demonstrate plugin capabilities:
+
+1. **@objectstack/studio-object-designer** — Visual object & field editor
+2. **@objectstack/studio-view-designer** — Grid/Kanban/Calendar view configurator
+3. **@objectstack/studio-flow-designer** — Automation flow canvas
+4. **@objectstack/studio-dashboard-designer** — Dashboard layout editor
+
+Each plugin is independently:
+- Versioned
+- Tested
+- Documented
+- Distributed via npm
+
+Community can build custom designers following these patterns.