How pablosnchz/gw2-wallet-ligero works
Tipo y propósito del proyecto (qué diagramar)
Por el file tree y el README, esto es una SPA 100% estática (sin backend) desplegada en GitHub Pages, cuyo objetivo es consumir la Guild Wars 2 API desde el navegador para mostrar módulos de cuenta: *Wallet, MetaEventos, Wizard’s Vault, Achievements, conversor Gem↔Gold, gestión de API keys*, etc.
Implicación clave para el diagrama: tu “sistema” es principalmente cliente (browser) + APIs externas + almacenamiento local. No hay servidor propio, pero sí hay “backend” externo: la GW2 API.
Lectura de la estructura (mapeo directo a componentes)
Top-level:
• index.html → Shell de la app + punto de montaje.
• css/ (main.css, theme-polish.css) → capa de estilos/temas (modos Deluxe/Compacto).
• js/ → lógica principal (router, módulos, API client, UI).
• .github/*, CHANGELOG.md, README.md → no “runtime”, pero útiles para anotar *deployment* (GitHub Pages) y versionado.
JS (componentización por archivo, útil para tu diagrama de componentes):
• js/app.js → bootstrap/inicialización global (probable wiring de router, sidebar, estado global, toasts, etc.).
• js/router.js → enrutado hash (#/meta, #/account/achievements, etc.) y eventos (README menciona gn:tabchange).
• js/api-gw2.js → GW2 API client (fetch, endpoints, manejo de permisos/errores, rate/limits si aplica).
• js/meta.js → módulo MetaEventos (horarios, “Hecho hoy”, favoritos, plantillas HTML reales, tooltips, etc.).
• js/achievements.js → módulo de Logros (progress, filtros, rareza, etc.).
• js/sidebar-nav.js → navegación lateral, “top-3 próximos”, favoritos, iconografía.
• js/achievements.js (y el resto) → cada módulo es un “sub-sistema” dentro del cliente.
Qué extraer del README (requisitos arquitectónicos)
Cosas que deben reflejarse en el diagrama:
• Sin backend: “liviano y sin backend”.
• Múltiples módulos (Wallet, WV, Achievements, MetaEventos, Converter, API Keys).
• Persistencia en LocalStorage para:
• API Keys / token seleccionado
• favoritos (máx 6)
• flags “hecho hoy”
• marcas WV / contadores (±) con persistencia
• Cache TTL (MetaEventos “Hecho hoy”: TTL 5 min por token + auto-refresh reset UTC).
• Robustez de permisos: token sin permisos → mensajes claros.
• Eventos UI / Router: #/meta dispara gn:tabchange para inicializar módulo.
• Datos estáticos: assets/meta-*.json y otros para enriquecer UI (drops, top-3, tooltips).
Diagrama 1 — Contexto (System Context)
Objetivo: qué es el sistema y con quién habla.
Incluye:
• Usuario (jugador GW2) en navegador.
• GW2 Wallet & MetaEventos SPA (este repo).
• ArenaNet / GW2 API (servicio externo).
• GitHub Pages como hosting estático/CDN.
• (Opcional) Wiki/Map links como “external links” (no integración técnica, pero sí salidas desde UI).
Flechas:
• Usuario ⇄ SPA (interacción UI).
• SPA ⇄ GW2 API (HTTPS fetch con token API key).
• Browser ⇄ LocalStorage (persistencia local).
• Browser ⇄ GitHub Pages (descarga de HTML/CSS/JS/assets).
Objetivo: separar runtime pieces dentro del “sistema”.
Contenedores típicos aquí:
Static Hosting (GitHub Pages)
• entrega index.html, css/*, js/*, assets/*
Browser App (SPA runtime)
• Router (hash routing)
• UI Shell + Sidebar
• Módulos de features
• API Client
• Cache/State (in-memory)
• LocalStorage (persistencia)
External: Guild Wars 2 API
• endpoints de cuenta, WV, achievements, worldbosses/mapchests, exchange (gem↔gold), etc.
Static Data Assets (puede ser parte del hosting o un “data container” lógico)
• assets/meta-events.json, assets/meta-drops.json, íconos
Relaciones:
• Router → Módulos (activa/instancia vistas por ruta)
• Módulos → API Client (todas las llamadas remotas)
• Módulos → Assets (cargan metadata local para render)
• Módulos ↔ LocalStorage (favoritos, flags, marcas, keys)
• API Client → GW2 API (fetch)
• Módulos → UI (render DOM, tooltips, toasts)
Objetivo: mostrar cómo está “partida” la SPA según js/*.
Un buen corte, basado en archivos reales:
• App Bootstrap (app.js)
• inicializa Router, Sidebar, tema, listeners globales, toasts
• Router (router.js)
• parsea location.hash
• emite evento gn:tabchange (según README)
• dispara inicialización/refresh de módulo activo
• API Gateway / Client (api-gw2.js)
• wrapper de fetch
• inyecta API key
• manejo de errores (401/403 permisos, 404 items retirados)
• (si existe) throttle/rate-limit handling
• Feature Modules
• MetaEventos (meta.js)
• scheduler/horarios, top-3 próximos
• “Hecho hoy”: cache TTL 5 min por token + reset UTC
• favoritos (máx 6) + filtros + vista tarjetas/tabla
• tooltips/íconos/drops (desde assets)
• Achievements (achievements.js)
• categorías, barras de progreso, filtros PvE/PvP/WvW
• sincronización con progression si API lo permite
• (Si existen en app.js aunque no haya archivo dedicado) Wallet / WV / Converter / API Keys UI
• Navigation / Sidebar (sidebar-nav.js)
• navegación, iconografía GW2, top-3, favoritos
• Assets / Metadata Loader (lógico)
• Storage Service (lógico)
• encapsula localStorage (keys, selected token, flags, marcas)
Dibuja dependencias (flechas sólidas) y eventos (flechas punteadas) por separado:
• Router →(event)→ MetaEventos init (via gn:tabchange)
• MetaEventos →(read/write)→ LocalStorage
• MetaEventos → API Client → GW2 API
Diagramas 4 (opcionales pero “gold”) — Secuencias para flujos críticos
El README menciona comportamientos no triviales (cache TTL, reset UTC, permisos). Documenta 1-2 secuencias:
Secuencia 1: “Cargar MetaEventos + Hecho hoy”
MetaEventos init
• carga assets meta-events.json / meta-drops.json (si no están cacheados in-memory)
• lee localStorage (favoritos, flags hecho-hoy, token seleccionado)
MetaEventos llama API Client
• endpoints “worldbosses” + “mapchests” (según README)
Cache
• si existe cache por token y TTL 5 min válido → usa cache
• si no → actualiza cache + render
Scheduler/Timer
• programa auto-refresh en reset UTC
Secuencia 2: “Token sin permisos”
Qué elementos deben aparecer sí o sí (para máxima precisión)
Para cada caja del diagrama:
• Etiqueta con: nombre + responsabilidad + archivo(s) (ej: “Router (js/router.js): parse hash, emit gn:tabchange”).
• Tecnología: “Static SPA (HTML/CSS/Vanilla JS)”, “Fetch API”, “LocalStorage”, “GitHub Pages”.
• Datos: dónde viven y cómo fluyen (token, favoritos, hecho-hoy flags, WV marks).
Para flechas:
• Direccionales y con verbos: fetch, read/write, emit event, load json, render DOM.
Sugerencia visual (simple y efectiva):
• Azul: UI/Views (Sidebar, módulos)
• Verde: servicios compartidos (API client, storage, router)
• Naranja: fuentes externas (GW2 API)
• Gris: assets estáticos y hosting
“No overthink”: separa en muchos componentes, pero anclados a cosas reales
Regla práctica para este repo:
• Todo lo que tenga archivo propio en js/ es un componente en el diagrama.
• Todo lo que el README enumera como “módulo” es un subcomponente aunque el código esté en app.js.
• Todo lo persistido en LocalStorage es un data store (aunque sea local).
• Todo endpoint/área de la GW2 API usada (account, WV, achievements, worldbosses/mapchests, exchange) es un external dependency con flechas explícitas.
Contenedores: Hosting / Browser App / External API / Static Assets
3. Componentes (dentro Browser App): app.js, router.js, api-gw2.js, meta.js, achievements.js, sidebar-nav.js, Storage, Toast/UI utils
Secuencias: #/meta init + cache TTL + reset UTC; token-permissions failure
Con esto obtienes una arquitectura fiel al repo, detallada, y útil para evolucionar módulos sin inventar infraestructura que no existe.