# zyronon/typewords architecture

> Architecture diagram of the GitHub repository zyronon/typewords, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zyronon/typewords
- Repository: https://github.com/zyronon/typewords

## Overview

##### Project type and purpose
- This is a front-end–only Single-Page Application (SPA) built with Vue (Composition API), Vite, and static hosting.
- Purpose: A self-contained English learning tool (“TypeWords”) offering word and article practice, local persistence, optional translation via external APIs, and offline-capable caching.

##### File structure
Top-level overview:
- src/         → Vue application source (components, pages, stores, hooks, utils)
- js_node/     → Node.js scripts for data preprocessing (dictionaries, crawlers)
- scripts/     → Build/deploy helper scripts (OSS upload, sitemap generation)
- Dockerfile, docker-compose.yml → Dev container definitions
- .github/workflows → CI pipelines for build & deploy (Aliyun OSS, GitHub Pages)
- netlify.toml, vercel/ → Hosting configuration
- README, docs/ → Project docs & contribution guide

##### Architecture insights from README
- Static-hosted SPA; data persisted locally (indexedDB/localStorage).
- Translation feature via Baidu or other external translation services (src/libs/translate).
- CI/CD pipelines deploy build output to multiple CDNs/hosts (OSS, Vercel, Netlify).

##### Elements
- Clear labels: “Browser”, “Service Worker”, “Vue SPA”, “LocalStorage/IndexedDB”, “CDN/OSS”, “Translation API”, “CI/CD”
- Browser → CDN (fetch assets)
- Service Worker ↔ CDN (cache & serve)
- SPA → LocalStorage (read/write)
- SPA → Translation API (HTTP request)
- GitHub Actions → Build artifact → CDN deployment
- Orange for external services
- Rounded rectangles for CI/CD pipelines

##### Detailed breakdown
- Split “Vue SPA” into sub-components:
- Router (router.ts)
- Stores (src/stores)
- Pages (src/pages/**)
- Components (src/components/**)
- Utilities & hooks (src/utils, src/hooks)
- “Public Data” area: JSON dictionaries & sound assets served from CDN.
- “js_node” scripts as an offline data-preparation step (not in production runtime).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Environment
    Browser["Browser / User Device"]:::client

    %% Hosting & CDN
    subgraph "Static Hosting / CDN" 
        OSS["Aliyun OSS / Vercel / Netlify"]:::hosting
        PublicAssets["Public Assets<br>(dicts/, sound/, list/, robots.txt, manifest.json)"]:::hosting
    end

    %% Service Worker
    SW["Service Worker<br>(service-worker.js)"]:::client

    %% Vue SPA
    subgraph "Vue SPA (Client-side)" 
        Main["Entry Point<br>main.ts"]:::client
        App["App.vue"]:::client
        Router["Router<br>router.ts"]:::client
        Stores["Stores<br>(src/stores/)"]:::client
        Pages["Pages<br>(src/pages/)"]:::client
        Components["UI Components<br>(src/components/)"]:::client
        Hooks["Hooks<br>(src/hooks/)"]:::client
        Utils["Utils<br>(src/utils/)"]:::client
        API["API Layer<br>apis/index.ts"]:::client
        TranslateLib["Translate Lib<br>(src/libs/translate/)"]:::client
        Persistence["Local Persistence<br>(IndexedDB/localStorage hooks)"]:::client
    end

    %% External Services
    ExtAPI["External Translation API"]:::external

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        GH_Aliyun["deploy-aliyun-oss.yml"]:::ci
        GH_Pages["deploy-pages.yml"]:::ci
    end

    %% Deployment Helpers
    subgraph "Deployment Helpers" 
        DeployOSS["scripts/deploy-oss.js"]:::ci
        SitemapGen["scripts/generate-sitemap.js"]:::ci
    end

    %% Data Preprocessing
    Preprocess["Data Preprocessing Scripts<br>(js_node/)"]:::offline

    %% Dev Environment
    DevEnv["Docker Dev Env<br>(Dockerfile, docker-compose.yml)"]:::ci

    %% Connections
    Browser -->|fetch index.html| OSS
    Browser -->|fetch assets| SW
    SW -->|cache & serve| OSS
    SW -->|intercept requests| Browser

    Browser -->|loads SPA| Main
    Main --> App
    App --> Router
    App --> Stores
    App --> Pages
    App --> Components
    App --> Hooks
    App --> Utils
    App --> API
    App --> Persistence
    App -->|use translate lib| TranslateLib
    API -->|HTTP calls| ExtAPI

    Browser -->|assets| PublicAssets
    App -->|fetch dicts/audio| PublicAssets

    GH_Aliyun -->|on push build| DeployOSS
    GH_Pages -->|on push build| OSS
    DeployOSS --> OSS
    SitemapGen --> OSS

    Preprocess -->|generate JSON| PublicAssets

    DevEnv --> Main

    %% Click Events
    click SW "https://github.com/zyronon/typewords/blob/master/service-worker.js"
    click Main "https://github.com/zyronon/typewords/blob/master/src/main.ts"
    click App "https://github.com/zyronon/typewords/blob/master/src/App.vue"
    click Router "https://github.com/zyronon/typewords/blob/master/src/router.ts"
    click Stores "https://github.com/zyronon/typewords/tree/master/src/stores/"
    click Pages "https://github.com/zyronon/typewords/tree/master/src/pages/"
    click Components "https://github.com/zyronon/typewords/tree/master/src/components/"
    click Hooks "https://github.com/zyronon/typewords/tree/master/src/hooks/"
    click Utils "https://github.com/zyronon/typewords/tree/master/src/utils/"
    click API "https://github.com/zyronon/typewords/blob/master/src/apis/index.ts"
    click TranslateLib "https://github.com/zyronon/typewords/tree/master/src/libs/translate/"
    click Persistence "https://github.com/zyronon/typewords/blob/master/src/hooks/dict.ts"
    click Persistence "https://github.com/zyronon/typewords/blob/master/src/hooks/article.ts"
    click Persistence "https://github.com/zyronon/typewords/blob/master/src/hooks/translate.ts"
    click PublicAssets "https://github.com/zyronon/typewords/tree/master/public/dicts/"
    click PublicAssets "https://github.com/zyronon/typewords/tree/master/public/sound/"
    click PublicAssets "https://github.com/zyronon/typewords/tree/master/public/list/"
    click PublicAssets "https://github.com/zyronon/typewords/blob/master/public/robots.txt"
    click PublicAssets "https://github.com/zyronon/typewords/blob/master/manifest.json"
    click Preprocess "https://github.com/zyronon/typewords/tree/master/js_node/"
    click GH_Aliyun "https://github.com/zyronon/typewords/blob/master/.github/workflows/deploy-aliyun-oss.yml"
    click GH_Pages "https://github.com/zyronon/typewords/blob/master/.github/workflows/deploy-pages.yml"
    click DeployOSS "https://github.com/zyronon/typewords/blob/master/scripts/deploy-oss.js"
    click SitemapGen "https://github.com/zyronon/typewords/blob/master/scripts/generate-sitemap.js"
    click DevEnv "https://github.com/zyronon/typewords/tree/master/Dockerfile"
    click DevEnv "https://github.com/zyronon/typewords/blob/master/docker-compose.yml"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0288D1,color:#000;
    classDef hosting fill:#DFFFE0,stroke:#2E7D32,color:#000;
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef ci fill:#FFE0E0,stroke:#C62828,color:#000;
    classDef offline fill:#E0E0E0,stroke:#424242,color:#000;
```
