sepehr/Keep
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Keep/README.md

433 lines
12 KiB
Markdown
Raw Blame History

# Memento - Your Digital Notepad ☕
A beautiful and functional note-taking app inspired by Google Keep, built with Next.js 16, TypeScript, Tailwind CSS 4, and Prisma.
## 🌟 Support Memento
**Memento is 100% free and open-source!** If you find it useful, please consider supporting its development:
- **[☕ Buy me a coffee on Ko-fi](https://ko-fi.com/yourusername)** - One-time or monthly support
- **[💚 Sponsor on GitHub](https://github.com/sponsors/yourusername)** - Recurring support
- **[⭐ Star on GitHub](https://github.com/yourusername/memento)** - Free way to show support
Your support helps:
- ☕ Keep the developer fueled with coffee
- 🐛 Cover hosting and server costs (~$50/month)
- ✨ Fund development of new features
- 📚 Improve documentation
- 🌍 Keep Memento 100% open-source
---
## 🚀 Project Location
The complete application is in the `keep-notes/` directory.
## ✅ Completed Features
### Core Functionality
- ✅ Create, read, update, delete notes
- ✅ Text notes and checklist notes
- ✅ Pin/unpin notes
- ✅ Archive/unarchive notes
- ✅ Real-time search across all notes
- ✅ Color customization (10 soft pastel themes)
- ✅ Label management
- ✅ Responsive masonry grid layout
- ✅ Drag-and-drop note reordering
- ✅ **Image upload with original size preservation**
### UI/UX Features
- ✅ Expandable note input (Google Keep style)
- ✅ Modal note editor with full editing (`!max-w-[min(95vw,1600px)]`)
- ✅ **Images display at original dimensions** (no cropping, `h-auto` without `w-full`)
- ✅ Hover effects and smooth animations
- ✅ **Masonry layout with CSS columns** (responsive: 1-5 columns)
- ✅ **Soft pastel color themes** (bg-red-50, bg-blue-50, etc.)
- ✅ Dark mode with system preference
- ✅ Mobile responsive design
- ✅ Icon-based navigation with 9 toolbar icons
- ✅ Toast notifications (via shadcn)
### Integration Features
- ✅ **REST API** (4 endpoints: GET, POST, PUT, DELETE)
- `/api/notes` - List all notes
- `/api/notes` - Create new note
- `/api/notes/[id]` - Update note
- `/api/notes/[id]` - Delete note
- ✅ **MCP Server** (Model Context Protocol) with 9 tools:
- `getNotes` - Fetch all notes
- `createNote` - Create new note
- `updateNote` - Update existing note
- `deleteNote` - Delete note
- `searchNotes` - Search notes by query
- `getNoteById` - Get specific note
- `archiveNote` - Archive/unarchive note
- `pinNote` - Pin/unpin note
- `addLabel` - Add label to note
### Technical Features
- ✅ Next.js 16 with App Router & Turbopack
- ✅ Server Actions for mutations
- ✅ TypeScript throughout
- ✅ Tailwind CSS 4
- ✅ shadcn/ui components (11 components)
- ✅ Prisma ORM 5.22.0 with SQLite
- ✅ Type-safe database operations
- ✅ **Base64 image encoding** (FileReader.readAsDataURL)
- ✅ **@modelcontextprotocol/sdk** v1.0.4
## 🏃 Quick Start
```bash
cd keep-notes
npm install
npx prisma generate
npx prisma migrate dev
npm run dev
```
Then open http://localhost:3000
## 📱 Application Features
### 1. Note Creation
- Click the input field to expand
- Add title and content
- **Upload images** (displayed at original size)
- Switch to checklist mode with one click
- Add labels and choose from 10 soft pastel colors
### 2. Note Management
- **Edit**: Click any note to open the editor (max-width: 95vw or 1600px)
- **Pin**: Click pin icon to keep notes at top
- **Archive**: Move notes to archive
- **Delete**: Remove notes permanently
- **Color**: Choose from 10 beautiful pastel colors
- **Labels**: Add multiple labels
- **Images**: Upload images that preserve original dimensions
### 3. Checklist Notes
- Create todo lists
- Check/uncheck items
- Add/remove items dynamically
- Strike-through completed items
### 4. Search & Navigation
- Real-time search in header
- Search by title or content
- Navigate to Archive page
- Dark/light mode toggle
### 5. API Integration
Use the REST API to integrate with other services:
```bash
# Get all notes
curl http://localhost:3000/api/notes
# Create a note
curl -X POST http://localhost:3000/api/notes \
-H "Content-Type: application/json" \
-d '{"title":"API Note","content":"Created via API"}'
# Update a note
curl -X PUT http://localhost:3000/api/notes/1 \
-H "Content-Type: application/json" \
-d '{"title":"Updated","content":"Modified via API"}'
# Delete a note
curl -X DELETE http://localhost:3000/api/notes/1
```
### 6. MCP Server for AI Agents
Start the MCP server for integration with Claude, N8N, or other MCP clients:
```bash
cd keep-notes
npm run mcp
```
The MCP server exposes 9 tools for AI agents to interact with your notes:
- Create, read, update, and delete notes
- Search notes by content
- Manage pins, archives, and labels
- Perfect for N8N workflows, Claude Desktop, or custom integrations
Example N8N workflow available in: `n8n-memento-workflow.json`
## 🛠️ Tech Stack
- **Frontend**: Next.js 16, React, TypeScript, Tailwind CSS 4
- **UI Components**: shadcn/ui (11 components: Dialog, Tooltip, Badge, etc.)
- **Icons**: Lucide React (Bell, Image, UserPlus, Palette, Archive, etc.)
- **Backend**: Next.js Server Actions
- **Database**: Prisma ORM 5.22.0 + SQLite (upgradeable to PostgreSQL)
- **Styling**: Tailwind CSS 4 with soft pastel themes (bg-*-50)
- **Layout**: CSS columns for masonry grid (responsive 1-5 columns)
- **Images**: Base64 encoding, original size preservation
- **Integration**: REST API + MCP Server (@modelcontextprotocol/sdk v1.0.4)
## 📂 Project Structure
```
keep-notes/
├── app/
│ ├── actions/notes.ts # Server actions (CRUD + images)
│ ├── api/notes/ # REST API endpoints
│ ├── archive/page.tsx # Archive page
│ ├── layout.tsx # Root layout
│ └── page.tsx # Home page
├── components/
│ ├── ui/ # shadcn components
│ ├── header.tsx # Navigation
│ ├── note-card.tsx # Note display (masonry, images)
│ ├── note-editor.tsx # Note editing (!max-w-[95vw])
│ ├── note-input.tsx # Note creation (image upload)
│ └── note-grid.tsx # Masonry layout
├── lib/
│ ├── types.ts # TypeScript types (Note with images)
│ └── utils.ts # Utilities
├── prisma/
│ ├── schema.prisma # Database schema (images String?)
│ └── dev.db # SQLite database
├── mcp/
│ └── server.ts # MCP server (9 tools)
└── package.json # Scripts: dev, build, start, mcp
```
│ ├── note-editor.tsx # Edit modal
│ ├── note-grid.tsx # Grid layout
│ └── note-input.tsx # Note creation
├── lib/
│ ├── prisma.ts # DB client
│ ├── types.ts # TypeScript types
│ └── utils.ts # Utilities
└── prisma/
├── schema.prisma # Database schema
└── migrations/ # DB migrations
```
## 🎨 Color Themes
The app includes 10 color themes:
- Default (White)
- Red
- Orange
- Yellow
- Green
- Teal
- Blue
- Purple
- Pink
- Gray
All themes support dark mode!
## 🔧 Configuration
### Database
Currently uses SQLite. To switch to PostgreSQL:
1. Edit `prisma/schema.prisma`:
```prisma
datasource db {
provider = "postgresql"
}
```
2. Update `prisma.config.ts` with PostgreSQL URL
3. Run: `npx prisma migrate dev`
### Environment Variables
Located in `.env`:
```
DATABASE_URL="file:./dev.db"
```
## 🚀 Deployment
### 🐳 Docker Deployment (Recommended for Proxmox)
Keep Notes includes complete Docker configuration for easy deployment on Proxmox or any Docker host.
#### Quick Start
```bash
cd keep-notes
# Create environment file
cat > .env << EOF
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=$(openssl rand -base64 32)
EOF
# Build and start
docker-compose build
docker-compose up -d
# Access at http://localhost:3000
```
#### Deployment Script
We provide an automation script for common tasks:
```bash
chmod +x deploy.sh
# Build image
./deploy.sh build
# Start containers
./deploy.sh start
# View logs
./deploy.sh logs
# Backup database
./deploy.sh backup
# Update application
./deploy.sh update
```
#### Features
- ✅ **Multi-stage Docker build** for optimized image size
- ✅ **Persistent volumes** for database and uploads
- ✅ **Health checks** for automatic restart
- ✅ **Resource limits** for stable performance
- ✅ **Ollama support** for local AI models (optional)
- ✅ **Nginx reverse proxy** configuration included
- ✅ **Automated backups** with cron scripts
#### Architecture
```
keep-notes/
├── Dockerfile # Multi-stage build
├── docker-compose.yml # Container orchestration
├── .dockerignore # Build optimization
├── deploy.sh # Deployment automation
└── DOCKER_DEPLOYMENT.md # Complete guide
```
#### Supported Platforms
- **Proxmox VE** (LXC containers or VMs)
- **Docker hosts** (Linux, Windows, macOS)
- **Cloud providers** (AWS, GCP, Azure)
- **Kubernetes** (via Docker Compose)
#### AI Features Setup
**Option 1: OpenAI (Cloud)**
```yaml
# In .env or docker-compose.yml
OPENAI_API_KEY=sk-your-key-here
```
**Option 2: Ollama (Local AI)**
```bash
# Uncomment ollama service in docker-compose.yml
./deploy.sh start
./deploy.sh ollama-pull granite4
```
#### Documentation
See [DOCKER_DEPLOYMENT.md](keep-notes/DOCKER_DEPLOYMENT.md) for:
- Complete Proxmox deployment guide
- SSL/HTTPS configuration with Let's Encrypt
- Database backup and restore procedures
- Performance tuning and resource recommendations
- Troubleshooting common issues
- Security best practices
### ☁️ Vercel (Alternative)
For serverless deployment:
```bash
cd keep-notes
npm run build
vercel deploy
```
### 📦 Traditional Deployment
For traditional VPS or bare metal:
```bash
cd keep-notes
npm install
npx prisma generate
npx prisma migrate deploy
npm run build
npm start
```
## 📝 Development Notes
### Server Actions
All CRUD operations use Next.js Server Actions:
- `createNote()` - Create new note
- `updateNote()` - Update existing note
- `deleteNote()` - Delete note
- `getNotes()` - Fetch all notes
- `searchNotes()` - Search notes
- `togglePin()` - Pin/unpin
- `toggleArchive()` - Archive/unarchive
### Type Safety
Full TypeScript coverage with interfaces:
- `Note` - Main note type
- `CheckItem` - Checklist item
- `NoteColor` - Color themes
### Responsive Design
- Mobile: Single column
- Tablet: 2 columns
- Desktop: 3-4 columns
- Auto-adjusts with window size
## 🎯 Future Enhancements
Possible additions:
- [x] User authentication (NextAuth.js) ✅ Already implemented!
- [ ] Real-time collaboration
- [x] Image uploads ✅ Already implemented!
- [ ] Rich text editor
- [ ] Note sharing
- [x] Reminders ✅ Already implemented!
- [ ] Export to PDF/Markdown
- [ ] Voice notes
- [ ] Drawing support
## 🤝 Contributing
We welcome contributions! Please feel free to:
- **Report bugs**: [Open an issue](https://github.com/yourusername/memento/issues)
- **Suggest features**: [Start a discussion](https://github.com/yourusername/memento/discussions)
- **Submit pull requests**: Fork and create a PR
- **Share feedback**: [Support page](/support)
## ☕ Support Development
Enjoying Memento? Consider supporting its development:
- **[Donate on Ko-fi](https://ko-fi.com/yourusername)** - Buy me a coffee ☕
- **[GitHub Sponsors](https://github.com/sponsors/yourusername)** - Monthly sponsorship 💚
- **[Star the repo](https://github.com/yourusername/memento)** - It's free! ⭐
## 📄 License
MIT License - feel free to use for personal or commercial projects!
---
**Built with ❤️ and ☕ using Next.js 16, TypeScript, and Tailwind CSS 4**
Server running at: http://localhost:3000
**⭐ If you like Memento, please consider giving it a star on GitHub!**
Reference in New Issue View Git Blame Copy Permalink