🌿 LiveLeaf

A modern, lightning-fast document workspace engineered for speed, fluid organization, and distraction-free writing.

---

📖 Table of Contents

• Overview
• Key Features
• Tech Stack
• Architecture & Directory Structure
• Database Schema & Performance
• Getting Started
• Environment Variables
• Available Scripts
• License

---

🌟 Overview

LiveLeaf is a full-featured, Notion-inspired document management platform designed to deliver desktop-grade performance in the browser. Featuring real-time debounced autosave, recursive page nesting, drag-and-drop reordering, full-text search, and cross-platform keyboard shortcuts, LiveLeaf provides a frictionless writing workspace.

---

✨ Key Features

✍️ Rich-Text & Editor Core

• Tiptap Block Engine: Built on Tiptap v3 with custom extensions for blockquotes, typography, code blocks, highlighting, and inline formatting.
• Real-Time Autosave: Background sync with status indicators (Saving... / Saved) and local state synchronization.
• Full-Width Canvas Toggle: Dynamic workspace mode switching between reading view and full-width editor canvas.
• Live Character & Word Counter: Real-time document statistics footer (X words · Y characters).
• Export & Portability: Export pages directly as Markdown (.md) or copy formatted page content in one click.

🌲 Recursive Tree Hierarchy & Drag-and-Drop

• Unlimited Document Nesting: Notion-style recursive hierarchy allowing pages to contain subpages indefinitely.
• Desktop-Class Drag & Drop: Powered by @dnd-kit/core and @dnd-kit/sortable with real-time visual depth projection indicators and drop-target positioning (before, after, or nest).
• Starred Favorites: Database-persisted favorites section with instant hover actions.

🔍 Command Palette & Full-Text Search

• Instant Search (Ctrl+K / ⌘K): Powered by PostgreSQL tsvector and pg_trgm indexes for fast searching across page titles and body snippets.
• Highlight Matches: Smart query term highlighting in search result previews.

🗑️ Soft-Delete & Trash Management

• Archiving & Recovery (Ctrl+Shift+T / ⌘⇧T): Soft-delete system with a dedicated Trash Modal supporting tree-aware document restoration and permanent deletion.

⌨️ Cross-Platform UX & Accessibility

• Native OS Keyboard Badges: Automatically detects Windows/macOS platforms (Ctrl vs. ⌘) rendering clean <Kbd> components.
• Shortcuts Panel: Dedicated Keyboard Shortcuts tab in Settings for rapid feature discovery.
• Theme Support: Seamless Dark/Light theme switching with next-themes and custom OKLCH color palettes.

---

🛠️ Tech Stack

Category	Technology
Framework	Next.js 16
Language	TypeScript
Database	PostgreSQL
ORM	Prisma 7.8
Authentication	Better Auth
State & Cache	TanStack Query v5 & Zustand
Editor Core	Tiptap v3
Drag & Drop	@dnd-kit
Styling	Tailwind CSS v4, Shadcn UI, Lucide Icons

---

📁 Architecture & Directory Structure

liveleaf/
├── prisma/
│   └── schema.prisma         # Database schema & indexes definition
├── public/                   # Static assets & icons
└── src/
    ├── app/                  # Next.js App Router (pages, layouts, API routes)
    │   ├── api/              # Document, Search, and User API endpoints
    │   └── d/[documentId]/   # Workspace document viewer routes
    ├── components/           # React components
    │   ├── editor/           # Tiptap rich-text editor components
    │   ├── landing/          # Public landing page components
    │   ├── modals/           # Search, Settings, and Trash dialogs
    │   ├── sidebar/          # Tree view, drag-and-drop items, and navigation
    │   └── ui/               # Shadcn UI primitives (Kbd, Tooltip, Dialog, etc.)
    ├── features/             # Feature-specific DTOs and business logic
    ├── hooks/                # Custom React hooks (shortcuts, document queries)
    ├── lib/                  # Utilities, Prisma client, and authentication setup
    └── stores/               # Zustand state stores (sidebar tree expansion)

---

⚡ Getting Started

Prerequisites

• Node.js: v20.0.0 or higher
• Package Manager: pnpm (v9+)
• Database: PostgreSQL database

1. Clone & Install Dependencies

git clone https://github.com/amanhuh/liveleaf.git
cd liveleaf
pnpm install

2. Configure Environment Variables

Copy the example environment file .env.example to create your local .env:

cp .env.example .env

Fill in your credentials in .env:

# Database connection URL (PostgreSQL)
DATABASE_URL="postgresql://user:password@localhost:5432/liveleaf?sslmode=require"

# BetterAuth Secrets & App Base URL
BETTER_AUTH_SECRET="your-32-character-secret-key"
BETTER_AUTH_URL="http://localhost:3000"

# GitHub OAuth Credentials
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Google OAuth Credentials
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

3. Database Migration & Setup

# Push Prisma schema to PostgreSQL
pnpm exec prisma db push

# Generate Prisma Client
pnpm exec prisma generate

4. Run Development Server

pnpm dev

Open http://localhost:3000 in your browser.

---

📜 Available Scripts

Command	Description
pnpm dev	Starts the Next.js development server
pnpm build	Builds the production bundle
pnpm start	Runs the compiled production server
pnpm lint	Runs ESLint code style check
pnpm tsc	Runs TypeScript type checker (--noEmit)

---

📄 License

Distributed under the MIT License. See LICENSE for details.