# Implementation Plan: Chatbot PDF Extractor (Baseline)

**Branch**: `001-chatbot-pdf-extractor` | **Date**: 2026-05-21 | **Spec**: [spec.md](./spec.md)

**Note**: Plan brownfield — describe el estado técnico actual. Nuevas features generan su propio `plan.md` bajo `specs/00N-*`.

## Summary

Monorepo Laravel 12 (API + JWT) + SPA Angular 19 (`ChatFront`). Dos canales: chat conversacional con orquestador de agente y extracción PDF con plantillas, visión nativa (OpenAI Responses / Gemini inline PDF) y persistencia dual (BD principal + secundaria).

## Technical Context

**Language/Version**: PHP 8.2+, TypeScript/Angular 19  
**Primary Dependencies**: Laravel 12, jwt-auth, openai-php/laravel, PrimeNG, RxJS  
**Storage**: BD principal (users, chat_messages, documents, extracted_data, document_templates); BD `secundaria` (tablas destino cliente)  
**Testing**: PHPUnit (`php artisan test`), Karma/Jasmine (ChatFront)  
**Target Platform**: Web (API Laravel + SPA)  
**Project Type**: Web application (backend + frontend desacoplado)  
**Performance Goals**: Upload PDF con timeout extendido (~300s); polling historial cada 5s en UI  
**Constraints**: PDF ≤ 50 MB (configurable); JWT Bearer; CORS explícito  
**Scale/Scope**: Operadores internos, multi-plantilla PDF, dual LLM provider  

## Constitution Check

- [x] I. Spec-First — baseline documentado en spec.md
- [x] II. Skinny controllers — servicios en `app/Services`
- [x] III. Contratos LLM y PDF vision
- [x] IV. API `/api/v1` + ApiResponseTrait + JWT
- [x] V. Contrato API — tipos en `ChatFront/.../api.types.ts`
- [x] VI. SPA desacoplada en `ChatFront/` (core + features)
- [x] VII. Fidelidad PDF — extracción sin inventar datos
- [x] VIII. Spec Kit workflow instalado (`.specify/`, skills Cursor)

## Project Structure

### Documentation (this feature)

```text
specs/001-chatbot-pdf-extractor/
├── spec.md           # Requisitos funcionales (baseline)
├── plan.md           # Este archivo
├── research.md       # Decisiones técnicas
├── data-model.md     # Entidades
└── quickstart.md     # Arranque local
```

Referencia machine-readable legacy: `.cursor/specs/proyecto-base.yml` (mantener sincronizado en cambios de arquitectura).

### Source Code

```text
# Backend (Laravel, repo root)
app/
├── Contracts/          # LlmChatCompletionContract, PdfVisionExtractorContract
├── Http/Controllers/Api/V1/
├── Services/
│   ├── Pdf/            # NativeOpenAi/Gemini/Imagick extractors
│   ├── Agent/          # Orchestrator, intent handlers
│   └── ChatDocumentService.php
config/
├── pdf.php, llm.php, openai.php, database.php
routes/api.php

# Frontend (Angular)
ChatFront/src/app/
├── core/               # auth, guards, interceptors
├── features/
│   ├── login, dashboard, conversation, chat, templates, users
└── environments/

.specify/               # Spec Kit templates, scripts, constitution
.cursor/skills/speckit-*  # Comandos SDD en Cursor
```

## API Surface (v1)

| Grupo | Rutas |
|-------|--------|
| Auth | POST `/auth/login`, GET `/auth/me` |
| Chat | POST `/chat/message`, GET/DELETE `/chat/conversation` |
| PDF | POST `/chat/upload`, GET `/chat/history`, GET `/chat/templates` |
| Users | CRUD `/users` (ADMINISTRADOR) |

## PDF Extraction Pipeline

1. Upload → `ChatDocumentService::processUpload`
2. Modo entrenamiento: visión + crea `DocumentTemplate`
3. Modo normal: `IntelligentPdfExtractionService` (clasificar → visión → BD secundaria)
4. `PdfVisionExtractorService` delega según `PDF_VISION_DRIVER` y `LLM_PROVIDER`

## Phase 0 / Research

Ver [research.md](./research.md).

## Phase 1 / Design

Ver [data-model.md](./data-model.md) y [quickstart.md](./quickstart.md).

## Next Steps (nuevas features)

Para trabajo incremental NO incluido en este baseline:

1. `/speckit-specify <descripción>` → crea `specs/002-.../spec.md`
2. `/speckit-plan` → plan técnico de la feature
3. `/speckit-tasks` → tasks.md
4. `/speckit-implement`