metabuilder/STRATEGIC_POLISH_GUIDE.md

MetaBuilder Strategic Polish Guide

How to Make the New System Delight Users Like the Old One

Status: Phase 2 (TypeScript DBAL) - 90% Complete Last Updated: 2026-01-21 Focus: Visual delight + Admin tools + Security hardening

---

EXECUTIVE SUMMARY

The new MetaBuilder system has superior architecture to the old one:

• ✅ Better component system (151+ fakemui vs 46 shadcn)
• ✅ Better styling (OKLCH modern colors vs traditional hex)
• ✅ Better database layer (DBAL abstraction vs direct indexedDB)
• ✅ Better testing (326 tests vs minimal in old)
• ✅ Better data-driven approach (100% JSON-based UI)

Problem: The old implementation's admin tooling and UX polish got left behind.

Solution: Complete these 5 phases to recapture that magic.

---

PHASE 1: VERIFY VISUAL DELIGHT ✅ (Status: DONE)

Current Status

• ✅ SCSS styling IS active and compiled
• ✅ Material Design tokens (OKLCH colors) present
• ✅ Dark mode support built-in
• ✅ Responsive design ready
• ✅ Typography system (3 font families) active

What Users Will See

When they load http://localhost:3000:

1. Beautiful Material Design colors (purple primary, warm secondary)
2. Professional typography (Space Grotesk headings, IBM Plex Sans body)
3. Proper spacing and visual hierarchy
4. Dark mode that actually works (if they prefer)
5. Responsive design on mobile/tablet

What's Different from Old

Old System	New System
Radix Colors (32 palettes)	OKLCH colors (modern, perceptual)
Static light/dark mode	CSS custom properties + theme detection
Limited dark mode	Full dark mode with LAB color support
Tailwind breakpoints	Comprehensive breakpoint system
No accessibility shortcuts	prefers-reduced-motion, high-contrast support

Next: PHASE 2 - Security Hardening

---

PHASE 2: SECURITY HARDENING (Est. 4-6 hours)

Why This Matters

Users won't trust a system without proper security. The old system had no rate limiting either, but we need it NOW for production.

What's Missing

1. Rate Limiting - Anyone can brute-force login, enumerate users
2. Multi-tenant Data Isolation - Users see all data from all tenants
3. API Documentation - Users don't know what endpoints exist

Implementation Tasks

Task 2.1: Add Rate Limiting [4 hours]

// packages/middleware/rate-limit.ts
import { Ratelimit } from "@upstash/ratelimit"; // or similar

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(5, "1 m"), // 5 requests per minute
});

// Apply to sensitive endpoints:
// - POST /api/v1/*/*/login (5 attempts per minute per IP)
// - GET /api/v1/*/users (100 requests per minute per IP)
// - POST /api/v1/*/* (limit all mutations)

Endpoint Rate Limits (Recommended):

• /login - 5 attempts/minute per IP
• /register - 3 attempts/minute per IP
• User list endpoints - 100 requests/minute per IP
• Mutation endpoints - 50 requests/minute per IP
• Public endpoints - 1000 requests/hour per IP

Task 2.2: Complete Multi-Tenant Filtering [2-3 hours]

Follow DBAL_REFACTOR_PLAN.md (TD-1):

1. Audit all queries to ensure tenantId filtering
2. Replace old getAdapter() calls with db.entity.list() pattern
3. Verify frontend isolation (admin sees only their tenant users)

Key Files to Check:

• /frontends/nextjs/src/app/api/v1/[...slug]/route.ts - Ensure tenant filtering
• /dbal/development/src/core/client/ - Verify DBAL enforces filtering
• /frontends/nextjs/src/lib/db-client.ts - Check integration points

Task 2.3: Add OpenAPI Documentation [4 hours]

// /frontends/nextjs/src/app/api/docs/route.ts
import swaggerUi from 'swagger-ui-express';
import spec from './swagger-spec.json';

export const GET = (req: Request) => {
  return new Response(swaggerUi.generate(spec), {
    headers: { 'content-type': 'text/html' }
  });
};

Why: Developers need to know what APIs exist. Old system had no docs either, but users asked for them.

Success Criteria

• ✅ Brute-force attacks prevented (5 attempts/min limit on login)
• ✅ User enumeration prevented (rate-limited list endpoint)
• ✅ Data isolation working (user A can't see tenant B's data)
• ✅ API docs available at /api/docs

---

PHASE 3: ADMIN TOOLS (Est. 3-5 days)

Why This Matters

This is what made the old system special. Admins could build pages, workflows, and styles WITHOUT CODE.

What the Old System Had (We Need to Recreate as JSON)

