PNGAPI

ASP.NET Core asset storage service for the Mockup Workflow Platform, providing secure file management, shared workflow storage, and a browser-based asset explorer.

Overview

PNGAPI is an ASP.NET Core service that provides centralized storage and retrieval of workflow assets for the Mockup Workflow Platform.

The service exposes REST endpoints for uploading, downloading, browsing, and managing workflow assets while storing files within a shared Docker volume. In addition to its REST API, it includes a built-in Blazor interface for browsing workflow folders and previewing generated assets during development and testing.

PNGAPI was created to provide a lightweight, secure asset storage service for the Mockup Workflow Platform, enabling workflow components to exchange generated artwork through a shared storage layer.

---

Contents

• Overview
• Features
• Technologies
• Platform Architecture
• REST API
• Storage Layout
• Running Locally
• Docker
• Screenshots
• Project Status
• Related Repositories
• License

Features

• Upload workflow assets through a REST API
• Download generated assets
• Browse files and folders using a built-in Blazor interface
• Preview generated PNG assets
• Create workflow folders through the API
• Delete workflow assets
• Safe path validation to prevent directory traversal
• Shared Docker volume storage
• Swagger/OpenAPI documentation

Technologies

• Language: C#
• Framework: ASP.NET Core (.NET 10)
• UI: Blazor Interactive Server
• API: Minimal APIs
• Documentation: Swagger / OpenAPI
• Containerization: Docker
• Storage: Shared Docker volume

Platform Architecture

PNGAPI serves as the shared asset storage service for the Mockup Workflow Platform. It provides a centralized location where workflow assets are uploaded, retrieved, and managed throughout the mockup generation pipeline.

 Mockup Workflow Platform
BuildUploader
│
▼
PhotoshopAutomation.Api
│
Coordinates workflow execution
│
▼
Photoshop UXP Batch Plugin
│
Downloads input assets / Uploads mockups
│
▼
PNGAPI
│
Shared Build Storage Volume
│
┌────────────┴────────────┐
▼ ▼
MockupWorkflow.Admin Other Platform Services
Browse workflow assets Consume generated files

Responsibilities

PNGAPI is responsible for:

• Storing workflow assets within the shared build storage.
• Providing REST endpoints for uploading and downloading files.
• Managing workflow folder structures.
• Browsing stored assets through a built-in Blazor interface.
• Protecting the storage volume through safe path validation.

REST API

PNGAPI exposes REST endpoints for managing workflow assets stored within the shared build storage.

Files

Method	Endpoint	Description
GET	/api/files	Lists every file stored under the configured build root.
GET	/api/files/{path}	Downloads a file from the shared storage.
POST	/api/files/{path}	Uploads a file to the specified path, creating parent directories if necessary.
DELETE	/api/files/{path}	Deletes the specified file.
GET	/api/files/list/{path}	Lists the folders and files within a specific directory.

Folders

Method	Endpoint	Description
GET	/api/folders	Lists every folder beneath the configured build root.
POST	/api/folders/{path}	Creates a folder within the shared storage.

---

Example Upload

POST /api/files/1783449343700/tshirt/input_folders/example/design.pngContent-Type: image/png

Uploads a PNG into the specified workflow folder.

---

Example Download

GET /api/files/1783449343700/tshirt/mockup_folders/example/design-Group.1.png

Returns the requested image.

---

Example Create Folder

POST /api/folders/1783449343700/tshirt/input_folders/example

Creates the folder if it does not already exist.

---

Path Safety

All file and folder operations are validated before accessing the file system.

PNGAPI resolves every requested path relative to the configured storage root and rejects requests that attempt to access locations outside the shared workflow directory. This prevents directory traversal attacks while allowing clients to work with relative workflow paths.

Storage Layout

PNGAPI stores workflow assets beneath a configurable build root.

By default:

/data/builds

Each workflow batch is organized by batch identifier and product type, providing a predictable structure that all platform services can share.

Example Layout

