sepehr
640fcb26f7
## Bug Fixes ### Note Card Actions - Fix broken size change functionality (missing state declaration) - Implement React 19 useOptimistic for instant UI feedback - Add startTransition for non-blocking updates - Ensure smooth animations without page refresh - All note actions now work: pin, archive, color, size, checklist ### Markdown LaTeX Rendering - Add remark-math and rehype-katex plugins - Support inline equations with dollar sign syntax - Support block equations with double dollar sign syntax - Import KaTeX CSS for proper styling - Equations now render correctly instead of showing raw LaTeX ## Technical Details - Replace undefined currentNote references with optimistic state - Add optimistic updates before server actions for instant feedback - Use router.refresh() in transitions for smart cache invalidation - Install remark-math, rehype-katex, and katex packages ## Testing - Build passes successfully with no TypeScript errors - Dev server hot-reloads changes correctly
348 lines
8.6 KiB
Markdown
348 lines
8.6 KiB
Markdown
# Memento - Project Overview
|
|
|
|
## Project Summary
|
|
|
|
**Memento** is a Google Keep-inspired note-taking application with AI-powered features, semantic search, and MCP (Model Context Protocol) integration for workflow automation.
|
|
|
|
**Name:** Memento
|
|
**Version:** 0.2.0
|
|
**Type:** Multi-part Web Application + MCP Server
|
|
**Repository Type:** Monorepo/Multi-part
|
|
**License:** Open Source (to be published on GitHub)
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Aspect | Details |
|
|
|--------|---------|
|
|
| **Primary Language** | TypeScript (keep-notes), JavaScript (mcp-server) |
|
|
| **Architecture** | Full-stack JAMstack (Next.js) + Microservice API (Express) |
|
|
| **Database** | SQLite with Prisma ORM |
|
|
| **Authentication** | NextAuth.js v5 with email/password |
|
|
| **AI Integration** | Vercel AI SDK (OpenAI, Ollama) |
|
|
| **State Management** | React Context + Custom Hooks |
|
|
| **Testing** | Playwright (E2E) |
|
|
| **Deployment** | Docker (planned) |
|
|
|
|
---
|
|
|
|
## Tech Stack Summary
|
|
|
|
### keep-notes (Web Application)
|
|
|
|
**Frontend:**
|
|
- Next.js 16.1.1 (App Router)
|
|
- React 19.2.3
|
|
- TypeScript 5
|
|
- Tailwind CSS 4
|
|
- Radix UI (component library)
|
|
- Lucide React (icons)
|
|
|
|
**Backend (Integrated):**
|
|
- Next.js API Routes
|
|
- Prisma 5.22.0 (ORM)
|
|
- SQLite (better-sqlite3)
|
|
|
|
**Auth:**
|
|
- NextAuth.js 5.0.0-beta.30
|
|
- bcryptjs (password hashing)
|
|
|
|
**AI/LLM:**
|
|
- Vercel AI SDK 6.0.23
|
|
- OpenAI Provider
|
|
- Ollama Provider (local models)
|
|
|
|
**Features:**
|
|
- PWA (@ducanh2912/next-pwa)
|
|
- Markdown (react-markdown)
|
|
- Drag & Drop (@dnd-kit)
|
|
- Grid Layout (Muuri, react-grid-layout)
|
|
- Email (nodemailer)
|
|
|
|
### mcp-server (Backend API)
|
|
|
|
**Backend:**
|
|
- Express.js 4.22.1
|
|
- Node.js (ES modules)
|
|
- Prisma 5.22.0 (ORM)
|
|
|
|
**Protocol:**
|
|
- MCP SDK 1.0.4 (Model Context Protocol)
|
|
- Stdio transport
|
|
- Shared SQLite database
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
D:/dev_new_pc/Keep/
|
|
├── keep-notes/ # Next.js web application
|
|
│ ├── app/ # Next.js App Router
|
|
│ │ ├── (auth)/ # Authentication routes
|
|
│ │ ├── (main)/ # Main application routes
|
|
│ │ ├── api/ # API endpoints
|
|
│ │ ├── actions/ # Server actions
|
|
│ │ ├── components/ # UI components
|
|
│ │ ├── context/ # React contexts
|
|
│ │ ├── hooks/ # Custom hooks
|
|
│ │ └── lib/ # Utilities
|
|
│ ├── components/ # Shared components
|
|
│ ├── prisma/ # Database schema & migrations
|
|
│ ├── tests/ # Playwright E2E tests
|
|
│ └── public/ # Static assets
|
|
│
|
|
├── mcp-server/ # MCP integration server
|
|
│ ├── index.js # Main MCP server (stdio)
|
|
│ ├── index-sse.js # SSE variant
|
|
│ └── prisma/ # Shared DB client
|
|
│
|
|
├── docs/ # Generated documentation
|
|
├── _bmad/ # BMAD framework artifacts
|
|
├── _bmad-output/ # BMAD workflow outputs
|
|
│ ├── planning-artifacts/ # PRD, epics, architecture
|
|
│ └── implementation-artifacts/ # Stories, sprint status
|
|
│
|
|
└── [Root files]
|
|
├── README.md
|
|
├── CHANGELOG.md
|
|
├── MCP-GUIDE.md
|
|
└── Various technical docs
|
|
```
|
|
|
|
---
|
|
|
|
## Project Parts
|
|
|
|
### 1. keep-notes (Web App)
|
|
- **Path:** `D:/dev_new_pc/Keep/keep-notes`
|
|
- **Type:** Web Application (Next.js)
|
|
- **Purpose:** Main user interface for note-taking
|
|
- **Technology:** Next.js + React + TypeScript
|
|
- **Entry Point:** `app/layout.tsx`
|
|
|
|
### 2. mcp-server (Backend)
|
|
- **Path:** `D:/dev_new_pc/Keep/mcp-server`
|
|
- **Type:** Backend API (Express)
|
|
- **Purpose:** MCP protocol integration for N8N and AI assistants
|
|
- **Technology:** Express + MCP SDK + Prisma
|
|
- **Entry Point:** `index.js`
|
|
|
|
---
|
|
|
|
## Architecture Type
|
|
|
|
**Pattern:** Full-stack Monolith with Microservice Extension
|
|
|
|
**keep-notes:**
|
|
- JAMstack architecture with Next.js App Router
|
|
- Server-side rendering (SSR)
|
|
- API routes integrated
|
|
- Server Actions for mutations
|
|
- Client-side state with React Context
|
|
|
|
**mcp-server:**
|
|
- Separate microservice
|
|
- Protocol-based API (MCP)
|
|
- Shared database layer
|
|
- Standalone execution
|
|
|
|
---
|
|
|
|
## Integration Between Parts
|
|
|
|
**Database Sharing:**
|
|
- Both parts connect to the same SQLite database
|
|
- `keep-notes/prisma/dev.db` is the single source of truth
|
|
- MCP server reads/writes directly to this file
|
|
|
|
**Communication:**
|
|
- Web app uses REST/Next.js API routes
|
|
- MCP server exposes MCP protocol tools
|
|
- No direct HTTP calls between parts
|
|
- Communication is database-mediated
|
|
|
|
**Deployment:**
|
|
- Can be deployed together or separately
|
|
- Docker Compose can orchestrate both services
|
|
- Environment variables control configuration
|
|
|
|
---
|
|
|
|
## Key Features
|
|
|
|
### User Features
|
|
- ✅ Rich text notes with markdown support
|
|
- ✅ Checklist notes
|
|
- ✅ Color-coded notes
|
|
- ✅ Labeling/tagging system
|
|
- ✅ Pinning and archiving
|
|
- ✅ Image attachments
|
|
- ✅ Reminders with recurrence
|
|
- ✅ Drag-and-drop grid layout
|
|
- ✅ Semantic search (vector embeddings)
|
|
- ✅ AI-powered auto-tagging
|
|
- ✅ User authentication (email/password)
|
|
- ✅ User profile management
|
|
- ✅ Admin panel
|
|
|
|
### Technical Features
|
|
- ✅ PWA (Progressive Web App)
|
|
- ✅ Responsive design
|
|
- ✅ E2E testing (Playwright)
|
|
- ✅ MCP integration (N8N workflows)
|
|
- ✅ Multiple AI providers (OpenAI, Ollama)
|
|
- ✅ Email notifications
|
|
- ✅ Cron job support (reminders)
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Node.js 20+
|
|
- npm or yarn
|
|
- SQLite3 (included via better-sqlite3)
|
|
|
|
### Installation (Current)
|
|
```bash
|
|
# Install dependencies
|
|
cd keep-notes
|
|
npm install
|
|
|
|
# Generate Prisma client
|
|
npm run db:generate
|
|
|
|
# Run development server
|
|
npm run dev
|
|
|
|
# Access app at http://localhost:3000
|
|
```
|
|
|
|
### MCP Server
|
|
```bash
|
|
cd mcp-server
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
**Current Status:**
|
|
- Active development on `bmad-features` branch
|
|
- Sprint status tracking implemented
|
|
- 6 stories completed
|
|
- PRD and Epics defined
|
|
- Implementation readiness reviewed
|
|
|
|
**Next Steps:**
|
|
1. Docker containerization
|
|
2. Complete documentation
|
|
3. Code review and cleanup
|
|
4. Monetization strategy
|
|
5. GitHub release preparation
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
**Generated Documentation:**
|
|
- [API Contracts - keep-notes](./api-contracts-keep-notes.md)
|
|
- [API Contracts - mcp-server](./api-contracts-mcp-server.md)
|
|
- [Data Models](./data-models.md)
|
|
- [Project Overview](./project-overview.md) (this file)
|
|
|
|
**Existing Documentation:**
|
|
- [README.md](../README.md) - Main project README
|
|
- [CHANGELOG.md](../CHANGELOG.md) - Version history
|
|
- [COMPLETED-FEATURES.md](../COMPLETED-FEATURES.md) - Feature list
|
|
- [MCP-GUIDE.md](../MCP-GUIDE.md) - MCP setup guide
|
|
- [MCP-SSE-ANALYSIS.md](../MCP-SSE-ANALYSIS.md) - SSE implementation notes
|
|
- [N8N-MCP-SETUP.md](../N8N-MCP-SETUP.md) - N8N integration guide
|
|
|
|
**Planning Artifacts:**
|
|
- `_bmad-output/planning-artifacts/prd.md` - Product Requirements Document
|
|
- `_bmad-output/planning-artifacts/epics.md` - Epic definitions
|
|
- `_bmad-output/implementation-artifacts/` - User stories and sprint tracking
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
**E2E Tests:** Playwright
|
|
```bash
|
|
cd keep-notes
|
|
npm test # Run all tests
|
|
npm run test:ui # Run with UI
|
|
npm run test:headed # Run in headed mode
|
|
```
|
|
|
|
**Test Results:** `keep-notes/test-results/`
|
|
**Playwright Report:** `keep-notes/playwright-report/`
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
**Environment Variables:** `.env` (root, keep-notes/, mcp-server/)
|
|
|
|
**Key Variables:**
|
|
- `DATABASE_URL` - SQLite database path
|
|
- `NEXTAUTH_SECRET` - Auth session secret
|
|
- `NEXTAUTH_URL` - Application URL
|
|
- Email configuration (SMTP)
|
|
- AI provider API keys (OpenAI, Ollama)
|
|
|
|
**See:** `.env.example` (if available) or ask for setup details
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
**Current:** Manual deployment
|
|
**Planned:** Docker Compose setup
|
|
|
|
**Target:** GitHub release with:
|
|
- Docker images for both services
|
|
- Docker Compose orchestration
|
|
- Environment configuration guide
|
|
- Deployment documentation
|
|
|
|
---
|
|
|
|
## Future Enhancements
|
|
|
|
**Requested Features:**
|
|
1. Complete Docker setup (docker-compose.yml)
|
|
2. Comprehensive installation documentation
|
|
3. Code review and test code cleanup
|
|
4. "Pay me a coffee" monitization
|
|
5. Business model analysis (open source monetization)
|
|
6. MCP feature restoration and enhancement
|
|
|
|
**Technical Debt:**
|
|
- Remove test/debug code before release
|
|
- Improve error handling
|
|
- Add comprehensive logging
|
|
- Implement rate limiting
|
|
- Add monitoring/observability
|
|
|
|
---
|
|
|
|
## License & Business Model
|
|
|
|
**License:** Open Source (to be determined - MIT/Apache/etc.)
|
|
**Monetization:** Under evaluation
|
|
**Status:** Preparing for GitHub public release
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
**Issues:** GitHub Issues (once published)
|
|
**Documentation:** See `/docs` folder
|
|
**Technical Guides:** Root-level markdown files
|