1. Lua Editor (686 LOC)

   • Syntax highlighting
   • Real-time execution
   • Error highlighting
   • Used for custom scripts

2. Schema Editor

   • Visual entity field builder
   • Type selector (string, number, boolean, etc.)
   • Constraint editor (required, unique, etc.)
   • Live schema validation

3. Workflow Editor

   • Node-based visual programming
   • Drag-drop node placement
   • Connection editor
   • Export to JSON Script format

4. CSS Class Manager

   • Visual CSS property builder
   • Color picker integration
   • Spacing/sizing quick-select
   • Responsive breakpoint editor

5. Database Manager

   • CRUD interface for all entities
   • Advanced filtering
   • Bulk operations
   • Data export/import

Implementation Strategy

Option A: Rapid MVP (Use Existing)

• Use Monaco Editor for code editing
• Use fakemui JSON renderer for schema builder UI
• Focus on Lua editor + basic workflow support first
• Timeline: 3 days

Option B: Full Experience (n8n-Style Integration)

• Integrate n8n's visual editor
• Use n8n's 500+ connector library for workflows
• Build custom editors for schemas
• Timeline: 5-7 days

Option C: Light Touch (Best for MVP)

• Create JSON-based editors using fakemui components
• No code editor (just JSON UI)
• Focus on what users need most
• Timeline: 2 days

Recommended: Hybrid Approach (Option A + C)

1. Day 1-2: Lua editor (Monaco) + basic workflow support
2. Day 2-3: Schema editor (JSON UI using fakemui)
3. Day 3: Database manager (simple CRUD UI)
4. Day 4+: CSS manager and advanced features

New Packages to Create

packages/
├── ui_lua_editor/              # Lua code editor with execution
│   └── components/
│       └── LuaEditor.json      # Monaco-based editor component
│
├── ui_schema_editor/           # Entity schema visual builder
│   └── components/
│       └── SchemaBuilder.json  # Form-based schema builder
│
├── ui_workflow_editor/         # Visual workflow node editor
│   └── components/
│       └── WorkflowEditor.json # Node-based visual programming
│
└── ui_database_manager/        # Data browser and CRUD
    └── components/
        └── DatabaseBrowser.json # Table/grid view of all entities

Key Integration Points

1. Authentication: Only Level 4+ (God) users can access
2. DBAL: All editors modify via DBAL (not direct database access)
3. Real-time: Use WebSockets for live collaboration (future)
4. Validation: All changes validated against schemas
5. Audit: All changes logged (who, what, when)

---

PHASE 4: MULTI-FRONTEND VERIFICATION (Est. 2-3 hours)

Current Status

Frontend	Status	Priority
Next.js	✅ Ready	HIGH
CLI	⏳ Build untested	MEDIUM
Qt6	⏳ Build untested	LOW

Tasks

Task 4.1: Build & Test CLI [30-45 min]

cd /frontends/cli
conan install . --output-folder build --build missing
cmake -S . -B build -G Ninja
cmake --build build
./build/bin/metabuilder-cli --version

Success: CLI launches and responds to commands

Task 4.2: Build & Test Qt6 [45-60 min]

cd /frontends/qt6
conan install . --output-folder build --build missing
cmake -S . -B build -G Ninja
cmake --build build
./build/metabuilder-qt6  # Should open window

Success: Qt6 app launches and renders pages

Task 4.3: C++ DBAL Daemon (Phase 3) [Low Priority]

cd /dbal/production
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/bin/dbal-daemon  # Should start WebSocket server

Note: Not required for Phase 2. Phase 2 uses TypeScript DBAL.

---

PHASE 5: PERFORMANCE & UX POLISH (Est. 2-3 days)

Checklist

Visual Polish

• Add loading skeletons on pages
• Add error boundary components
• Add empty state components (no data messages)
• Add transitions/animations to Material Design components
• Verify hover states on all interactive elements

UX Polish

• Add "first login" experience (password reset modal)
• Add onboarding wizard for new users
• Add role-based help text and tutorials
• Add keyboard shortcuts (Cmd+K search, Cmd+? help)
• Add analytics (track user actions for improvements)

Performance

• Implement code splitting (routes load on demand)
• Add image optimization (next/image)
• Add caching headers (static assets cached 1 year)
• Add CDN integration (CloudFlare, Vercel Edge)
• Profile and optimize slow pages

Monitoring

• Add error tracking (Sentry or similar)
• Add performance monitoring (Web Vitals)
• Add user behavior analytics (Mixpanel or similar)
• Add database query logging
• Add API performance tracking

---

IMPLEMENTATION ROADMAP

Week 1: Foundation (MVP Launch)

