# Recall - Resumen del Proyecto

## Fecha
2026-03-22

## Descripción
Recall es una aplicación de gestión de conocimiento personal (PKM) para captura y recuperación de notas, comandos, snippets y conocimiento técnico.

## Stack Tecnológico
- **Framework**: Next.js 16.2.1 con App Router + Turbopack
- **Base de datos**: SQLite via Prisma ORM
- **Lenguaje**: TypeScript
- **UI**: TailwindCSS + shadcn/ui components
- **Testing**: Jest (226 tests)
- **Notificaciones**: Sonner (toasts)

## Estructura del Proyecto

```
src/
├── app/
│   ├── api/
│   │   ├── notes/         # CRUD, versions, quick, backlinks, links, suggest
│   │   ├── tags/          # Tags y sugerencias
│   │   ├── search/        # Búsqueda avanzada
│   │   ├── usage/         # Tracking de uso y co-uso
│   │   ├── metrics/       # Métricas internas
│   │   ├── centrality/     # Notas centrales
│   │   ├── export-import/ # Import/export JSON, Markdown, HTML
│   │   ├── import-markdown/ # Importador Markdown mejorado
│   │   └── capture/       # Captura externa (bookmarklet)
│   ├── notes/[id]/        # Detalle de nota
│   ├── edit/[id]/         # Edición de nota
│   ├── new/               # Nueva nota
│   ├── capture/           # Página de confirmación de captura
│   └── settings/          # Configuración
├── components/
│   ├── ui/                # shadcn/ui components
│   ├── dashboard.tsx      # Dashboard inteligente
│   ├── quick-add.tsx      # Captura rápida
│   ├── note-form.tsx      # Formulario de nota
│   ├── note-connections.tsx # Panel de conexiones
│   ├── note-list.tsx      # Lista de notas
│   ├── keyboard-navigable-note-list.tsx # Lista con navegación teclado
│   ├── keyboard-hint.tsx  # Hint de atajos
│   ├── related-notes.tsx  # Notas relacionadas
│   ├── version-history.tsx # Historial de versiones
│   ├── track-note-view.tsx # Tracking de vistas
│   ├── search-bar.tsx     # Búsqueda en tiempo real
│   ├── command-palette.tsx # Command palette (Ctrl+K)
│   ├── keyboard-shortcuts-dialog.tsx # Diálogo de atajos
│   ├── shortcuts-provider.tsx # Provider de shortcuts
│   ├── work-mode-toggle.tsx # Toggle modo trabajo
│   ├── draft-recovery-banner.tsx # Banner de recuperación
│   ├── backup-restore-dialog.tsx # Restore con preview
│   ├── backup-list.tsx    # Lista de backups
│   ├── bookmarklet-instructions.tsx # Instrucciones del bookmarklet
│   ├── recent-context-list.tsx # Historial de navegación
│   ├── track-navigation-history.tsx # Tracking de historial
│   └── preferences-panel.tsx # Panel de preferencias
├── hooks/
│   ├── use-global-shortcuts.ts # Atajos globales
│   ├── use-note-list-keyboard.ts # Navegación teclado en listas
│   ├── use-unsaved-changes.ts # Guard de cambios sin guardar
│   └── ...
└── lib/
    ├── prisma.ts          # Cliente Prisma
    ├── usage.ts           # Tracking de uso y co-uso
    ├── search.ts          # Búsqueda con scoring
    ├── query-parser.ts     # Parser de queries avanzadas
    ├── versions.ts        # Historial de versiones
    ├── related.ts         # Notas relacionadas
    ├── backlinks.ts        # Sistema de enlaces [[wiki]]
    ├── tags.ts            # Normalización y sugerencias
    ├── metrics.ts         # Métricas de dashboard
    ├── centrality.ts      # Cálculo de centralidad
    ├── type-inference.ts  # Detección automática de tipo
    ├── link-suggestions.ts # Sugerencias de enlaces
    ├── features.ts        # Feature flags
    ├── validators.ts      # Zod schemas
    ├── errors.ts          # Manejo de errores
    ├── backup.ts          # Snapshot de backup
    ├── backup-storage.ts   # IndexedDB storage
    ├── backup-policy.ts    # Política de retención
    ├── backup-validator.ts # Validación de backups
    ├── restore.ts         # Restore de backups
    ├── drafts.ts          # Borradores locales
    ├── work-mode.ts       # Modo trabajo
    ├── navigation-history.ts # Historial de navegación
    ├── export-markdown.ts  # Exportación Markdown
    ├── export-html.ts     # Exportación HTML
    ├── import-markdown.ts  # Importador Markdown
    └── external-capture.ts # Captura externa
```

