MangaReader/docs

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

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

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

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 - 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 - Sección "Modelos de Datos"
2. Revisa los servicios disponibles
3. Mira los ejemplos de uso

Para Contribuir

1. Lee 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 - 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 - Sección "Cómo Modificar el Scraper".

¿Cómo ejecuto los tests? Ve a 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

/// 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
• SwiftUI Documentation
• WKWebView Reference

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.

---

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