• ✅ Phase 1 - Verify styling works (DONE in 1 hour)
• ⏳ Phase 2 - Security hardening (4-6 hours)
• ⏳ Phase 4 - Multi-frontend verification (2-3 hours)
• ✅ Tests - Ensure 95%+ passing (already at 99.7%)

Week 2: Admin Tools (First Cut)

• Day 1-2: Lua editor + schema editor (2 packages)
• Day 3: Database manager (1 package)
• Day 4: Testing and fixes
• Day 5: Buffer and optimization

Week 3: Polish & Launch

• Phase 5 - UX polish and performance
• Final security audit
• Load testing
• Beta user feedback

Weeks 4+: Continuous Improvement

• Collect user feedback
• Fix bugs reported by beta users
• Add requested features
• Optimize based on analytics

---

HOW THIS COMPARES TO OLD SYSTEM

What We Kept (and Improved)

Feature	Old	New	Status
Multi-role experience	✅	✅+	Improved with better permissions
Material Design	✅	✅+	Upgraded from shadcn to fakemui
Component system	✅	✅+	151+ components vs 46
Database seeding	✅	✅+	YAML + JSON hybrid
Dark mode	✅	✅+	Full LAB color support
Responsive design	✅	✅+	Better mobile UX
Testing	⚠️	✅+	326 tests vs minimal

What We Need to Add Back

Feature	Old	New	Gap
Lua editor	✅	❌	Need to recreate (2-3 days)
Schema visual editor	✅	❌	Need to create (2 days)
Workflow editor	✅	❌	Need to create (2-3 days)
CSS class manager	✅	❌	Nice-to-have (1-2 days)
Database manager	✅	⚠️	Have API, need UI (1 day)

New Capabilities

Feature	Old	New	Advantage
Multi-tenant	❌	✅	Enterprise feature
Rate limiting	❌	✅	Security
API documentation	❌	✅	Developer experience
n8n integration	❌	✅	Workflow connector library
Type safety	⚠️	✅	Fewer bugs
Performance monitoring	❌	✅	Production readiness

---

QUICK WIN: Verify Everything Works Right Now

Run these commands to confirm system health:

# 1. Verify build works
cd /frontends/nextjs
npm run build

# 2. Run tests
npm run test:e2e

# 3. Verify styling exists
grep -r "color-primary" .next/static/chunks/*.css | head -1

# 4. Check database
npm run db:push

# 5. Check DBAL
grep -r "getDBALClient" src/app | head -3

# Expected results:
# ✅ Build succeeds
# ✅ 95%+ tests pass
# ✅ CSS contains colors
# ✅ Database schema updated
# ✅ DBAL used throughout

---

SUCCESS METRICS (After All Phases)

Users Will Experience

🎯 Landing page loads in <2 seconds
🎯 Login works smoothly
🎯 Dashboard responds instantly
🎯 Admin panel is intuitive
🎯 Building pages requires zero code
🎯 Mobile experience is excellent
🎯 Dark mode looks great
🎯 No error messages (errors handled gracefully)
🎯 Performance is snappy
🎯 Security is obvious (login limits prevent brute-force)

System Will Be

✅ Production-ready (MVP)
✅ Secure (rate limiting, multi-tenant isolation)
✅ Performant (< 2s load time)
✅ Reliable (99.7% test pass rate)
✅ Scalable (DBAL layer abstracts database)
✅ Maintainable (JSON-based configuration)
✅ Extensible (package system allows plugins)
✅ Documented (API docs + guides)
✅ Monitored (error tracking + analytics)
✅ User-delightful (beautiful design + intuitive UX)

---

NEXT STEPS

Immediately (Now)

1. ✅ Verify styling works - RUN: npm run dev and open http://localhost:3000
2. ✅ Verify build succeeds - RUN: npm run build
3. ✅ Verify tests pass - RUN: npm run test:e2e

Next 2 Hours

1. Implement rate limiting (Phase 2, Task 2.1)
2. Add OpenAPI documentation (Phase 2, Task 2.3)
3. Verify multi-tenant isolation works (Phase 2, Task 2.2)

Next 1-2 Days

1. Verify CLI frontend builds and works
2. Verify Qt6 frontend builds and works
3. Create first admin tool (Lua editor package)

Next 1-2 Weeks

1. Complete admin tools (Lua, Schema, Workflow, Database, CSS editors)
2. Implement Phase 5 UX polish
3. Conduct security audit
4. Load test the system

---

KEY PRINCIPLE

The old system was special because it empowered users to build without code. The new system is MORE special because it's built on a superior foundation. We just need to restore the tools that made it magical.

---

Remember: The difference between "shipped" and "delightful" is 20% code, 80% polish. We have the code. Now let's add the polish.