/data/builds/
└── 1783449343700/
└── tshirt/
├── input_folders/
│ ├── Awaiting.Further.Instructions/
│ │ └── duck-design.png
│ └── Coffee.Until.Further.Notice/
│ └── coffee-design.png
│
└── mockup_folders/
├── Awaiting.Further.Instructions/
│ ├── duck-design-Group.1.png
│ ├── duck-design-Group.2.png
│ └── ...
│
└── Coffee.Until.Further.Notice/
├── coffee-design-Group.1.png
├── coffee-design-Group.2.png
└── ...

Configuration

The storage root is configured through appsettings.json:

{
"Storage": {
"BuildRoot": "/data/builds"
}
}

The location can be overridden for different environments using standard ASP.NET Core configuration providers, making the application suitable for local development, Docker deployments, and production environments.

Running Locally

Prerequisites

• .NET 10 SDK
• Docker Desktop (recommended for containerized development)

Clone the Repository

git clone https://github.com/swisherman/PNGAPI.git
cd PNGAPI

Run from Visual Studio

Open:

PNGAPI.slnx

Then start the PNGAPI project.

Run from the Command Line

From the repository root:

dotnet run --project src/PNGAPI/PNGAPI.csproj

The application will start using the URLs defined in your launch profile.

Browse the Application

Once running, open:

Page	Purpose
/	Project home page
/files	Browse and preview workflow assets
/swagger	Explore and test the REST API

Configuration

The storage location is configured in appsettings.json:

{
"Storage": {
"BuildRoot": "/data/builds"
}
}

The configured storage directory is automatically created during application startup if it does not already exist.

Docker

PNGAPI includes Docker support for running the service in a Linux container with access to shared workflow storage.

Build and Start

From the repository root:

docker compose up --build

To run the containers in the background:

docker compose up --build -d

To stop the application:

docker compose down

Shared Storage

Inside the container, PNGAPI uses the configured build root:

/data/builds

The Docker configuration mounts shared storage at this location so PNGAPI and other Mockup Workflow Platform services can access the same workflow assets.

PNGAPI container
│
▼
/data/builds
│
▼
Shared Docker volume
│
├── input_folders
└── mockup_folders

This shared-volume design allows:

• MockupWorkflow.BuildUploader to upload prepared input assets.
• The Photoshop UXP plug-in to download source artwork.
• The Photoshop UXP plug-in to upload generated mockups.
• MockupWorkflow.Admin and other services to browse or consume workflow output.

Environment Overrides

The storage root can be overridden through ASP.NET Core configuration.

For example:

environment:
Storage__BuildRoot: /data/builds

ASP.NET Core uses double underscores to represent nested configuration keys, so:

Storage__BuildRoot

maps to:

{
"Storage": {
"BuildRoot": "/data/builds"
}
}

Rebuild After Changes

After changing application code or the Dockerfile, rebuild the image:

docker compose up --build

Swagger and the Blazor interface are available through the host port configured in docker-compose.override.yml.

Screenshots

Home Page

Screenshot coming soon

Swagger API

Workflow Asset Browser

Project Status

PNGAPI is under active development as part of the Mockup Workflow Platform.

Current capabilities include:

• REST API for workflow asset management
• Browser-based asset explorer
• Safe file and folder operations
• Shared Docker volume storage
• Swagger/OpenAPI documentation

Future enhancements include:

• Asset metadata support
• Improved file search and filtering
• Thumbnail generation
• Additional administrative tooling

Related Repositories

PNGAPI is one component of the Mockup Workflow Platform.

Repository	Purpose
MockupWorkflow.Platform	Platform overview and architecture
PhotoshopAutomation.Api	Workflow orchestration and batch processing
photoshop-uxp-batch-mockup-plugin	Photoshop workflow execution
MockupWorkflow.Admin	Administrative dashboard
FolderCreator.API	Creates standardized workflow folder structures
MockupWorkflow.BuildUploader	Uploads prepared workflow assets
MockupWorkflow.Shared	Shared domain models and contracts

License

This project is licensed under the MIT License.

See the LICENSE file for details.