# ekam02/wordweave architecture

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

- Interactive diagram: https://gitdiagram.com/ekam02/wordweave
- Repository: https://github.com/ekam02/wordweave

## Overview

##### Project type and purpose
- WordWeave is a Python-based command-line application whose goal is to generate Anki flashcards from lists of English words by scraping definitions/examples from various online dictionaries (Cambridge, Oxford, and a site called “Inglés”).
- It reads word lists, fetches data from external dictionary pages, transforms that data into card “notes” (by part of speech), and outputs a deck file that can be imported into Anki.

##### File structure
- Top-level files:
- main.py            – orchestration entry point
- requirements.txt   – external dependencies
- README.md, LICENSE
- Directories:
- pages/             – scraper modules for each dictionary
- notes/             – note-factory modules (adjective, noun, verb, general vocabulary)
- utils/             – shared helpers (configuration, ID generation, word-list reading)
- tests/             – unit tests for each scraper module
- No database; output is an Anki deck file (likely created in main.py or a notes module).

##### README for additional insights
- README is minimal, but its title (“Maker Anki Flashcards (English)”) confirms that the core use case is automated flashcard generation.

##### Main components and their relationships
a. CLI Orchestrator (main.py)
- Reads CLI arguments or configuration
- Invokes utils.read_words to load a list of target words
- Iterates through each word, dispatching it to the scrapers and note generators
- Aggregates all Note objects into an Anki deck
- Writes out the deck file
b. Configuration Layer (utils/config.py)
- Central place for API endpoints, output paths, scraping parameters
- Injected into pages scrapers and main process
c. Word Input Layer (utils/read_words.py)
- Loads word lists from files or other sources
- Returns a normalized list for processing
d. Scraping Layer (pages/*.py)
- Three separate modules (cambridge, oxford, ingles)
- Each module:
- Accepts a word
- Fetches HTML from the corresponding dictionary website
- Parses out definitions, examples, pronunciations
- Returns raw data structures to the orchestrator
e. -Factory Layer (notes/*.py)
- Four modules: adjective, noun, verb, vocabulary
- Each module knows how to format scraped data into the correct Anki note template
- Provides a uniform Note object interface (fields: front, back, tags, etc.)
f. Output Layer (inside main.py or a notes utility)
- Aggregates Note objects into a deck
- Uses a library (e.g., genanki) to serialize into .apkg
g. Testing Layer (tests/*.py)
- Each scraper has its own test to verify parsing logic
- Ensures robustness against HTML changes

##### Architectural patterns and design principles
- Layered architecture (CLI → utilities → scrapers → note generators → output)
- Single responsibility per module (one dictionary scraper per file)
- Dependency injection of config into scrapers
- Test-driven approach for scraping logic
- Factory pattern for Note creation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Orchestration Layer
    subgraph "Core Orchestration"
        CLI["CLI Orchestrator (main.py)"]:::core
        Config["Config Service"]:::core
        Reader["Word Reader"]:::core
        IDGen["ID Generation Utility"]:::core
    end

    %% Scraping Layer
    subgraph "Scraping Layer"
        CamScraper["Cambridge Scraper"]:::external
        OxfScraper["Oxford Scraper"]:::external
        IngScraper["Inglés Scraper"]:::external
        CambridgeSite["☁️ Cambridge Website"]:::external
        OxfordSite["☁️ Oxford Website"]:::external
        InglesSite["☁️ Inglés Website"]:::external
    end

    %% Note-Factory Layer
    subgraph "Note Factory Layer"
        AdjFactory["Adjective Note Factory"]:::process
        NounFactory["Noun Note Factory"]:::process
        VerbFactory["Verb Note Factory"]:::process
        VocabFactory["Vocabulary Note Factory"]:::process
    end

    %% Output Layer
    subgraph "Output Layer"
        DeckBuilder["Anki Deck Builder"]:::output
        OutputFile["📄 Anki Deck (.apkg)"]:::output
    end

    %% Test Layer
    subgraph "Test Suite"
        TestCam["Test Cambridge Scraper"]:::test
        TestOxf["Test Oxford Scraper"]:::test
        TestIng["Test Inglés Scraper"]:::test
    end

    %% External Input
    WordList["📄 Word List File"]:::external

    %% Relationships
    WordList -->|loads words| Reader
    Reader -->|word list| CLI
    CLI -->|dispatch word| CamScraper
    CLI -->|dispatch word| OxfScraper
    CLI -->|dispatch word| IngScraper

    CamScraper -->|fetch HTML| CambridgeSite
    OxfScraper -->|fetch HTML| OxfordSite
    IngScraper -->|fetch HTML| InglesSite

    CamScraper -->|raw data| AdjFactory
    OxfScraper -->|raw data| NounFactory
    IngScraper -->|raw data| VerbFactory

    AdjFactory -->|Note objects| DeckBuilder
    NounFactory -->|Note objects| DeckBuilder
    VerbFactory -->|Note objects| DeckBuilder
    VocabFactory -->|Note objects| DeckBuilder

    DeckBuilder -->|create deck| OutputFile

    %% Config injections
    Config -.->|config params| CLI
    Config -.->|config params| CamScraper
    Config -.->|config params| OxfScraper
    Config -.->|config params| IngScraper
    Config -.->|config params| AdjFactory
    Config -.->|config params| NounFactory
    Config -.->|config params| VerbFactory
    Config -.->|config params| VocabFactory

    %% Tests
    TestCam -->|tests parsing| CamScraper
    TestOxf -->|tests parsing| OxfScraper
    TestIng -->|tests parsing| IngScraper

    %% Click Events
    click CLI "https://github.com/ekam02/wordweave/blob/main/main.py"
    click Config "https://github.com/ekam02/wordweave/blob/main/utils/config.py"
    click Reader "https://github.com/ekam02/wordweave/blob/main/utils/read_words.py"
    click IDGen "https://github.com/ekam02/wordweave/blob/main/utils/ident.py"
    click CamScraper "https://github.com/ekam02/wordweave/blob/main/pages/cambridge.py"
    click OxfScraper "https://github.com/ekam02/wordweave/blob/main/pages/oxford.py"
    click IngScraper "https://github.com/ekam02/wordweave/blob/main/pages/ingles.py"
    click AdjFactory "https://github.com/ekam02/wordweave/blob/main/notes/adjective.py"
    click NounFactory "https://github.com/ekam02/wordweave/blob/main/notes/noun.py"
    click VerbFactory "https://github.com/ekam02/wordweave/blob/main/notes/verb.py"
    click VocabFactory "https://github.com/ekam02/wordweave/blob/main/notes/vocabulary.py"
    click TestCam "https://github.com/ekam02/wordweave/blob/main/tests/test_cambridge.py"
    click TestOxf "https://github.com/ekam02/wordweave/blob/main/tests/test_oxford.py"
    click TestIng "https://github.com/ekam02/wordweave/blob/main/tests/test_ingles.py"

    %% Styles
    classDef core fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef external fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20;
    classDef process fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef output fill:#F3E5F5,stroke:#9C27B0,color:#4A148C;
    classDef test fill:#ECEFF1,stroke:#90A4AE,color:#546E7A;
```
