ModMe GenUI Workspace

A Generative UI (GenUI) R&D laboratory combining Next.js 16, React 19, and Python ADK for building dynamic, AI-generated interfaces.

🎯 Porting Ready: This monorepo contains highly portable components designed for reuse. See PORTING_GUIDE.md and CODEBASE_INDEX.md for complete component catalog and integration patterns.

🚀 Quick Start

Option 1: GitHub Codespaces (Recommended)

Click Code → Codespaces → Create codespace
Wait for setup to complete (~3-5 minutes)
Run npm run dev to start both servers
Access UI at forwarded port 3000

Option 2: DevContainer (Local)

Install Docker Desktop
Install VS Code with Dev Containers extension
Clone and open in VS Code
Click Reopen in Container when prompted
Run npm run dev after setup completes

Option 3: Local Setup

The Fastest Way (One Command)

# Clone repository
git clone https://github.com/Ditto190/modme-ui-01.git
cd modme-ui-01
 
# Run quick start (installs dependencies + starts servers)
./scripts/quick-start.sh  # Unix/macOS
# or
scripts\quick-start.bat  # Windows (coming soon)

What it does:

✅ Checks prerequisites
✅ Installs Node.js dependencies
✅ Sets up Python agent
✅ Configures environment
✅ Starts both servers (UI + Agent)

Result: UI at http://localhost:3000, Agent at http://localhost:8000

Option 1: Complete Installation

For more control over the installation process:

# 1. Install all dependencies
./scripts/install-all.sh  # Unix/macOS
# or
scripts\install-all.bat  # Windows
 
# 2. Configure environment (add your GOOGLE_API_KEY)
nano .env  # or vim, code, etc.
 
# 3. Start development
npm run dev

Available flags:

--check-only - Only verify prerequisites
--force - Force reinstall all dependencies
--skip-validation - Skip validation steps

See INSTALLATION_GUIDE.md for detailed instructions.

Option 2: GitHub Codespaces (Recommended for Cloud)

Click Code → Codespaces → Create codespace
Wait for setup to complete (~3-5 minutes)
Add GOOGLE_API_KEY to .env (or use Codespaces secrets)
Run npm run dev to start both servers
Access UI at forwarded port 3000

Option 3: DevContainer (Local)

Install Docker Desktop
Install VS Code with Dev Containers extension
Clone and open in VS Code
Click Reopen in Container when prompted
Add GOOGLE_API_KEY to .env
Run npm run dev after setup completes

📋 Prerequisites

Node.js 22.9.0+ (required; earlier versions may cause EBADENGINE warnings and compatibility issues)
- We recommend using nvm (Unix/macOS) or nvm-windows (Windows) to manage Node.js versions
Python 3.12+
Google Makersuite API Key (for the ADK agent) (see https://makersuite.google.com/app/apikey)
Any of the following package managers:
- pnpm (recommended)
- npm
- yarn
- bun

Note: This repository ignores lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) to avoid conflicts between different package managers. Each developer should generate their own lock file using their preferred package manager. After that, make sure to delete it from the .gitignore.

Getting Started

💡 Tip: For the easiest setup, use GitHub Codespaces or DevContainer (see Quick Start above). Everything is pre-configured!

Manual Setup

1. Set up Node.js with nvm (Recommended)

If you're using nvm, install and activate the recommended Node.js version:

# Install Node.js 22.9.0
nvm install 22.9.0
 
# Use Node.js 22.9.0
nvm use 22.9.0
 
# Verify the version
node --version  # Should output v22.9.0

2. Run Setup Script

# Automated setup (recommended)
./scripts/setup.sh  # Linux/macOS
# or
.\scripts\setup.ps1  # Windows PowerShell
 
# This will:
# - Check Node.js and Python versions
# - Install Node.js dependencies
# - Set up Python virtual environment
# - Install agent dependencies with uv (or pip)
# - Create .env from .env.example

3. Manual Installation (Alternative)

Install dependencies manually if you prefer:

# Using pnpm (recommended)
pnpm install
 
# Using npm
npm install
 
# Using yarn
yarn install
 
# Using bun
bun install

Install Python dependencies:

# Using pnpm
pnpm install:agent
 
# Using npm
npm run install:agent
 
# Using yarn
yarn install:agent
 
# Using bun
bun run install:agent

4. Set Up Your Google API Key

Create a .env file (or copy from .env.example):

cp .env.example .env

Then add your Google API key:

export GOOGLE_API_KEY="your-google-api-key-here"
# Or add to .env file: GOOGLE_API_KEY=your-google-api-key-here

Get your API key from Google AI Studio.

5. Start the Development Server

# Using pnpm
pnpm dev
 
# Using npm
npm run dev
 
