MangaReader/docs/README.md

# MangaReader - Documentación Técnica

Bienvenido a la documentación técnica de MangaReader. Este directorio contiene toda la información necesaria para entender, desarrollar y contribuir al proyecto.

## Documentos Disponibles

### [ARCHITECTURE.md](./ARCHITECTURE.md)
Documentación completa de la arquitectura del sistema.

**Contenido:**
- Visión general del sistema (Backend + iOS App)
- Arquitectura MVVM de la app iOS
- Diagramas de flujo de datos (scraping, lectura, guardado)
- Patrones de diseño implementados (Singleton, MVVM, Repository, etc.)
- Diagramas de secuencia en ASCII
- Decisiones arquitectónicas y su justificación

**Para quién es:**
- Desarrolladores que necesitan entender la estructura general
- Arquitectos que evalúan el diseño del sistema
- Nuevos contribuyentes que necesitan orientación

---

### [API.md](./API.md)
Documentación de la API y modelos de datos.

**Contenido:**
- Modelos de datos (Manga, Chapter, MangaPage, ReadingProgress, etc.)
- Documentación completa de servicios (ManhwaWebScraper, StorageService)
- Descripción de ViewModels y sus responsabilidades
- Errores y manejo de excepciones
- Ejemplos de uso para cada método público

**Para quién es:**
- Desarrolladores que integran funcionalidades
- Equipo QA que necesita entender comportamientos esperados
- Contribuyentes que agregan nuevas features

---

### [CONTRIBUTING.md](./CONTRIBUTING.md)
Guía para contribuir al proyecto.

**Contenido:**
- Configuración del entorno de desarrollo
- Cómo agregar nuevas fuentes de manga
- Cómo modificar el scraper existente
- Estándares de código (Swift style guide)
- Testing (unit tests, integración)
- Pull request guidelines
- Troubleshooting común

**Para quién es:**
- Nuevos contribuyentes
- Desarrolladores que agregan features
- Maintainers que revisan PRs

---

## Estructura del Proyecto

```
MangaReader/
├── docs/                       # Documentación técnica
│   ├── README.md              # Este archivo (índice)
│   ├── ARCHITECTURE.md        # Arquitectura y diagramas
│   ├── API.md                 # API y modelos de datos
│   └── CONTRIBUTING.md        # Guía para contribuyentes
│
├── ios-app/                   # Aplicación iOS
│   ├── MangaReaderApp.swift   # Entry point de la app
│   ├── Sources/
│   │   ├── Models/           # Modelos de datos
│   │   │   └── Manga.swift   # Models documentados
│   │   ├── Services/         # Lógica de negocio
│   │   │   ├── ManhwaWebScraper.swift  # Scraper documentado
│   │   │   └── StorageService.swift    # Storage documentado
│   │   └── Views/            # UI SwiftUI
│   │       ├── ContentView.swift
│   │       ├── MangaDetailView.swift
│   │       └── ReaderView.swift
│   └── MangaReader.xcodeproj
│
└── backend/                   # Backend opcional (Node.js)
    ├── scraper.js
    ├── server.js
    └── package.json
```

---

## Resumen Rápido de Componentes

### Modelos de Datos
- **Manga**: Información completa de un manga
- **Chapter**: Capítulo individual con estado de lectura
- **MangaPage**: Página individual (imagen)
- **ReadingProgress**: Progreso de lectura del usuario
- **DownloadedChapter**: Capítulo descargado localmente

### Servicios
- **ManhwaWebScraper**: Scraper usando WKWebView para manhwaweb.com
- **StorageService**: Gestión de almacenamiento local (UserDefaults + FileManager)

### ViewModels
- **MangaListViewModel**: Lista principal de mangas
- **MangaDetailViewModel**: Detalle de un manga
- **ReaderViewModel**: Lector de capítulos

### Views
- **ContentView**: Vista principal con lista de mangas
- **MangaDetailView**: Detalle y capítulos de un manga
- **ReaderView**: Lector de imágenes con zoom/pan

---

## Comenzar Rápidamente

### Para Entender la Arquitectura
1. Lee [ARCHITECTURE.md](./ARCHITECTURE.md) - Sección "Visión General"
2. Revisa los diagramas de flujo de datos
3. Estudia los patrones de diseño usados

### Para Usar la API
1. Consulta [API.md](./API.md) - Sección "Modelos de Datos"
2. Revisa los servicios disponibles
3. Mira los ejemplos de uso

### Para Contribuir
1. Lee [CONTRIBUTING.md](./CONTRIBUTING.md) - "Configuración del Entorno"
2. Configura tu entorno de desarrollo
3. Revisa los estándares de código
4. Sigue el workflow de Pull Requests

