# Recall - Resumen Técnico Detallado

## Información General

**Nombre:** Recall
**Descripción:** Sistema de gestión de conocimiento personal (PKM) para captura y recuperación de notas, comandos, snippets y conocimiento técnico.
**Fecha de creación:** 2026-03-22
**Estado:** MVP-5 Completo

## Stack Tecnológico

| Componente | Tecnología | Versión |
|------------|-------------|---------|
| Framework | Next.js + App Router + Turbopack | 16.2.1 |
| Base de datos | SQLite via Prisma ORM | 5.22.0 |
| Lenguaje | TypeScript | 5.x |
| UI | TailwindCSS + shadcn/ui | 4.x / latest |
| Testing | Jest | 30.3.0 |
| Notificaciones | Sonner (toasts) | latest |
| IDE | VSCode / Cursor |

## Estructura del Proyecto

```
src/
├── app/
│   ├── api/
│   │   ├── notes/
│   │   │   ├── route.ts           # GET, POST /api/notes
│   │   │   ├── [id]/route.ts      # GET, PUT, DELETE /api/notes/:id
│   │   │   ├── quick/route.ts     # POST /api/notes/quick
│   │   │   ├── links/route.ts     # GET /api/notes/links
│   │   │   ├── suggest/route.ts   # GET /api/notes/suggest
│   │   │   ├── backlinks/route.ts # GET /api/notes/:id/backlinks
│   │   │   └── versions/
│   │   │       ├── route.ts       # GET, POST /api/notes/:id/versions
│   │   │       └── [versionId]/route.ts # GET, PUT
│   │   ├── tags/
│   │   │   ├── route.ts           # GET /api/tags
│   │   │   └── suggest/route.ts   # GET /api/tags/suggest
│   │   ├── search/route.ts       # GET /api/search
│   │   ├── usage/
│   │   │   ├── route.ts           # GET /api/usage
│   │   │   └── co-usage/route.ts # GET /api/usage/co-usage
│   │   ├── metrics/route.ts      # GET /api/metrics
│   │   ├── centrality/route.ts   # GET /api/centrality
│   │   ├── export-import/route.ts # GET, POST
│   │   ├── import-markdown/route.ts # POST
│   │   └── capture/route.ts       # POST /api/capture
│   ├── notes/[id]/page.tsx       # Detalle de nota
│   ├── edit/[id]/page.tsx        # Edición de nota
│   ├── new/page.tsx              # Nueva nota
│   ├── capture/page.tsx          # Confirmación de captura
│   ├── settings/page.tsx         # Configuración
│   └── page.tsx                  # Dashboard (raíz)
├── components/
│   ├── ui/                       # Componentes shadcn/ui
│   ├── dashboard.tsx             # Dashboard inteligente
│   ├── note-form.tsx             # Formulario de notas
│   ├── note-card.tsx             # Tarjeta de nota
│   ├── note-list.tsx             # Lista de notas (grid)
│   ├── keyboard-navigable-note-list.tsx # Lista con navegación teclado
│   ├── note-connections.tsx      # Panel de conexiones
│   ├── related-notes.tsx         # Notas relacionadas
│   ├── version-history.tsx        # Historial de versiones
│   ├── 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 atajos
│   ├── keyboard-hint.tsx         # Hint de atajos
│   ├── 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 bookmarklet
│   ├── recent-context-list.tsx    # Historial de navegación
│   ├── track-navigation-history.tsx # Tracking de historial
│   ├── preferences-panel.tsx     # Panel de preferencias
│   ├── markdown-content.tsx       # Contenido con highlight
│   ├── quick-add.tsx             # Captura rápida
│   └── track-note-view.tsx       # Tracking de vistas
├── hooks/
│   ├── use-global-shortcuts.ts   # Atajos globales
│   ├── use-note-list-keyboard.ts # Navegación teclado
│   └── use-unsaved-changes.ts   # Guard de cambios sin guardar
└── lib/
    ├── prisma.ts                 # Cliente Prisma
    ├── search.ts                 # Búsqueda con scoring
    ├── query-parser.ts           # Parser de queries
    ├── related.ts                # Notas relacionadas
    ├── backlinks.ts               # Sistema de enlaces [[wiki]]
    ├── tags.ts                   # Normalización y sugerencias
    ├── usage.ts                  # Tracking de uso
    ├── 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
    ├── versions.ts               # Historial de versiones
    ├── 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
    ├── templates.ts              # Templates por tipo
    ├── command-items.ts          # Items de command palette
    └── command-groups.ts         # Grupos de comandos
```

## Modelos de Datos (Prisma)

