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
379 lines
14 KiB
Markdown
379 lines
14 KiB
Markdown
# 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
|