metabuilder/ROADMAP.md

# MetaBuilder Roadmap

> **The Single Source of Truth for MetaBuilder Development**

**Version:** 0.8.8
**Last Updated:** March 4, 2026
**Status:** 🎯 C++ DBAL Production Live ✅ — Event-Driven Workflows, JWT Auth, Full-Stack Pastebin
**Structure:** Universal Platform Monorepo

---

## 📁 Monorepo Structure

```
metabuilder/
├── cadquerywrapper/      # Parametric 3D CAD modeling (Python, CadQuery)
├── caproverforge/        # CapRover PaaS mobile client (Android, Kotlin)
├── codegen/              # Visual code generation studio (React, Vite)
├── config/               # Lint, test, misc configs
├── dbal/                 # Database Abstraction Layer
│   ├── development/      # TypeScript implementation
│   ├── production/       # C++ implementation
│   └── shared/api/schema/# JSON entities (SOURCE OF TRUTH)
├── deployment/           # Docker & infrastructure
├── dockerterminal/       # Docker Swarm management (Next.js)
├── docs/                 # Documentation (organized)
│   ├── analysis/         # Status reports, assessments
│   ├── architecture/     # System design docs
│   ├── guides/           # Quick references, how-tos
│   ├── implementation/   # Implementation details
│   ├── packages/         # Package-specific docs
│   ├── phases/           # Phase completion reports
│   ├── testing/          # E2E and test docs
│   └── workflow/         # Workflow engine docs
├── e2e/                  # End-to-end Playwright tests
├── fakemui/              # Material UI clone (React, QML)
├── frontends/            # Multiple frontends
│   ├── cli/              # Command-line interface
│   ├── nextjs/           # Primary web UI
│   └── qt6/              # Desktop application
├── gameengine/           # SDL3 C++ game engine
├── mojo/                 # Mojo examples (systems programming)
│   └── examples/         # Official Modular examples
├── packagerepo/          # Package repository service (Python, FastAPI)
├── packages/             # 62+ MetaBuilder feature packages
├── pastebin/             # Snippet pastebin (Next.js)
├── pcbgenerator/         # PCB design library (Python)
├── postgres/             # PostgreSQL admin dashboard (Next.js, Drizzle)
├── repoforge/            # GitHub Android client (Kotlin, Compose)
├── schemas/              # JSON validation schemas
├── scripts/              # Build and migration scripts
├── services/             # Background services
├── smtprelay/            # SMTP relay server (Python, Twisted)
├── sparkos/              # Minimal Linux distro + Qt6 app
├── storybook/            # Component documentation (React, Vite)
├── workflow/             # Workflow engine
│   ├── executor/         # Multi-language executors (ts, python, cpp)
│   ├── examples/         # Workflow examples
│   └── plugins/          # Workflow plugins
└── [root files]          # package.json, playwright.config.ts, etc.
```

### Standalone Projects (15)

| Project | Purpose | Tech Stack |
|---------|---------|------------|
| `cadquerywrapper/` | Parametric 3D CAD modeling | Python, CadQuery |
| `caproverforge/` | CapRover PaaS mobile client | Android, Kotlin |
| `codegen/` | Visual code generation studio | React, Vite, TypeScript |
| `dockerterminal/` | Docker Swarm management | Next.js, TypeScript |
| `fakemui/` | Material UI clone (React + QML) | React, QML, TypeScript |
| `gameengine/` | 2D/3D game engine | C++, SDL3 |
| `mojo/` | Systems programming examples | Mojo (Python superset) |
| `packagerepo/` | Package repository service | Python, FastAPI |
| `pastebin/` | Code snippet sharing | Next.js, TypeScript |
| `pcbgenerator/` | PCB design automation | Python |
| `postgres/` | PostgreSQL admin dashboard | Next.js, Drizzle ORM |
| `repoforge/` | GitHub client for Android | Kotlin, Compose |
| `smtprelay/` | Email relay server | Python, Twisted |
| `sparkos/` | Minimal Linux + Qt6 app | C++, Qt6, Linux |
| `storybook/` | Component documentation | React, Vite, Storybook |

---

## 🚀 Executive Summary

**What's Done (Phase 0–2 - ✅ Complete):**
- ✅ Core architecture (Next.js, Prisma, DBAL, Multi-tenant)
- ✅ Authentication & authorization (Session-based, 6-level permissions)
- ✅ CRUD operations (Schema-driven, all major endpoints)
- ✅ Package system (62 packages, auto-loading, dynamic routing)
- ✅ Generic component renderer (JSON-to-React)
- ✅ Infrastructure (Docker, PostgreSQL, Redis, Nginx)
- ✅ Game engine (SDL3/bgfx, 27/27 tests passing)
- ✅ FakeMUI (167 components — Material Design clone)
- ✅ WorkflowUI visual editor (n8n-style, 152 plugin nodes)

**What's Done (Phase 7 — C++ DBAL Production ✅ Complete, shipped Mar 2026):**
- ✅ C++ DBAL daemon in production (Drogon HTTP, 14 DB backends)
- ✅ Full YAML → JSON migration (63 files, yaml-cpp removed)
- ✅ JWT authentication + JSON ACL config
- ✅ Event-driven workflow engine (`pastebin.User.created` → 15-node JSON workflow)
- ✅ Declarative seed data (`dbal/shared/seeds/database/` — 3 users, 12 namespaces, 28 snippets)
- ✅ Flask auth backend (register, login, JWT, Python runner)
- ✅ Pastebin full-stack (Next.js + Redux + IndexedDB + Flask + DBAL C++)
- ✅ Dark/light theme switcher, i18n (EN/ES)

**What's Planned (Phase 3+ - Future):**
- 🔮 Phase 3: Enhanced CRUD (Rich forms, bulk operations, relationships)
- 🔮 Phase 4: God Panel (Admin dashboard, system management)
- 🔮 Phase 5: Advanced Features (Webhooks, DBAL workflow triggers)
- 🔮 Phase 6: Advanced Auth (SSO, SAML, OAuth)
- 🔮 Phase 8: Multi-Source Packages (NPM, git, http sources)
- 🔮 Phase 9: Universal Platform (State Machine, Command Bus, Event Stream, VFS)

---

## Status Dashboard

| Phase | Name | Status | Completion | Timeline |
|-------|------|--------|------------|----------|
| **0** | Foundation | ✅ Complete | 100% | Pre-2026 |
| **1** | MVP | ✅ Complete | 100% | January 2026 |
| **2** | Backend Integration | ✅ Complete | 100% | Q1 2026 |
| **2.5** | Monorepo Consolidation | ✅ Complete | 100% | January 2026 |
| **3** | Enhanced CRUD | 🔄 In Progress | 25% | Q1-Q2 2026 |
| **4** | God Panel | 🔮 Planned | 0% | Q2 2026 |
| **5** | Advanced Features | 🔮 Planned | 0% | Q2-Q3 2026 |
| **6** | Advanced Auth | 🔮 Planned | 0% | Q3 2026 |
| **7** | C++ DBAL Production | ✅ Complete | 100% | March 2026 |
| **8** | Multi-Source Packages | 🔮 Planned | 0% | Q4 2026 |
| **9** | Universal Platform | 🔮 Planned | 0% | 2027 |

---

## 📚 What To Read First