### 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 REST

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/notes` | GET, POST | Listar/crear notas |
| `/api/notes/[id]` | GET, PUT, DELETE | CRUD nota |
| `/api/notes/quick` | POST | Creación rápida |
| `/api/notes/links` | GET | Sugerencias de enlaces |
| `/api/notes/suggest` | GET | Sugerencias automática |
| `/api/notes/[id]/versions` | GET, POST | Versiones |
| `/api/notes/[id]/backlinks` | GET | Backlinks |
| `/api/search` | GET | Búsqueda avanzada |
| `/api/tags` | GET | Tags |
| `/api/tags/suggest` | GET | Sugerencias de tags |
| `/api/usage` | GET | Uso de notas |
| `/api/usage/co-usage` | GET | Co-uso entre notas |
| `/api/metrics` | GET | Métricas dashboard |
| `/api/centrality` | GET | Notas centrales |
| `/api/export-import` | GET, POST | Export/Import |
| `/api/import-markdown` | POST | Importar Markdown |
| `/api/capture` | POST | Captura externa |

## Features Implementadas

### MVP-1: Fundamentos
- [x] CRUD completo de notas
- [x] Sistema de tags
- [x] Búsqueda básica

### MVP-2: Captura Inteligente
- [x] Búsqueda avanzada con scoring
- [x] Quick Add con prefijos (cmd:, snip:, etc.)
- [x] Backlinks con sintaxis [[wiki]]
- [x] Formularios guiados por tipo
- [x] Templates inteligentes por tipo
- [x] Vista command con copiar
- [x] Vista snippet con syntax highlight
- [x] Checklist interactivo en procedure

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

### MVP-4: Query Parser y Navegación
- [x] Query parser (`type:`, `tag:`, `is:favorite`, `is:pinned`)
- [x] Búsqueda en tiempo real (300ms debounce)
- [x] Navegación por teclado (↑↓ Enter ESC)
- [x] Dropdown de resultados con cache
- [x] Sidebar contextual con co-uso
- [x] Historial de versiones
- [x] Preload de notas en hover

### MVP-5: Flujo Diario y Portabilidad

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

**Sprint 2 - Shortcuts Globales:**
- [x] Command Palette (Ctrl+K / Cmd+K)
- [x] Shortcuts: g h, g n, n, /, ?
- [x] Navegación de listas por teclado

**Sprint 3 - Contexto y Continuidad:**
- [x] Sidebar contextual persistente
- [x] Modo trabajo con toggle
- [x] Autosave de borradores locales
- [x] Historial de navegación contextual

**Sprint 4 - Captura Ubicua:**
- [x] Bookmarklet para capturar desde web
- [x] Página de confirmación
- [x] Endpoint seguro con rate limiting

**P2 - Exportación e Importación:**
- [x] Exportación Markdown con frontmatter
- [x] Exportación HTML legible
- [x] Importador Markdown mejorado
- [x] Centro de respaldo en Settings
- [x] Panel de preferencias
- [x] Validaciones y límites

## Algoritmos de Scoring

### Búsqueda
```
score = baseScore + favoriteBoost(+2) + pinnedBoost(+1) + usageBoost
```

### Notas Relacionadas
```
score = sameType(+3) + sharedTags(×3) + titleKeywords(max+3) + contentKeywords(max+2) + usageBoost
```

### Centralidad
```
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 |
| `F` | Favoritar nota |
| `P` | Fijar nota |

## Tipos de Nota

| Tipo | Descripción | Color |
|------|-------------|-------|
| `note` | Nota general | Slate |
| `command` | Comando o snippet ejecutable | Green |
| `snippet` | Fragmento de código | Blue |
| `decision` | Decisión tomada | Purple |
| `recipe` | Receta o procedimiento | Orange |
| `procedure` | Procedimiento con checkboxes | Yellow |
| `inventory` | Inventario o lista | Gray |

## Comandos npm

```bash
npm run dev          # Desarrollo (Turbopack)
npm run build        # Build producción
npm run start        # Iniciar producción
npm test             # Tests (Jest)
npx jest --watch     # Tests en watch mode
npx prisma db push   # Sync schema a BD
npx prisma studio    # UI de base de datos
npx prisma generate  # Generar tipos
```

## Tests

**226 tests** organizados en:
- `__tests__/api.*.test.ts` - Tests de integración de APIs
- `__tests__/search.test.ts` - Búsqueda y scoring
- `__tests__/query-parser.test.ts` - Parser de queries
- `__tests__/related.test.ts` - Notas relacionadas
- `__tests__/backlinks.test.ts` - Sistema de enlaces
- `__tests__/tags.test.ts` - Tags y sugerencias
- `__tests__/usage.test.ts` - Tracking de uso
- `__tests__/versions.test.ts` - Historial de versiones
- `__tests__/dashboard.test.ts` - Dashboard
- `__tests__/command-items.test.ts` - Command palette
- `__tests__/external-capture.test.ts` - Captura externa
- `__tests__/navigation-history.test.ts` - Historial
- `__tests__/link-suggestions.test.ts` - Sugerencias de enlaces
- `__tests__/type-inference.test.ts` - Inferencia de tipo
- `__tests__/quick-add.test.ts` - Quick Add

## Feature Flags

Configurables via `localStorage` o `.env`:

```bash
FLAG_CENTRALITY=true        # Habilitar centralidad
FLAG_PASSIVE_RECOMMENDATIONS=true  # Recomendaciones pasivas
FLAG_TYPE_SUGGESTIONS=true  # Sugerencias de tipo
FLAG_LINK_SUGGESTIONS=true  # Sugerencias de enlaces
```

## Límites del Sistema

| Recurso | Límite |
|---------|--------|
| Tamaño de backup | 50MB |
| Cantidad de notas | 10,000 |
| Longitud de título (captura) | 500 chars |
| Longitud de URL (captura) | 2000 chars |
| Longitud de selección (captura) | 10,000 chars |
| Backups retenidos | 10 máximo |
| Días de retención | 30 días |

## Commits del Proyecto

```
33a4705 feat: MVP-4 P2 - Preload notes on hover
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
6694bce mvp
af0910f feat: initial commit
f2e4706 Initial commit
```

## Dependencias Principales

```json
{
  "next": "16.2.1",
  "@prisma/client": "5.22.0",
  "prisma": "5.22.0",
  "sonner": "latest",
  "zod": "latest",
  "tailwindcss": "4.x",
  "@radix-ui/react-*": "latest"
}
```

## Patrones de Diseño

- **Server Components** para páginas estáticas
- **Client Components** para interactividad
- **Hooks personalizados** para lógica reutilizable
- **Feature Flags** para features opcionales
- **IndexedDB** para persistencia local de backups
- **localStorage** para preferencias y borradores

## Estado 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) |
| Preload on hover | ✅ |