fix: improve note interactions and markdown LaTeX support
## 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
This commit is contained in:
378
docs/source-tree-analysis.md
Normal file
378
docs/source-tree-analysis.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# Source Tree Analysis - Memento Project
|
||||
|
||||
## Overview
|
||||
|
||||
Complete directory structure analysis for the Memento note-taking application, a multi-part project consisting of a Next.js web application and an Express-based MCP server.
|
||||
|
||||
---
|
||||
|
||||
## Repository Root Structure
|
||||
|
||||
```
|
||||
D:/dev_new_pc/Keep/
|
||||
├── keep-notes/ # Main Next.js web application
|
||||
├── mcp-server/ # MCP integration server
|
||||
├── docs/ # Generated documentation
|
||||
├── _bmad/ # BMAD framework configuration
|
||||
├── _bmad-output/ # BMAD workflow artifacts
|
||||
│ ├── planning-artifacts/ # PRD, epics, architecture docs
|
||||
│ └── implementation-artifacts/ # Stories, sprint tracking
|
||||
├── node_modules/ # Root dependencies
|
||||
├── package-lock.json # Root lock file
|
||||
├── .git/ # Git repository
|
||||
├── .github/ # GitHub-specific files
|
||||
└── [Root level docs] # README.md, CHANGELOG.md, etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## keep-notes/ - Web Application
|
||||
|
||||
### Application Structure (Next.js App Router)
|
||||
|
||||
```
|
||||
keep-notes/
|
||||
├── app/ # Next.js App Router directory
|
||||
│ ├── (auth)/ # Auth route group
|
||||
│ │ ├── forgot-password/ # Password reset flow
|
||||
│ │ ├── login/ # Login page
|
||||
│ │ ├── register/ # Registration page
|
||||
│ │ └── reset-password/ # Reset password page
|
||||
│ ├── (main)/ # Main app route group
|
||||
│ │ ├── admin/ # Admin panel
|
||||
│ │ │ └── settings/ # Admin settings page
|
||||
│ │ ├── archive/ # Archived notes view
|
||||
│ │ ├── settings/ # User settings
|
||||
│ │ │ └── profile/ # User profile settings
|
||||
│ │ ├── page.tsx # Home/main page
|
||||
│ │ └── layout.tsx # Main layout
|
||||
│ ├── debug-search/ # Debug search interface
|
||||
│ ├── actions/ # Server actions
|
||||
│ │ ├── notes.ts # Note mutations
|
||||
│ │ ├── register.ts # User registration
|
||||
│ │ ├── scrape.ts # Web scraping
|
||||
│ │ └── [other actions]
|
||||
│ ├── api/ # API routes
|
||||
│ │ ├── admin/ # Admin endpoints
|
||||
│ │ │ ├── randomize-labels/ # Label randomization
|
||||
│ │ │ └── sync-labels/ # Label sync
|
||||
│ │ ├── ai/ # AI endpoints
|
||||
│ │ │ ├── tags/ # Auto-tagging
|
||||
│ │ │ └── test/ # AI testing
|
||||
│ │ ├── auth/ # Authentication
|
||||
│ │ │ └── [...nextauth]/ # NextAuth handler
|
||||
│ │ ├── cron/ # Scheduled jobs
|
||||
│ │ │ └── reminders/ # Reminder cron
|
||||
│ │ ├── debug/ # Debug endpoints
|
||||
│ │ │ └── search/ # Search debug
|
||||
│ │ ├── labels/ # Label CRUD
|
||||
│ │ │ └── [id]/ # Single label ops
|
||||
│ │ ├── notes/ # Note CRUD
|
||||
│ │ │ └── [id]/ # Single note ops
|
||||
│ │ └── upload/ # File uploads
|
||||
│ ├── globals.css # Global styles
|
||||
│ └── layout.tsx # Root layout
|
||||
│
|
||||
├── components/ # React components
|
||||
│ ├── ui/ # Radix UI components
|
||||
│ ├── editor-images.tsx # Image editor
|
||||
│ ├── ghost-tags.tsx # Tag display
|
||||
│ ├── header-wrapper.tsx # Header wrapper
|
||||
│ ├── header.tsx # Main header
|
||||
│ ├── label-badge.tsx # Label badges
|
||||
│ ├── label-filter.tsx # Label filtering
|
||||
│ ├── label-management-dialog.tsx # Label manager
|
||||
│ ├── label-manager.tsx # Label management
|
||||
│ ├── label-selector.tsx # Label selection
|
||||
│ ├── login-form.tsx # Login form
|
||||
│ ├── markdown-content.tsx # Markdown renderer
|
||||
│ ├── masonry-grid.tsx # Masonry layout
|
||||
│ ├── note-actions.tsx # Note actions menu
|
||||
│ ├── note-card.tsx # Note card component
|
||||
│ ├── note-checklist.tsx # Checklist component
|
||||
│ ├── note-editor.tsx # Note editor
|
||||
│ ├── note-images.tsx # Note images
|
||||
│ ├── note-input.tsx # Note input
|
||||
│ ├── register-form.tsx # Registration form
|
||||
│ ├── reminder-dialog.tsx # Reminder dialog
|
||||
│ ├── sidebar.tsx # Sidebar
|
||||
│ └── [20+ more components]
|
||||
│
|
||||
├── context/ # React Context providers
|
||||
│ └── [Context files]
|
||||
│
|
||||
├── hooks/ # Custom React hooks
|
||||
│ └── [Hook files]
|
||||
│
|
||||
├── lib/ # Utilities and libraries
|
||||
│ ├── ai/ # AI integration
|
||||
│ │ ├── providers/ # AI provider implementations
|
||||
│ │ │ ├── ollama.ts # Ollama provider
|
||||
│ │ │ └── [other providers]
|
||||
│ │ ├── factory.ts # Provider factory
|
||||
│ │ └── types.ts # AI types
|
||||
│ ├── prisma.ts # Prisma client
|
||||
│ ├── types.ts # TypeScript types
|
||||
│ └── utils.ts # Utility functions
|
||||
│
|
||||
├── prisma/ # Database schema and migrations
|
||||
│ ├── schema.prisma # Database schema
|
||||
│ ├── dev.db # SQLite database
|
||||
│ ├── client-generated/ # Generated Prisma client
|
||||
│ └── migrations/ # Database migrations
|
||||
│ ├── 20260104094125_init # Initial schema
|
||||
│ ├── 20260104102002_init # Additional init
|
||||
│ ├── 20260104102801_add_order # Note ordering
|
||||
│ ├── 20260104105155_add_images # Image support
|
||||
│ ├── 20260104140638_add_reminder # Reminders
|
||||
│ ├── 20260104144627_add_markdown # Markdown
|
||||
│ ├── 20260104145004_add_reminder_recurrence # Recurrence
|
||||
│ ├── 20260104145141_add_auth_models # Auth models
|
||||
│ ├── 20260104203746_add_labels_table # Labels
|
||||
│ ├── 20260106201929_add_reminder_done # Reminder done flag
|
||||
│ ├── 20260106213349_add_links # Links field
|
||||
│ ├── 20260106215037_add_auth # Additional auth
|
||||
│ └── 20260108220408_add_embedding # Vector embeddings
|
||||
│
|
||||
├── tests/ # Playwright E2E tests
|
||||
│ └── search-quality/ # Search quality tests
|
||||
│ └── search-quality.spec.ts
|
||||
│
|
||||
├── playwright-report/ # Playwright test reports
|
||||
│ └── index.html
|
||||
│
|
||||
├── test-results/ # Test execution results
|
||||
│ └── .last-run.json
|
||||
│
|
||||
├── public/ # Static assets
|
||||
│ ├── icons/ # Icon files
|
||||
│ ├── manifest.json # PWA manifest
|
||||
│ └── uploads/ # User uploads
|
||||
│ └── notes/ # Note attachments
|
||||
│
|
||||
├── scripts/ # Utility scripts
|
||||
│ ├── check-labels-userid.js # Label migration
|
||||
│ ├── debug-smtp.js # SMTP debug
|
||||
│ ├── diagnose-mail.js # Mail diagnosis
|
||||
│ ├── fix-labels-userid.js # Fix labels
|
||||
│ ├── promote-admin.js # Admin promotion
|
||||
│ └── [other scripts]
|
||||
│
|
||||
├── types/ # TypeScript type definitions
|
||||
│ └── [Type files]
|
||||
│
|
||||
├── auth.config.ts # NextAuth configuration
|
||||
├── auth.ts # Auth export
|
||||
├── next.config.ts # Next.js configuration
|
||||
├── package.json # Dependencies
|
||||
├── playwright.config.ts # Playwright E2E config
|
||||
├── postcss.config.mjs # PostCSS config
|
||||
├── tsconfig.json # TypeScript config
|
||||
└── [config files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## mcp-server/ - MCP Integration Server
|
||||
|
||||
```
|
||||
mcp-server/
|
||||
├── index.js # Main MCP server (stdio transport)
|
||||
├── index-sse.js # SSE variant (Server-Sent Events)
|
||||
├── package.json # Dependencies
|
||||
├── README.md # Server documentation
|
||||
├── README-SSE.md # SSE documentation
|
||||
├── N8N-CONFIG.md # N8N configuration guide
|
||||
├── prisma/ # Shared Prisma client
|
||||
│ └── [Prisma client files]
|
||||
└── [server files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Directories Explained
|
||||
|
||||
### Application Routes (app/)
|
||||
- **(auth)/**: Authentication pages (login, register, password reset)
|
||||
- **(main)/**: Main application interface after auth
|
||||
- **actions/**: Server actions for mutations (notes, labels, auth)
|
||||
- **api/**: REST API endpoints
|
||||
|
||||
### Components (components/)
|
||||
- **ui/**: Reusable Radix UI primitives
|
||||
- **20+ domain components**: Note-related, label-related, auth-related
|
||||
|
||||
### State Management (context/ & hooks/)
|
||||
- React Context providers for global state
|
||||
- Custom hooks for component logic
|
||||
|
||||
### Database (prisma/)
|
||||
- Schema definition in schema.prisma
|
||||
- 13 migrations showing schema evolution
|
||||
- Generated client for type-safe DB access
|
||||
|
||||
### Testing (tests/ & playwright-report/)
|
||||
- E2E tests with Playwright
|
||||
- Test reports and results
|
||||
|
||||
---
|
||||
|
||||
## File Organization Patterns
|
||||
|
||||
**Route Groups:** Parentheses in folder names `(auth)`, `(main)` create route groups without affecting URL structure
|
||||
|
||||
**Dynamic Routes:** Square brackets `[id]`, `[...nextauth]` indicate dynamic routes
|
||||
|
||||
**API Routes:** `app/api/` follows RESTful conventions
|
||||
- Resource: `/api/notes`
|
||||
- Single item: `/api/notes/[id]`
|
||||
|
||||
**Server Actions:** `app/actions/` contain server-side mutations
|
||||
|
||||
**Component Organization:** Domain-driven (note-*, label-*, auth-*)
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
**Web Application:**
|
||||
- Entry: `keep-notes/app/layout.tsx`
|
||||
- Home: `keep-notes/app/(main)/page.tsx`
|
||||
- Dev: `npm run dev` → http://localhost:3000
|
||||
|
||||
**MCP Server:**
|
||||
- Entry: `mcp-server/index.js`
|
||||
- SSE: `mcp-server/index-sse.js`
|
||||
- Run: `npm start`
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
**Database Sharing:**
|
||||
- Both parts connect to: `keep-notes/prisma/dev.db`
|
||||
- MCP server path: `../keep-notes/prisma/dev.db`
|
||||
|
||||
**Communication:**
|
||||
- No direct HTTP between parts
|
||||
- Database-mediated communication
|
||||
- Independent deployment possible
|
||||
|
||||
---
|
||||
|
||||
## Build Artifacts (Excluded from Analysis)
|
||||
|
||||
- `node_modules/` - Dependencies
|
||||
- `.next/` - Next.js build output
|
||||
- `prisma/client-generated/` - Generated Prisma client
|
||||
- `playwright-report/` - Test reports
|
||||
- `test-results/` - Test execution data
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `package.json` | Dependencies and scripts |
|
||||
| `tsconfig.json` | TypeScript configuration |
|
||||
| `next.config.ts` | Next.js framework config |
|
||||
| `playwright.config.ts` | E2E test configuration |
|
||||
| `auth.config.ts` | NextAuth authentication setup |
|
||||
| `postcss.config.mjs` | PostCSS/Tailwind config |
|
||||
| `schema.prisma` | Database schema definition |
|
||||
|
||||
---
|
||||
|
||||
## Migration History
|
||||
|
||||
The `prisma/migrations/` directory shows the evolution of the data model:
|
||||
|
||||
1. Initial schema (User, Note basics)
|
||||
2. Order field for drag-and-drop
|
||||
3. Image attachments
|
||||
4. Reminders
|
||||
5. Markdown support
|
||||
6. Reminder recurrence
|
||||
7. Authentication models (NextAuth)
|
||||
8. Labels table
|
||||
9. Reminder done flag
|
||||
10. Links field
|
||||
11. Additional auth fields
|
||||
12. Vector embeddings (AI search)
|
||||
|
||||
**Total Migrations:** 13
|
||||
**Latest:** Vector embeddings for semantic search
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
**Directory Access Patterns:**
|
||||
- Components import from: `@/components/*`, `@/lib/*`
|
||||
- Server actions: `@/app/actions/*`
|
||||
- API routes: `@/app/api/*`
|
||||
- Types: `@/lib/types`, `@/types`
|
||||
- Utils: `@/lib/utils`
|
||||
|
||||
**Import Aliases:**
|
||||
- `@/` → Project root (`keep-notes/`)
|
||||
|
||||
---
|
||||
|
||||
## Static Assets
|
||||
|
||||
**Public Files:** `keep-notes/public/`
|
||||
- PWA manifest: `manifest.json`
|
||||
- Icons: `icons/`
|
||||
- User uploads: `uploads/notes/`
|
||||
|
||||
**Note Images:** Base64 encoded in DB or uploaded to `public/uploads/notes/`
|
||||
|
||||
---
|
||||
|
||||
## Testing Structure
|
||||
|
||||
**Test Files:** `keep-notes/tests/`
|
||||
- Located at: `tests/search-quality/search-quality.spec.ts`
|
||||
- Config: `keep-notes/playwright.config.ts`
|
||||
|
||||
**Test Results:**
|
||||
- Execution: `keep-notes/test-results/.last-run.json`
|
||||
- Reports: `keep-notes/playwright-report/index.html`
|
||||
|
||||
---
|
||||
|
||||
## Key Observations
|
||||
|
||||
1. **Monorepo Structure:** Two distinct parts sharing database
|
||||
2. **Route Organization:** Clear separation between auth and main app
|
||||
3. **Component Count:** 20+ React components for notes, labels, auth
|
||||
4. **API Design:** RESTful with Next.js App Router conventions
|
||||
5. **Database Evolution:** 13 migrations showing feature growth
|
||||
6. **Testing:** E2E coverage with Playwright
|
||||
7. **State Management:** Context + hooks (no Redux/Zustand)
|
||||
8. **AI Integration:** Provider pattern in `lib/ai/providers/`
|
||||
9. **Authentication:** NextAuth v5 with Prisma adapter
|
||||
10. **PWA Support:** Progressive Web App capabilities
|
||||
|
||||
---
|
||||
|
||||
## Next Steps for Development
|
||||
|
||||
**For Feature Development:**
|
||||
1. Add new components in `components/`
|
||||
2. Create server actions in `app/actions/`
|
||||
3. Add API routes in `app/api/`
|
||||
4. Update Prisma schema and migrate
|
||||
|
||||
**For Docker Deployment:**
|
||||
1. Create Dockerfile for keep-notes
|
||||
2. Create Dockerfile for mcp-server
|
||||
3. Create docker-compose.yml
|
||||
4. Configure environment variables
|
||||
|
||||
**For Documentation:**
|
||||
1. Reference component-inventory.md for component details
|
||||
2. Reference api-contracts-*.md for API details
|
||||
3. Reference data-models.md for database schema
|
||||
Reference in New Issue
Block a user