# szymon-25/wikiscraper architecture

> Architecture diagram of the GitHub repository szymon-25/wikiscraper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/szymon-25/wikiscraper
- Repository: https://github.com/szymon-25/wikiscraper

## Overview

##### Typ projektu i jego cel (z kontekstu drzewa + README)

To jest **narzędzie CLI w Pythonie** do:
- **scrapowania** stron Bulbapedii (HTTP → HTML),
- **parsowania i ekstrakcji** treści (np. pierwszy paragraf, tabele, linki),
- **analizy tekstu** (count words, względna częstotliwość słów, porównanie z częstotliwością w języku),
- opcjonalnie **eksportu danych** (CSV/JSON) oraz **generowania wykresów**.

##### Analiza struktury repo (co mapować na komponenty)

Z drzewa i README wynika naturalny podział na warstwy/moduły:

##### Warstwa uruchomieniowa (entrypoints)
- `wiki_scraper.py` — **CLI** (argparse), dispatch komend/trybów działania.
- `obtain_data.py` — **skrypt pomocniczy** do pobierania danych demonstracyjnych (offline cache / przykładowe dane).
- `lang_confidence.ipynb` — notebook analityczny (raczej poza “runtime”, ale może być “offline analysis”).

##### Warstwa logiki biznesowej
- `scraper.py` — klasa `Scraper` i “core” logiki scrapowania/parsowania/analiz.

##### Warstwa narzędziowa
- `utils.py` — konwersje zapytań→URL, małe helpery.

##### Testy
- `tests/test_offline_only.py` — unit testy offline (deterministyczne).
- `tests/data/team_rocket.html` — fixture HTML.
- `wiki_scraper_integration_test.py` — integracyjny test (real HTTP / real parsing).

##### Zależności zewnętrzne (z README/requirements)
- `requests` — HTTP client
- `beautifulsoup4` — HTML parsing
- `pandas` — tablice/tabele + eksport CSV
- `matplotlib` — wykresy
- `wordfreq` — częstotliwość w języku (słownik/algorytm; potencjalnie też dane w `data/word_counts_*.json` wg README)

##### Systemy zewnętrzne / zasoby
- Bulbapedia (`bulbapedia.bulbagarden.net`) — upstream źródło HTML
- Lokalny filesystem — JSON/CSV/PNG, fixtures testowe

##### Co z README dopowiada architektonicznie (i co warto pokazać na diagramie)

README definiuje konkretne “use cases” CLI, które łatwo zamienić na “podsługi” w diagramie:

- `--summary <title>`: pobierz stronę → parse → wyciągnij 1 paragraf → stdout
- `--table <title> --number N --first-row-is-header`: pobierz → parse tabelę → pandas → CSV / analiza
- `--count-words <title>`: pobierz/parse text → tokenizacja → liczenie → wynik
- `--analyze-relative-word-frequency --mode article|language --count K [--chart path]`: agregacja z artykułów + porównanie z `wordfreq`/słownikami + opcjonalny wykres
- `--auto-count-words <title> --depth D --wait S`: rekursja po linkach + rate limiting (ważne: pokaż pętlę, kontrolę głębokości, “politeness delay”)

- wyraźny **dispatcher komend** (CLI → wybór ścieżki),
- wspólne **pipeline’y**: Fetch → Parse → Extract → Analyze → Output.

Podziel system na 6–8 bloków (im bardziej granularnie, tym lepiej, ale bez zgadywania):

##### CLI: `wiki_scraper.py`
- parsing args
- routing do funkcji
##### Core: `Scraper` (`scraper.py`)
- fetch_page(title/url)
- parse_html(...)
- extract_summary(...)
- extract_table(...)
- extract_links(...) (dla rekurencji)
- text extraction/cleaning
##### Utilities: `utils.py`
- build_bulbapedia_url(title)
- normalization (np. spacje/underscore) – o ile istnieje
##### External libs (podblok “Libraries”)
- `requests` (HTTP)
- `BeautifulSoup4` (DOM parsing)
- `pandas` (table ops/export)
- `matplotlib` (chart)
- `wordfreq` (language freq baseline)
##### Local Storage / Artifacts
- `data/*.json` (jeśli faktycznie używane)
- `Type.csv` / `Type_table.csv` (z README)
- `*.png` (chart)
##### Tests
- Offline: `tests/test_offline_only.py` + fixture HTML
- Integration: `wiki_scraper_integration_test.py` → Bulbapedia

