# k2209/usdz_convertor_node_api architecture

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

- Interactive diagram: https://gitdiagram.com/k2209/usdz_convertor_node_api
- Repository: https://github.com/k2209/usdz_convertor_node_api

## Overview

##### Project Type and Purpose
- This is a self-hosted backend REST API service (“usdz_convertor_node_api”) that offers on-demand conversion of remote `.glb` 3D model URLs into `.usdz` format for iOS AR QuickLook.
- It leverages two supporting Docker builds:
- A base “Pixar USD” image (`usd` directory + Dockerfile)
- A “gltf-to-usdz” image layered on top of USD (`usd-from-gltf` directory + Dockerfile)
- The Node.js/Express app orchestrates conversions by invoking Docker, serving files and cleanup.

##### File Structure
- Top-level:
- usd/            → Dockerfile to build Pixar USD libraries
- usd-from-gltf/ → Dockerfile that installs Google’s `usd_from_gltf` tool atop USD
- usdz_convertor_api/ → The Node.js Express REST API
- Inside `usdz_convertor_api`:
- public/converted → Exposed folder for final `.usdz` files
- temp/            → Temp workspace for downloads & intermediate outputs
- config.js, .env, server.js → API configuration and entrypoint
- No frontend code; this is a pure backend/microservice architecture.
- Dependencies and scripts managed via `package.json`.

##### README for Additional Insights
- Workflow described in Quick Setup:
1. Build base USD image (`docker build` in `usd`)
2. Build glTF-to-USDZ image (`docker build` in `usd-from-gltf`)
3. Install Node.js deps, configure `.env`, launch `server.js`
4. API exposes:
- GET /convertglbtousdz?url=<GLB_URL>
- PATCH /health
- Mentions optional Nginx reverse proxy for pretty URLs.

a. Components:
1. Client (curl, mobile/web AR viewer)
2. (Optional) Nginx Reverse Proxy
3. Node.js Express API Service
– Config, Environment Variables
– `public/converted` folder (static hosting)
– `temp/` folder (ephemeral workspace)
4. Docker Engine
– USD Base Image (`leon/usd:latest`)
– glTF→USDZ Image (`gltf-to-usdz:latest`)
5. External Storage/Download (for remote `.glb` URLs)
b. Interactions & Data Flow:
- Client → (Nginx) → Express API
- Express downloads `.glb` into `temp/`
- Express issues Docker run: mounts `temp/`, `public/converted` into container
- Converter container uses `usd_from_gltf` within `gltf-to-usdz` image to produce `.usdz`
- Container writes `.usdz` to `public/converted`
- Express deletes temp, responds with a link to the `.usdz` in `public/converted`
- Client → HTTP GET on returned URL → iOS AR QuickLook
c. Architectural Patterns & Principles:
– Microservice/Worker pattern: the API delegates heavy-lift conversion to Docker containers
– Separation of concerns: Docker images handle conversion logic; Node API handles orchestration & HTTP layer
– Ephemeral compute: temporary files are auto-removed after each run
– Static asset hosting via Express (or optional Nginx)
d. Key Technologies & Frameworks:
– Node.js + Express
– Docker Engine
– Pixar USD, Google `usd_from_gltf`
– Linux filesystem mounts for sharing between host & container
– (Optional) Nginx reverse proxy for SSL and URL rewriting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Context Diagram
    Client["Client (curl / AR Viewer)"]:::network
    ExternalStorage["Remote .glb URL"]:::external

    %% Optional Nginx
    Nginx["Nginx Reverse Proxy (optional)"]:::network

    %% Express API Service
    subgraph "Express API Service" 
        direction TB
        API["Node.js Express API<br/>(port 3003)"]:::network
        Env[".env"]:::network
        Config["config.js"]:::network
        PKG["package.json"]:::network
        Public["public/converted<br/(.usdz files)"]:::volume
        Temp["temp/<br/ workspace"]:::volume
        Entrypoint["server.js"]:::network
    end

    %% Docker Engine and Images
    subgraph "Docker Engine" 
        direction TB
        USDImage["USD Base Image<br/ (Pixar USD)"]:::compute
        GltfImage["glTF→USDZ Image"]:::compute
    end

    %% README
    README["README.md"]:::external

    %% Data Flow
    Client -->|1. HTTP GET /convertglbtousdz| Nginx
    Nginx -->|1. forward request| API
    API -->|2. download .glb| Temp
    API -->|3. docker run mount volumes| DockerEngine[(Docker Engine)] 
    DockerEngine --> USDImage
    DockerEngine --> GltfImage
    DockerEngine -->|4. write .usdz| Public
    API -->|5. cleanup Temp| Temp
    API -->|6. response .usdz URL| Client
    Client -->|7. GET .usdz file| Public

    %% External storage flow
    API -->|fetch| ExternalStorage

    %% Click Events
    click USDImage "https://github.com/k2209/usdz_convertor_node_api/tree/main/usd/Dockerfile"
    click GltfImage "https://github.com/k2209/usdz_convertor_node_api/tree/main/usd-from-gltf/Dockerfile"
    click API "https://github.com/k2209/usdz_convertor_node_api/tree/main/usdz_convertor_api/"
    click Entrypoint "https://github.com/k2209/usdz_convertor_node_api/blob/main/usdz_convertor_api/server.js"
    click Env "https://github.com/k2209/usdz_convertor_node_api/blob/main/usdz_convertor_api/.env"
    click Config "https://github.com/k2209/usdz_convertor_node_api/blob/main/usdz_convertor_api/config.js"
    click PKG "https://github.com/k2209/usdz_convertor_node_api/blob/main/usdz_convertor_api/package.json"
    click Public "https://github.com/k2209/usdz_convertor_node_api/tree/main/usdz_convertor_api/public/converted"
    click Temp "https://github.com/k2209/usdz_convertor_node_api/tree/main/usdz_convertor_api/temp"
    click README "https://github.com/k2209/usdz_convertor_node_api/blob/main/README.md"

    %% Styles
    classDef network fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px
    classDef volume fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px
    class DockerEngine compute

    style DockerEngine fill:#E0FFE0,stroke:#333,stroke-width:1px
    linkStyle default stroke:#333,stroke-width:1px,fill:none

    %% Alias for Docker Engine container for click
    click DockerEngine "https://github.com/k2209/usdz_convertor_node_api/tree/main/docker_engine_placeholder"
```