# Using yarn
yarn dev
 
# Using bun
bun run dev

This will start both the UI and agent servers concurrently.

🐳 DevContainer Features

This workspace includes a full DevContainer setup for portable, consistent development:

What's Included

✅ Multi-runtime support: Node.js 22.9.0+ and Python 3.12+
✅ Package managers: npm, nvm, uv (Python)
✅ VS Code extensions: Pre-installed and configured
✅ Port forwarding: Automatic for UI (3000) and Agent (8000)
✅ Auto-setup: Dependencies installed on container creation
✅ GitHub CLI: For managing issues, PRs, and workflows

DevContainer Commands

# Health check your workspace
./scripts/health-check.sh
 
# Start development servers
./scripts/start-dev.sh
 
# Manual setup (if needed)
./scripts/setup.sh
 
# Set up VS Code shell integration
.\scripts\setup-shell-integration.ps1  # PowerShell
bash scripts/setup-shell-integration.sh  # Bash

Shell Integration

VS Code shell integration provides enhanced terminal features:

✅ Command decorations - Visual indicators for success/failure
✅ Command navigation - Ctrl/Cmd+Up/Down to navigate between commands
✅ IntelliSense - File/folder suggestions in terminal
✅ Recent commands - Ctrl+Alt+R to search command history
✅ Sticky scroll - Commands stick at top when scrolling
✅ Quick fixes - Automatic suggestions for common errors

Quick setup: Run .\scripts\setup-shell-integration.ps1 (PowerShell) or bash scripts/setup-shell-integration.sh (Bash)

Documentation: See .config/README.md and .config/QUICKSTART.md

Workspace File

Open workspace.code-workspace in VS Code for a multi-root workspace with:

Separate folders for Frontend, Agent, Scripts, and Prompts
Pre-configured debugging for both Node.js and Python
Integrated tasks for common operations

Available Scripts

The following scripts can also be run using your preferred package manager:

dev - Starts both UI and agent servers in development mode
dev:debug - Starts development servers with debug logging enabled
dev:ui - Starts only the Next.js UI server
dev:agent - Starts only the ADK agent server
build - Builds the Next.js application for production
start - Starts the production server
lint - Runs ESLint for code linting
install:agent - Installs Python dependencies for the agent

📚 Documentation

Core Documentation

CONTRIBUTING.md - Development workflow, issue templates, and guidelines
Project_Overview.md - Generative UI architecture and vision
Architecture Overview - System architecture (new in this workspace; may not exist on older branches)
GenUI Development - GenUI patterns and practices (new in this workspace; may not exist on older branches)

Issue Management & Automation

Issue Management System - Complete issue system with templates and automation
Knowledge Base Integration - Semantic issue enrichment with KB Context Mapper
KB Quick Reference - Quick start guide for knowledge base features

Toolset Management

Toolset Management - GitHub MCP-style toolset lifecycle automation
Toolset Quick Start - Quick start guide for toolsets
TOOLSET_README.md - Toolset system overview

Code Quality & Patterns

Refactoring Patterns - Project-specific refactoring guides
Schema Crawler - JSON Schema → Zod + TypeScript generator
Markdown Automation - Automated markdown linting and formatting
Markdown Quick Reference - Quick commands for markdown fixes

External Resources

ADK Documentation - Google ADK features
CopilotKit Documentation - CopilotKit capabilities
Next.js Documentation - Next.js features and API

🤖 Issue Reporting & Management

This project uses an intelligent issue management system with:

✅ Structured templates for bugs, features, toolsets, and questions
✅ Automatic labeling based on issue content (component, priority, type)
✅ Knowledge Base Context Mapper - Automatically enriches issues with relevant files and documentation
✅ Toolset lifecycle integration for deprecation and validation workflows

How it works: When you open an issue, the Knowledge Base analyzes the content and automatically:

Detects relevant concepts (e.g., "StatCard", "Agent Tools", "State Sync")
Links to related files and documentation
Suggests appropriate labels
Posts a helpful context comment with all the information

Learn more: See Issue Management System and Knowledge Base Integration

🔒 Privacy & Security

This workspace follows a local-first, privacy-focused approach:

Client data in data/ directory never leaves your machine
All API keys stored in .env (git-ignored)
Agent processing happens locally or through configured endpoints
Sandboxed execution for generated code

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

DevContainer setup instructions
Development workflow
Code standards and conventions
Testing guidelines
Pull request process

Feel free to submit issues and enhancement requests!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Agent Connection Issues

If you see "I'm having trouble connecting to my tools", make sure:

The ADK agent is running on port 8000
Your Google API key is set correctly
Both servers started successfully

Python Dependencies

If you encounter Python import errors:

cd agent
pip install -r requirements.txt

stream-coding