Skip to content

CLAUDE.md

Latest commit

 

History

History
85 lines (67 loc) · 2.67 KB

CLAUDE.md

File metadata and controls

85 lines (67 loc) · 2.67 KB

CLAUDE.md

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

Overview

This is the first reference implementation of LEAF Specification, an AI-native knowledge base application.

Stack:

  • Next.js 16 (App Router)
  • Convex (backend, vector search, file storage)
  • OpenAI (embeddings + chat)
  • Tailwind CSS

Project Structure

leaf-nextjs-convex/
├── src/
│   ├── app/                 # Next.js App Router pages
│   ├── components/          # React components
│   └── lib/                 # Utilities
├── convex/
│   ├── schema.ts            # Database schema
│   ├── documents.ts         # Document mutations/queries
│   ├── conversations.ts     # Conversation mutations/queries
│   ├── messages.ts          # Message mutations/queries
│   ├── search.ts            # Semantic search
│   └── _generated/          # Auto-generated Convex types
├── docs/
│   ├── specs/               # LEAF spec (source of truth)
│   ├── adrs/                # Architecture Decision Records
│   ├── architecture-overview.md
│   ├── api-overview.md
│   ├── data-model.md
│   ├── deployment.md
│   ├── security.md
│   ├── testing-overview.md
│   └── ui-guide.md
└── public/

LEAF Spec Compliance

This implementation must comply with:

Convex-Specific Patterns

Since Convex is reactive, we use subscriptions instead of polling for:

  • Document processing status
  • Real-time message updates
  • Search results

This aligns with the spec's "Processing Status" section which explicitly allows reactive subscriptions.

Commands

# Development
npm run dev          # Start Next.js dev server
npx convex dev       # Start Convex dev server (run in separate terminal)

# Deployment
npx convex deploy    # Deploy Convex functions
npm run build        # Build Next.js for production

Environment Variables

# .env.local
CONVEX_DEPLOYMENT=dev:your-deployment
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
OPENAI_API_KEY=sk-...

Planning