# grant-vranes/typst2pdf-report-label-qrcode architecture

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

- Interactive diagram: https://gitdiagram.com/grant-vranes/typst2pdf-report-label-qrcode
- Repository: https://github.com/grant-vranes/typst2pdf-report-label-qrcode

## Overview

##### Main Components
- PDF Generation API (Backend Service): This is the core of the application. At the heart is the Spring Boot (or similar) application initialized in PdfGenerateApplication.java. It likely exposes REST endpoints through TypstController.
- Controller Layer: Represented by TypstController and possibly other similar classes. This layer receives external HTTP requests (as partially demonstrated by the test.http file) for generating PDFs.
- Service Layer: Captured in the implementation classes and DTOs within the modules/typst/service and modules/typst/service/impl directories. They contain business logic, including invoking the Typst execution process.
- Utility/Helper Components: Several common utility classes (DatePlusUtil, FileUtil, JsonUtil, ProcessUtil, ResourceFileUtil, UUIDUtils) support common operations like file handling or process execution.
- External Typst Engine & Template Files: The tool/ directory hosts the external Typst runtime binaries (for macOS, Windows, Linux) and Typst templates (under tool/typst_template) that are invoked by the Java backend. This part is crucial because it provides the conversion functionality via the CLI.
- Temporary File Storage: The service generates and stores temporary .typ and .pdf files (as described in the README during conversion) likely using the convert subfolder inside tool/typst_ctl.

##### Interactions and Data Flow
- A client (or testing tool such as the provided http_script/test.http) sends an HTTP request to the PDF Generation API endpoint.
- The request is handled by the TypstController, which extracts data and maps it to DTOs (like TemplateData, CoupletTemplateData, etc.).
- The controller then delegates to the service layer. Here, the implementation classes (TemplateImpl and CoupletTemplateImpl) produce the necessary data and prepare the Typst template (including any placeholder replacements).
- The service layer uses utility classes to generate temporary Typst (.typ) files and then calls the external Typst runtime (from the tool/typst_ctl directory) via command-line or process invocation (ProcessUtil could be responsible for this).
- The Typst runtime processes the .typ file and generates a PDF as output.
- The service layer collects the output PDF and returns it back through the controller to the client.

##### Architectural Patterns
- Layered (or MVC-like) Architecture: Clear separation between the controller (handling request/response), service (business logic), and utility/helper components.
- External Process Integration: The design includes calling external command-line tools (the Typst runtimes) for converting templates to PDFs.
- Pluggability for Templates: Using a designated template folder, the system supports varied template types (standard and couplet templates as evidenced by the two provided template files).

##### Additional Notes
- Integration between custom Java business logic and the Typst toolchain.
- Usage of configuration files (application.yaml) found in src/main/resources to indicate operational parameters.
- Remember to mark any intermediate data transformations, especially the manipulation of template data (DTOs) before conversion.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client("Client (HTTP Request)"):::client

    %% Backend API Subgraph
    subgraph "Backend API"
        direction TB
        A("PDF Generation API"):::backend
        B("Typst Controller"):::backend

        subgraph "Service Layer"
            direction TB
            C("Template Service (TemplateImpl)"):::service
            D("Couplet Template Service (CoupletTemplateImpl)"):::service
            E("Service Base: TypstExec"):::service
            F("Service Base: AbstractTypstExecBase"):::service
        end

        subgraph "DTOs"
            direction TB
            G("TemplateData"):::dto
            H("CoupletTemplateData"):::dto
            I("PrintLocation"):::dto
            J("TemplateRecord"):::dto
            K("TypstExecInfo"):::dto
        end

        subgraph "Utility Components"
            direction TB
            U1("DatePlusUtil"):::utility
            U2("FileUtil"):::utility
            U3("JsonUtil"):::utility
            U4("ProcessUtil"):::utility
            U5("ResourceFileUtil"):::utility
            U6("UUIDUtils"):::utility
        end
    end

    %% External Components
    L("Typst Runtime & Template Conversion"):::external
    M("Temporary File Storage"):::external

    %% Data Flow Connections
    Client -->|"HTTP"| A
    A -->|"initializes"| B
    B -->|"routes request to"| C
    B -->|"routes request to"| D
    %% Association with DTOs
    B -->|"maps data to"| G
    B -->|"maps data to"| H
    B -->|"maps data to"| I
    B -->|"maps data to"| J
    B -->|"maps data to"| K
    %% Service uses Utility for process execution and file handling
    C -->|"invokes"| U4
    D -->|"invokes"| U4
    %% Utility calls External Typst Engine
    U4 -->|"calls"| L
    %% External conversion uses Temporary File Storage
    L -->|"reads/writes temp files"| M
    %% External process returns PDF back to Service Layer
    L -->|"returns output"| C
    %% Service aggregates results and returns to Controller
    C --> B
    D --> B
    %% Controller passes response back up the chain
    B --> A
    A -->|"HTTP Response"| Client

    %% Click Events
    click A "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/PdfGenerateApplication.java"
    click B "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/controller/TypstController.java"
    click C "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/service/impl/TemplateImpl.java"
    click D "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/service/impl/CoupletTemplateImpl.java"
    click E "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/service/TypstExec.java"
    click F "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/service/AbstractTypstExecBase.java"
    click G "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/dto/TemplateData.java"
    click H "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/dto/CoupletTemplateData.java"
    click I "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/dto/PrintLocation.java"
    click J "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/dto/TemplateRecord.java"
    click K "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/modules/typst/dto/TypstExecInfo.java"
    click U1 "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/common/utils/DatePlusUtil.java"
    click U2 "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/common/utils/FileUtil.java"
    click U3 "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/common/utils/JsonUtil.java"
    click U4 "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/common/utils/ProcessUtil.java"
    click U5 "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/common/utils/ResourceFileUtil.java"
    click U6 "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/blob/main/src/main/java/com/shenhua/typst2pdf/common/utils/UUIDUtils.java"
    click L "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/tree/main/tool/typst_ctl"
    click M "https://github.com/grant-vranes/typst2pdf-report-label-qrcode/tree/main/tool/typst_ctl/convert"

    %% Styles
    classDef client fill:#8dd3c7,stroke:#000,stroke-width:1px;
    classDef backend fill:#bebada,stroke:#000,stroke-width:1px;
    classDef service fill:#fb8072,stroke:#000,stroke-width:1px;
    classDef dto fill:#80b1d3,stroke:#000,stroke-width:1px;
    classDef utility fill:#fdb462,stroke:#000,stroke-width:1px;
    classDef external fill:#b3de69,stroke:#000,stroke-width:1px;
```
