# thomasatlantis/words2card architecture

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

- Interactive diagram: https://gitdiagram.com/thomasatlantis/words2card
- Repository: https://github.com/thomasatlantis/words2card

## Overview

##### Project type and purpose
- This is a small, single-purpose Python CLI tool (“Words2Card”) that takes user-supplied quotes (in JSON), overlays them on a cover image, and outputs a shareable picture card.

##### File structure
- Top-level files
– data.txt: a JSON array of quote objects (author, quotes, optional image URL/path)
– words2card.py: the core Python program orchestrating input→render→output
– netease_lyric.py: an auxiliary script (from the NeteaseLyric project) for fetching lyrics (optional integration)
- Directories
– image/: user-provided cover images used when a quote’s “image” field is empty
– output/: destination folder for generated card images
- Dependencies and config
– Python 3.x, PIL/Pillow (for image manipulation)
– No complex build or deployment scripts—just `pip install Pillow`

##### README for architectural hints
- Mentions optional remote image URLs and fallback to local images

##### Components
a. Main components
1. Input Data Store
- JSON file (data.txt)
- Optional NeteaseLyric API module (netease_lyric.py)
2. Resource Manager
- Local cover images (image/)
3. Card Generation Engine
- words2card.py (Python script using PIL)
- Layout & typography logic
4. Output Sink
- output/ directory (PNG files)
b. Relationships & Data Flow
- Engine → Output Sink (writes .png files)
- If network image URL provided: Engine → External HTTP Service → Engine
c. Architectural patterns & principles
- Pipeline pattern: a sequential flow of transform steps (parse → select resources → render → write)
- Single-responsibility modules: separation between data access (JSON/lyrics), rendering logic, and resource management
d. Key technologies
- Python 3.x, PIL/Pillow (image compositing)
- JSON parsing (built-in `json` module)
- Font rendering via .ttc file
- Optional HTTP client (for remote images or lyrics)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Data Store"
        data["data.txt<br/>(JSON Quotes)"]:::input
        netease["netease_lyric.py<br/>(Lyrics Module)"]:::input
    end

    subgraph "Resource Manager"
        image["image/<br/>(Cover Images)"]:::resource
        static["static/<br/>(Assets: icons, fonts)"]:::resource
        font["STHeiti_Light.ttc<br/>(Font File)"]:::resource
    end

    subgraph "External Services"
        http["External HTTP Service"]:::external
    end

    engine["words2card.py<br/>(Card Generation Engine)"]:::engine
    output["output/<br/>(Generated PNGs)"]:::output

    data -->|reads| engine
    netease -->|fetches lyrics| engine
    image -->|provides background| engine
    static -->|provides assets| engine
    font -->|provides font| engine
    engine -->|writes PNGs| output

    engine -->|fetch remote image| http
    http -->|returns image| engine

    click data "https://github.com/thomasatlantis/words2card/blob/master/data.txt"
    click netease "https://github.com/thomasatlantis/words2card/blob/master/netease_lyric.py"
    click image "https://github.com/thomasatlantis/words2card/tree/master/image/"
    click static "https://github.com/thomasatlantis/words2card/tree/master/static/"
    click font "https://github.com/thomasatlantis/words2card/blob/master/static/STHeiti_Light.ttc"
    click engine "https://github.com/thomasatlantis/words2card/blob/master/words2card.py"
    click output "https://github.com/thomasatlantis/words2card/tree/master/output/"

    classDef input fill:#cce5ff,stroke:#004085;
    classDef engine fill:#d4edda,stroke:#155724;
    classDef resource fill:#fff3cd,stroke:#856404;
    classDef output fill:#e2e3e5,stroke:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24;
```
