How grant-vranes/typst2pdf-report-label-qrcode works
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.