LEAF Reference Implementation - Next.js + Convex

Reference implementation of the LEAF Specification using Next.js and Convex.

Overview

This is the first reference implementation of LEAF (Listen, Embed, Augment, Flow) - an AI-native knowledge base application specification. Currently implements hello world scaffolding to validate the Next.js + Convex stack.

Stack:

• Next.js 16 (App Router)
• Convex (reactive backend with real-time sync)
• shadcn/ui + Tailwind CSS

Live Demo

• Production: leaf-nextjs-convex.vercel.app
• LEAF Spec: github.com/leafspec/spec

Features

✅ Currently Implemented (SPEC-001):

• Real-time message sync across browser tabs
• Next.js + Convex integration
• Production deployment to Vercel + Convex Cloud

🚧 Future Implementation:

• User authentication
• Document upload and processing
• Vector embeddings and semantic search
• AI chat with document context
• Full LEAF spec compliance

Development

Prerequisites

• Node.js 18+
• Convex account (free tier available)
• Vercel account (optional, for deployment)

Setup

1. Clone and install:

   git clone https://github.com/leafspec/leaf-nextjs-convex.git
   cd leaf-nextjs-convex
   npm install

2. Set up Convex:

   npx convex dev

   Follow the prompts to create a Convex project.

3. Start development:

   # Terminal 1 - Convex backend
   npx convex dev
   
   # Terminal 2 - Next.js frontend
   npm run dev

4. Open: http://localhost:3000

Environment Variables

# .env.local (auto-generated by convex dev)
CONVEX_DEPLOYMENT=dev:your-deployment
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

Architecture

├── convex/
│   ├── schema.ts          # Database schema
│   ├── messages.ts        # Query and mutation functions
│   └── _generated/        # Auto-generated types
├── src/
│   ├── app/
│   │   ├── ConvexClientProvider.tsx  # Convex React provider
│   │   ├── layout.tsx               # Root layout with providers
│   │   └── page.tsx                 # Homepage with messages UI
│   └── components/ui/     # shadcn/ui components
└── ideas/                 # Project planning (separate repo)

Deployment

Convex Cloud

npx convex deploy

Vercel

1. Connect GitHub repo to Vercel
2. Add environment variable: NEXT_PUBLIC_CONVEX_URL (production URL from convex deploy)
3. Deploy

Contributing

This reference implementation follows the patterns defined in the LEAF Specification. See the planning docs in the my-life repo for development roadmap.

Links

• LEAF Specification: https://github.com/leafspec/spec
• Convex Documentation: https://docs.convex.dev
• Next.js Documentation: https://nextjs.org/docs