metabuilder/docs/guides/IMPLEMENTATION_ROADMAP.md

MetaBuilder Complete Implementation Roadmap

Current Status: Phase 1 Complete ✅

Last Commit: 7a3acb3 - Phase 1: Next.js 15 migration setup and core structure

---

Remaining Work

Phase 2: API Routes & Component Migration (8-12 hours)

Priority: HIGH Status: NOT STARTED

API Routes Implementation

• /app/api/auth/[...nextauth]/route.ts - NextAuth configuration
• /app/api/auth/login/route.ts - Login endpoint
• /app/api/auth/logout/route.ts - Logout endpoint
• /app/api/dbal/[...path]/route.ts - DBAL proxy routes
• /app/api/users/route.ts - User management
• /app/api/tenants/route.ts - Tenant management
• /app/api/kv/route.ts - KV store operations
• /app/api/blob/route.ts - Blob storage operations

Component Conversion (Level 1-5)

1. Level 1 (Home) - Public homepage ✅ Basic structure exists
2. Level 2 (Dashboard) - User dashboard
   • Convert src/level2-dashboard.tsx → app/(auth)/dashboard/page.tsx
   • Add server components for data fetching
3. Level 3 (Admin) - Admin panel
   • Convert src/level3-admin.tsx → app/(auth)/admin/page.tsx
   • User management UI
   • Tenant management UI
4. Level 4 (Builder) - Visual builder
   • Convert src/level4-builder.tsx → app/(auth)/builder/page.tsx
   • Canvas component
   • PropertyInspector
   • ComponentLibrary
5. Level 5 (SuperGod) - System administration
   • Convert src/level5-supergod.tsx → app/(auth)/supergod/page.tsx
   • System settings
   • Global configuration

Server vs Client Components

• Server Components: Data fetching, SEO, static content
• Client Components: Interactive UI, forms, real-time updates

---

Phase 3: Features & Optimization (4-6 hours)

Priority: MEDIUM Status: NOT STARTED

Server-Side Rendering (SSR)

• Level 1 (home) with SSR for SEO
• Server data fetching for dashboards
• Streaming for large datasets

Static Site Generation (SSG)

• Static pages (docs, landing)
• Incremental Static Regeneration (ISR)

Optimization

• Image optimization with next/image
• Font optimization with next/font ✅ Already configured
• Code splitting and lazy loading
• Bundle analysis and reduction

---

Phase 4: Docker Configuration (2-3 hours)

Priority: MEDIUM Status: NOT STARTED

Next.js Dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Update docker-compose files

• Update deployment/docker-compose.production.yml
• Update deployment/docker-compose.development.yml
• Update deployment/Dockerfile.app

---

Phase 5: Qt6 Desktop Frontend (6-8 hours)

Priority: MEDIUM Status: NOT STARTED

Structure

frontends/desktop/
├── CMakeLists.txt
├── src/
│   ├── main.cpp
│   ├── mainwindow.cpp/.h
│   ├── dbal_client.cpp/.h
│   ├── dashboard_widget.cpp/.h
│   ├── user_management_widget.cpp/.h
│   ├── tenant_management_widget.cpp/.h
│   └── settings_widget.cpp/.h
├── ui/
│   ├── mainwindow.ui
│   └── *.ui files
└── README.md

Features

• Qt6 Widgets application
• HTTP client for DBAL API
• Multi-tab interface
• System tray integration
• Cross-platform builds

---

Phase 6: CLI Interface (4-6 hours)

Priority: LOW Status: NOT STARTED

Structure

frontends/cli/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   ├── commands/
│   │   ├── auth.ts
│   │   ├── user.ts
│   │   ├── tenant.ts
│   │   ├── kv.ts
│   │   ├── blob.ts
│   │   └── server.ts
│   └── utils/
│       ├── config.ts
│       ├── http-client.ts
│       └── formatters.ts
└── README.md

Features

• Interactive mode with Inquirer.js
• Batch mode for scripting
• JSON/Table output formats
• Configuration file support
• Session management

---

Implementation Order (Recommended)

Immediate (Next commit)

1. Reorganize to frontends/ structure
   • Move app/ → frontends/web/app/
   • Move src/ → frontends/web/src/
   • Update all imports and path references
   • Update next.config.ts paths
   • Update tsconfig.json paths

Short-term (Next 2-3 commits)

2. Implement API routes (Phase 2a)

   • Auth endpoints
   • DBAL proxy routes
   • Essential CRUD operations

3. Convert Level 2-3 components (Phase 2b)

   • Dashboard
   • Admin panel
   • Basic functionality working

Medium-term (Next 4-5 commits)

4. Convert Level 4-5 components (Phase 2c)

   • Builder
   • SuperGod
   • Advanced features

5. SSR/SSG optimization (Phase 3)

   • Server components
   • Data fetching strategies
   • Performance improvements

6. Docker configuration (Phase 4)

   • Standalone Next.js build
   • Updated docker-compose files

Long-term (Separate PRs recommended)

7. Qt6 desktop frontend (Phase 5)

   • Basic window and tabs
   • DBAL client integration
   • Essential features

8. CLI interface (Phase 6)

   • Command structure
   • Interactive mode
   • Essential commands

---

Estimated Timeline

• Phase 2: 2-3 days full-time (API routes + all components)
• Phase 3: 1 day full-time (optimization)
• Phase 4: Half day (Docker)
• Phase 5: 2 days full-time (Qt6 desktop)
• Phase 6: 1 day full-time (CLI)

Total: 6-7 days full-time development

---

Decision Points

Should we split this?

Given the scope, consider:

• Option A: Complete all phases in this PR (recommended against - too large)
• Option B: Complete Phases 2-4 in this PR, Phases 5-6 in separate PRs (recommended)
• Option C: Complete Phase 2 only in this PR, rest in separate PRs (most manageable)

Recommendation

Complete Phase 2 (API routes + Level 2-3) in this PR to get Next.js functional. Create separate PRs for:

• Phase 2 continuation (Level 4-5)
• Phase 3 (optimization)
• Phase 4 (Docker)
• Phase 5 (Qt6 desktop)
• Phase 6 (CLI)

This allows for:

• Better code review
• Incremental testing
• Easier rollback if issues arise
• Parallel development if needed

---

Next Steps

To proceed with "Make it so", I recommend:

1. Immediate: Create frontend reorganization commit
2. Next commit: Implement essential API routes
3. Following commits: Convert Level 2-3 components
4. Validate: Test Next.js app is functional
5. Document: Update migration status

Would you like me to:

• A) Proceed with Phase 2 implementation (API routes + Level 2-3)?
• B) Create the frontend reorganization first?
• C) Focus on a specific phase?

Current recommendation: Start with B (reorganization), then A (Phase 2 core features)