# cookercandle/kadomaker architecture

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

- Interactive diagram: https://gitdiagram.com/cookercandle/kadomaker
- Repository: https://github.com/cookercandle/kadomaker

## Overview

##### Project Type and Purpose
- This is a command-line tool designed to generate PDF flashcards for learning Japanese.
- Its primary purpose is to take a JSON file (files/words.json) containing the flashcards data (with kanji, reading, and translation) and output a formatted PDF. The design supports both landscape and portrait orientations (landscape.py and portrait.py).

##### Key Components Based on the File Structure
- Entry Point Scripts:
- landscape.py and portrait.py: These are the executable scripts that trigger PDF generation. They serve as the main interfaces to run the application in different layouts.
- Data Files:
- files/words.json: The source of flashcards data.
- files/yumin.ttf (mentioned in the README but not shown in the file tree): A font file, crucial for rendering Japanese scripts correctly.
- Output Directory:
- output/: Contains the generated PDF files (e.g., landscape-dars.pdf and portrait-dars.pdf).
- Core Library Modules (located in the sources directory):
- sources/__init__.py: Initializes the library module.
- sources/fonts.py: Likely handles font-related functionality including loading and setting up custom Japanese fonts.
- sources/words.py: Manages processing and structuring flashcards from the input JSON.
- sources/wrap.py: Takes care of text wrapping for long translations and possibly layouts the flashcards neatly.
- Configuration and Dependency Files:
- requirements.txt: Lists all Python dependencies needed.
- .gitignore, LICENSE, and README.md: Standard project meta-information.

##### Architectural Patterns & Relationships
- Layered/Modular Design Pattern:
- The project clearly separates the presentation (entry scripts) from the core processing logic (modules in the sources folder).
- Input → Processing → Output Flow:
- Input: The JSON file (files/words.json) provides the flashcards data.
- Processing: The sources modules handle parsing, layout computations, text wrapping, and applying fonts as specified.
- Output: The PDF files are generated and saved in the output folder.
- Separation of Orientation Logic:
- Two distinct scripts (landscape.py and portrait.py) indicate that layout adjustments for different print orientations are handled somewhat separately but reuse the core processing libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Points"
        LANDSCAPE["landscape.py"]:::entry
        PORTRAIT["portrait.py"]:::entry
    end

    subgraph "Input Layer"
        JSON["files/words.json"]:::data
        FONT["files/yumin.ttf"]:::data
    end

    subgraph "Core Processing Modules"
        LIB_INIT["sources/__init__.py"]:::core
        FLASHCARDS["sources/words.py"]:::core
        WRAPPER["sources/wrap.py"]:::core
        FONTS["sources/fonts.py"]:::core
    end

    subgraph "Output Layer"
        PDF_BUILDER["PDF Generator"]:::output
        OUTPUT_DIR["output/"]:::output
    end

    subgraph "Configuration & Metadata"
        CONFIG["requirements.txt"]:::metadata
        META[".gitignore, LICENSE, README.md"]:::metadata
    end

    %% Connections from Entry Points to Core Processing
    LANDSCAPE -->|"calls"| FLASHCARDS
    PORTRAIT -->|"calls"| FLASHCARDS

    %% Input Layer feeds Core Processing
    JSON -->|"feeds"| FLASHCARDS
    FONT -->|"supplies"| FONTS

    %% Core Library Initialization
    LIB_INIT -->|"initializes"| FLASHCARDS
    LIB_INIT -->|"initializes"| WRAPPER
    LIB_INIT -->|"initializes"| FONTS

    %% Core Processing interactions
    FLASHCARDS -->|"sends-data"| WRAPPER
    FLASHCARDS -->|"sends-data"| FONTS

    %% Generation of PDF
    WRAPPER -->|"formats"| PDF_BUILDER
    FONTS -->|"formats"| PDF_BUILDER
    PDF_BUILDER -->|"writes"| OUTPUT_DIR

    %% Configuration and Metadata influence Initialization
    CONFIG -->|"loads"| LIB_INIT
    META -->|"informs"| LIB_INIT

    %% Click Events
    click LANDSCAPE "https://github.com/cookercandle/kadomaker/blob/main/landscape.py"
    click PORTRAIT "https://github.com/cookercandle/kadomaker/blob/main/portrait.py"
    click JSON "https://github.com/cookercandle/kadomaker/blob/main/files/words.json"
    click FONT "https://github.com/cookercandle/kadomaker/blob/main/files/yumin.ttf"
    click FLASHCARDS "https://github.com/cookercandle/kadomaker/blob/main/sources/words.py"
    click WRAPPER "https://github.com/cookercandle/kadomaker/blob/main/sources/wrap.py"
    click FONTS "https://github.com/cookercandle/kadomaker/blob/main/sources/fonts.py"
    click LIB_INIT "https://github.com/cookercandle/kadomaker/blob/main/sources/__init__.py"
    click CONFIG "https://github.com/cookercandle/kadomaker/blob/main/requirements.txt"
    click META "https://github.com/cookercandle/kadomaker/blob/main/.gitignore, LICENSE, README.md"
    click OUTPUT_DIR "https://github.com/cookercandle/kadomaker/tree/main/output/"

    %% Styles
    classDef entry fill:#f9d5e5,stroke:#b32454,stroke-width:2px;
    classDef data fill:#ffd9b3,stroke:#d47f1d,stroke-width:2px;
    classDef core fill:#c7f7c7,stroke:#479a47,stroke-width:2px;
    classDef output fill:#fcd5ce,stroke:#aa6d32,stroke-width:2px;
    classDef metadata fill:#d7d0f0,stroke:#6666ff,stroke-width:2px;
```