Relacje (strzałki) na tym diagramie:
- User → CLI
- CLI → Scraper (wywołania metod)
- Scraper → utils
- Scraper → requests → Bulbapedia (HTTP)
- Scraper → BeautifulSoup (parse)
- Scraper → pandas (tables)
- Scraper → wordfreq / lokalne `data/*.json` (jeśli to jest baseline)
- Scraper → filesystem (CSV/JSON/PNG)
- Tests → (Scraper/CLI) oraz Offline test → fixture HTML (bez requests)

**(1) Summary / Count-words (prosty pipeline)**
- CLI args → Scraper.fetch(title) → HTTP GET → HTML
- HTML → BS4 parse → Text extraction → Summary/Tokenize+count → stdout

**(2) Table extraction**
- CLI → Scraper.fetch(title) → parse → select table #N → normalize header (flag) → pandas DataFrame → export CSV → opcjonalna analiza

**(3) Auto recursion**
- CLI → (queue of pages) → loop(depth, wait)
- For each page: fetch → parse → extract links → enqueue next-level
- Aggregator: accumulate word counts
- Output: JSON/summary
- **rate limit (wait), depth guard, visited set** (nawet jeśli nie widzisz tego w kodzie, zostaw jako “recommended internal mechanism” i oznacz jako “if implemented”/“assumed”; najlepiej zweryfikować w `scraper.py`).

##### Najważniejsze wzorce/zasady architektoniczne do podkreślenia

Dla tego repo to raczej:
- **Layering**: CLI (I/O) vs Core logic vs Helpers
- **Pipeline / ETL**: Extract (HTML) → Transform (parse/clean) → Load/Output (stdout/files)
- **Separation of concerns**: tests offline vs integration
- **External dependency boundaries**: Bulbapedia + libs (requests/bs4/pandas/wordfreq)

Na diagramie warto zaznaczyć “granice”:
- granica procesu (to jest single-process CLI),
- granica sieci (wyjście do Bulbapedii),
- granica dysku (artefakty).

##### Jak dobrać poziom szczegółowości do tego typu projektu (CLI tool)

- **komponenty kodu** (pliki/moduły jako boxy),
- **przepływy danych** w ramach jednego procesu,
- **ścieżki testowe** (offline/integration) jako równoległe “consumer’y” core.

Unikaj wrzucania typowych elementów web-arch (load balancer, serwery, DB) jeśli nie ma ich w repo.

1) **Czytelne etykiety**: nazwy plików/modułów (`wiki_scraper.py`, `scraper.py`, `utils.py`) oraz technologie (`requests`, `bs4`, `pandas`, `matplotlib`, `wordfreq`)
##### Strzałki kierunkowe z opisem
- “HTTP GET / HTML”
- “DOM parse”
- “Extract table → DataFrame”
- “Write CSV/JSON/PNG”
##### Kolory / kształty (proponowany standard)
- Prostokąty: moduły repo
- Chmura: Bulbapedia (external)
- Przerywana ramka: test harness
- Inny kolor dla bibliotek zewnętrznych

##### Proponowany układ diagramu (żeby principal szybko to narysował)

Układ lewo→prawo, jedna “linia produkcyjna”:

**[User] → [CLI wiki_scraper.py] → [Scraper (scraper.py)] →**
- górą: **[requests] → (Internet) → [Bulbapedia]**
- środkiem: **[BeautifulSoup parse] → [Extractors] → [Analyzers]**
- dołem: **[pandas/matplotlib/wordfreq]**
- na końcu: **[stdout] + [files: CSV/JSON/PNG]**

Z boku (prawy dół): **[Tests]**
- Offline test → fixture HTML → Scraper (bez network)
- Integration test → Scraper → Bulbapedia

##### “Nie overthinkuj” – jak rozdzielić na jak najwięcej komponentów bez konfabulacji