---

## Tecnologías Utilizadas

### iOS App
- **SwiftUI**: Framework de UI declarativo
- **Combine**: Programación reactiva
- **WKWebView**: Rendering de JavaScript
- **UserDefaults**: Almacenamiento de preferencias
- **FileManager**: Almacenamiento de archivos

### Backend (Opcional)
- **Node.js**: Runtime de JavaScript
- **Express**: Framework web
- **Puppeteer**: Headless Chrome automation

---

## Patrones de Diseño Principales

| Patrón | Implementación | Propósito |
|--------|---------------|-----------|
| **MVVM** | ViewModels separados de Views | Separar UI de lógica |
| **Singleton** | `StorageService.shared`, `ManhwaWebScraper.shared` | Instancia única compartida |
| **Repository** | `StorageService` abstrae UserDefaults/FileManager | Interfaz unificada de datos |
| **Async/Await** | Métodos `async throws` en scraper | Código asíncrono legible |
| **Observable** | `@Published`, `ObservableObject` | Reactividad en SwiftUI |

---

## Flujos Principales

### 1. Agregar Manga
```
Usuario → ContentView → MangaListViewModel
  ↓
ManhwaWebScraper.scrapeMangaInfo()
  ↓
WKWebView + JavaScript
  ↓
Manga actualizado en UI
```

### 2. Leer Capítulo
```
Usuario → MangaDetailView → ReaderView
  ↓
ReaderViewModel.loadPages()
  ↓
¿Descargado? ─NO→ ManhwaWebScraper.scrapeChapterImages()
  │S                      ↓
  └─→ StorageService.getDownloadedChapter()
  ↓
Mostrar páginas en ReaderView
```

### 3. Guardar Progreso
```
Usuario navega a página X
  ↓
ReaderViewModel.currentPage = X
  ↓
ReaderViewModel.saveProgress()
  ↓
StorageService.saveReadingProgress()
  ↓
UserDefaults (JSON codificado)
```

---

## Preguntas Frecuentes

**¿Puedo agregar nuevas fuentes de manga?**
Sí. Lee [CONTRIBUTING.md](./CONTRIBUTING.md) - Sección "Cómo Agregar Nuevas Fuentes de Manga".

**¿El backend es obligatorio?**
No. La app iOS funciona completamente de manera autónoma. El backend es opcional y puede servir como cache/API intermedia.

**¿Cómo cambio el scraper si manhwaweb.com cambia su estructura?**
Consulta [CONTRIBUTING.md](./CONTRIBUTING.md) - Sección "Cómo Modificar el Scraper".

**¿Cómo ejecuto los tests?**
Ve a [CONTRIBUTING.md](./CONTRIBUTING.md) - Sección "Testing".

---

## Convenciones de Documentación

### En Código Swift
- **///**: Comentarios de documentación públicos (soportan Markdown)
- **//:**: Comentarios de sección (MARK)
- **//**: Comentarios de implementación

### Ejemplo de Documentación de Método
```swift
/// Obtiene la lista de capítulos de un manga.
///
/// Este método carga la página del manga, espera a que JavaScript renderice
/// el contenido, y extrae todos los links de capítulos disponibles.
///
/// - Parameter mangaSlug: Slug único del manga
/// - Returns: Array de `Chapter` ordenados por número (descendente)
/// - Throws: `ScrapingError` si el WebView no está inicializado
///
/// # Example
/// ```swift
/// let chapters = try await scraper.scrapeChapters(mangaSlug: "one-piece")
/// ```
func scrapeChapters(mangaSlug: String) async throws -> [Chapter]
```

---

## Recursos Adicionales

### Documentación Oficial
- [Swift Language Guide](https://docs.swift.org/swift-book/)
- [SwiftUI Documentation](https://developer.apple.com/documentation/swiftui)
- [WKWebView Reference](https://developer.apple.com/documentation/webkit/wkwebview)

### Herramientas
- **SwiftLint**: Linter para código Swift
- **SwiftFormat**: Formateador automático
- **Jazzy**: Generador de documentación (Objective-C/Swift)

---

## Soporte y Contribución

¿Encontraste un error en la documentación? ¿Falta algo?

1. Abre un issue en el repositorio
2. O envía un Pull Request con las mejoras

Para más detalles sobre cómo contribuir, revisa [CONTRIBUTING.md](./CONTRIBUTING.md).

---

**Última actualización**: Febrero 2026
**Versión**: 1.0.0
**Mantenedor**: MangaReader Team