# sleepysoong/booklistbuilder architecture

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

- Interactive diagram: https://gitdiagram.com/sleepysoong/booklistbuilder
- Repository: https://github.com/sleepysoong/booklistbuilder

## Overview

##### Project Type and Purpose
- BookListBuilder is an open-source CLI tool (with optional GUI builds via PyInstaller) that automates fetching book details (cover image, metadata, ratings, library holdings) and outputs a consolidated Excel file. It integrates with external services (Aladin OpenAPI and a school library web portal) to retrieve data.

##### Main Components
a. Input Layer
- config.yml – holds API key, library URL, desired output filename
- .xlsx – user’s list of ISBN13s, target sheet names, optional memos
b. Processing Core
- script.py – orchestrates workflow
– Config Loader
– ISBN List Reader (openpyxl)
– Data Fetchers
◦ AladinAPI Client (requests to Aladin OpenAPI)
◦ LibraryLookup Scraper (requests + HTML parsing of school library site)
– Data Merger & Transformer (combines metadata, ratings, library status)
– Excel Writer (openpyxl or pandas)
c. External Services
- Aladin OpenAPI – provides book metadata, ratings, sales points
- School Library Web Portal – indicates campus holdings
d. Output Layer
- output.xlsx – final Excel workbook with separate sheets per list entry
- (Optional) cover image downloads or embedded URLs
e. Packaging & Deployment
- PyInstaller build (GitHub Actions workflow) produces standalone executables for Windows/macOS
- GitHub Releases – distribution channel

##### Relationships and Data Flow
- User invokes script.py → config.yml & list.xlsx are read → for each ISBN:
1. Fetch metadata from Aladin API
2. Scrape library site to check holdings
3. Aggregate results → write rows into output.xlsx
- CI/CD (GitHub Actions) listens on push/tags → runs PyInstaller to produce binaries → publishes to Releases.

##### Architectural Patterns & Design Principles
- Modular layering: Input → Processing → Output
- Single-responsibility modules: separate fetchers, readers, writers
- External integration abstracted behind client interfaces
- CI/CD pipeline automates packaging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    User["User"]:::external
    Config[("config.yml")]:::file
    List[("list.xlsx")]:::file

    User -->|invokes| ScriptOrch
    ScriptOrch["script.py"]:::local

    User -->|provides| Config
    User -->|provides| List

    %% Processing Core
    subgraph "Processing Core"
        CL["Config Loader"]:::local
        IR["ISBN List Reader"]:::local
        AC["AladinAPI Client"]:::local
        LS["LibraryLookup Scraper"]:::local
        DM["Data Merger & Transformer"]:::local
        EW["Excel Writer"]:::local
    end

    ScriptOrch -->|orchestrates| CL
    ScriptOrch -->|orchestrates| IR
    CL -->|reads| Config
    IR -->|reads| List

    IR -->|for each ISBN| AC
    IR -->|for each ISBN| LS
    AC -->|metadata| DM
    LS -->|holdings| DM
    DM -->|combined data| EW
    EW -->|writes| Output

    %% External Services
    subgraph "External Services"
        style ExternalCloud fill:#e0ffe0,stroke:#2d702d
        AAPI["Aladin OpenAPI"]:::external
        LibPortal["School Library Portal"]:::external
    end

    AC -->|requests| AAPI
    LS -->|scrapes| LibPortal

    %% Output Layer
    Output[("output.xlsx")]:::file

    %% Deployment
    subgraph "Deployment & CI/CD"
        CI["CI/CD Pipeline"]:::deployment
        PI["PyInstaller Build"]:::deployment
        EXE["Executables"]:::deployment
        GH["GitHub Releases"]:::deployment
    end

    ScriptOrch -->|on push/tags| CI
    CI -->|runs| PI
    PI -->|produces| EXE
    EXE -->|publishes| GH

    %% Project Artifacts
    subgraph "Project Artifacts"
        Req["requirements.txt"]:::file
        Readme["README.md"]:::file
        Img["images/"]:::file
    end

    %% Click Events
    click ConfigLoader "https://github.com/sleepysoong/booklistbuilder/blob/main/script.py"
    click ISBNListReader "https://github.com/sleepysoong/booklistbuilder/blob/main/script.py"
    click AladinAPIClient "https://github.com/sleepysoong/booklistbuilder/blob/main/script.py"
    click LibraryLookupScraper "https://github.com/sleepysoong/booklistbuilder/blob/main/script.py"
    click DataMergerTransformer "https://github.com/sleepysoong/booklistbuilder/blob/main/script.py"
    click ExcelWriter "https://github.com/sleepysoong/booklistbuilder/blob/main/script.py"
    click CI "https://github.com/sleepysoong/booklistbuilder/blob/main/ .github/workflows/build-with-pyinstaller.yml"
    click Req "https://github.com/sleepysoong/booklistbuilder/blob/main/requirements.txt"
    click Readme "https://github.com/sleepysoong/booklistbuilder/blob/main/README.md"
    click Img "https://github.com/sleepysoong/booklistbuilder/tree/main/images/"

    %% Styling
    classDef local fill:#ddeeff,stroke:#004488,stroke-width:1px
    classDef external fill:#e0ffe0,stroke:#228833,stroke-width:1px
    classDef deployment fill:#ffe0b3,stroke:#cc6600,stroke-width:1px
    classDef file fill:#f2f2f2,stroke:#999999,stroke-width:1px
    class User,AAPI,LibPortal external
    class Output,Config,List,Req,Readme,Img file
```
