# 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
