# PLAN: Captain Claude Mobile v2

## Objetivo
App móvil nativa de chat con Claude que ejecuta comandos en el servidor y muestra resultados formateados.

---

## 1. ARQUITECTURA

```
┌──────────────────┐     HTTPS/WSS      ┌──────────────────┐
│                  │ ◄────────────────► │                  │
│   Flutter App    │                    │   FastAPI        │
│   (Android/iOS)  │                    │   Backend        │
│                  │                    │                  │
└──────────────────┘                    └────────┬─────────┘
                                                 │
                                                 │ subprocess
                                                 ▼
                                        ┌──────────────────┐
                                        │                  │
                                        │   Claude CLI     │
                                        │   (claude -p)    │
                                        │                  │
                                        └──────────────────┘
```

### Backend (FastAPI)
- Recibe mensajes del usuario via WebSocket
- Ejecuta `claude -p "mensaje" --output-format stream-json`
- Parsea el output JSON de Claude
- Envía respuesta formateada al frontend
- Guarda historial en PostgreSQL

### Frontend (Flutter)
- UI de chat nativa (burbujas, input, etc.)
- Renderiza Markdown en respuestas
- Syntax highlighting en code blocks
- Muestra progreso de ejecución
- Historial de conversaciones

---

## 2. DISEÑO UI/UX

### Pantalla Principal (Chat)
```
┌─────────────────────────────────┐
│ ☰  Captain Claude    [●] Online│  ← AppBar con estado conexión
├─────────────────────────────────┤
│                                 │
│ ┌─ User ────────────────────┐  │
│ │ Muéstrame el uso de disco │  │  ← Burbuja usuario (derecha)
│ └───────────────────────────┘  │
│                                 │
│ ┌─ Claude ──────────────────┐  │  ← Burbuja Claude (izquierda)
│ │ Ejecutando `df -h`...     │  │
│ │                           │  │
│ │ ```                       │  │  ← Code block con resultado
│ │ Filesystem  Size  Used    │  │
│ │ /dev/sda1   100G  45G     │  │
│ │ ```                       │  │
│ │                           │  │
│ │ El disco principal tiene  │  │  ← Explicación en texto
│ │ 55% libre (55GB).         │  │
│ └───────────────────────────┘  │
│                                 │
├─────────────────────────────────┤
│ ┌─────────────────────────┐ 📎│  ← Input con attach
│ │ Escribe un mensaje...   │ ➤ │  ← Botón enviar
│ └─────────────────────────────┘│
└─────────────────────────────────┘
```

### Pantalla Historial
```
┌─────────────────────────────────┐
│ ← Conversaciones                │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐│
│ │ 📁 Backup de base de datos  ││  ← Título auto-generado
│ │ Hace 2 horas • 5 mensajes   ││
│ └─────────────────────────────┘│
│ ┌─────────────────────────────┐│
│ │ 🔧 Fix error en nginx       ││
│ │ Ayer • 12 mensajes          ││
│ └─────────────────────────────┘│
│ ┌─────────────────────────────┐│
│ │ 📊 Análisis de logs         ││
│ │ 15 Ene • 8 mensajes         ││
│ └─────────────────────────────┘│
└─────────────────────────────────┘
```

### Estados de Mensaje Claude
1. **Pensando**: Spinner + "Claude está pensando..."
2. **Ejecutando**: Muestra comando siendo ejecutado
3. **Streaming**: Texto aparece progresivamente
4. **Completado**: Mensaje completo con formato
5. **Error**: Mensaje rojo con opción de reintentar

---

## 3. API BACKEND

### Endpoints REST

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /auth/login | Login, retorna JWT |
| GET | /conversations | Lista conversaciones |
| GET | /conversations/{id} | Mensajes de una conversación |
| DELETE | /conversations/{id} | Eliminar conversación |
| POST | /upload | Subir archivo para contexto |

### WebSocket /ws/chat

**Cliente → Servidor:**
```json
{
  "type": "message",
  "content": "Muéstrame el uso de disco",
  "conversation_id": "uuid-opcional",
  "files": ["/path/to/file"]
}
```

**Servidor → Cliente (streaming):**
```json
{"type": "thinking"}
{"type": "tool_use", "tool": "Bash", "input": "df -h"}
{"type": "tool_result", "output": "Filesystem  Size..."}
{"type": "text", "content": "El disco principal..."}
{"type": "done", "conversation_id": "uuid"}
```