- **Quick status?** → See [Executive Summary](#-executive-summary) above (2 min read)
- **What's currently working?** → Go to [Current Status: What's Working Today](#whats-working-today) (5 min read)
- **Details on Phase 2?** → Jump to [Phase 2: Backend Integration](#-phase-2-backend-integration-in-progress) (15 min read)
- **Full phase details?** → See [Roadmap Phases](#roadmap-phases) (30 min read)
- **Project history?** → See [Project History](#project-history) at end (10 min read)

---

## Vision

MetaBuilder is an ultra-generic, data-driven multi-tenant platform where **everything flows through the database**. No hardcoded routes, no component imports, no assumptions—the entire application structure lives in the database, rendered by a generic JSON-to-React engine.

This vision evolved from our original Spark-based admin panel generator (see [Project History](#project-history)) into a more scalable, enterprise-ready platform with enhanced multi-tenancy, security, and flexibility.

### Core Philosophy

```
Browser URL → Database Query → JSON Component → Generic Renderer → React → User
```

**Zero hardcoded connections. Everything is data.**

---

## Project History

### Evolution from Spark-Based Version

MetaBuilder began as a Django-style admin panel generator built on GitHub's Spark framework. The original version (preserved in `/old` directory) demonstrated the core concept of declarative, data-driven application building but was limited in scope and scalability.

#### Original Version (Spark-Based) - Pre-2026

**Architecture:**
- **Framework:** GitHub Spark + Vite + React 19
- **UI Library:** Radix UI components with Tailwind CSS
- **Storage:** KV (Key-Value) storage via Spark
- **Scripting:** Lua integration (Fengari) for custom logic
- **Permission System:** 4 levels (Public, User, Admin, God)
- **Scope:** Single-tenant admin panel generator

**Key Features:**
- Declarative schema definition via JSON
- Auto-generated CRUD interfaces
- Visual component hierarchy editor with drag-and-drop
- Monaco code editor for Lua scripts
- Page routing configuration
- Database export/import

**Limitations:**
- No multi-tenancy support
- Limited scalability (KV storage)
- Single deployment architecture
- No package system
- No production-grade database support
- Limited permission granularity

#### Current Version (Next.js-Based) - 2026+

**Architecture:**
- **Framework:** Next.js 16 + React 19 + App Router
- **UI Library:** Material-UI (MUI) with SCSS modules
- **Database:** PostgreSQL (production) / SQLite (development) via Prisma ORM
- **DBAL:** Dual implementation (TypeScript for dev, C++ daemon for production)
- **Scripting:** JSON-based scripts with controlled execution
- **Permission System:** 6 levels (Public → User → Moderator → Admin → God → Supergod)
- **Scope:** Multi-tenant enterprise platform

**Major Enhancements:**
- ✨ **Multi-tenancy:** Complete tenant isolation with per-tenant data
- ✨ **Package System:** 52 built-in packages with dynamic loading
- ✨ **DBAL:** Language-agnostic database abstraction with credential isolation
- ✨ **Production-Ready:** PostgreSQL, Redis caching, C++ services
- ✨ **Enhanced Security:** 6-level permissions, row-level security, C++ credential isolation
- ✨ **Scalability:** Docker deployment, Kubernetes support, multi-instance ready
- ✨ **Testing:** Comprehensive test suite (464 tests, 100% pass rate)
- ✨ **Type Safety:** Full TypeScript with Prisma ORM

### Migration Path

#### What Was Preserved
- ✅ Core philosophy of data-driven architecture
- ✅ Declarative component definitions (enhanced to JSON)
- ✅ Generic rendering system (JSON-to-React)
- ✅ Visual configuration capabilities
- ✅ Schema-driven CRUD generation
- ✅ Permission-based access control (expanded)

#### What Was Reimplemented
- 🔄 **Storage:** KV → PostgreSQL/SQLite with Prisma
- 🔄 **UI Library:** Radix + Tailwind → Material-UI + SCSS
- 🔄 **Scripting:** Lua → JSON-based scripts
- 🔄 **Framework:** Vite/Spark → Next.js App Router
- 🔄 **Architecture:** Single-tenant → Multi-tenant
- 🔄 **Permissions:** 4 levels → 6 levels

#### What Was Added
- ➕ Multi-tenant support with complete isolation
- ➕ Package system with 52 built-in packages
- ➕ DBAL (TypeScript + C++ dual implementation)
- ➕ Production deployment infrastructure (Docker, Nginx, Redis)
- ➕ C++ media processing daemon
- ➕ Comprehensive test suite (unit, integration, E2E)
- ➕ Static site generation with ISR
- ➕ Session management with expiry tracking
- ➕ Remote package loading capability

### Architecture Comparison

| Aspect | Old (Spark) | New (Next.js) |
|--------|-------------|---------------|
| **Framework** | Vite + Spark | Next.js 16 App Router |
| **UI Components** | Radix UI | Material-UI (MUI) |
| **Styling** | Tailwind CSS | SCSS Modules + MUI sx prop |
| **Database** | KV Storage | PostgreSQL/SQLite + Prisma |
| **Scripting** | Lua (Fengari) | JSON Scripts |
| **Permissions** | 4 levels | 6 levels |
| **Tenancy** | Single | Multi-tenant |
| **Package System** | None | 52 packages + dynamic loading |
| **Deployment** | Single process | Docker + microservices |
| **Testing** | Limited | 464 tests (100% pass) |
| **Type Safety** | TypeScript | TypeScript + Prisma |
| **Production Ready** | Dev only | Production + C++ services |

### Why We Migrated

#### Scalability Needs
The KV storage approach limited our ability to:
- Handle complex queries and relationships
- Scale to thousands of users
- Support multi-tenancy efficiently
- Provide ACID guarantees

#### Enterprise Requirements
Production deployments required:
- Robust database with transactions
- Credential isolation (C++ DBAL)
- Multi-tenant data isolation
- Professional deployment options
- Comprehensive testing

#### Ecosystem Maturity
- PostgreSQL provides battle-tested reliability
- Prisma ORM offers excellent type safety
- Next.js App Router enables optimal performance
- Material-UI provides comprehensive component library

### Legacy Code Location

The original Spark-based version is preserved in `/old` directory for reference:
- Documentation: `/old/*.md`
- Source code: `/old/src/`
- Configuration: `/old/package.json`, `/old/tsconfig.json`

**Note:** The old version is maintained for historical reference only and is not actively developed.

---

## Table of Contents

**Start Here (Essential Reading):**
1. [Executive Summary](#-executive-summary) - Status overview (2 min)
2. [Status Dashboard](#status-dashboard) - Phase completion matrix (1 min)
3. [Current Status](#current-status) - What's working today (5 min)

**Development Reference:**
4. [Technology Stack](#technology-stack) - Technologies used
5. [System Architecture](#system-architecture) - How it all works together
6. [Roadmap Phases](#roadmap-phases) - Detailed phase breakdown

**Information:**
7. [Package Ecosystem](#package-ecosystem) - Available packages
8. [Feature Status Matrix](#feature-status-matrix) - Feature checklist
9. [Release History](#release-history) - What changed when
10. [Known Issues & Technical Debt](#known-issues--technical-debt) - What needs fixing

**Deep Dives (Optional):**
11. [Project History](#project-history) - Evolution from Spark to Next.js
12. [MVP Milestone](#mvp-milestone--) - MVP completion details
13. [Testing Strategy & Best Practices](#testing-strategy--best-practices)
14. [Development Best Practices](#development-best-practices)
15. [Long-Term Vision](#long-term-vision) - 5-year roadmap
16. [Success Metrics](#success-metrics) - How we measure success
17. [Contributing](#contributing) - How to contribute

---

## Current Status

| Metric | Value |
|--------|-------|
| **Current Phase** | Phase 7 Complete ✅ — C++ DBAL Production shipped |
| **Version** | 0.8.8 (pastebin) |
| **Build Status** | ✅ Production |
| **Game Engine Tests** | 27/27 passing (100%) |
| **Last Release** | March 4, 2026 (C++ DBAL + workflows + JWT auth) |
| **Last Update** | March 4, 2026 |

### Quick Stats

- **Entity Schemas:** 39 JSON entity definitions (was YAML, migrated Mar 2026)
- **DB Backends:** 14 (memory, sqlite, postgres, mysql, mariadb, cockroachdb, mongodb, redis, elasticsearch, cassandra, surrealdb, supabase, prisma)
- **Built-in Packages:** 62+ packages ready to use
- **Standalone Projects:** 15 integrated into monorepo
- **Technology Stack:** Next.js 16, React 19, TypeScript 5.9, Flask, Drogon C++
- **Services:** Next.js frontend, Flask auth, DBAL C++ daemon, PostgreSQL, Nginx
- **Workflow Steps:** 7 (dbal.uuid, dbal.timestamp, dbal.entity.create/get/list, dbal.var.set, dbal.log)
- **Languages:** TypeScript, Python, C++, Kotlin, Mojo, Go, Rust

### What's Working Today

✅ **Core Platform**
- ✨ Data-driven routing system (PageConfig + InstalledPackage)
- ✨ 6-level permission system (Public → User → Moderator → Admin → God → Supergod)
- ✨ Multi-tenant architecture with complete tenant isolation
- ✨ DBAL C++ daemon (production) — 14 database backends, Drogon HTTP
- ✨ Event-driven workflow engine — JSON workflows fire async on CRUD events
- ✨ JWT authentication + JSON ACL rules (auth.json)
- ✨ Declarative seed data — JSON files in `dbal/shared/seeds/database/`
- ✨ Generic JSON-to-React component renderer
- ✨ Package system with auto-loading seed data (62 packages available)
- ✨ Dynamic package loading from filesystem
- ✨ SQLite (dev) and PostgreSQL (production) support

✅ **Authentication & Authorization**
- ✨ JWT authentication (Flask issues tokens, DBAL validates via auth.json ACL)
- ✨ Session-based authentication with secure cookies
- ✨ Role-to-level mapping (public=0, user=1, moderator=2, admin=3, god=4, supergod=5)
- ✨ Permission level checks with automatic redirects
- ✨ Flask auth backend (register, login, token refresh, Python runner)
- ✨ Session expiry tracking and IP/user-agent logging

✅ **CRUD Operations**
- ✨ Schema-driven entity list views with dynamic tables
- ✨ Entity detail views with field-by-field display
- ✨ Entity create forms (auto-generated from schema)
- ✨ Entity edit forms (pre-populated with existing data)
- ✨ Placeholder API client infrastructure (ready for backend)
- ✨ Error handling and user feedback
- ✨ Breadcrumb navigation

✅ **Development Tools**
- ✨ TypeScript/JavaScript compiler (esbuild integration)
- ✨ Minification support with configurable options
- ✨ Source map generation for debugging
- ✨ Hot-reload development server
- ✨ Vitest testing framework with 97.9% pass rate
- ✨ ESLint + Prettier code formatting
- ✨ Prisma ORM with type-safe database access

✅ **Static Site Generation**
- ✨ Database-driven generateStaticParams() for UI pages
- ✨ ISR (Incremental Static Regeneration) support
- ✨ Build-time page generation
- ✨ Graceful fallback to dynamic rendering

✅ **Infrastructure**
- ✨ PostgreSQL database with Prisma ORM
- ✨ Next.js 16 frontend (App Router + Server Components)
- ✨ Docker deployment with docker-compose
- ✨ Nginx reverse proxy with SSL support
- ✨ Redis caching layer
- ✨ Development and production environments
- ✨ Health checks and monitoring

---

### What's NOT Done Yet (Phase 2 Remaining & Future Phases)

❌ **Phase 2 - Final Items** (see `/TECH_DEBT.md` for detailed instructions):
- TD-1: DBAL Refactoring - Move database logic from frontend to DBAL (🔴 CRITICAL)
- TD-2: Rate limiting - API endpoint protection (🟡 HIGH)
- TD-3: OpenAPI/Swagger API documentation (🟡 HIGH)
- TD-4: Error handling documentation (🟡 MEDIUM)

🔮 **Phase 3+** (blocked until Phase 2 completes):
- TD-5: Rich form editors with nested object/array support
- TD-6: Bulk operations (multi-select, bulk delete, export)
- TD-7: Advanced filtering UI with visual builder
- TD-8: Relationship/foreign key dropdown selectors
- TD-9: God Panel (system admin dashboard)
- TD-10: Workflow automation UI
- TD-11: Advanced authentication (SSO, SAML, OAuth)
- TD-12: C++ DBAL daemon (production security mode)
- TD-13: Multi-source package system (NPM, git, http)

**See `/TECH_DEBT.md` for bot-actionable instructions on each task.**

---

## Technology Stack

### Frontend
| Technology | Version | Purpose |
|------------|---------|---------|
| **Next.js** | 16.1.1 | React framework with App Router + RSC |
| **React** | 19.2.3 | UI library |
| **TypeScript** | 5.9.3 | Type-safe JavaScript |
| **SASS** | 1.97.1 | Styling with SCSS modules |
| **esbuild** | 0.27.2 | Fast JavaScript/TypeScript compilation |
| **Zod** | 4.3.5 | Schema validation |
| **Vitest** | 4.0.16 | Unit testing framework |

### Backend & Database
| Technology | Version | Purpose |
|------------|---------|---------|
| **Prisma** | 7.2.0 | ORM and database toolkit |
| **PostgreSQL** | Latest | Production database |
| **SQLite** | via better-sqlite3 | Development database |
| **DBAL (TypeScript)** | Custom | Development database abstraction |
| **DBAL (C++)** | Custom | Production database abstraction |

### Infrastructure
| Technology | Version | Purpose |
|------------|---------|---------|
| **Docker** | Latest | Containerization |
| **Docker Compose** | Latest | Multi-container orchestration |
| **Nginx** | Latest | Reverse proxy and SSL termination |
| **Redis** | Latest | Caching layer |

### Development Tools
| Tool | Purpose |
|------|---------|
| **ESLint** | Code linting |
| **Prettier** | Code formatting |
| **Monaco Editor** | In-browser code editor |
| **Octokit** | GitHub API integration |

### C++ Services
| Service | Purpose | Status |
|---------|---------|--------|
| **DBAL Daemon** | Secure database access, JWT auth, event-driven workflows, 14 backends | ✅ Production |
| **Flask Auth** | JWT issuance, user registration/login, Python runner | ✅ Production |
| **Media Daemon** | Video/audio transcoding, radio streaming, TV channels | ✅ Functional |

---

## System Architecture

### High-Level Overview

```
┌─────────────┐
│   Browser   │
└──────┬──────┘
       │ HTTPS
┌──────▼──────┐     ┌───────────┐
│   Nginx     │────▶│   Redis   │ (Cache)
│ (SSL/Proxy) │     └───────────┘
└──────┬──────┘
       │
┌──────▼──────────┐     ┌──────────────┐
│  Next.js        │────▶│  DBAL        │
│  Frontend       │     │  (TS/C++)    │
│  (React 19 +    │     │              │
│   App Router)   │     └──────┬───────┘
└─────────────────┘            │
                               │
                        ┌──────▼────────┐
                        │  PostgreSQL   │
                        │  (Production) │
                        │  or SQLite    │
                        │  (Development)│
                        └───────────────┘

┌─────────────────┐     ┌──────────────┐
│  Media Daemon   │────▶│ Media Files  │
│  (C++)          │     │ (Storage)    │
└─────────────────┘     └──────────────┘
```

### Database Schema (9 Models)

1. **User** - User accounts with role-based permissions
2. **Credential** - Password hashes (separate for security)
3. **Session** - Active user sessions with expiry tracking
4. **PageConfig** - Route configurations (God panel routes)
5. **ComponentNode** - Component tree hierarchy
6. **ComponentConfig** - Component properties and styling
7. **Workflow** - Automated workflow definitions
8. **InstalledPackage** - Package installation and configuration
9. **PackageData** - Package-specific data storage

### Data Flow Architecture

```
1. User Request → Nginx → Next.js
2. Next.js → Check PageConfig (God panel routes)
3. If not found → Check InstalledPackage (default routes)
4. Load package from /packages/{packageId}/seed/
5. Parse JSON component definition
6. Generic renderer → Convert JSON to React
7. DBAL → Query data (with tenant isolation)
8. Render page → Send to browser
```

### Permission System (6 Levels)

| Level | Role | Capabilities |
|-------|------|--------------|
| **0** | Public | Unauthenticated access to public pages |
| **1** | User | Basic authenticated access |
| **2** | Moderator | Content moderation, user management |
| **3** | Admin | Package installation, configuration |
| **4** | God | Route configuration, schema editing |
| **5** | Supergod | System-wide configuration, all access |

### Package Architecture

```
packages/{packageId}/
├── seed/
│   ├── metadata.json         # Package info, version, dependencies
│   ├── components.json       # Component definitions (JSON)
│   ├── scripts/              # JSON scripts organized by function
│   │   ├── init/             # Initialization scripts
│   │   ├── actions/          # User-triggered actions
│   │   └── cron/             # Scheduled tasks
│   └── index.ts              # Exports packageSeed object
├── src/                      # Optional React components (TSX)
└── static_content/           # Assets (images, CSS, etc.)
```

### DBAL Architecture

**Purpose:** Language-agnostic database abstraction with credential isolation and event-driven workflows

**Production Implementation (C++ — shipped Mar 2026):**
- Drogon HTTP framework, 14 database backends
- JWT auth + JSON ACL (`/app/schemas/auth/auth.json`)
- Event-driven workflow engine (fires async on CRUD events, detached thread)
- Auto-seed on startup (`DBAL_SEED_ON_STARTUP=true` → `SeedLoaderAction`)
- All schemas pure JSON — yaml-cpp removed

**Event Flow (on user registration):**
```
POST /pastebin/pastebin/User
  └── handleCreate() → dispatchAsync("pastebin.User.created")
        └── detached thread → on_user_created.json
              ├── 7× dbal.uuid nodes (namespace + snippet IDs)
              ├── 1× dbal.timestamp
              ├── 2× dbal.entity.create → Namespace (Default, Examples)
              └── 5× dbal.entity.create → seed Snippets
```

**Key Features:**
- Credential isolation (users never see database URLs)
- Row-level security enforcement
- Multi-tenant query filtering (tenantId on every query)
- Declarative seed data (JSON files, idempotent, loaded at startup)
- JSON entity schemas as single source of truth (39 entities)

---

## Package Ecosystem

MetaBuilder includes **52 built-in packages** that provide ready-to-use functionality. All packages follow the same structure and can be installed, configured, and removed through the system.

### Core UI Packages (9)
Essential UI components and pages

| Package | Purpose | Status |
|---------|---------|--------|
| **ui_home** | Homepage component | ✅ Ready |
| **ui_login** | Login/authentication UI | ✅ Ready |
| **ui_header** | Site header component | ✅ Ready |
| **ui_footer** | Site footer component | ✅ Ready |
| **ui_auth** | Authentication flows | ✅ Ready |
| **ui_dialogs** | Modal dialog components | ✅ Ready |
| **ui_intro** | Introduction/onboarding | ✅ Ready |
| **ui_pages** | Generic page templates | ✅ Ready |
| **ui_permissions** | Permission management UI | ✅ Ready |

### Permission-Level UI (5)
UI packages for each permission level

| Package | Level | Purpose | Status |
|---------|-------|---------|--------|
| **ui_level2** | Moderator | Moderator dashboard | ✅ Ready |
| **ui_level3** | Admin | Admin dashboard | ✅ Ready |
| **ui_level4** | God | God panel UI | ✅ Ready |
| **ui_level5** | Supergod | Supergod controls | ✅ Ready |
| **ui_level6** | Reserved | Future use | ✅ Ready |

### Admin & Configuration (12)
System management and configuration tools

| Package | Purpose | Status |
|---------|---------|--------|
| **admin_dialog** | Admin modal dialogs | ✅ Ready |
| **config_summary** | System configuration viewer | ✅ Ready |
| **database_manager** | Database admin UI | ✅ Ready |
| **package_manager** | Package installation/removal | ✅ Ready |
| **package_validator** | Package validation tools | ✅ Ready |
| **route_manager** | Route configuration UI | ✅ Ready |
| **schema_editor** | Database schema editor | ✅ Ready |
| **theme_editor** | UI theme customization | ✅ Ready |
| **user_manager** | User management UI | ✅ Ready |
| **role_editor** | Role and permission editor | ✅ Ready |
| **smtp_config** | Email configuration | ✅ Ready |
| **workflow_editor** | Workflow builder UI | ✅ Ready |

### Development Tools (6)
Tools for developers and power users

| Package | Purpose | Status |
|---------|---------|--------|
| **code_editor** | In-browser code editor | ✅ Ready |
| **codegen_studio** | Code generation tools | ✅ Ready |
| **component_editor** | Visual component builder | ✅ Ready |
| **css_designer** | CSS design tools | ✅ Ready |
| **nerd_mode_ide** | Advanced IDE features | ✅ Ready |
| **screenshot_analyzer** | Screenshot analysis tools | ✅ Ready |

### Data & Content (5)
Data management and content tools

| Package | Purpose | Status |
|---------|---------|--------|
| **data_table** | Generic data table component | ✅ Ready |
| **form_builder** | Dynamic form builder | ✅ Ready |
| **dashboard** | Dashboard layouts | ✅ Ready |
| **audit_log** | System audit logging | ✅ Ready |
| **dropdown_manager** | Dropdown/select manager | ✅ Ready |

### Communication & Social (3)
Communication and social features

| Package | Purpose | Status |
|---------|---------|--------|
| **forum_forge** | Forum/discussion boards | ✅ Ready |
| **irc_webchat** | IRC web chat client | ✅ Ready |
| **social_hub** | Social features hub | ✅ Ready |

### Media & Streaming (3)
Media processing and streaming

| Package | Purpose | Status |
|---------|---------|--------|
| **media_center** | Media library UI | ✅ Ready |
| **stream_cast** | Live streaming tools | ✅ Ready |
| **arcade_lobby** | Game/arcade interface | ✅ Ready |

### Integrations & Tools (5)
Third-party integrations and utilities

| Package | Purpose | Status |
|---------|---------|--------|
| **github_tools** | GitHub integration | ✅ Ready |
| **dbal_demo** | DBAL demonstration | ✅ Ready |
| **json_script_example** | JSON script examples | ✅ Ready |
| **notification_center** | Notification system | ✅ Ready |
| **quick_guide** | Quick start guide | ✅ Ready |

### Utility (4)
Miscellaneous utilities

| Package | Purpose | Status |
|---------|---------|--------|
| **nav_menu** | Navigation menu component | ✅ Ready |
| **stats_grid** | Statistics dashboard | ✅ Ready |
| **testing** | Test utilities | ✅ Ready |
| **workflow_editor** | Workflow visual editor | ✅ Ready |

### Package Installation

All packages are installed by default in the system. They can be:
- Enabled/disabled per tenant via `InstalledPackage` table
- Configured with custom settings via the `config` JSON field
- Set as default routes using `defaultRoute` in config
- Overridden by God panel routes in `PageConfig` table

### Creating New Packages

See `docs/architecture/packages.md` for package development guide.

Basic structure:
```json
// packages/my_package/seed/metadata.json
{
  "name": "My Package",
  "version": "1.0.0",
  "description": "Package description",
  "author": "Your Name",
  "minLevel": 0,
  "dependencies": [],
  "exports": ["component1", "component2"]
}
```

---

## MVP Milestone ✨

**Achieved:** January 2026

The MVP represents the **minimum viable product** that demonstrates MetaBuilder's core value proposition: a fully data-driven platform with zero hardcoded routes or components.

### MVP Acceptance Criteria

All criteria met ✅

#### 1. Authentication & Authorization ✅
- [x] Session-based user authentication
- [x] Permission level checks (0-5 scale)
- [x] Auth requirement enforcement (redirect to login)
- [x] Access denied UI for insufficient permissions
- [x] Server-side getCurrentUser() function
- [x] Comprehensive test coverage (11 tests)

#### 2. Dynamic Package Loading ✅
- [x] Load packages from filesystem
- [x] Home component discovery (priority: 'home_page' > 'HomePage' > 'Home')
- [x] 404 handling for missing packages
- [x] Package metadata integration
- [x] Error handling and logging

#### 3. CRUD Operations ✅
- [x] Schema-driven entity list view
- [x] Entity detail view with field display
- [x] Entity create form (schema-generated)
- [x] Entity edit form (pre-populated)
- [x] API client utilities (placeholder implementation)
- [x] Error handling and user feedback

#### 4. Static Page Generation ✅
- [x] Database query for active pages
- [x] generateStaticParams() implementation
- [x] Next.js static export support
- [x] ISR (Incremental Static Regeneration) compatibility
- [x] Graceful build-time error handling

#### 5. Code Compilation ✅
- [x] esbuild integration
- [x] TypeScript/JavaScript compilation
- [x] Minification option
- [x] Source map generation
- [x] Error handling with source preservation
- [x] Comprehensive test coverage (9 tests)

### MVP Deliverables

**Code Changes:**
- ✅ 5 major features implemented
- ✅ 20 new tests added (100% passing)
- ✅ Zero breaking changes
- ✅ All TODO items from `docs/TODO_MVP_IMPLEMENTATION.md` completed

**Documentation:**
- ✅ Implementation summary (`docs/MVP_IMPLEMENTATION_SUMMARY.md`)
- ✅ Architecture documentation in README.md
- ✅ API documentation for new utilities
- ✅ Test documentation

**Quality Metrics:**
- ✅ TypeScript compilation: 0 errors
- ✅ ESLint: All new files pass
- ✅ Test pass rate: 97.9% (188/192)
- ✅ Code review: Approved

---

## Release History

### v0.1.0-alpha (January 2026) - MVP Release ✨
**Status:** Current

**Features:**
- Authentication & session management
- Dynamic package loading
- CRUD operations (schema-driven)
- Static page generation
- Code compilation (esbuild)

**Files Changed:**
- `frontends/nextjs/src/lib/auth/get-current-user.ts` (new)
- `frontends/nextjs/src/lib/auth/get-current-user.test.ts` (new)
- `frontends/nextjs/src/components/AccessDenied.tsx` (new)
- `frontends/nextjs/src/lib/entities/load-entity-schema.ts` (new)
- `frontends/nextjs/src/lib/entities/api-client.ts` (new)
- `frontends/nextjs/src/lib/compiler/index.ts` (enhanced)
- `frontends/nextjs/src/lib/compiler/index.test.ts` (new)
- `frontends/nextjs/src/app/page.tsx` (enhanced)
- `frontends/nextjs/src/app/[tenant]/[package]/page.tsx` (enhanced)
- `frontends/nextjs/src/app/[tenant]/[package]/[...slug]/page.tsx` (enhanced)
- `frontends/nextjs/src/app/ui/[[...slug]]/page.tsx` (enhanced)

**Dependencies Added:**
- `esbuild` - Fast JavaScript/TypeScript compiler

**Test Results:**
- New tests: 20
- Total tests: 192
- Pass rate: 97.9%

### v0.0.0 (Pre-MVP)
**Status:** Foundation

**Core Infrastructure:**
- Next.js 14 frontend setup
- Prisma + PostgreSQL database
- DBAL (TypeScript development + C++ production)
- Package system architecture
- Generic JSON component renderer
- Multi-tenancy support
- 6-level permission system foundation

---

## Roadmap Phases

### ✅ Phase 0: Foundation (Completed)
**Timeline:** Pre-2026
**Goal:** Establish core architecture

- [x] Next.js 14 with App Router
- [x] Prisma ORM + PostgreSQL
- [x] DBAL architecture (TypeScript + C++)
- [x] Package system foundation
- [x] Generic component renderer
- [x] Multi-tenant database schema
- [x] Permission level system (0-5)

### ✅ Phase 1: MVP (Completed - January 2026)
**Timeline:** January 2026
**Goal:** Minimum viable product with core features

- [x] User authentication & authorization
- [x] Session management
- [x] Permission checks with redirects
- [x] Dynamic package loading
- [x] CRUD operations (schema-driven)
- [x] Static page generation
- [x] Code compilation (esbuild)
- [x] Comprehensive testing

**Success Metrics:**
- ✅ All TODO items resolved
- ✅ Test coverage >80%
- ✅ Zero breaking changes
- ✅ Documentation complete

**🔄 Phase 2: Backend Integration (In Progress)**
**Timeline:** Q1 2026 (January - March)
**Goal:** Connect frontend to real backend APIs
**Status:** 🚀 90% Complete - Core APIs, Validation, Pagination, Filtering Implemented

**Priority: HIGH** ⭐

**✅ Completed (January 8, 2026):**
- API endpoints fully implemented in `/api/v1/[...slug]/route.ts`
- Session-based authentication middleware
- Multi-tenant access validation
- CRUD operations (list, read, create, update, delete)
- Custom package action support
- Standardized error responses
- TypeScript API client (api-client.ts) with all methods
- Retry utility with exponential backoff (38 tests)
- Pagination utilities - offset and cursor-based (35 tests)
- Filtering and sorting utilities (36 tests)
- Zod validation utilities for request/response validation (39 tests)
- Unit tests for API client (29 tests)
- Unit tests for API route structure (10 tests)
- E2E tests for CRUD operations (14 scenarios)
- **Total new utilities tests:** 148 tests
- **Overall test coverage:** 414/418 passing (99.0%)

#### Implementation Tasks

##### 2.1 API Endpoint Implementation ✅ COMPLETE
**Status:** ✅ All endpoints implemented (January 2026)

- [x] **GET /api/v1/{tenant}/{package}/{entity}** - List entities
  - [x] Pagination support (`page`, `limit` query params)
  - [x] Filtering support (`filter` query param with JSON)
  - [x] Sorting support (`sort` query param)
  - [x] Tenant isolation checks
  - [x] Response time logging
  - [x] Unit tests (10+ test cases)
  - [x] E2E tests (4 scenarios)

- [x] **GET /api/v1/{tenant}/{package}/{entity}/{id}** - Get single entity
  - [x] Entity ID validation
  - [x] Return 404 for non-existent entities
  - [x] Tenant isolation checks
  - [x] Unit tests (5+ test cases)
  - [x] E2E tests (2 scenarios)

- [x] **POST /api/v1/{tenant}/{package}/{entity}** - Create entity
  - [x] Route handler with POST method
  - [x] JSON body parsing and validation
  - [x] Return created entity with 201 status
  - [x] Handle validation errors with 400 status
  - [x] Tenant isolation
  - [x] Unit tests (5+ test cases)
  - [x] E2E tests (3 scenarios)

- [x] **PUT /api/v1/{tenant}/{package}/{entity}/{id}** - Update entity
  - [x] Route handler with PUT method
  - [x] JSON body parsing
  - [x] Support partial updates
  - [x] Return 404 for non-existent entities
  - [x] Return updated entity with 200 status
  - [x] Tenant isolation
  - [x] Unit tests (5+ test cases)
  - [x] E2E tests (3 scenarios)

- [x] **DELETE /api/v1/{tenant}/{package}/{entity}/{id}** - Delete entity
  - [x] Route handler with DELETE method
  - [x] Return 404 for non-existent entities
  - [x] Return 200 status on success
  - [x] Tenant isolation
  - [x] Unit tests (5+ test cases)
  - [x] E2E tests (2 scenarios)

##### 2.2 API Client Integration ✅ COMPLETE
**Status:** ✅ All methods implemented with retry logic (January 8, 2026)

- [x] **Update `api-client.ts`** - Fully functional implementation
  - [x] `listEntities()` with fetch calls and query params
  - [x] `getEntity()` with error handling
  - [x] `createEntity()` with JSON body
  - [x] `updateEntity()` with actual fetch calls and partial updates
  - [x] `deleteEntity()` with actual fetch calls and proper status codes
  - [x] Error handling (network errors, API errors)
  - [x] Request timeout handling
  - [x] Unit tests with parameterized scenarios (29 tests)
  - [x] Retry logic for transient failures (retry utility with exponential backoff)
  - [x] Comprehensive retry tests (38 tests)

##### 2.3 Request/Response Validation ✅ COMPLETE
**Status:** ✅ All validation utilities implemented (January 8, 2026)

- [x] **Zod Schema Generation**
  - [x] Create utility to generate Zod schemas from entity definitions
  - [x] Support all field types (string, number, boolean, date, enum, array, object, relation)
  - [x] Support validation rules (required, min, max, pattern, email, url, custom)
  - [x] Support nested objects and arrays
  - [x] Write tests for schema generation (39 test cases - exceeded target)

- [x] **Validation Middleware**
  - [x] Create validation middleware for API routes
  - [x] Validate request body against entity schema
  - [x] Return detailed validation errors with formatted messages
  - [x] Support custom validation messages
  - [x] Common schema patterns (email, uuid, phone, password, username)
  - [x] Write comprehensive tests for validation (39 tests total)

##### 2.4 Pagination Implementation ✅ COMPLETE
**Status:** ✅ All pagination components and utilities implemented (January 8, 2026)

- [x] **Pagination Utilities** ✅ COMPLETE
  - [x] Create pagination helper functions
  - [x] Support cursor-based pagination
  - [x] Support offset-based pagination
  - [x] Calculate total pages and items
  - [x] Return pagination metadata in responses
  - [x] Cursor encoding/decoding utilities
  - [x] Page number generation for UI
  - [x] Write tests for pagination (35 test cases - exceeded target)

- [x] **Frontend Pagination Components** ✅ COMPLETE
  - [x] Create pagination UI component (PaginationControls.tsx using fakemui)
  - [x] Add page navigation controls (first, last, prev, next buttons)
  - [x] Add items-per-page selector (ItemsPerPageSelector.tsx)
  - [x] Add pagination info display (PaginationInfo.tsx)
  - [x] Write unit tests for pagination components (25 tests)
  - [ ] Update list views to use pagination (pending integration)
  - [ ] Write E2E tests for pagination UI

##### 2.5 Filtering and Sorting ✅ COMPLETE
**Status:** ✅ All filtering and sorting utilities implemented (January 8, 2026)

- [x] **Filter Implementation** ✅ COMPLETE
  - [x] Support equality filters (`eq`, `ne`)
  - [x] Support comparison filters (`gt`, `gte`, `lt`, `lte`)
  - [x] Support array filters (`in`, `notIn`)
  - [x] Support text search filters (`contains`, `startsWith`, `endsWith`)
  - [x] Support null checks (`isNull`, `isNotNull`)
  - [x] Prisma query builder integration
  - [x] SQL injection prevention with field validation
  - [x] Write tests for filtering (36 test cases - exceeded target)

- [x] **Sort Implementation** ✅ COMPLETE
  - [x] Support single field sorting (`sort=field`)
  - [x] Support multi-field sorting (`sort=field1,-field2`)
  - [x] Support ascending/descending (`-` prefix for desc)
  - [x] Prisma orderBy integration
  - [x] Field name validation for security
  - [x] Write comprehensive tests for sorting (included in 36 tests)

##### 2.6 Authentication Middleware ✅ COMPLETE
**Status:** ✅ All authentication middleware implemented (January 8, 2026)

- [x] **API Authentication** ✅ COMPLETE
  - [x] Create auth middleware for API routes (auth-middleware.ts)
  - [x] Validate session tokens from cookies via getCurrentUser()
  - [x] Check user permission levels (0-5 scale)
  - [x] Return 401 for unauthenticated requests
  - [x] Return 403 for insufficient permissions
  - [x] Add auth bypass for public endpoints (allowPublic option)
  - [x] Support custom permission checks
  - [x] Provide requireAuth helper for simplified usage
  - [x] Write tests for auth middleware (21 test cases - exceeded target)

##### 2.7 Rate Limiting
**Target:** Week 5-6 of Q1 2026

- [ ] **Rate Limiter Implementation**
  - [ ] Install `@upstash/ratelimit` or similar
  - [ ] Configure rate limits per endpoint
  - [ ] Configure rate limits per user/tenant
  - [ ] Return 429 status when rate limit exceeded
  - [ ] Add rate limit headers to responses
  - [ ] Write tests for rate limiting (8+ test cases)

##### 2.8 Error Handling
**Target:** Ongoing throughout implementation

- [ ] **Standardized Error Responses**
  - [ ] Create error response format (code, message, details)
  - [ ] Handle validation errors (400)
  - [ ] Handle authentication errors (401)
  - [ ] Handle authorization errors (403)
  - [ ] Handle not found errors (404)
  - [ ] Handle rate limit errors (429)
  - [ ] Handle server errors (500)
  - [ ] Log all errors to error tracking service
  - [ ] Write tests for error handling (20+ test cases)

#### Testing Requirements

**Unit Tests:** Target 150+ new tests - ✅ **EXCEEDED (194 tests implemented)**
- API route handlers: 50 tests ✅ Complete
- API client functions: 29 tests ✅ Complete
- Retry utilities: 38 tests ✅ Complete
- Validation utilities: 39 tests ✅ Complete
- Pagination utilities: 35 tests ✅ Complete
- Filtering/sorting utilities: 36 tests ✅ Complete
- Pagination components: 25 tests ✅ Complete
- Auth middleware: 21 tests ✅ Complete
- Rate limiting: 8 tests 🔄 Pending
- Error handling: 20 tests 🔄 Pending

**Integration Tests:** Target 30+ new tests - 🔄 Partially Complete
- Full CRUD flows: 15 tests 🔄 Partially Complete
- Multi-tenant isolation: 5 tests 🔄 Partially Complete
- Permission-based access: 10 tests 🔄 Partially Complete

**E2E Tests:** Target 15+ new tests - 🔄 Partially Complete
- Complete CRUD user flows: 14 tests ✅ Complete
- Authentication flows: 3 tests 🔄 Pending
- Permission-based UI changes: 4 tests 🔄 Pending
- Pagination UI: 3 tests 🔄 Pending
- Filtering/sorting UI: 3 tests 🔄 Pending

#### Performance Benchmarks

| Endpoint | Target Response Time | Target Throughput |
|----------|---------------------|-------------------|
| GET (list) | <100ms (p50), <200ms (p95) | >1000 req/s |
| GET (single) | <50ms (p50), <100ms (p95) | >2000 req/s |
| POST (create) | <150ms (p50), <300ms (p95) | >500 req/s |
| PUT (update) | <150ms (p50), <300ms (p95) | >500 req/s |
| DELETE | <100ms (p50), <200ms (p95) | >1000 req/s |

#### Documentation Requirements

- [ ] OpenAPI/Swagger specification for all endpoints
- [ ] API authentication guide
- [ ] Rate limiting documentation
- [ ] Error response format documentation
- [ ] Pagination documentation
- [ ] Filtering and sorting guide
- [ ] Example API requests for all endpoints

**Success Metrics:**
- [ ] All CRUD operations functional (100% coverage)
- [ ] API tests passing (>95% pass rate)
- [ ] Performance benchmarks met (<200ms avg response p95)
- [ ] Zero security vulnerabilities in API layer
- [ ] API documentation complete (OpenAPI spec)

### 🔮 Phase 3: Enhanced CRUD (Planned)
**Timeline:** Q1-Q2 2026
**Goal:** Rich editing experience

**Priority: HIGH**

- [ ] RenderComponent integration for forms
  - [ ] Form field generation from schema
  - [ ] Field type support (text, number, date, select, etc.)
  - [ ] Nested object/array editing
  - [ ] File upload support
- [ ] Client-side form validation
  - [ ] Required field validation
  - [ ] Type validation
  - [ ] Custom validation rules from schema
  - [ ] Real-time validation feedback
- [ ] Advanced list features
  - [ ] Search/filter UI
  - [ ] Column sorting
  - [ ] Bulk operations (select, delete, export)
  - [ ] Customizable views (table, grid, list)
- [ ] Relationship handling
  - [ ] Foreign key dropdowns
  - [ ] Related entity displays
  - [ ] Many-to-many relationship UI

**Success Metrics:**
- [ ] Form validation: 100% schema coverage
- [ ] List operations: <100ms client-side filtering
- [ ] User satisfaction: Positive feedback from beta testers

### 🔮 Phase 4: God Panel (Planned)
**Timeline:** Q2 2026
**Goal:** Admin UI for system configuration

**Priority: MEDIUM**

- [ ] Route management UI
  - [ ] Add/edit/delete routes in PageConfig
  - [ ] Visual route priority editor
  - [ ] Route testing/preview
- [ ] Package management UI
  - [ ] Install/uninstall packages
  - [ ] Package configuration editor
  - [ ] Dependency visualization
- [ ] User management
  - [ ] Create/edit users
  - [ ] Role assignment
  - [ ] Permission testing
- [ ] Schema editor
  - [ ] Visual entity schema builder
  - [ ] Field type selector
  - [ ] Validation rule editor
- [ ] Component builder
  - [ ] Visual JSON component editor
  - [ ] Component preview
  - [ ] Component templates

**Success Metrics:**
- [ ] God users can manage routes without code
- [ ] Package installation: <2 minutes
- [ ] Schema changes: No manual database migrations

### 🔮 Phase 5: Advanced Features (Planned)
**Timeline:** Q2-Q3 2026
**Goal:** Production-ready enhancements

**Priority: MEDIUM**

- [ ] **Search & Discovery**
  - [ ] Full-text search across entities
  - [ ] Global search UI
  - [ ] Search result ranking
  - [ ] Search filters

- [ ] **Caching & Performance**
  - [ ] Redis integration
  - [ ] Query result caching
  - [ ] Component render caching
  - [ ] CDN support for static assets

- [ ] **Audit & Logging**
  - [ ] Change history tracking
  - [ ] User activity logs
  - [ ] System audit trail
  - [ ] Log viewer UI

- [ ] **Webhooks & Events**
  - [ ] Entity change webhooks
  - [ ] Custom event triggers
  - [ ] Webhook management UI
  - [ ] Event replay capability

- [ ] **Import/Export**
  - [ ] CSV import/export
  - [ ] JSON bulk operations
  - [ ] Schema migration tools
  - [ ] Data backup/restore

**Success Metrics:**
- [ ] Cache hit rate: >80%
- [ ] Search response time: <100ms
- [ ] Audit coverage: 100% of mutations

### 🔮 Phase 6: Advanced Auth (Planned)
**Timeline:** Q3 2026
**Goal:** Enterprise-grade authentication

**Priority: MEDIUM**

- [ ] Multi-factor authentication (MFA)
  - [ ] TOTP support (Google Authenticator)
  - [ ] SMS verification
  - [ ] Backup codes
- [ ] OAuth integration
  - [ ] Google OAuth
  - [ ] GitHub OAuth
  - [ ] Microsoft Azure AD
- [ ] Session enhancements
  - [ ] "Remember Me" functionality
  - [ ] Session refresh tokens
  - [ ] Device management
  - [ ] Concurrent session control
- [ ] Security features
  - [ ] Brute force protection
  - [ ] IP whitelisting
  - [ ] Anomaly detection
  - [ ] Security audit logs

**Success Metrics:**
- [ ] MFA adoption rate: >50% of users
- [ ] OAuth login success rate: >95%
- [ ] Zero security incidents

### 🔮 Phase 7: C++ DBAL Production (Planned)
**Timeline:** Q3-Q4 2026
**Goal:** Production-ready C++ daemon

**Priority: MEDIUM**

- [ ] C++ implementation conformance
  - [ ] All TypeScript DBAL features implemented
  - [ ] Conformance test suite: 100% passing
- [ ] Performance optimization
  - [ ] Connection pooling
  - [ ] Query optimization
  - [ ] Memory management
- [ ] Security hardening
  - [ ] Credential isolation (env vars only)
  - [ ] Row-level security enforcement
  - [ ] SQL injection prevention
- [ ] Monitoring & observability
  - [ ] Metrics endpoint
  - [ ] Health checks
  - [ ] Performance profiling

**Success Metrics:**
- [ ] Performance: 10x faster than TypeScript DBAL
- [ ] Memory: <100MB resident
- [ ] Security: Zero credential exposure

### 🔮 Phase 8: Multi-Source Packages (Planned)
**Timeline:** Q4 2026
**Goal:** Package ecosystem

**Priority: LOW**

- [ ] Remote package repositories
  - [ ] Package index API
  - [ ] Remote package loading
  - [ ] Version management
- [ ] Package marketplace
  - [ ] Package discovery UI
  - [ ] Package ratings/reviews
  - [ ] Package documentation
- [ ] Conflict resolution
  - [ ] Priority-based resolution
  - [ ] Latest-version resolution
  - [ ] Local-first resolution
  - [ ] Custom resolution strategies

**Success Metrics:**
- [ ] Package ecosystem: >20 public packages
- [ ] Installation time: <30 seconds per package
- [ ] Conflict resolution: 0 manual interventions

---

## Feature Status Matrix

| Feature | Status | Phase | Priority | Notes |
|---------|--------|-------|----------|-------|
| **Core Platform** |
| Next.js Frontend | ✅ Complete | 0 | - | App Router with RSC |
| PostgreSQL Database | ✅ Complete | 0 | - | Prisma ORM |
| DBAL (TypeScript) | ✅ Complete | 0 | - | Development mode |
| DBAL (C++) | 🔨 In Progress | 7 | Medium | Production daemon |
| Multi-tenancy | ✅ Complete | 0 | - | Tenant isolation |
| Package System | ✅ Complete | 0 | - | JSON packages |
| Component Renderer | ✅ Complete | 0 | - | JSON → React |
| **Authentication** |
| Session Management | ✅ Complete | 1 | - | Cookie-based |
| getCurrentUser() | ✅ Complete | 1 | - | Server function |
| Permission Checks | ✅ Complete | 1 | - | 6-level system |
| Access Denied UI | ✅ Complete | 1 | - | User-friendly |
| OAuth Integration | 📋 Planned | 6 | Medium | Google, GitHub, Azure |
| Multi-Factor Auth | 📋 Planned | 6 | Medium | TOTP, SMS |
| Session Refresh | 📋 Planned | 6 | Medium | Auto-refresh tokens |
| **CRUD Operations** |
| Entity List View | ✅ Complete | 1 | - | Schema-driven |
| Entity Detail View | ✅ Complete | 1 | - | All fields |
| Entity Create Form | ✅ Complete | 1 | - | Schema-generated |
| Entity Edit Form | ✅ Complete | 1 | - | Pre-populated |
| API Client (Placeholder) | ✅ Complete | 1 | - | Ready for backend |
| API Backend | 📋 Planned | 2 | High | Real endpoints |
| RenderComponent Forms | 📋 Planned | 3 | High | Enhanced UX |
| Client-side Validation | 📋 Planned | 3 | High | Real-time feedback |
| Pagination | 📋 Planned | 2 | High | List views |
| Filtering/Sorting | 📋 Planned | 2 | High | List views |
| Bulk Operations | 📋 Planned | 3 | Medium | Multi-select |
| **Routing** |
| Priority Routing | ✅ Complete | 0 | - | PageConfig + Packages |
| Dynamic Package Routes | ✅ Complete | 1 | - | Filesystem loading |
| Static Generation | ✅ Complete | 1 | - | generateStaticParams |
| ISR Support | ✅ Complete | 1 | - | Revalidation |
| Route Management UI | 📋 Planned | 4 | Medium | God panel |
| **Development Tools** |
| Compiler (esbuild) | ✅ Complete | 1 | - | TS/JS compilation |
| Minification | ✅ Complete | 1 | - | Optional |
| Source Maps | ✅ Complete | 1 | - | Debugging support |
| Component Preview | 📋 Planned | 4 | Low | Live preview |
| Schema Editor | 📋 Planned | 4 | Medium | Visual builder |
| **Performance** |
| Redis Caching | 📋 Planned | 5 | Medium | Query results |
| CDN Support | 📋 Planned | 5 | Medium | Static assets |
| Component Caching | 📋 Planned | 5 | Low | Render cache |
| **Data Management** |
| CSV Import/Export | 📋 Planned | 5 | Low | Bulk operations |
| JSON Bulk Ops | 📋 Planned | 5 | Low | API-driven |
| Backup/Restore | 📋 Planned | 5 | Medium | System-wide |
| Change History | 📋 Planned | 5 | Medium | Audit trail |
| **Search** |
| Full-Text Search | 📋 Planned | 5 | Medium | PostgreSQL FTS |
| Global Search UI | 📋 Planned | 5 | Medium | Unified interface |
| Search Filters | 📋 Planned | 5 | Low | Advanced queries |
| **Integration** |
| Webhooks | 📋 Planned | 5 | Low | Entity changes |
| Event System | 📋 Planned | 5 | Low | Custom triggers |
| Package Marketplace | 📋 Planned | 8 | Low | Public packages |
| Remote Packages | 📋 Planned | 8 | Low | Multi-source |

**Legend:**
- ✅ Complete - Implemented and tested
- 🔨 In Progress - Currently being developed
- 📋 Planned - On the roadmap, not started
- ⏸️ On Hold - Deprioritized
- ❌ Cancelled - No longer planned

---


## Testing Strategy & Best Practices

MetaBuilder follows a comprehensive testing strategy to ensure code quality, reliability, and maintainability.

### Testing Philosophy

We emphasize **Test-Driven Development (TDD)** as a core practice:

1. **Write tests first** - Design APIs through tests
2. **Fast feedback** - Tests provide immediate confidence
3. **High coverage** - Target >80% code coverage
4. **Maintainable tests** - Tests are as important as production code
5. **Realistic scenarios** - Tests reflect real-world usage

### Testing Pyramid

```
              /\
             /  \
            /E2E \       Few, Slow, Expensive (15-30 tests)
           /------\      Critical user flows
          /        \
         /Integration\   More, Medium Speed (50-100 tests)
        /------------\   Components working together
       /              \
      /   Unit Tests   \  Many, Fast, Cheap (200-500 tests)
     /------------------\ Individual functions
```

### Target Test Distribution

| Test Type | Current | Target | Coverage Focus |
|-----------|---------|--------|----------------|
| **Unit Tests** | 220 | 500+ | Individual functions, utilities |
| **Integration Tests** | 30 | 100+ | API endpoints, database operations |
| **E2E Tests** | 8 | 30+ | Critical user journeys |
| **Total** | 258 | 630+ | Overall system |

### Critical Test Scenarios

#### Unit Test Scenarios (Priority Order)

**API Layer (High Priority)**
1. **CRUD Operations** (50 tests)
   - List entities with pagination
   - List entities with filters
   - List entities with sorting
   - Get single entity by ID
   - Get non-existent entity (404)
   - Create entity with valid data
   - Create entity with invalid data (validation)
   - Update entity with valid data
   - Update entity with partial data
   - Update non-existent entity (404)
   - Delete entity by ID
   - Delete non-existent entity (404)

2. **Authentication & Authorization** (30 tests)
   - Valid session token
   - Invalid session token (401)
   - Expired session token (401)
   - Missing session token (401)
   - Insufficient permissions (403)
   - Permission level checks (0-5)
   - Tenant isolation validation
   - Cross-tenant access prevention

3. **Validation** (40 tests)
   - Required field validation
   - Type validation (string, number, boolean, date)
   - Min/max length validation
   - Min/max value validation
   - Pattern/regex validation
   - Enum validation
   - Nested object validation
   - Array validation
   - Custom validation rules

4. **Pagination** (20 tests)
   - Offset-based pagination
   - Cursor-based pagination
   - Page size limits
   - Total count calculation
   - Empty result sets
   - Single page results
   - Multiple page results
   - Invalid pagination params

5. **Filtering** (30 tests)
   - Equality filters
   - Comparison filters (gt, gte, lt, lte)
   - Array filters (in, notIn)
   - Text search filters (contains, startsWith, endsWith)
   - Boolean filters
   - Null/undefined filters
   - Date range filters
   - Nested field filters
   - Multiple filter combinations

6. **Sorting** (15 tests)
   - Single field ascending
   - Single field descending
   - Multiple field sorting
   - Nested field sorting
   - Invalid sort fields
   - Case-insensitive sorting

7. **Rate Limiting** (15 tests)
   - Within rate limit
   - Exceeding rate limit (429)
   - Rate limit headers
   - Different rate limits per endpoint
   - Different rate limits per user
   - Rate limit reset

**Utility Functions (Medium Priority)**
8. **Schema Generation** (20 tests)
   - Generate Zod schema from entity definition
   - All field type support
   - Validation rule support
   - Nested object schema
   - Array schema
   - Optional/required fields

9. **Database Helpers** (30 tests)
   - Query building
   - Transaction management
   - Error handling
   - Tenant filtering
   - Soft delete support

10. **Component Rendering** (20 tests)
    - JSON to React conversion
    - Component props mapping
    - Nested component rendering
    - Error component rendering

#### Integration Test Scenarios (Priority Order)

**API Integration (High Priority)**
1. **Complete CRUD Flow** (15 tests)
   - Create → Read → Update → Delete flow
   - List empty collection
   - List with data
   - Pagination through large datasets
   - Filter and sort combinations

2. **Multi-Tenant Isolation** (10 tests)
   - Create entity in tenant A
   - List entities in tenant A (only shows A's data)
   - List entities in tenant B (only shows B's data)
   - Attempt cross-tenant access (blocked)
   - Tenant-specific filtering

3. **Permission-Based Access** (15 tests)
   - Public user (level 0) access
   - Authenticated user (level 1) access
   - Moderator (level 2) access
   - Admin (level 3) access
   - God (level 4) access
   - Supergod (level 5) access
   - Permission escalation prevention

4. **Authentication Flows** (10 tests)
   - Login → Create session → Make authenticated request
   - Logout → Session invalidated → Request fails
   - Session expiry → Request fails
   - Session refresh → Continued access

5. **Error Scenarios** (10 tests)
   - Network timeout handling
   - Database connection failure
   - Invalid JSON in request
   - Large payload handling
   - Concurrent request handling

**Database Integration (Medium Priority)**
6. **Transaction Management** (10 tests)
   - Successful transaction commit
   - Transaction rollback on error
   - Nested transaction support
   - Concurrent transaction isolation

7. **Data Integrity** (10 tests)
   - Foreign key constraints
   - Unique constraints
   - Not-null constraints
   - Check constraints
   - Cascade delete behavior

#### E2E Test Scenarios (Priority Order)

**Critical User Flows (High Priority)**
1. **Authentication Journey** (4 tests)
   - Landing page → Sign in → Dashboard
   - Landing page → Register → Verify email → Dashboard
   - Dashboard → Logout → Landing page
   - Forgot password → Reset → Login

2. **CRUD Operations Journey** (8 tests)
   - Navigate to entity list → View list
   - Click "Create" → Fill form → Submit → View detail page
   - Detail page → Click "Edit" → Update form → Submit → View updated detail
   - Detail page → Click "Delete" → Confirm → Return to list
   - List page → Use pagination → Navigate pages
   - List page → Apply filters → See filtered results
   - List page → Apply sorting → See sorted results
   - List page → Search → See search results

3. **Permission-Based UI** (6 tests)
   - Login as public user → See public pages only
   - Login as user → See user pages
   - Login as admin → See admin pages
   - Login as god → See god panel
   - Attempt to access higher-level page → See access denied
   - Permission level indicator in UI

4. **Package Rendering** (4 tests)
   - Navigate to package home page → See rendered components
   - Navigate to package sub-route → See rendered components
   - Navigate to non-existent package → See 404
   - Navigate to disabled package → See access denied

5. **Form Validation** (4 tests)
   - Submit empty required field → See validation error
   - Submit invalid format → See format error
   - Submit valid data → Success message
   - Server-side validation error → Display error to user

6. **Multi-Tenant Scenarios** (2 tests)
   - Login to tenant A → See tenant A data
   - Login to tenant B → See tenant B data (different)

7. **Error Handling** (2 tests)
   - Network error during operation → User-friendly error message
   - Server error (500) → Error page with retry option

### Test Performance Targets

| Test Type | Target Execution Time | Parallelization |
|-----------|----------------------|-----------------|
| Unit test (single) | <100ms | Yes (max CPU cores) |
| Unit test suite | <30s | Yes |
| Integration test (single) | <1s | Yes (database per test) |
| Integration test suite | <2 minutes | Yes |
| E2E test (single) | <30s | Yes (browser per test) |
| E2E test suite | <10 minutes | Yes |
| Full test suite (CI) | <15 minutes | Yes |

### Test Data Management

**Unit Tests**
- Use mocked data (no database)
- Use factories for test data generation
- Keep test data minimal and focused

**Integration Tests**
- Use test database (separate from dev/prod)
- Reset database between tests
- Use database transactions (rollback after test)
- Use seed data for common scenarios

**E2E Tests**
- Use separate test environment
- Use isolated test accounts
- Clean up test data after suite
- Use realistic but anonymized data

### Test Maintenance Best Practices

1. **Keep Tests Fast**
   - Mock external services
   - Use in-memory databases where possible
   - Parallelize test execution
   - Skip slow tests in watch mode

2. **Keep Tests Isolated**
   - Each test is independent
   - No shared state between tests
   - Clean up after each test
   - Don't rely on execution order

3. **Keep Tests Readable**
   - Descriptive test names
   - Clear arrange-act-assert sections
   - Meaningful variable names
   - Document complex scenarios

4. **Keep Tests Maintainable**
   - Use test utilities and helpers
   - Avoid test code duplication
   - Update tests when requirements change
   - Remove obsolete tests

### Test Coverage

| Component | Unit Tests | Integration Tests | E2E Tests |
|-----------|-----------|-------------------|-----------|
| **Utilities** | >90% | - | - |
| **Database Layer** | >85% | >70% | - |
| **API Routes** | >80% | >75% | Critical paths |
| **React Components** | >75% | - | - |
| **User Flows** | - | - | All critical paths |
| **Overall** | >80% | >70% | 100% critical |

### Test-Driven Development (TDD)

**Red-Green-Refactor Cycle:**

```
1. 🔴 RED: Write a failing test
   ↓
2. 🟢 GREEN: Write minimal code to pass
   ↓
3. 🔵 REFACTOR: Improve code while keeping tests green
   ↓
4. ♻️  REPEAT: Move to next feature
```

**Example TDD Workflow:**
```typescript
// Step 1: RED - Write failing test
describe('validatePassword', () => {
  it.each([
    { password: 'short', expected: { valid: false, error: 'Too short' } },
    { password: 'validpass123', expected: { valid: true, error: null } },
  ])('should validate "$password"', ({ password, expected }) => {
    expect(validatePassword(password)).toEqual(expected)
  })
})

// Step 2: GREEN - Implement to pass tests
export function validatePassword(password: string) {
  if (password.length < 8) {
    return { valid: false, error: 'Too short' }
  }
  return { valid: true, error: null }
}

// Step 3: REFACTOR - Improve while keeping tests green
```

### Testing Tools

| Tool | Purpose | Usage |
|------|---------|-------|
| **Vitest** | Unit & integration testing | `npm test` |
| **Playwright** | E2E browser testing | `npx playwright test` |
| **Testing Library** | React component testing | Integrated with Vitest |
| **Prisma** | Database testing | Test database utilities |

### Unit Testing Best Practices

**✅ Use Parameterized Tests:**
```typescript
it.each([
  { input: 'hello', expected: 'HELLO' },
  { input: 'world', expected: 'WORLD' },
])('should uppercase $input', ({ input, expected }) => {
  expect(uppercase(input)).toBe(expected)
})
```

**✅ Follow AAA Pattern:**
```typescript
it('should calculate total', () => {
  // ARRANGE
  const items = [{ price: 10 }, { price: 20 }]
  // ACT
  const total = calculateTotal(items)
  // ASSERT
  expect(total).toBe(30)
})
```

**✅ Mock External Dependencies:**
```typescript
vi.mock('@/lib/database', () => ({
  Database: {
    getUser: vi.fn().mockResolvedValue({ id: '1', name: 'Test' })
  }
}))
```

### E2E Testing with Playwright

**Configuration:** `e2e/playwright.config.ts`

**Key Features:**
- Cross-browser testing (Chromium, Firefox, WebKit)
- Auto-waiting for elements
- Screenshots and videos on failure
- Trace viewer for debugging
- Page Object Model support

**Example E2E Test:**
```typescript
import { test, expect } from '@playwright/test'

test('should login successfully', async ({ page }) => {
  await page.goto('/login')
  await page.fill('input[name="email"]', 'admin@example.com')
  await page.fill('input[name="password"]', 'password123')
  await page.click('button[type="submit"]')

  await expect(page).toHaveURL(/\/dashboard/)
  await expect(page.locator('text=Welcome')).toBeVisible()
})
```

### Running Tests

```bash
# Unit tests
npm test                    # Run all unit tests
npm run test:watch          # Watch mode
npm run test:coverage       # With coverage report

# E2E tests
npx playwright test         # Run all E2E tests
npx playwright test --ui    # Interactive UI mode
npx playwright test --debug # Debug mode
npx playwright show-report  # View HTML report

# CI
npm run test:ci             # All tests for CI
```

### Test Maintenance

**Keep Tests Fast:**
- Unit tests: <1s each
- Integration tests: <5s each
- E2E tests: <30s each

**Keep Tests Isolated:**
- Each test is independent
- Use beforeEach/afterEach for setup/cleanup
- Don't rely on test execution order

**Keep Tests Readable:**
- Descriptive test names
- Clear arrange-act-assert sections
- Meaningful variable names
- Document complex scenarios

### CI/CD Integration

Tests run automatically on:
- Every push to main/develop branches
- Every pull request
- Pre-deployment checks

**GitHub Actions:**
- Unit tests with coverage reporting
- E2E tests across multiple browsers
- Automatic artifact upload on failure
- Retry failed tests (2x in CI)

### Comprehensive Testing Guide

For detailed testing documentation, examples, and best practices, see:
**[docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md)**

This comprehensive guide includes:
- Complete TDD workflows with examples
- Advanced Playwright patterns (POM, fixtures)
- Integration testing strategies
- Troubleshooting common issues
- CI/CD configuration examples

---

## Development Best Practices

### Core Principles

1. **One Lambda Per File** - Functions in separate files, classes only as containers
2. **Write Tests First (TDD)** - Red-Green-Refactor cycle
3. **TypeScript Strict Mode** - No `any` types, explicit types everywhere
4. **Follow DRY** - Don't Repeat Yourself, extract common logic
5. **Pure Functions** - Make functions pure when possible

### Code Quality

**✅ Good Practices:**
```typescript
// Explicit types
function getUser(id: string): Promise<User> {
  return Database.getUser(id)
}

// Pure function
function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0)
}

// One function per file
// src/lib/users/get-user-by-id.ts
export async function getUserById(id: string): Promise<User> {
  return Database.getUser(id)
}
```

**❌ Bad Practices:**
```typescript
// Using 'any'
function getUser(id: any): Promise<any> {
  return Database.getUser(id)
}

// Multiple unrelated functions
export function getUserById(id) { ... }
export function formatUserName(user) { ... }
export function validateEmail(email) { ... }
```

### Development Workflow

```
1. Planning → Review requirements, check docs
2. Design → Data models, API contracts, interfaces
3. TDD → Write tests, implement, refactor
4. Integration → Run tests, lint, type check
5. Review → Self-review, create PR, address feedback
6. Deploy → Staging → E2E tests → Production
```

### Git Workflow

```bash
# Feature branch
git checkout -b feature/user-auth

# Commit frequently
git commit -m "feat: add login form"
git commit -m "test: add validation tests"

# Push and create PR
git push origin feature/user-auth
```

### Code Review Checklist

**Before PR:**
- [ ] All tests pass
- [ ] Lint and type check pass
- [ ] New code has tests (>80% coverage)
- [ ] Self-reviewed changes
- [ ] Documentation updated

**Reviewer checks:**
- [ ] Code follows conventions
- [ ] No security vulnerabilities
- [ ] Performance considered
- [ ] Accessible (a11y)
- [ ] Mobile responsive

### Security Best Practices

**✅ Input Validation:**
```typescript
import { z } from 'zod'

const userSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export function createUser(input: unknown) {
  const validated = userSchema.parse(input)
  return Database.createUser(validated)
}
```

**✅ SQL Injection Prevention:**
```typescript
// Use Prisma's parameterized queries
const users = await prisma.user.findMany({
  where: { email: userEmail },
})
```

**✅ XSS Prevention:**
```typescript
// React automatically escapes
<div>{user.name}</div>

// Sanitize HTML when needed
import DOMPurify from 'dompurify'
<div dangerouslySetInnerHTML={{
  __html: DOMPurify.sanitize(user.bio)
}} />
```

### Performance Best Practices

**✅ Database Queries:**
```typescript
// Query only needed fields
const users = await Database.getUsers({
  select: ['id', 'name', 'email'],
  where: { active: true },
  limit: 10,
})
```

**✅ React Performance:**
```typescript
import { useMemo, useCallback } from 'react'

function UserList({ users, onSelect }) {
  const sortedUsers = useMemo(
    () => users.sort((a, b) => a.name.localeCompare(b.name)),
    [users]
  )

  const handleSelect = useCallback(
    (userId) => onSelect(userId),
    [onSelect]
  )

  return <List items={sortedUsers} onSelect={handleSelect} />
}
```

### Accessibility (a11y)

```typescript
// ✅ Accessible components
<button
  type="button"
  aria-label="Delete user"
  onClick={handleDelete}
>
  <DeleteIcon aria-hidden="true" />
  Delete
</button>

<form onSubmit={handleSubmit}>
  <label htmlFor="email">Email</label>
  <input
    id="email"
    type="email"
    required
    aria-required="true"
    aria-describedby="email-error"
  />
  <span id="email-error" role="alert">
    {emailError}
  </span>
</form>
```

### Development Tools

| Tool | Purpose | Command |
|------|---------|---------|
| **ESLint** | Code linting | `npm run lint:fix` |
| **Prettier** | Code formatting | `npm run format` |
| **TypeScript** | Type checking | `npm run typecheck` |
| **Prisma** | Database ORM | `npm run db:generate` |
| **Vitest** | Unit testing | `npm test` |
| **Playwright** | E2E testing | `npx playwright test` |

## Known Issues & Technical Debt

### Active Issues

#### Test Failures (4 tests)
**Status:** 🔍 Investigating
**Impact:** Low - Pre-existing failures unrelated to MVP work
**Tests:** 188/192 passing (97.9%)

These 4 failing tests existed before MVP implementation and do not affect core functionality. They are scheduled for investigation in Phase 2.

#### TLA+ Specification Error
**File:** `spec/metabuilder.tla`
**Status:** 📋 Documented
**Impact:** Low - Affects formal verification only, not runtime

**Issue:** Syntax error at line 323 in `PackageConsistency` invariant
```tla
\* Current (incorrect)
PackageConsistency ==
    \A t \in Tenants, p \in installedPackages[t]:
        packageStates[p] \in {"installed", "disabled", "installing"}

\* Suggested fix
PackageConsistency ==
    \A t \in Tenants:
        \A p \in installedPackages[t]:
            packageStates[p] \in {"installed", "disabled", "installing"}
```

**Note:** New specifications (workflow_system.tla, collaboration.tla, integrations.tla) all pass validation.

### Technical Debt

#### Codebase Composition (Current State)

**Overview**: MetaBuilder is a **well-architected, data-driven system** with approximately **2,047 files**:

```
TypeScript/TSX:    1,487 files (73%)
  ├── DBAL              282 files (14%)
  ├── FakeMUI           514 files (25%)
  ├── NextJS Frontend   491 files (24%)
  ├── E2E Tests         16 files (1%)
  └── Deprecated        119 files (6%)

JSON/YAML:           560 files (27%)
  ├── Packages         376 files (18%)
  ├── Schemas          76 files (4%)
  └── Seed Config      5 files (<1%)
```

**Data-Driven Ratio**: 27% (could reach 35-40% with recommended refactoring)

#### High Priority (Quick Wins - ~2-3 hours)

1. **Delete `/old` Directory** (119 files)
   - Pre-Next.js SPA implementation, completely superseded
   - Contains Vite, React 19, Radix UI components
   - Pure cruft from Spark-based era
   - **Action**: Delete `/old/` entirely
   - **Impact**: Reduces confusion, removes maintenance burden

2. **Delete Backup Files** (4 files)
   - `/dbal/development/src/core/foundation/tenant-context.ts.backup`
   - `/dbal/development/src/core/client/client.ts.backup`
   - `/dbal/development/src/bridges/websocket-bridge.ts.backup`
   - `/dbal/development/src/adapters/acl-adapter.ts.backup`
   - **Action**: Delete all `.backup` files
   - **Impact**: Clean code footprint, no functionality impact (Git history preserved)

3. **Migrate Seed Data from TypeScript to YAML**
   - **Current**: `/frontends/nextjs/src/lib/db/database-admin/seed-default-data/*.ts` (5 files, ~150 lines)
     - `seed-users.ts` - Hardcoded default users
     - `seed-app-config.ts` - App configuration
     - `seed-css-categories.ts` - CSS categories
     - `seed-dropdown-configs.ts` - Dropdown definitions
   - **Better**: `/seed/database/*.yaml` loaded via DBAL orchestration
   - **Status**: Current approach bypasses DBAL, should use seed system
   - **Effort**: 4-5 hours
   - **Impact**: 100% YAML-based seed system, better bootstrapping

#### Medium Priority (~4-5 hours)

4. **Eliminate Adapter Code Duplication**
   - **Current**: Frontend duplicates adapter logic at `/frontends/nextjs/src/lib/dbal-client/adapter/` (355 lines)
     - `PrismaAdapter` class
     - `DevelopmentAdapter` class
   - **Problem**: Two implementations of same adapter, inconsistent with DBAL ownership
   - **Better**: Frontend should only use DBAL client, not re-implement adapters
   - **Effort**: 2-3 hours
   - **Impact**: Single source of truth for database logic

5. **Migrate Role/Permission Constants to Seed Data**
   - **Current**: Hardcoded in `/frontends/nextjs/src/lib/constants.ts`
     ```typescript
     export const ROLE_LEVELS = {
       public: 0, user: 1, moderator: 2, admin: 3, god: 4, supergod: 5
     }
     ```
   - **Better**: `/schemas/permissions_schema.json` or `/seed/database/permissions.yaml`
   - **Effort**: 2-3 hours
   - **Impact**: All roles database-driven, dynamic permission system

6. **Migrate Environment Configuration**
   - **Current**: Hardcoded defaults in `constants.ts` (`ENV_DEFAULTS`, `TIMEOUTS`)
   - **Better**: `/seed/config/app-config.yaml` loaded at startup
   - **Effort**: 2-3 hours
   - **Impact**: All configuration declarative, environment-specific

#### Low Priority (~2-3 hours)

7. **Remove Experimental Code**
   - Verify `/frontends/nextjs/src/lib/db/database-admin/seed-default-data/css/categories/experimental.ts`
   - Check usage, delete if unused
   - **Effort**: 1 hour
   - **Impact**: Minimal

8. **Complete TODO Items**
   - Review `/docs/TODO_MVP_IMPLEMENTATION.md`
   - Compiler implementation (`/lib/compiler/index.ts` - marked TODO, unimplemented)
   - **Status**: Affects 2-3 files
   - **Effort**: Variable depending on scope

#### Architecture Strengths (Keep As-Is)

✅ **Infrastructure (TypeScript) - 14% of codebase**
- DBAL (282 files) - Type-safe database abstraction, multi-adapter support
- FakeMUI (514 files) - Consistent UI components across web/QML
- NextJS Frontend (491 files) - Server-side rendering, API routes

✅ **Data-Driven Design (JSON/YAML) - 27% of codebase**
- 18 interconnected schemas in `/schemas/` - Single source of truth
- 376 component definitions in `/packages/*/components/ui.json` - 100% declarative
- Package system - Fully self-contained with seed data

#### Migration Path to 35-40% Data-Driven

| Task | Current % | Target % | Effort | Impact |
|------|-----------|----------|--------|--------|
| Remove cruft (old/, backups) | 73% TS | 70% TS | 1h | High |
| Migrate seed data YAML | 73% TS | 68% TS | 4-5h | Medium |
| Eliminate adapter duplication | 73% TS | 72% TS | 2-3h | Medium |
| Migrate constants/config | 73% TS | 70% TS | 2-3h | Low |
| **Total (recommended)** | **73%** | **~35-40%** | **9-16h** | **High** |

**Recommended Timeline**: Address high-priority items first (Phase 1: 1-2 weeks), then medium-priority refactoring (Phase 2: 4-6 weeks)

### Deprecated Features

None - This is a new project with no deprecated features

### Security Audit Status

✅ **Session Management:** Secure cookie-based sessions with httpOnly flag
✅ **Password Storage:** SHA-512 hashing (see `password-utils.ts`)
✅ **SQL Injection:** Protected by Prisma ORM
✅ **CSRF:** Next.js built-in protection
✅ **XSS:** React automatic escaping
⏸️ **Rate Limiting:** Planned for Phase 5
⏸️ **MFA:** Planned for Phase 6
⏸️ **OAuth:** Planned for Phase 6

### Migration Notes

#### From 0.0.0 (Pre-MVP) to 0.1.0 (MVP)
No breaking changes - all changes were additive or fulfilled TODO placeholders.

**New Dependencies:**
- `esbuild` (^0.27.2) - Added for compiler functionality

**Database Changes:**
None - Used existing schema

**Configuration Changes:**
None - All configuration remains backward compatible

---

## Technical Debt & Prioritization Roadmap

Based on comprehensive codebase audit (January 2026), MetaBuilder has **well-managed technical debt** with a clear refactoring path to increase data-driven architecture from 27% to 35-40%.

### Executive Summary

**Current State**:
- 2,047 total files
- 73% TypeScript (1,487 files) - Infrastructure + UI
- 27% JSON/YAML (560 files) - Schemas + packages + seed data
- **Goal**: 35-40% JSON/YAML (data-driven) through strategic cleanup

**Total Estimated Effort**: 9-16 hours of refactoring
**Recommended Timeline**: Phase 1 (1-2 weeks) + Phase 2 (4-6 weeks)

### Phase 1: Critical Cleanup (1-2 weeks, ~2-3 hours)

**🔴 P0 - Block Production Issues** (None identified - codebase is stable)

**🟠 P1 - Quick Wins, High Impact**

| # | Task | Effort | Impact | Files | Status |
|---|------|--------|--------|-------|--------|
| **1.1** | **Delete `/old` directory** | 1h | High | 119 | ❌ TODO |
| | Pre-Next.js SPA implementation | | | | |
| | Contains Vite, React, Radix UI | | | | |
| | Completely superseded by NextJS | | | | |
| **1.2** | **Delete `.backup` files** | 10m | Low | 4 | ❌ TODO |
| | Not needed with Git history | | | | |
| | Files: `*.backup` in `/dbal/development/` | | | | |
| **1.3** | **Verify experimental code** | 1h | Low | 1 | ❌ TODO |
| | `/css/categories/experimental.ts` | | | | |
| | Check usage, delete if unused | | | | |

**P1 Deliverables**: Remove 124 files of dead code, reduce confusion

### Phase 2: Architecture Refactoring (4-6 weeks, ~9-16 hours)

**🟡 P2 - Medium Priority, Medium Effort**

| # | Task | Effort | Impact | Type | Status |
|---|------|--------|--------|------|--------|
| **2.1** | **Migrate seed data to YAML** | 4-5h | ⭐⭐⭐ High | Architecture | ❌ TODO |
| | Move `/lib/db/database-admin/seed-default-data/*.ts` to `/seed/database/` | | | | |
| | Load via DBAL `seedDatabase()` orchestration | | | | |
| | Affected files: 5 TS files (~150 lines) | | | | |
| | **Sub-tasks**: | | | | |
| | - `seed-users.ts` → `users.yaml` | 1h | | | |
| | - `seed-app-config.ts` → `app-config.yaml` | 1h | | | |
| | - `seed-css-categories.ts` → `css-categories.yaml` | 1h | | | |
| | - `seed-dropdown-configs.ts` → `dropdown-configs.yaml` | 1h | | | |
| | - Update DBAL `seedDatabase()` to load all YAML | 1-2h | | | |
| **2.2** | **Eliminate adapter code duplication** | 2-3h | ⭐⭐ Medium | DRY | ❌ TODO |
| | Delete `/frontends/nextjs/src/lib/dbal-client/adapter/` | | | | |
| | Remove `PrismaAdapter` and `DevelopmentAdapter` classes (355 lines) | | | | |
| | Frontend uses DBAL client exclusively | | | | |
| | **Sub-tasks**: | | | | |
| | - Audit current adapter usage | 30m | | | |
| | - Move any unique logic to DBAL | 1h | | | |
| | - Delete adapter classes | 30m | | | |
| | - Update imports to use DBAL | 30m | | | |
| **2.3** | **Migrate role/permission constants to DB** | 2-3h | ⭐⭐ Medium | Data-Driven | ❌ TODO |
| | Move hardcoded `ROLE_LEVELS` from `constants.ts` | | | | |
| | Target: `/schemas/permissions_schema.json` + seed | | | | |
| | **Sub-tasks**: | | | | |
| | - Update `permissions_schema.json` with role definitions | 1h | | | |
| | - Create `seed/database/roles.yaml` | 30m | | | |
| | - Update frontend to load roles from DB | 1h | | | |
| **2.4** | **Migrate environment configuration** | 2-3h | ⭐ Medium | Data-Driven | ❌ TODO |
| | Move `ENV_DEFAULTS`, `TIMEOUTS` from `constants.ts` | | | | |
| | Target: `/seed/config/app-config.yaml` | | | | |
| | **Sub-tasks**: | | | | |
| | - Extract config to YAML | 1h | | | |
| | - Add config loading at startup | 1h | | | |
| | - Update all config references | 30m | | | |

**P2 Deliverables**: Reach 35-40% data-driven architecture, eliminate 3 sources of hardcoded data

### Phase 3: Polish & Optimization (Future, 2-3 hours)

**🟢 P3 - Low Priority, Low Effort**

| # | Task | Effort | Impact | Type | Status |
|---|------|--------|--------|------|--------|
| **3.1** | **Complete TODO items** | Varies | Low | Code Quality | ❌ TODO |
| | Compiler implementation (`/lib/compiler/index.ts`) | | | | |
| | Review `/docs/TODO_MVP_IMPLEMENTATION.md` | 1h | | | |
| **3.2** | **Add error boundaries** | 2h | Low | UX | ❌ TODO |
| | Comprehensive React error boundaries | | | | |
| **3.3** | **Improve TypeScript coverage** | 2-3h | Low | Type Safety | ❌ TODO |
| | Strict mode compliance, eliminate `any` types | | | | |

### Implementation Timeline

```
Week 1 (P1 - Quick Wins)
├── Day 1-2: Delete /old and backups (1.5h)
└── Day 3-5: Verify experimental code (1h)

Week 2-6 (P2 - Architecture Refactoring)
├── Week 2: Migrate seed data to YAML (2.1) - 4-5h
├── Week 3: Eliminate adapter duplication (2.2) - 2-3h
├── Week 4: Migrate roles to DB (2.3) - 2-3h
├── Week 5: Migrate environment config (2.4) - 2-3h
└── Week 6: Integration testing & validation

Ongoing (P3 - Polish)
└── As time permits after P1 + P2
```

### Dependencies & Blocking Issues

**No blockers identified** - All work is independent and can be started immediately.

**Recommended Sequence**:
1. **Start P1 immediately** (delete old code) - quick win, high clarity
2. **Start P2.1 next** (seed data) - foundation for other refactoring
3. **Parallel P2.2, P2.3, P2.4** - Can work in parallel after P2.1

### Success Metrics

| Metric | Current | Target | Timeline |
|--------|---------|--------|----------|
| **Data-Driven Ratio** | 27% JSON/YAML | 35-40% | After P2 |
| **Hardcoded Data** | 3 sources | 0 sources | After P2 |
| **Deprecated Code** | 119 files | 0 files | After P1 |
| **Adapter Duplication** | 355 lines | 0 lines | After P2.2 |
| **Code Clarity** | 73% TS overhead | 60-65% TS | After P2 |

### Risk Assessment

**Low Risk**: All refactoring is backward compatible
- Git history preserved
- No production impact (development artifacts only)
- All changes are additive to data-driven architecture
- Can be tested incrementally with E2E tests

**Testing Plan**:
1. Verify all existing tests pass after each phase
2. Run E2E tests to ensure no functionality lost
3. Manual testing of seed data loading
4. Verification of role/permission system after 2.3
5. Environment config testing after 2.4

### Post-Refactoring Priorities

Once technical debt is addressed (after Phase 2), focus on feature development:

#### Feature Roadmap (Q1-Q2 2026)

**Q1 2026: Foundation**
- ✅ Core platform (completed)
- ✅ DBAL integration (completed)
- 🎯 **Tech Debt Cleanup** (Phase 1-2, Jan-Feb 2026)

**Q2 2026: Enhanced Features**
- 🎯 Backend API Integration (real endpoints, not mocks)
- 🎯 Enhanced CRUD UX (forms, validation, pagination)
- 🎯 God Panel Foundation (route/package management)

**Q3-Q4 2026: Production Hardening**
- 🎯 C++ DBAL in production
- 🎯 Performance optimization
- 🎯 Security hardening
- 🎯 First production deployments

### Related Documentation

- **Audit Report**: See "Codebase Composition" section above for detailed breakdown
- **Architecture**: See `/ARCHITECTURE.md` for system design
- **Development**: See `CLAUDE.md` for AI assistant guidance
- **Implementation**: See `.github/prompts/` for development workflows

---

## Long-Term Vision

### Year 1 (2026) - Foundation & Growth

**Q1 2026: Platform Foundation**
- ✅ MVP with core features (Completed)
- ✅ DBAL TypeScript implementation (Completed)
- 🎯 **Tech Debt Cleanup Phase 1** (Jan-Feb, ~2-3 hours)
  - Delete `/old` directory (119 files)
  - Delete backup files (4 files)
  - Remove experimental code (1 file)

**Q2 2026: Architecture Hardening & Features**
- 🎯 **Tech Debt Cleanup Phase 2** (Feb-Mar, ~9-16 hours)
  - Migrate seed data to YAML (4-5h)
  - Eliminate adapter duplication (2-3h)
  - Migrate roles to database (2-3h)
  - Migrate environment config (2-3h)
- 🎯 Production-ready CRUD operations (integration with real API endpoints)
- 🎯 Enhanced CRUD UX (forms, validation, pagination)
- 🎯 God panel foundation (route/package management)

**Q3-Q4 2026: Production Hardening & Scale**
- 🎯 C++ DBAL in production
- 🎯 Performance optimization
- 🎯 Security hardening
- 🎯 First production deployments: >5 sites
- 🎯 Active users: >100
- 🎯 First 10 third-party packages

### Year 2 (2027) - Ecosystem & Enterprise
- 🔮 Package marketplace with ratings
- 🔮 Advanced search capabilities (full-text, filters)
- 🔮 Multi-language i18n support
- 🔮 Enterprise authentication (OAuth, MFA, SSO)
- 🔮 Real-time collaboration features
- 🔮 Plugin ecosystem for extensions
- 🔮 100+ public packages
- 🔮 Active deployments: >50 sites
- 🔮 Active users: >5,000

### Year 3 (2028+) - AI & Scale
- 🔮 Visual component builder (drag-and-drop)
- 🔮 AI-assisted schema generation
- 🔮 AI-powered package recommendations
- 🔮 Real-time collaborative editing
- 🔮 Advanced analytics and insights
- 🔮 Multi-cloud deployment (AWS, Azure, GCP)
- 🔮 Kubernetes native deployment
- 🔮 1000+ active deployments
- 🔮 Active users: >50,000
- 🔮 Enterprise customers: >25

### Features Inspired by Original Spark Version

The following features from our original Spark-based version are being considered for future implementation in the Next.js platform:

#### High Priority (Q3-Q4 2026)
- 🎯 **Visual Component Hierarchy Editor** - Drag-and-drop component organization (originally in Level 4 God panel)
- 🎯 **Monaco Code Editor Integration** - In-browser code editing with syntax highlighting
- 🎯 **Database Export/Import** - Complete system backup and restoration
- 🎯 **Live Schema Editing** - Real-time schema modifications through UI

#### Medium Priority (2027)
- 🔮 **Component Catalog Browser** - Searchable library of available components
- 🔮 **Visual Workflow Builder** - Node-based workflow design interface
- 🔮 **Template Library** - Pre-built page and component templates
- 🔮 **Live Preview Mode** - See changes in real-time while editing

#### Low Priority (2028+)
- 🔮 **Alternative Scripting Support** - Consider Lua or other scripting languages as alternatives to JSON scripts
- 🔮 **Component Version Control** - Track component changes over time
- 🔮 **Collaborative Editing** - Multiple users editing simultaneously

#### Features Not Planned for Migration
Some features from the original version are intentionally not being migrated:
- ❌ **KV Storage** - Replaced by PostgreSQL for better scalability and reliability
- ❌ **Radix UI** - Replaced by Material-UI for comprehensive enterprise components
- ❌ **Tailwind CSS** - Replaced by SCSS modules for better component isolation
- ❌ **4-Level Permission System** - Enhanced to 6-level system with more granular control
- ❌ **Single-Tenant Architecture** - Completely redesigned for multi-tenancy

### Strategic Goals

#### Platform Goals
1. **Zero Configuration Deployments** - One command to deploy everything
2. **Complete Flexibility** - Everything configurable through UI
3. **Performance First** - Sub-100ms response times
4. **Security by Default** - Built-in security best practices
5. **Developer Experience** - Fast iteration, great tooling

#### Community Goals
1. **Open Source Ecosystem** - Vibrant package community
2. **Comprehensive Documentation** - Every feature documented
3. **Educational Resources** - Tutorials, videos, courses
4. **Community Support** - Active forums and Discord
5. **Contributor Growth** - 100+ active contributors

#### Business Goals
1. **Enterprise Adoption** - Fortune 500 deployments
2. **Cloud Marketplace** - Available on AWS, Azure, GCP marketplaces
3. **Professional Services** - Training, consulting, custom development
4. **Managed Hosting** - MetaBuilder Cloud service
5. **Partner Ecosystem** - Integration partners and resellers

---

## Deployment Options

### Quick Start (Development)

```bash
# Clone repository
git clone https://github.com/yourusername/metabuilder
cd metabuilder

# Install dependencies
npm install

# Setup database
npm run db:generate
npm run db:push

# Start development server
npm run dev
```

Visit http://localhost:3000

### Docker Compose (Development)

```bash
# Start all services
docker-compose -f deployment/docker-compose.development.yml up

# Services available:
# - App: http://localhost:5173
# - DBAL API: http://localhost:8081
# - Adminer (DB UI): http://localhost:8082
# - Redis Commander: http://localhost:8083
# - Mailhog (Email): http://localhost:8025
```

### Docker Compose (Production)

```bash
# Configure environment
cp .env.production.example .env
vim .env  # Update with production values

# Start production stack
docker-compose -f deployment/docker-compose.production.yml up -d

# Services:
# - PostgreSQL (internal)
# - DBAL Daemon (internal)
# - Next.js App (internal)
# - Nginx (public: 80, 443)
# - Redis (internal)
```

### One-Command Deployment

```bash
# Deploy everything (PostgreSQL, DBAL, Next.js, Media daemon, Redis, Nginx)
cd deployment && python3 deployment.py deploy --all
```

### Cloud Platforms

#### Docker Swarm
```bash
docker swarm init
docker stack deploy -c deployment/docker-compose.production.yml metabuilder
docker service scale metabuilder_metabuilder-app=5
```

#### Kubernetes
```bash
kubectl apply -f deployment/kubernetes/
kubectl scale deployment metabuilder-app --replicas=5
```

#### Managed Services
- **AWS:** ECS, EKS, or EC2 with docker-compose
- **Azure:** Container Instances, AKS, or VM with docker-compose
- **Google Cloud:** Cloud Run, GKE, or Compute Engine
- **DigitalOcean:** App Platform or Droplet with docker-compose
- **Heroku:** Container registry
- **Fly.io:** Native support

### Resource Requirements

#### Minimum (Development)
- **CPU:** 2 cores
- **RAM:** 4GB
- **Storage:** 20GB
- **Network:** Broadband internet

#### Recommended (Production - Small)
- **CPU:** 4 cores
- **RAM:** 8GB
- **Storage:** 100GB SSD
- **Network:** 100Mbps dedicated

#### Recommended (Production - Medium)
- **CPU:** 8 cores
- **RAM:** 16GB
- **Storage:** 500GB SSD
- **Network:** 1Gbps dedicated

#### Enterprise (Production - Large)
- **CPU:** 16+ cores
- **RAM:** 32GB+
- **Storage:** 1TB+ SSD
- **Network:** 10Gbps dedicated
- **Load Balancer:** Required
- **CDN:** Recommended

---

## Development Workflow

### For Contributors

1. **Setup Development Environment**
   ```bash
   git clone <repo>
   cd metabuilder
   npm install
   npm run db:generate
   npm run db:push
   ```

2. **Create Feature Branch**
   ```bash
   git checkout -b feature/my-new-feature
   ```

3. **Make Changes**
   - Follow existing patterns
   - Add tests (parameterized with `it.each`)
   - Update documentation
   - One lambda per file

4. **Test Changes**
   ```bash
   npm run lint:fix
   npm run test
   npm run typecheck
   ```

5. **Commit and Push**
   ```bash
   git add .
   git commit -m "feat: add my new feature"
   git push origin feature/my-new-feature
   ```

6. **Create Pull Request**
   - Reference related issues
   - Include screenshots for UI changes
   - Ensure CI passes

### Code Standards

✅ **One lambda per file** - Functions are separate files, classes only as containers
✅ **Parameterized tests** - Use `it.each()` for comprehensive test coverage
✅ **Material-UI** - Use MUI components, not Radix or Tailwind
✅ **SCSS Modules** - Component-specific styles in `.module.scss`
✅ **Absolute imports** - Use `@/` for all imports
✅ **Server-only** - Mark server code with `'server-only'`
✅ **DBAL for data** - All database access through DBAL
✅ **Tenant isolation** - Always filter by `tenantId`

### Testing Standards

- **Unit tests:** All new functions must have tests
- **Coverage:** Target >80% for new code
- **Parameterized:** Use `it.each()` for multiple test cases
- **Naming:** Test files match source files (`utils.ts` → `utils.test.ts`)
- **Run tests:** `npm run test` before committing

### Release Process

1. **Version Bump:** Update version in package.json
2. **Changelog:** Document all changes
3. **Tag Release:** `git tag v0.x.x`
4. **Build:** Test production build
5. **Deploy:** Deploy to staging first
6. **Verify:** Run E2E tests
7. **Production:** Deploy to production
8. **Monitor:** Watch logs and metrics

---

## Success Metrics

### MVP (Achieved)
- [x] Core features implemented (5/5)
- [x] Test coverage >80% (97.9%)
- [x] Documentation complete
- [x] Zero breaking changes

### Post-MVP (2026)
- [ ] Production deployments: >5
- [ ] Active users: >100
- [ ] Public packages: >20
- [ ] API response time: <200ms avg
- [ ] Uptime: >99.9%
- [ ] Customer satisfaction: >4.5/5

### Long-Term (2027+)
- [ ] Active deployments: >100
- [ ] Active users: >10,000
- [ ] Public packages: >100
- [ ] Community contributors: >50
- [ ] Enterprise customers: >10

---

## Contributing

We welcome contributions! MetaBuil der is an open-source project that thrives on community involvement.

### Ways to Contribute

1. **Code Contributions**
   - Implement features from the roadmap
   - Fix bugs and issues
   - Improve performance
   - Add tests
   - Refactor code

2. **Documentation**
   - Write tutorials and guides
   - Improve API documentation
   - Create video tutorials
   - Translate documentation

3. **Packages**
   - Create new packages
   - Improve existing packages
   - Share package templates
   - Write package documentation

4. **Testing & QA**
   - Report bugs
   - Test new features
   - Improve test coverage
   - Performance testing

5. **Community Support**
   - Answer questions
   - Help new users
   - Write blog posts
   - Share use cases

### Getting Started

**New to MetaBuilder?**
1. Read the [README.md](README.md) - Understand the core concept
2. Follow the [Quick Start](#deployment-options) - Get it running locally
3. Explore `/packages` - See example packages
4. Check `docs/TODO_MVP_IMPLEMENTATION.md` - See what's been done
5. Join discussions - Ask questions, share ideas

**Ready to Contribute?**
1. Check [GitHub Issues](https://github.com/yourusername/metabuilder/issues)
2. Look for "good first issue" labels
3. Read [Development Workflow](#development-workflow)
4. Follow [Code Standards](#code-standards)
5. Submit a pull request

### Project Resources

#### Documentation
- **README.md** - Project overview and quick start
- **ROADMAP.md** (this file) - Comprehensive development roadmap
- **docs/TODO_MVP_IMPLEMENTATION.md** - MVP implementation checklist
- **docs/MVP_IMPLEMENTATION_SUMMARY.md** - MVP completion summary
- **deployment/README.md** - Deployment guide
- **dbal/README.md** - DBAL documentation
- **dbal/docs/AGENTS.md** - AI development guidelines

#### Specifications
- **spec/** - Formal TLA+ specifications
- **schemas/** - JSON schemas and validation
- **prisma/schema.prisma** - Database schema

#### Examples
- **packages/** - 52 example packages
- **e2e/** - End-to-end test examples
- **storybook/** - Component stories

#### Configuration
- **.github/prompts/** - AI agent workflows
- **deployment/** - Docker and deployment configs
- **config/** - Application configuration

### Communication Channels

- **GitHub Issues** - Bug reports and feature requests
- **GitHub Discussions** - Questions and community discussions
- **Pull Requests** - Code contributions and reviews
- **Discord** (coming soon) - Real-time chat and support

### Code of Conduct

- Be respectful and inclusive
- Help others learn and grow
- Accept constructive feedback
- Focus on what's best for the community
- Show empathy and kindness

---

## Quick Reference

### Key Commands

```bash
# Development
npm run dev              # Start development server
npm run build            # Build for production
npm run test             # Run tests
npm run lint:fix         # Fix linting issues
npm run typecheck        # Check TypeScript types

# Database
npm run db:generate      # Generate Prisma client
npm run db:push          # Push schema to database
npm run db:migrate       # Run migrations

# Testing
npm run test             # Run all tests
npm run test:run         # Run tests once (no watch)
npm run test:watch       # Watch mode
```

### Important Files

| File | Purpose |
|------|---------|
| **ROADMAP.md** | This comprehensive roadmap |
| **README.md** | Project overview and setup |
| **package.json** | Dependencies and scripts |
| **prisma/schema.prisma** | Database schema |
| **frontends/nextjs/src/app/page.tsx** | Root page with routing logic |
| **frontends/nextjs/src/lib/auth/get-current-user.ts** | Authentication |
| **frontends/nextjs/src/lib/db/core/dbal-client.ts** | Database access |

### Key Directories

| Directory | Purpose |
|-----------|---------|
| **frontends/nextjs/** | Next.js frontend application |
| **packages/** | 52 built-in packages |
| **dbal/** | Database abstraction layer (TS + C++) |
| **services/media_daemon/** | C++ media processing service |
| **deployment/** | Docker and deployment configs |
| **prisma/** | Database schema and migrations |
| **docs/** | Project documentation |
| **e2e/** | End-to-end tests |
| **.github/prompts/** | AI development workflows |

### Architecture Principles

1. **Data-Driven Everything** - No hardcoded routes or components
2. **Database as Source of Truth** - All configuration in database
3. **Generic Rendering** - JSON → React via generic renderer
4. **Multi-Tenant by Default** - All queries filter by tenantId
5. **Permission-Based Access** - 6-level permission system
6. **Package-Based Architecture** - Self-contained, installable packages
7. **DBAL Abstraction** - All database access through DBAL
8. **Zero Coupling** - Frontend knows nothing about specific packages

### Version History

| Version | Date | Status | Highlights |
|---------|------|--------|------------|
| **0.1.0-alpha** | Jan 2026 | ✅ Current | MVP achieved with all 5 TODO items |
| **0.0.0** | Pre-2026 | ✅ Complete | Foundation and architecture |
| **0.2.0-alpha** | Q1 2026 | 📋 Planned | Backend API integration |
| **0.3.0-beta** | Q2 2026 | 📋 Planned | God panel, enhanced CRUD |
| **1.0.0** | Q4 2026 | 🔮 Target | Production-ready release |

---

## Changelog

### v0.1.0-alpha (January 2026) ✨ MVP Release

**New Features:**
- ✨ Session-based authentication with getCurrentUser()
- ✨ Permission level checks and access control
- ✨ Dynamic package loading from filesystem
- ✨ Schema-driven CRUD operations (list, detail, create, edit)
- ✨ Static page generation with ISR support
- ✨ Code compilation with esbuild (minification, source maps)

**New Files:**
- `frontends/nextjs/src/lib/auth/get-current-user.ts`
- `frontends/nextjs/src/lib/auth/get-current-user.test.ts`
- `frontends/nextjs/src/components/AccessDenied.tsx`
- `frontends/nextjs/src/lib/entities/load-entity-schema.ts`
- `frontends/nextjs/src/lib/entities/api-client.ts`
- `frontends/nextjs/src/lib/compiler/index.test.ts`

**Enhanced Files:**
- `frontends/nextjs/src/app/page.tsx` - Added auth and permission checks
- `frontends/nextjs/src/app/[tenant]/[package]/page.tsx` - Dynamic package loading
- `frontends/nextjs/src/app/[tenant]/[package]/[...slug]/page.tsx` - Full CRUD views
- `frontends/nextjs/src/app/ui/[[...slug]]/page.tsx` - Static generation
- `frontends/nextjs/src/lib/compiler/index.ts` - Full esbuild integration

**Testing:**
- 20 new tests added (100% passing)
- Total: 188/192 tests passing (97.9%)
- Parameterized test coverage for all new functions

**Dependencies:**
- Added: `esbuild` (^0.27.2)

**Documentation:**
- Created comprehensive `ROADMAP.md` (this file)
- Updated `docs/TODO_MVP_IMPLEMENTATION.md` - All items completed
- Created `docs/MVP_IMPLEMENTATION_SUMMARY.md`

**Breaking Changes:**
- None - All changes additive or fulfilling TODO placeholders

---

## Questions or Feedback?

- **Documentation:** See `/docs` directory and README.md
- **Issues:** [GitHub Issues](https://github.com/yourusername/metabuilder/issues)
- **Discussions:** [GitHub Discussions](https://github.com/yourusername/metabuilder/discussions)
- **Email:** support@metabuilder.dev (coming soon)

---

## License

MIT License - See [LICENSE](LICENSE) file

---

**Document Status:** 📊 Comprehensive Single Source of Truth
**Last Updated:** January 8, 2026
**Current Version:** 0.1.0-alpha
**Current Phase:** 🎯 MVP Achieved → Post-MVP Development
**Next Milestone:** Backend API Integration (Q1 2026)

---

*This roadmap is a living document. It will be updated as the project evolves. All major decisions, features, and milestones are documented here to serve as the single source of truth for MetaBuilder development.*