## Modelos de Datos

### Note
```prisma
model Note {
  id             String    @id @default(cuid())
  title          String
  content        String
  type           String    @default("note")
  isFavorite     Boolean   @default(false)
  isPinned       Boolean   @default(false)
  createdAt      DateTime  @default(now())
  updatedAt      DateTime  @updatedAt
  creationSource String    @default("form")
}
```

### NoteUsage
```prisma
model NoteUsage {
  id        String   @id @default(cuid())
  noteId    String
  eventType String
  query     String?
  createdAt DateTime @default(now())
}
```

### NoteCoUsage
```prisma
model NoteCoUsage {
  id         String @id @default(cuid())
  fromNoteId String
  toNoteId   String
  weight     Int    @default(1)
}
```

### NoteVersion
```prisma
model NoteVersion {
  id        String   @id @default(cuid())
  noteId    String
  title     String
  content   String
  createdAt DateTime @default(now())
}
```

### Backlink
```prisma
model Backlink {
  sourceNoteId String
  targetNoteId String
}
```

## APIs Principales

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/notes` | GET, POST | Listar/crear notas |
| `/api/notes/[id]` | GET, PUT, DELETE | CRUD de nota |
| `/api/notes/[id]/versions` | GET, POST | Listar/crear versiones |
| `/api/notes/[id]/versions/[vid]` | GET, PUT | Ver/restaurar versión |
| `/api/notes/quick` | POST | Creación rápida |
| `/api/notes/links` | GET | Sugerencias de enlaces |
| `/api/search` | GET | Búsqueda con scoring |
| `/api/tags` | GET | Listar/buscar tags |
| `/api/tags/suggest` | GET | Sugerencias automáticas |
| `/api/usage` | GET | Estadísticas de uso |
| `/api/usage/co-usage` | GET | Notas co-usadas |
| `/api/metrics` | GET | Métricas de dashboard |
| `/api/centrality` | GET | Notas más centrales |
| `/api/export-import` | GET, POST | Export/Import (JSON, Markdown, HTML) |
| `/api/import-markdown` | POST | Importador Markdown mejorado |
| `/api/capture` | POST | Captura externa segura |

## Features Implementadas

### MVP-1
- CRUD completo de notas
- Sistema de tags
- Búsqueda básica

### MVP-2
- Búsqueda avanzada con scoring
- Quick Add con prefijos (cmd:, snip:, etc.)
- Backlinks con sintaxis [[wiki]]
- Formularios guiados por tipo de nota

### MVP-3
- Usage tracking (vistas, clics, copias)
- Dashboard inteligente
- Scoring boost basado en uso
- Sugerencias automáticas de tags
- Panel "Conectado con"
- Quick Add multilínea
- Pegado inteligente con detección de tipo
- Sugerencia automática de tipo de nota
- Sugerencia de enlaces internos
- Registro de co-uso entre notas
- Métricas internas
- Cálculo de notas centrales
- Feature flags configurables

### MVP-4
- Query parser para búsquedas avanzadas (`type:`, `tag:`, `is:favorite`, `is:pinned`)
- Búsqueda en tiempo real con 300ms debounce
- Navegación por teclado (↑↓ Enter ESC) estilo Spotlight
- Dropdown de resultados con cache
- Sidebar contextual con co-uso
- Historial de versiones de notas

### MVP-5 (Completo)

**Sprint 1 - Confianza total:**
- Sistema de backup automático (IndexedDB)
- Política de retención (max 10 backups, 30 días)
- Restore con preview y validación
- Backup previo automático pre-destructivo
- Guard de cambios sin guardar

**Sprint 2 - Flujo diario desde teclado:**
- Command Palette global (Ctrl+K / Cmd+K)
- Modelo de acciones para palette
- Shortcuts globales (g h, g n, n, /, ?)
- Navegación de listas por teclado (↑↓ Enter E F P)

**Sprint 3 - Contexto y continuidad:**
- Sidebar contextual persistente mejorada
- Modo trabajo con toggle
- Autosave de borradores locales
- Historial de navegación contextual

**Sprint 4 - Captura ubicua:**
- Bookmarklet para capturar desde cualquier web
- Página de confirmación de captura
- Endpoint seguro /api/capture con rate limiting

**P2 - Exportación, Importación y Settings:**
- Exportación Markdown con frontmatter
- Exportación HTML legible
- Importador Markdown mejorado (frontmatter, tags, wiki links)
- Importador Obsidian-compatible
- Centro de respaldo en Settings
- Panel de preferencias (backup on/off, retención, work mode)
- Tests de command palette y captura
- Validaciones y límites (50MB backup, 10K notas, etc)

## Algoritmo de Scoring

```typescript
// Search scoring
score = baseScore + favoriteBoost(+2) + pinnedBoost(+1) + usageBoost