Jeśli chcesz maksymalnej szczegółowości, ale nadal zgodnej z repo, rozbij `Scraper` wewnątrz jednego boxa na podboxy funkcjonalne (nawet jeśli to metody w jednej klasie), podpisane jako “functions/methods”:
- URL Builder (utils)
- Fetcher (requests)
- Parser (bs4)
- Content Extractor (summary/text)
- Table Extractor (tables→DataFrame)
- Word Count / Tokenizer
- Relative Frequency Analyzer (wordfreq baseline)
- Chart Renderer (matplotlib)
- Exporter (CSV/JSON)

To jest najlepszy kompromis: bardzo detalicznie pokazujesz architekturę, ale nie twierdzisz, że to osobne serwisy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Global Inputs/Outputs
    %% =========================
    User["User / Shell"]:::external
    Stdout[/"stdout (terminal output)"/]:::io

    Bulbapedia["Bulbapedia\n(bulbapedia.bulbagarden.net)"]:::external

    FS[("Local filesystem\n(CSV/JSON/PNG, fixtures, caches)")]:::storage

    %% =========================
    %% Repo: Runtime Entry Points
    %% =========================
    subgraph "Runtime (single-process CLI tool)"
        direction TB

        CLI["CLI entrypoint\nwiki_scraper.py\n(argparse + command dispatch)"]:::repo
        Obtain["Helper script\nobtain_data.py\n(demo/offline data fetch/cache)"]:::repo

        subgraph "Core business logic"
            direction TB
            Scraper["Scraper core\nscraper.py\n(fetch/parse/extract/analyze/export)"]:::repo
            Utils["Utilities\nutils.py\n(URL building + normalization helpers)"]:::repo

            subgraph "Scraper internal pipeline (functions/methods)"
                direction TB
                Fetcher["Fetcher\n(fetch_page title/url)"]:::internal
                Parser["HTML Parser\n(parse_html)"]:::internal
                ExtractText["Content Extractor\n(summary/text cleaning)"]:::internal
                ExtractTable["Table Extractor\n(select N, header flag)"]:::internal
                ExtractLinks["Link Extractor\n(for recursion)"]:::internal
                WordCount["Tokenizer + Word Counter\n(count_words)"]:::internal
                RelFreq["Relative Frequency Analyzer\n(article vs language)"]:::internal
                Exporter["Exporter\n(CSV/JSON)"]:::internal
                Chart["Chart Renderer\n(PNG)"]:::internal
                Recursion["Auto recursion loop\n(depth guard + wait/rate-limit + visited set)\n(if implemented/assumed)"]:::internal
            end
        end

        subgraph "External libraries"
            direction TB
            Req["requirements.txt\n(dependencies list)"]:::repo
            Requests["requests\n(HTTP client)"]:::lib
            BS4["beautifulsoup4\n(DOM parsing)"]:::lib
            Pandas["pandas\n(DataFrame + CSV export)"]:::lib
            Matplotlib["matplotlib\n(charts)"]:::lib
            Wordfreq["wordfreq\n(language baseline frequency)"]:::lib
        end

        subgraph "Offline analysis (not runtime-critical)"
            direction TB
            Notebook["lang_confidence.ipynb\n(exploratory analysis)"]:::repo
        end
    end

    %% =========================
    %% Tests
    %% =========================
    subgraph "Test harness"
        direction TB
        OfflineTest["Offline unit tests\ntests/test_offline_only.py\n(deterministic, no network)"]:::test
        Fixture["HTML fixture\ntests/data/team_rocket.html"]:::artifact
        IntegrationTest["Integration test\nwiki_scraper_integration_test.py\n(real HTTP + real parsing)"]:::test
        Readme["README.md\n(CLI use-cases + outputs)"]:::repo
    end

    %% =========================
    %% Main control/dataflow
    %% =========================
    User -->|"invoke CLI"| CLI
    CLI -->|"dispatch command/mode"| Scraper

    Obtain -->|"writes cached/demo HTML/JSON"| FS
    CLI -->|"read/write artifacts (optional)"| FS

    Scraper -->|"uses helpers"| Utils

    %% Pipeline ordering inside Scraper (dataflow)
    Scraper -->|"orchestrates"| Fetcher
    Fetcher -->|"HTTP GET / HTML"| Requests
    Requests -->|"network"| Bulbapedia
    Requests -->|"HTML response"| Fetcher

    Scraper -->|"orchestrates"| Parser
    Parser -->|"DOM parse"| BS4

    Parser -->|"parsed DOM"| ExtractText
    Parser -->|"parsed DOM"| ExtractTable
    Parser -->|"parsed DOM"| ExtractLinks

    ExtractText -->|"text"| WordCount
    WordCount -->|"counts"| RelFreq
    RelFreq -->|"language baseline"| Wordfreq

    ExtractTable -->|"table rows"| Pandas
    Pandas -->|"DataFrame"| Exporter

    RelFreq -->|"top K + metrics"| Chart
    Chart -->|"render plot"| Matplotlib

    Exporter -->|"write CSV/JSON"| FS
    Chart -->|"write PNG"| FS

    ExtractText -->|"summary/cleaned text"| Stdout
    WordCount -->|"word counts"| Stdout
    RelFreq -->|"relative freq report"| Stdout

    %% Recursion scenario
    CLI -->|"--auto-count-words"| Recursion
    Recursion -->|"loop over pages"| Fetcher
    Recursion -->|"extract links to enqueue"| ExtractLinks
    Recursion -->|"aggregate counts"| WordCount
    Recursion -->|"optional export"| Exporter

    %% =========================
    %% Tests dataflow
    %% =========================
    OfflineTest -->|"load fixture HTML"| Fixture
    OfflineTest -->|"parse/extract/analyze offline"| Scraper
    IntegrationTest -->|"exercise real fetch+parse"| Scraper
    IntegrationTest -->|"hits upstream"| Bulbapedia

    Readme -.->|"documents CLI modes"| CLI
    Req -.->|"declares dependencies"| Requests
    Req -.->|"declares dependencies"| BS4
    Req -.->|"declares dependencies"| Pandas
    Req -.->|"declares dependencies"| Matplotlib
    Req -.->|"declares dependencies"| Wordfreq

    %% =========================
    %% Click events (component mapping)
    %% =========================
    click CLI "https://github.com/szymon-25/wikiscraper/blob/master/wiki_scraper.py"
    click Obtain "https://github.com/szymon-25/wikiscraper/blob/master/obtain_data.py"
    click Scraper "https://github.com/szymon-25/wikiscraper/blob/master/scraper.py"
    click Utils "https://github.com/szymon-25/wikiscraper/blob/master/utils.py"
    click Notebook "https://github.com/szymon-25/wikiscraper/blob/master/lang_confidence.ipynb"
    click OfflineTest "https://github.com/szymon-25/wikiscraper/blob/master/tests/test_offline_only.py"
    click Fixture "https://github.com/szymon-25/wikiscraper/blob/master/tests/data/team_rocket.html"
    click IntegrationTest "https://github.com/szymon-25/wikiscraper/blob/master/wiki_scraper_integration_test.py"
    click Req "https://github.com/szymon-25/wikiscraper/blob/master/requirements.txt"
    click Readme "https://github.com/szymon-25/wikiscraper/blob/master/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef repo fill:#1f4b99,stroke:#0f2a55,color:#ffffff,stroke-width:1.5px
    classDef internal fill:#2f7d32,stroke:#1b4a1d,color:#ffffff,stroke-width:1.2px
    classDef lib fill:#6a1b9a,stroke:#3a0f55,color:#ffffff,stroke-width:1.2px
    classDef external fill:#b71c1c,stroke:#5f0d0d,color:#ffffff,stroke-width:1.5px
    classDef storage fill:#f9a825,stroke:#8a5a00,color:#1b1b1b,stroke-width:1.5px
    classDef io fill:#00838f,stroke:#004d52,color:#ffffff,stroke-width:1.3px
    classDef test fill:#455a64,stroke:#1c252b,color:#ffffff,stroke-width:1.2px
    classDef artifact fill:#8d6e63,stroke:#4e342e,color:#ffffff,stroke-width:1.2px
```