---

## 4. MODELO DE DATOS

### PostgreSQL

```sql
-- Conversaciones
CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id VARCHAR(255) NOT NULL,
    title VARCHAR(500),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Mensajes
CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID REFERENCES conversations(id),
    role VARCHAR(50) NOT NULL,  -- 'user' | 'assistant'
    content TEXT NOT NULL,
    tool_uses JSONB,  -- [{tool, input, output}]
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 5. FLUTTER - ESTRUCTURA

```
lib/
├── main.dart
├── config/
│   └── api_config.dart
├── models/
│   ├── conversation.dart
│   ├── message.dart
│   └── tool_use.dart
├── services/
│   ├── api_service.dart
│   ├── chat_service.dart      # WebSocket
│   └── auth_service.dart
├── providers/
│   ├── auth_provider.dart
│   └── chat_provider.dart
├── screens/
│   ├── login_screen.dart
│   ├── chat_screen.dart
│   └── history_screen.dart
└── widgets/
    ├── message_bubble.dart    # Burbuja de mensaje
    ├── code_block.dart        # Syntax highlighting
    ├── tool_use_card.dart     # Muestra ejecución de tool
    ├── thinking_indicator.dart
    └── chat_input.dart        # Input con attach
```

---

## 6. COMPONENTES CLAVE

### MessageBubble (Flutter)
```dart
class MessageBubble extends StatelessWidget {
  final Message message;

  // Renderiza según tipo:
  // - Texto normal → Markdown
  // - Code blocks → Syntax highlighting
  // - Tool uses → Cards expandibles
  // - Errores → Estilo rojo
}
```

### ToolUseCard (Flutter)
```dart
// Muestra:
// ┌─ Bash ──────────────────────┐
// │ ▶ df -h                     │  ← Comando ejecutado
// ├─────────────────────────────┤
// │ Filesystem  Size  Used  ... │  ← Output (colapsable)
// └─────────────────────────────┘
```

### ChatInput (Flutter)
```dart
// - TextField multilínea
// - Botón adjuntar archivo
// - Botón enviar (disabled si vacío o desconectado)
// - Indicador de conexión
```

---

## 7. PROCESO DE DESARROLLO

### Fase 1: Backend básico
1. FastAPI con WebSocket
2. Integración con Claude CLI
3. Parsing de output JSON
4. Base de datos PostgreSQL

### Fase 2: Frontend básico
1. Chat UI con burbujas
2. Conexión WebSocket
3. Streaming de mensajes
4. Markdown rendering

### Fase 3: Features completas
1. Historial de conversaciones
2. Syntax highlighting
3. Tool use cards
4. Upload de archivos
5. Estados de conexión

### Fase 4: Pulido
1. Animaciones
2. Error handling robusto
3. Offline mode básico
4. Notificaciones

---

## 8. PROCESO DE AUDITORÍA (post-código)

### Ronda 1: Agentes paralelos
- **Arquitecto**: Revisa estructura del código
- **QA**: Busca bugs y edge cases
- **UX**: Evalúa usabilidad

### Ronda 2: Tests reales
- Probar cada endpoint con curl
- Instalar APK y probar flujos
- Documentar problemas

### Ronda 3: Fixes + re-test
- Aplicar correcciones
- Verificar que funcionan
- Compilar versión final

---

## 9. DIFERENCIAS CON v1

| Aspecto | v1 (Terminal) | v2 (Chat) |
|---------|---------------|-----------|
| UI | Emulador xterm | Chat nativo |
| Input | Teclado terminal | Texto natural |
| Output | Raw ANSI | Markdown formateado |
| Comandos | Ctrl+C manual | Claude decide |
| UX | Técnico | Amigable |

---

## 10. CRITERIOS DE ÉXITO

1. ✅ Usuario puede chatear con Claude en lenguaje natural
2. ✅ Claude ejecuta comandos y muestra resultados formateados
3. ✅ Code blocks tienen syntax highlighting
4. ✅ Conversaciones se guardan y se pueden retomar
5. ✅ UI es responsiva y agradable en móvil
6. ✅ Errores se muestran claramente con opción de reintentar
7. ✅ Conexión se reconecta automáticamente

---

## PRÓXIMO PASO

¿Apruebas este plan para empezar a implementar?