// Related notes scoring
score = sameType(+3) + sharedTags(×3) + titleKeywords(max+3) + contentKeywords(max+2) + usageBoost

// Centrality score
centrality = backlinks(×3) + outboundLinks(×1) + usageViews(×0.5) + coUsageWeight(×2)
```

## Atajos de Teclado

| Atajo | Acción |
|-------|--------|
| `Ctrl+K` / `Cmd+K` | Command Palette |
| `g h` | Ir al Dashboard |
| `g n` | Ir a Notas |
| `n` | Nueva nota |
| `/` | Enfocar búsqueda |
| `?` | Mostrar ayuda |
| `↑↓` | Navegar listas |
| `Enter` | Abrir nota |
| `E` | Editar nota (en lista) |
| `F` | Favoritar nota (en lista) |
| `P` | Fijar nota (en lista) |

## Tests

**226 tests** cubriendo:
- API routes (CRUD, search, tags, versions)
- Search y scoring
- Query parser
- Notas relacionadas
- Backlinks
- Type inference
- Link suggestions
- Usage tracking
- Dashboard
- Version history
- Command items
- External capture
- Navigation history

## Comandos

```bash
npm run dev      # Desarrollo
npm run build    # Build producción
npm test         # Tests (usar npx jest)
npx prisma db push  # Sync schema
npx prisma studio   # UI de BD
```

## Configuración de Feature Flags

```bash
FLAG_CENTRALITY=true
FLAG_PASSIVE_RECOMMENDATIONS=true
FLAG_TYPE_SUGGESTIONS=true
FLAG_LINK_SUGGESTIONS=true
```

## Estados de Implementación

| Feature | Estado |
|---------|--------|
| CRUD notas | ✅ |
| Tags | ✅ |
| Búsqueda avanzada | ✅ |
| Quick Add | ✅ |
| Backlinks [[wiki]] | ✅ |
| Usage tracking | ✅ |
| Dashboard inteligente | ✅ |
| Versiones de notas | ✅ |
| Command Palette | ✅ |
| Shortcuts globales | ✅ |
| Modo trabajo | ✅ |
| Backup/Restore | ✅ |
| Bookmarklet capture | ✅ |
| Export Markdown/HTML | ✅ |
| Import Markdown | ✅ |
| Settings completo | ✅ |
| Feature flags UI | ✅ |
| Tests | ✅ (226) |

## Commits Recientes

```
e66a678 feat: MVP-5 P2 - Export/Import, Settings, Tests y Validaciones
8d56f34 feat: MVP-5 Sprint 4 - External Capture via Bookmarklet
a40ab18 feat: MVP-5 Sprint 3 - Sidebar, Work Mode, and Drafts
cde0a14 feat: MVP-5 Sprint 2 - Command Palette and Global Shortcuts
8c80a12 feat: MVP-5 Sprint 1 - Backup/Restore system
```