📄 DocuNote

Turn documents into conversations

An intelligent AI-powered chat application built with Next.js 15 and Google Gemini that lets you upload files, scrape websites, and have natural conversations about your content—with automatic summaries and complete conversation history.

✨ Features

💬 Conversational AI Chat: Interact with Google Gemini 2.5 Flash to ask questions and get information from your provided sources
📚 Chat History: Save and load multiple conversations with auto-generated titles
⭐ Pin Conversations: Star important conversations to keep them at the top ✨ NEW
🔍 Conversation Search: Search conversations by title or message content with real-time filtering
🎯 Advanced Search Filters: Filter conversations by date range, source type, and more
⌨️ Keyboard Shortcuts: Navigate faster with Ctrl+N, Ctrl+K, Ctrl+E, and more
✨ Content Summaries: AI-generated summaries for uploaded files and URLs with key points
📥 Export Conversations: Download chat history as TXT or PDF files
⚡ Streaming Responses: Real-time AI response streaming with animated progress indicator
💾 Auto-Save Everything: Messages, sources, themes, and conversations automatically persist across sessions
🔒 Input Validation: Comprehensive security with file size limits, URL validation, and SSRF protection
🛡️ Error Boundaries: Graceful error handling with recovery options - prevents app crashes
📱 Mobile Responsive: Optimized for all devices with touch-friendly interactions and auto-close sidebar
📄 File Uploads: Upload and process .txt, .pdf, .md, .csv, and .docx files (10MB limit) to use as a knowledge base
- Text files (.txt) - Plain text content
- PDF documents (.pdf) - Extracted text from PDFs
- Markdown files (.md) - Preserves formatting
- CSV files (.csv) - Parsed and formatted with headers
- Word documents (.docx) - Extracted text content
🌐 Website Scraping: Provide any website URL, and the application will scrape its content to use as a source
📊 Source Management: Clean sidebar interface to easily add, view, and remove your files and URL sources

🚀 Recent Updates

November 4, 2025 - Major Test Coverage Improvements 🎯

