# codacy20/nodejs-ts-pdf-label-maker architecture

> Architecture diagram of the GitHub repository codacy20/nodejs-ts-pdf-label-maker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codacy20/nodejs-ts-pdf-label-maker
- Repository: https://github.com/codacy20/nodejs-ts-pdf-label-maker

## Overview

##### Project type and purpose
- Type: Standalone backend microservice (REST API)
- Purpose: Receive HTTP requests to generate shipping-label PDFs from HTML templates, expose health-check endpoints, and run inside Docker/Kubernetes.

##### File structure
- Top level:
– Dockerfile, docker-compose support → containerization
– README.md, postman-collection.json → documentation/testing
– assets/ → HTML templates, sample PDFs
– functions/ → the application code
- functions/src:
– config/ → InversifyJS DI container setup
– constants/ → symbols, types for DI
– health/ → HealthController (liveness/readiness)
– shipping-label/ → ShippingLabelController + ShippingLabelService
– pdf/ → IPdfGenerator and PuppeteerPdfGenerator
– utils/ → HtmlRenderer, Logger, RequestLogger
– index.ts → Express app entry point
- functions/tests: unit tests for service layer (ShippingLabelService)

##### README for additional insights
- Clean architecture: controller–service separation, DI for loose coupling
- Tech stack: Node.js 20+, TypeScript, Express (implied), Puppeteer, InversifyJS
- Features: REST API (/get-label, /health), multi-language support, Docker

##### Main components & their interactions
A. API Layer
- Express HTTP server (functions/src/index.ts)
- Middleware: RequestLogger, error handlers
- Controllers:
– ShippingLabelController: handles POST /get-label
– HealthController: handles GET /health, /liveness, /readiness
B. Service Layer
- ShippingLabelService: business logic (validate input, select template, orchestrate PDF gen)
- IPdfGenerator & PuppeteerPdfGenerator: render HTML and create PDF via Puppeteer
- HtmlRenderer: inject data into labelTemplate.html
C. Infrastructure & Utilities
- InversifyJS Container (config/inversify.config.ts): binds interfaces → implementations
- Logger: application-wide logging
D. Assets & External Dependencies
- assets/labelTemplate.html: HTML template
- Puppeteer (headless Chrome)
- Docker container runtime

Data Flow:
HTTP POST → Express → RequestLogger → ShippingLabelController
→ ShippingLabelService → HtmlRenderer (loads labelTemplate.html from assets)
→ PuppeteerPdfGenerator → headless Chrome → PDF Buffer
← ShippingLabelService → Controller → HTTP Response (PDF)
Health checks follow a similar, simpler path to HealthController.

##### Architectural patterns & design principles
- Controller–Service pattern: thin controllers, fat services
- Dependency Injection (InversifyJS): decouple modules, easy testing
- Clean Architecture: separate layers (API, business, infrastructure)
- Single Responsibility: each module has a clear, narrow purpose

##### Essential elements
- Notes on ports (e.g. 3000) and health-probe URLs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Container"
        direction TB

        subgraph "API Layer"
            direction TB
            Express["Express Server"]:::api
            RequestLogger["RequestLogger Middleware"]:::infra
            HealthController["HealthController"]:::api
            ShippingLabelController["ShippingLabelController"]:::api
        end

        subgraph "Service Layer"
            direction TB
            IShippingService["IShippingLabelService"]:::service
            ShippingService["ShippingLabelService"]:::service
        end

        subgraph "Infrastructure Layer"
            direction TB
            DIContainer["Dependency Injection Container"]:::infra
            Logger["Logger"]:::infra
            HtmlRenderer["HtmlRenderer"]:::infra
            IPdfGenerator["IPdfGenerator"]:::service
            PuppeteerPdfGenerator["PuppeteerPdfGenerator"]:::service
        end

        subgraph "Assets & External"
            direction TB
            Template["labelTemplate.html"]:::external
            SamplePDF["sample-label.pdf"]:::external
            PuppeteerExt["Puppeteer/Chrome"]:::external
        end
    end

    %% Data Flow
    Express -->|receives request| RequestLogger
    RequestLogger -->|for POST /get-label| ShippingLabelController
    RequestLogger -->|for GET /health| HealthController
    ShippingLabelController -->|calls| ShippingService
    HealthController -->|returns status| Express
    ShippingService -->|implements| IShippingService
    ShippingService -->|injects via DI| IPdfGenerator
    ShippingService -->|renders HTML| HtmlRenderer
    HtmlRenderer -->|loads template| Template
    IPdfGenerator -->|implemented by| PuppeteerPdfGenerator
    PuppeteerPdfGenerator -->|launches| PuppeteerExt
    PuppeteerPdfGenerator -->|generates PDF| SamplePDF
    ShippingService -->|returns PDF buffer| ShippingLabelController
    ShippingLabelController -->|responds with PDF| Express

    %% DI Bindings
    DIContainer -->|binds controllers & services| ShippingLabelController
    DIContainer -->|binds controllers & services| HealthController
    DIContainer -->|binds| ShippingService
    DIContainer -->|binds| IShippingService
    DIContainer -->|binds| IPdfGenerator
    DIContainer -->|binds| PuppeteerPdfGenerator

    %% Click Events
    click Express "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/index.ts"
    click DIContainer "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/config/inversify.config.ts"
    click HealthController "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/health/controller/HealthController.ts"
    click ShippingLabelController "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/shipping-label/controller/ShippingLabelController.ts"
    click ShippingService "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/shipping-label/services/ShippingLabelService.ts"
    click IShippingService "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/shipping-label/services/IShippingLabelService.ts"
    click IPdfGenerator "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/pdf/IPdfGenerator.ts"
    click PuppeteerPdfGenerator "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/pdf/PuppeteerPdfGenerator.ts"
    click HtmlRenderer "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/utils/HtmlRenderer.ts"
    click Logger "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/utils/Logger.ts"
    click RequestLogger "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/functions/src/utils/RequestLogger.ts"
    click Template "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/assets/labelTemplate.html"
    click SamplePDF "https://github.com/codacy20/nodejs-ts-pdf-label-maker/blob/main/assets/sample-label.pdf"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef service fill:#E6FFED,stroke:#28A745,color:#22863A
    classDef infra fill:#FFF5B1,stroke:#D69A00,color:#735C0F
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333
```
