Keep/docs/source-tree-analysis.md

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