metabuilder/docs/analysis/FUNCTIONAL_PRIORITIES.md

MetaBuilder: Functional Priorities & Action Plan

Date: 2026-01-21 Status: Phase 2 - 90% Complete, 3 Immediate Fixes Block All Frontends

---

🎯 Functional Priority Matrix

CRITICAL (Blocks all 3 frontends)

Next.js TypeScript Build Failure ❌

• Issue: Type error at /frontends/nextjs/src/app/page.tsx:67
• Impact: Cannot build → Cannot deploy → CLI and QT6 have no backend
• Fix Time: 5 minutes
• Dependencies: Fixes fakemui-registry expansion, page.tsx type narrowing

Styling System Disabled ❌

• Issue: SCSS imports commented out in /src/main.scss (lines 3-11)
• Impact: Components render unstyled (Material Design completely missing)
• Fix Time: 30 minutes (debug what caused original errors)
• Root Cause: Unknown - comments say "TODO: Fix SCSS imports - causing build errors"

PackageStyleLoader Commented ⚠️

• Issue: Component style loading disabled in layout.tsx:60-61
• Impact: Packages can't apply custom styles
• Fix Time: 2 minutes (uncomment once SCSS fixed)

---

📋 Immediate Action Plan

Phase 1: Unblock Next.js Build (10 minutes)

Step 1.1: Fix TypeScript error (5 min)

File: /frontends/nextjs/src/app/page.tsx:67
Current: const renderObj = parsed.render as Record<string, unknown> | undefined
Problem: Type narrowing lost after `as unknown` cast
Solution: Add explicit type cast after typeof check
  renderObj.type as string
  renderObj.template as JsonValue | undefined

Step 1.2: Verify build passes

cd /frontends/nextjs
npm run typecheck
# Should output: "Compiled successfully"

---

Phase 2: Restore Styling (30 minutes)

Step 2.1: Investigate SCSS import errors

File: /frontends/nextjs/src/main.scss (lines 3-11)
Commented imports:
  @use './styles/core/theme.scss'
  @import '../../fakemui/styles/components.scss'

Action: Find out what was causing errors
- Check if fakemui/styles/components.scss exists
- Check if ./styles/core/theme.scss exists
- Try uncommenting one at a time to isolate issue

Step 2.2: Fix SCSS imports

Options:
A) Fix the files that are being imported
B) Use CSS imports instead of SCSS @use
C) Move styling to inline/CSS modules temporarily
D) Use styled-components instead
Recommendation: Option A (fix root cause)

Step 2.3: Verify styling works

cd /frontends/nextjs
npm run dev
Navigate to http://localhost:3000
Verify Material Design styling visible on components

---

Phase 3: Test All Frontends (15 minutes)

Step 3.1: Test Next.js

npm run test:e2e
# Should see: All tests passing

Step 3.2: Test CLI (if building)

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

Step 3.3: Test QT6 (if building)

cd /frontends/qt6
conan install . --output-folder build --build missing
cmake -S . -B build -G Ninja
cmake --build build
./build/metabuilder-qt6
# Verify landing page loads and Material Design visible

---

🏗️ Architecture Requirements (All Frontends)

1. Database Connection (DBAL)

• Next.js: import { getDBALClient } from '@/dbal' ✅ Working
• CLI: HTTP calls to http://localhost:3000/api/dbal/* ✅ Implemented
• QT6: C++ DBALClient via HTTP ✅ Implemented (untested)

2. Component Rendering

• Next.js: JSON → fakemui via registry ✅ Working (blocked by styling)
• CLI: Lua scripts + text output ✅ Implemented
• QT6: JSON → QML via Material mapping ✅ Implemented (untested)

3. Styling

• Next.js: SCSS + Tailwind ✗ Broken (imports disabled)
• CLI: N/A (CLI only)
• QT6: Material Design QML ✅ Working

4. Seed Data Loading

• DBAL: seedDatabase() function ✅ Working
• All frontends use: 12 core packages (bootstrap order)
• Data flows through PageConfig table for routing

---

📊 Functional State by Component

Components System (131+ fakemui + Material equivalents)

Category	Next.js	CLI	QT6	Status
Form Controls (28)	Available	N/A	22+ mapped	✅ Complete
Data Display (26)	Available	Tables	18+ mapped	✅ Complete
Layout (8)	Available	N/A	8 mapped	✅ Complete
Navigation (22)	Available	N/A	15+ mapped	✅ Complete
Feedback (6)	Available	N/A	5+ mapped	✅ Complete
Icons (30+)	Available	N/A	Yes	✅ Complete

Issue: Next.js components available but unstyled due to SCSS disabled

---

Packages System (56 packages, 100% JSON)

Aspect	Status	Working?
Package structure	✅ Complete	Yes - 56 packages consistent
Seed data format	✅ Complete	Yes - JSON arrays with metadata
Package loading	✅ Complete	Yes - loadJSONPackage() works
Entity seed loading	✅ Complete	Yes - seedDatabase() idempotent
PageConfig routing	✅ Complete	Yes - database-driven routes
Component definitions	✅ Complete	Yes - JSON definitions valid
Package bootstrap order	✅ Complete	Yes - 12 core packages seeded

No issues - packages system fully functional

