# pablosnchz/gw2-wallet-ligero architecture

> Architecture diagram of the GitHub repository pablosnchz/gw2-wallet-ligero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pablosnchz/gw2-wallet-ligero
- Repository: https://github.com/pablosnchz/gw2-wallet-ligero

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% CONTEXT (System Context)
  %% =======================
  subgraph "System Context"
    U["User (GW2 Player)\nBrowser"]:::external

    GH["GitHub Pages\nStatic Hosting/CDN"]:::hosting
    SPA["GW2 Account SPA\nStatic HTML/CSS/Vanilla JS"]:::app
    LS[("Browser LocalStorage\n(token, favorites, flags, WV marks)")]:::storage
    API["ArenaNet Guild Wars 2 API\nExternal Backend"]:::external
    OUT["External Links (Wiki/Map)\n(navigation out of app)"]:::external
  end

  U -->|"interacts"| SPA
  GH -->|"serves (HTML/CSS/JS/assets)"| SPA
  SPA <-->|"read/write"| LS
  SPA <-->|"HTTPS fetch (API key)"| API
  SPA -->|"opens links"| OUT

  %% =======================
  %% CONTAINERS (Runtime)
  %% =======================
  subgraph "Containers"
    subgraph "Static Hosting"
      IDX["index.html\nSPA shell + mount point"]:::hosting
      CSSA["CSS Themes\nDeluxe/Compact"]:::hosting
      CSSP["Theme 'polish'"]:::hosting
      ASSETS["Static Assets\n(meta json, icons, meta docs)"]:::hosting
    end

    subgraph "Browser App (SPA Runtime)"
      RUNTIME["Runtime\nDOM + Fetch + Events"]:::app
      MEM["In-memory State/Cache\n(TTL, computed view models)"]:::cache
      LS2[("LocalStorage\npersistent user data")]:::storage
    end

    subgraph "External Services"
      GW2["Guild Wars 2 API\n(account, achievements, WV, worldbosses, mapchests, exchange)"]:::external
    end
  end

  IDX -->|"loads"| RUNTIME
  CSSA -->|"styles"| RUNTIME
  CSSP -->|"styles"| RUNTIME
  ASSETS -->|"loads json/icons"| RUNTIME
  RUNTIME <-->|"read/write"| LS2
  RUNTIME -->|"fetch"| GW2

  %% =======================
  %% COMPONENTS (Inside Browser App)
  %% =======================
  subgraph "Components (js/*) — inside Browser App"
    APP["App Bootstrap (app.js)\ninit theme, global listeners, wire router + sidebar, toasts"]:::service
    ROUTER["Router (router.js)\nhash routing '#/...'\nemits 'gn:tabchange'"]:::service
    APIClient["GW2 API Client (api-gw2.js)\nfetch wrapper, inject token, handle 401/403/404"]:::service

    SIDEBAR["Sidebar Navigation (sidebar-nav.js)\nnav, icons, top-3 upcoming, favorites"]:::ui

    subgraph "Feature Modules"
      META["MetaEvents Module (meta.js)\nschedule, 'Done today', favorites (max 6)\nTTL cache 5 min per token + reset UTC"]:::ui
      ACH["Achievements Module (achievements.js)\nprogress, filters, categories"]:::ui
      OTHER["Other Modules (logical)\nWallet, Wizard's Vault, Gem↔Gold Converter, API Keys UI"]:::ui
    end

    subgraph "Local Data + Persistence (logical services)"
      STORAGE["Storage Service (logical)\nencapsulate localStorage keys/selected token/flags/marks"]:::storage
      ASSETLOADER["Assets/Metadata Loader (logical)\nload meta-events.json, meta-drops.json, icons"]:::data
      CACHE["Client Cache (logical)\nTTL (5 min/token), auto-refresh at UTC reset"]:::cache
      UIUTILS["UI Utils (logical)\ntoasts, tooltips, render helpers"]:::service
    end
  end

  %% Wiring / dependencies (solid)
  APP -->|"initializes"| ROUTER
  APP -->|"initializes"| SIDEBAR
  APP -->|"uses"| UIUTILS
  APP -->|"uses"| STORAGE

  ROUTER -->|"activates view"| META
  ROUTER -->|"activates view"| ACH
  ROUTER -->|"activates view"| OTHER

  META -->|"calls"| APIClient
  ACH -->|"calls"| APIClient
  OTHER -->|"calls"| APIClient

  META -->|"load json/icons"| ASSETLOADER
  SIDEBAR -->|"load icons/meta"| ASSETLOADER

  META <-->|"read/write favorites + done flags"| STORAGE
  SIDEBAR <-->|"read/write favorites"| STORAGE
  OTHER <-->|"read/write token + WV marks"| STORAGE

  META <-->|"use/update"| CACHE
  CACHE -->|"may refresh"| APIClient

  APIClient -->|"fetch (HTTPS)"| GW2

  %% Event-driven init (dotted)
  ROUTER -.->|"emit 'gn:tabchange'"| META
  ROUTER -.->|"emit 'gn:tabchange'"| ACH
  ROUTER -.->|"emit 'gn:tabchange'"| OTHER

  %% =======================
  %% FLOWS (as mini-graphs, vertical)
  %% =======================
  subgraph "Flow 1 — Navigate '#/meta' + 'Done today' (TTL + UTC reset)"
    F1A["User navigates to '#/meta'"]:::note
    F1B["Router parses hash"]:::note
    F1C["Emit 'gn:tabchange'"]:::note
    F1D["MetaEvents init"]:::note
    F1E["Load assets (meta-events/drops/icons)\n(if not in memory)"]:::note
    F1F["Read LocalStorage\n(token, favorites, done flags)"]:::note
    F1G["Check cache\n(TTL 5 min per token)"]:::note
    F1H["Fetch GW2 endpoints\n(worldbosses, mapchests, etc.)"]:::note
    F1I["Render UI + tooltips\nUpdate Sidebar top-3"]:::note
    F1J["Schedule auto-refresh\nat UTC reset"]:::note

    F1A --> F1B --> F1C --> F1D --> F1E --> F1F --> F1G
    F1G -->|"cache miss/expired"| F1H --> F1I --> F1J
    F1G -->|"cache hit"| F1I
  end

  subgraph "Flow 2 — Token without permissions (403)"
    F2A["User adds/selects API key"]:::note
    F2B["Persist key in LocalStorage"]:::note
    F2C["Module calls API Client"]:::note
    F2D["GW2 API returns 403\n(permission missing)"]:::note
    F2E["Show clear toast/message\nDisable restricted UI sections"]:::note

    F2A --> F2B --> F2C --> F2D --> F2E
  end

  %% =======================
  %% Click Events (from mapping)
  %% =======================
  click IDX "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/index.html"
  click CSSA "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/css/main.css"
  click CSSP "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/css/theme-polish.css"
  click APP "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/js/app.js"
  click ROUTER "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/js/router.js"
  click APIClient "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/js/api-gw2.js"
  click META "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/js/meta.js"
  click ACH "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/js/achievements.js"
  click SIDEBAR "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/js/sidebar-nav.js"
  click ASSETS "https://github.com/pablosnchz/gw2-wallet-ligero/tree/main/assets/"
  click ASSETLOADER "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/assets/meta-events.json"
  click ASSETLOADER "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/assets/meta-drops.json"
  click ASSETS "https://github.com/pablosnchz/gw2-wallet-ligero/tree/main/assets/icons/"
  click ASSETS "https://github.com/pablosnchz/gw2-wallet-ligero/tree/main/assets/meta/"
  click GH "https://github.com/pablosnchz/gw2-wallet-ligero/tree/main/.github/"
  click SPA "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/README.md"

  %% Dedicated clicks for specific asset files (separate invisible nodes to avoid path in label)
  MEVENTS["meta-events.json"]:::data
  MDROPS["meta-drops.json"]:::data
  ICONS["icons/"]:::data
  METAAS["meta/"]:::data
  MEVENTS -->|"used by"| META
  MDROPS -->|"used by"| META
  ICONS -->|"used by"| SIDEBAR
  METAAS -->|"reference"| META
  click MEVENTS "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/assets/meta-events.json"
  click MDROPS "https://github.com/pablosnchz/gw2-wallet-ligero/blob/main/assets/meta-drops.json"
  click ICONS "https://github.com/pablosnchz/gw2-wallet-ligero/tree/main/assets/icons/"
  click METAAS "https://github.com/pablosnchz/gw2-wallet-ligero/tree/main/assets/meta/"

  %% =======================
  %% Styles
  %% =======================
  classDef app fill:#1f77b4,stroke:#0b3d91,stroke-width:1.2px,color:#ffffff
  classDef ui fill:#4ea3ff,stroke:#0b3d91,stroke-width:1.0px,color:#0b1b2b
  classDef service fill:#2ca02c,stroke:#145a14,stroke-width:1.0px,color:#062006
  classDef storage fill:#8e44ad,stroke:#4a235a,stroke-width:1.0px,color:#ffffff
  classDef cache fill:#16a085,stroke:#0b5345,stroke-width:1.0px,color:#042a24
  classDef hosting fill:#7f8c8d,stroke:#2c3e50,stroke-width:1.0px,color:#ffffff
  classDef external fill:#e67e22,stroke:#7a3e00,stroke-width:1.0px,color:#1f1206
  classDef data fill:#bdc3c7,stroke:#2c3e50,stroke-width:1.0px,color:#111111
  classDef note fill:#f9e79f,stroke:#b7950b,stroke-width:1.0px,color:#3b2f00
```