✅ Test Coverage: 63.29% → 66.92% (+3.63%) - Core business logic now has 95%+ coverage
- Storage Tests (PR #26): lib/storage.ts 69.14% → 97.14% (+28%)
  - 45 comprehensive tests for localStorage utilities
  - Tests: messages, sources, AI themes, conversations, bulk operations
  - Full coverage of CRUD operations, pin/unpin, sorting logic
- Validation Tests (PR #27): lib/validation.ts 71.95% → 95.85% (+23.9%)
  - 61 comprehensive tests for security and input validation
  - Tests: URL validation (SSRF, XSS protection), message/content length
  - File name security, HTML sanitization, utility functions
- Error Logger Tests (PR #27): lib/error-logger.ts 35.95% → 99.25% (+63.3%)
  - 50 comprehensive tests for error tracking and logging
  - Tests: error levels, history management, persistence, formatting
  - Error type detection (network, timeout), user-friendly messages
- Total Impact: 156 new tests added (532 → 688 tests)
- Methodology: Test-Driven Development (TDD) with edge case focus
- All PRs merged with CI validation ✅

November 4, 2025 - Stable Conversation Sorting & Pin Feature ⭐

✅ Fixed Conversation Sorting - Conversations no longer rearrange when selected
- Root Cause: saveConversation() was updating updatedAt timestamp even when just loading from history
- Solution: Added updateTimestamp parameter (default: true) - set to false when loading
- Impact: Conversation list stays in consistent order, only changes when content actually changes
- Testing: 8 new TDD tests for sorting stability and pin feature ✅
✅ Pin/Star Conversations - Keep important conversations at the top
- Click star icon to pin/unpin any conversation
- Pinned conversations always appear first (sorted by most recent)
- Unpinned conversations follow (also sorted by most recent)
- Visual distinction: yellow background for pinned items
- Pin status persists in localStorage
- Branch: feat/conversation-sorting-and-pinning

November 4, 2025 - Conversation Title UI Fix 🐛

✅ Fixed Critical Bug - Conversation titles now update immediately in the header
- Root Cause: ConversationTitle component was overriding the title prop with hardcoded "New Conversation" when messages.length === 0
- Solution: Removed conditional override logic - component now displays actual title prop
- Impact: Instant UI updates when changing conversation titles (no more page refresh needed)
- Testing: TDD methodology with 3 new tests, all 511 tests passing ✅
- Branch: fix/conversation-title-ui-update

November 2, 2025 - Enhanced Conversation Management

✅ Save Empty Conversations - You can now save and name conversations even without messages or files
- Create conversations with custom titles before chatting
- Edit conversation titles anytime (not just after first message)
- Better organization for planning and research workflows

October 30, 2025 - Extended File Type Support 📄

✅ Added support for 3 new file types: CSV, Markdown, and Word documents
- .csv - Parsed with column headers and formatted tables
- .md - Markdown files with preserved formatting
- .docx - Microsoft Word documents with extracted text
✅ Updated welcome message to reflect all 5 supported file types
✅ Comprehensive testing with Jest and Playwright for all file formats

�🚀 Getting Started

Prerequisites

Node.js 18 or higher
npm or yarn
Google Gemini API Key (Get one here) - Powers both chat and image generation!

Installation

Clone the repository:

git clone https://github.com/flegaspi700/DocuNote.git
cd DocuNote

Install Dependencies:
```
npm install
```
Set up environment variables:

Create a .env.local file in the root directory:
```
# Required: Gemini API for chat, theme generation, and image generation
GEMINI_API_KEY=your_gemini_api_key_here
```
That's it! Your Gemini API key powers everything: chat responses, theme generation, and Gemini 2.5 Flash Image background images. No additional setup needed!
Run the Development Server:
```
npm run dev
```
This will start the Next.js development server on http://localhost:9002.
Start building! 🎉

Quick Testing

Run the test suite to verify everything works:

# Unit and integration tests
npm test

# End-to-end tests
npm run test:e2e

# Coverage report
npm run test:coverage

For detailed testing documentation, see TESTING-README.md.

📚 Documentation

Comprehensive documentation is available in the docs/ folder:

Getting Started Guide - Project overview and setup
Testing Documentation - How to write and run tests
Features Documentation - Feature implementation guides
Development Guide - Contributing and workflow
Daily Logs - Development progress tracking

Start here: 📖 Documentation Index

🛠️ Tech Stack

Frontend

Next.js 15.3.3 - React framework with App Router
React 18.3.1 - UI library
TypeScript 5 - Type safety
Tailwind CSS 3.4.1 - Utility-first CSS
ShadCN UI - Component library (30+ components)
next-themes 0.3.0 - Theme management
Lucide React - Icon library

AI & Backend

Google Genkit 1.20.0 - AI orchestration framework
Google Gemini 2.5 Flash - Large Language Model
Cheerio 1.0.0 - Server-side HTML parsing
pdfjs-dist 4.5.136 - PDF parsing

Development & Testing

Jest 30.2.0 - Unit and integration testing
Playwright 1.50.2 - End-to-end testing
React Testing Library 16.3.0 - Component testing
Turbopack - Fast development bundler

🎯 Project Status

✅ What's Working (Nov 4, 2025)

Chat Interface - Full conversational AI with context from sources
Chat History - Save, load, and manage multiple conversations with auto-generated titles
Pin Conversations - Star important conversations to keep them at the top ⭐ NEW
Conversation Search - Search by title or message content with debounced filtering
Search Filters - Filter conversations by date range, source type
Testing - 688 tests (675 passing, 13 skipped), 66.92% coverage, CI/CD pipeline ✨ NEW
- Core business logic: 95%+ coverage (storage, validation, error-logger)
Keyboard Shortcuts - Quick navigation with Ctrl+N, Ctrl+K, Ctrl+E, Ctrl+Shift+T
Message Editing - Edit and regenerate AI responses
Conversation Tags - Organize with custom color-coded tags
Content Summaries - AI-generated summaries for files and URLs
Export Conversations - Download chat history as TXT or PDF
Response Streaming - Real-time token-by-token AI responses
Data Persistence - Auto-save/restore messages, sources, themes, and conversations
Input Validation - Comprehensive security and data validation (SSRF, XSS protection)
Error Logging - Centralized error tracking with persistence and user-friendly messages
Error Boundaries - Graceful error handling and crash prevention
Mobile Responsive - Optimized for all devices (320px - 1920px+)
File Upload - .txt, .pdf, .md, .csv, .docx file processing (10MB limit) ✨ NEW
URL Scraping - Website content extraction with SSRF protection
Source Management - Add/remove files and URLs with summary generation
Theme System - Dark/light mode + AI-generated themes with optimized fonts
CI/CD - TypeScript, ESLint, Jest, and build checks on every push

🚧 Known Limitations

No user authentication (single-user local app)
No swipe gestures for sidebar (future enhancement)
5MB localStorage limit (can store ~1000 messages)
Content limits (500K chars per file, 100K chars per message)

See Development Issue Log for detailed status.

🔮 Next Steps & Roadmap

High Priority (Production Ready)

~~Persist Sources & Themes~~ ✅ COMPLETED (Oct 13, 2025)
~~Streaming Responses~~ ✅ COMPLETED (Oct 13, 2025)
~~Input Validation~~ ✅ COMPLETED (Oct 13, 2025)
~~UI Layout Improvements~~ ✅ COMPLETED (Oct 13, 2025)
~~Error Boundaries~~ ✅ COMPLETED (Oct 13, 2025)
~~Mobile Responsive Layout~~ ✅ COMPLETED (Oct 17, 2025)

Medium Priority (Enhanced UX)

~~Chat History~~ ✅ COMPLETED (Oct 17, 2025) - Save and load past conversations
~~Content Summaries~~ ✅ COMPLETED (Oct 17, 2025) - AI-generated summaries for uploaded sources
~~Conversation Search~~ ✅ COMPLETED (Oct 17, 2025) - Search conversations by title and content
~~Export Conversations~~ ✅ COMPLETED (Oct 30, 2025) - Download chat history as TXT/PDF
~~Keyboard Shortcuts~~ ✅ COMPLETED (Oct 30, 2025) - Navigate with Ctrl+N, Ctrl+K, Ctrl+E, Ctrl+Shift+T
~~Advanced Search Filters~~ ✅ COMPLETED (Oct 30, 2025) - Filter by date, source type, message count
~~Message Editing~~ ✅ COMPLETED (Oct 30, 2025) - Edit and regenerate AI responses
~~Conversation Tags~~ ✅ COMPLETED (Oct 30, 2025) - Organize with custom tags

Low Priority (Future Features)

User Authentication - Multi-user support with accounts
Cloud Storage - Sync conversations across devices
More AI Models - Support for Claude, GPT-4, etc.
Voice Input - Speech-to-text for messages
Collaborative Chats - Share conversations with others
Multi-Model Support - Switch between AI models
Collaborative Features - Share conversations, team workspaces
Voice Integration - Speech-to-text and text-to-speech

Polish & Documentation

Screenshots & Media - Add screenshots to README and documentation
Demo Video/GIF - Create visual walkthrough of features
Deployment Guide - Step-by-step deployment instructions (Vercel, Netlify, Azure)
Contributing Guidelines - Detailed contribution workflow and standards
API Documentation - Document Genkit flows and server actions
Architecture Diagrams - Visual representation of app structure

See detailed roadmap: Daily Logs

🧪 Testing

This project has comprehensive test coverage:

Unit Tests: Component and utility testing with Jest
Integration Tests: AI flow testing with 92%+ coverage
E2E Tests: Browser automation with Playwright

Quick Commands:

npm test                    # Run Jest tests
npm run test:e2e           # Run Playwright E2E tests
npm run test:coverage      # Generate coverage report
npx playwright show-report # View E2E test report

Current Status:

688 tests (675 passing, 13 skipped)
20+ E2E tests with Playwright
66.92% statement coverage, 81.20% branch coverage, 54.85% function coverage
CI/CD pipeline with automated checks

For complete testing guide, see Testing Documentation.

📖 Learn More

Documentation

Full Documentation - Complete documentation index
Testing Guide - Quick testing reference
Project Blueprint - Design vision
Theme Toggle Feature - Feature example

External Resources

🤝 Contributing

Contributions are welcome! Please see:

Development Guide - How to contribute
Git Commit Guide - Commit standards
Testing Guide - How to write tests

Development Workflow:

Fork the repository
Create a feature branch
Make your changes
Write/update tests
Update documentation
Submit a pull request

📊 Project Metrics

Metric	Value	Last Updated
Lines of Code	~7,500+ lines	Nov 4, 2025
Documentation	~25,000+ lines	Nov 4, 2025
Tests	688 tests (675 passing, 13 skipped)	Nov 4, 2025
Test Coverage	66.92% statements, 81.20% branches, 54.85% functions	Nov 4, 2025
Components	32+ reusable UI components	Nov 4, 2025
AI Flows	6 Genkit flows	Nov 4, 2025
Custom Hooks	7 hooks	Nov 4, 2025

📝 License

This project is open source. See the LICENSE file for details.

🙏 Acknowledgments

Built with:

Next.js by Vercel
Google Genkit by Google
ShadCN UI by shadcn
Tailwind CSS by Tailwind Labs

Last Updated: November 4, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📄 DocuNote

✨ Features

🚀 Recent Updates

November 4, 2025 - Major Test Coverage Improvements 🎯

November 4, 2025 - Stable Conversation Sorting & Pin Feature ⭐

November 4, 2025 - Conversation Title UI Fix 🐛

November 2, 2025 - Enhanced Conversation Management

October 30, 2025 - Extended File Type Support 📄

�🚀 Getting Started

Prerequisites

Installation

Quick Testing

📚 Documentation

🛠️ Tech Stack

Frontend

AI & Backend

Development & Testing

🎯 Project Status

✅ What's Working (Nov 4, 2025)

🚧 Known Limitations

🔮 Next Steps & Roadmap

High Priority (Production Ready)

Medium Priority (Enhanced UX)

Low Priority (Future Features)

Polish & Documentation

🧪 Testing

📖 Learn More

Documentation

External Resources

🤝 Contributing

📊 Project Metrics

📝 License

🙏 Acknowledgments

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

📄 DocuNote

✨ Features

🚀 Recent Updates

November 4, 2025 - Major Test Coverage Improvements 🎯

November 4, 2025 - Stable Conversation Sorting & Pin Feature ⭐

November 4, 2025 - Conversation Title UI Fix 🐛

November 2, 2025 - Enhanced Conversation Management

October 30, 2025 - Extended File Type Support 📄

�🚀 Getting Started

Prerequisites

Installation

Quick Testing

📚 Documentation

🛠️ Tech Stack

Frontend

AI & Backend

Development & Testing

🎯 Project Status

✅ What's Working (Nov 4, 2025)

🚧 Known Limitations

🔮 Next Steps & Roadmap

High Priority (Production Ready)

Medium Priority (Enhanced UX)

Low Priority (Future Features)

Polish & Documentation

🧪 Testing

📖 Learn More

Documentation

External Resources

🤝 Contributing

📊 Project Metrics

📝 License

🙏 Acknowledgments