---

Database & DBAL (TypeScript Phase 2)

Component	Status	Details
Prisma schema generation	✅ Works	From YAML → schema.prisma
Entity types	✅ Generated	types.generated.ts from YAML
Client factory	✅ Works	getDBALClient() exports
Seed orchestration	✅ Works	seedDatabase() loads all entities
Multi-tenant isolation	✅ Works	tenantId filtering on all queries
ACL/permissions	✅ Works	Role-based access control
SQLite (dev)	✅ Works	better-sqlite3 adapter
PostgreSQL (prod)	✅ Works	Native PostgreSQL adapter

No issues - DBAL fully functional

---

Routing & Auth

Feature	Status	Details
Database routing	✅ Works	PageConfig table queries
God panel override	✅ Works	Supergod users can remap routes
Session auth	✅ Works	Cookie-based session
Permission levels	✅ Works	6-level hierarchy (0-5)
Current user fetching	✅ Works	getCurrentUser() function
Protected routes	✅ Works	requiresAuth flag checked
Permission checks	✅ Works	Level comparison logic

No issues - auth fully functional

---

🐛 Known Issues by Severity

CRITICAL (Blocks deployment)

1. Next.js TypeScript error - Type safety issue prevents build
2. Styling disabled - Components render unstyled (Material Design missing)

HIGH (Impacts functionality)

3. No JSON Schema validation at runtime - Seed data trusts input correctness
4. IDE schema integration not configured - No autocomplete for seed data
5. Zod vs JSON Schema mismatch - Two parallel validation systems

MEDIUM (Quality of life)

6. Pre-commit validation missing - No local validation hook
7. DBAL Phase 3 not implemented - C++ daemon deferred (Phase 2 works fine)

LOW (Documentation/UX)

8. API docs missing - No OpenAPI/Swagger
9. Rate limiting not implemented - Security feature missing
10. CLI not built locally - Only Qt6 and Next.js tested

---

✅ What Works Right Now

Fully Functional Systems

• ✅ Database: PostgreSQL/SQLite with Prisma
• ✅ DBAL: Complete TypeScript abstraction layer
• ✅ Packages: 56 JSON packages, consistent structure
• ✅ Routing: Database-driven with overrides
• ✅ Authentication: Session-based, 6-level permissions
• ✅ Components: 131+ Material Design components (unfunc due to styling)
• ✅ Seed System: Idempotent, 12 core packages bootstrap
• ✅ API: RESTful CRUD endpoints multi-tenant safe
• ✅ Testing: 326 tests, 99.7% passing
• ✅ Deployment: Docker stack ready

NOT Yet Functional

• ❌ Next.js Build: TypeScript errors + disabled styling
• ❌ CLI Build: Untested (architecturally sound)
• ❌ QT6 Build: Untested (architecturally sound)
• ❌ Rate Limiting: Not implemented (security)
• ❌ API Documentation: Not implemented (DX)

---

🚀 Deployment Timeline

Task	Time	Blocker?
Fix Next.js TypeScript	5 min	YES
Restore SCSS styling	30 min	YES
Verify tests pass	10 min	No
Test Next.js locally	10 min	No
Docker deploy (dev)	15 min	No
Docker deploy (prod)	20 min	No
CLI build & test	30 min	No (parallel)
QT6 build & test	30 min	No (parallel)
TOTAL	~2 hours

Critical path: Fix TypeScript → Restore styling → Deploy

---

🎯 Post-MVP Priorities

Once functional:

1. Rate Limiting (TD-2) - Security blocker

   • Per-IP limiting on API endpoints
   • Configurable by route
   • Redis/memory-based

2. API Documentation (TD-3) - Developer experience

   • OpenAPI 3.0 spec
   • Swagger UI at /api/docs
   • Auto-generated from TypeScript

3. Pre-Commit Validation (Quality)

   • JSON Schema validation for seed data
   • Linting for package metadata
   • Hook into git pre-commit

4. IDE Integration (DX)

   • VS Code schema associations
   • Autocomplete for seed data files
   • Schema tooltips

5. DBAL Phase 3 (Future)

   • C++ daemon implementation
   • WebSocket RPC protocol
   • Credential isolation

---

📝 Notes

• Styling issue root cause unknown - Need to debug what made SCSS imports fail originally
• SCSS strategy: Try uncommenting incrementally to find culprit
• CLI/QT6: Architecturally sound, just untested. Build process likely straightforward (conan + cmake).
• DBAL complete: No gaps, fully functional for Phase 2
• Packages complete: No issues, 56 packages working
• Tests solid: 99.7% pass rate, only 1 test failing (auth middleware status code)

---

🔧 Tech Stack Summary

Layer	Technology	Status
Database	PostgreSQL 16 / SQLite 3	✅ Complete
DBAL	TypeScript + Prisma	✅ Complete
Next.js Backend	Node.js 18 + Express-like routing	✅ Complete
Next.js Frontend	React 19 + fakemui + SCSS	🔴 Blocked
CLI	C++20 + Conan + Lua 5.4	⏳ Untested
QT6	C++20 + Qt6 QML + Conan	⏳ Untested
Testing	Vitest + Playwright	✅ Complete
Deployment	Docker Compose	✅ Ready