Open Arsenal

See the stars

PicPorter Specification

Home / PicPorter / PicPorter Specification

PicPorter

Your open source pipeline for files, images, and video.

PicPorter is an open source file upload specification designed to provide a simple, flexible, and extensible way to handle images, videos, documents, and general files across blogs, forums, platforms, and custom applications.

The specification defines a modular upload experience focused on usability, validation, security, storage flexibility, integration, and extensibility.

Goals

PicPorter is designed to:

  • Provide a simple drag-and-drop upload experience
  • Support images, videos, documents, and general files
  • Support single and multiple file uploads
  • Provide clear upload status and progress information
  • Validate files before and during processing
  • Support flexible storage destinations
  • Provide a foundation for integration with other platforms and applications
  • Maintain a modular design that can be extended through optional plugins
  • Support secure and predictable file handling
  • Remain useful across a wide range of deployment scenarios

Core Modules

Upload Interface

The Upload Interface defines the primary user experience for selecting and submitting files.

Features include:

  • Drag-and-drop file selection
  • Click-to-upload file selection
  • Multiple file selection
  • Batch upload support
  • Visual upload area
  • Drag-and-drop state feedback
  • File selection feedback
  • Upload queue presentation
  • File removal before submission
  • Responsive interaction across screen sizes

File Processing

The File Processing module defines how selected files are prepared and handled during the upload process.

Features include:

  • File intake
  • File type detection
  • File metadata handling
  • File size evaluation
  • File validation
  • Safe file naming
  • Duplicate filename handling
  • Upload preparation
  • Batch processing
  • Processing status reporting

Media Support

The Media Support module defines handling for common media and document categories.

Features include:

  • Image uploads
  • Video uploads
  • Document uploads
  • General file uploads
  • Image previews
  • Video previews
  • Document identification
  • Media type identification
  • Configurable supported file types
  • Extensible media type support

Upload Validation

The Upload Validation module provides configurable controls for determining which files may be accepted.

Features include:

  • Allowed file type configuration
  • File extension validation
  • MIME type validation
  • File size limits
  • Individual file limits
  • Batch upload limits
  • Client-side validation
  • Server-side validation
  • Invalid file rejection
  • Clear validation feedback

Server-side validation must remain authoritative regardless of client-side validation results.

Upload Progress

The Upload Progress module provides users with visibility into active uploads.

Features include:

  • Upload progress indicators
  • Per-file upload status
  • Overall batch progress
  • Upload completion states
  • Upload failure states
  • Processing states
  • Error reporting
  • Retry-ready status handling

Storage Management

The Storage Management module defines how successfully processed files are stored.

Features include:

  • Local storage support
  • Remote storage support
  • Configurable storage destinations
  • Storage path configuration
  • File naming rules
  • Collision prevention
  • Storage result reporting
  • Storage abstraction for future extensions

Storage implementations should remain independent from the upload interface.

Security

The Security module defines safeguards for file handling and upload processing.

Features include:

  • Server-side file validation
  • File type verification
  • File size enforcement
  • Safe file naming
  • Path traversal prevention
  • Upload destination protection
  • Malicious file handling controls
  • Authentication integration points
  • Rate limiting integration points
  • Malware scanning integration points
  • Abuse prevention controls

Security controls should be configurable without weakening required validation.

Upload API

The Upload API module defines interfaces for integrating PicPorter with external applications and services.

Features include:

  • File upload endpoints
  • Upload request handling
  • Upload response handling
  • Upload status reporting
  • Validation responses
  • Processing results
  • Storage results
  • Error responses
  • Integration-ready request and response conventions

The API should allow applications to use PicPorter without requiring direct access to internal upload processing.

Preview Management

The Preview Management module defines how selected media is presented before and during upload.

Features include:

  • Image previews
  • Video previews
  • File type indicators
  • Filename display
  • File size display
  • Preview removal
  • Preview ordering
  • Upload state indicators

Preview generation must not be treated as proof that a file is safe to store or process.

Error Handling

The Error Handling module defines consistent behavior when uploads cannot be completed.

Features include:

  • Invalid file notifications
  • File size errors
  • Unsupported file type errors
  • Upload failures
  • Processing failures
  • Storage failures
  • Authentication errors
  • Permission errors
  • Network-related failure reporting
  • User-readable error messages

Errors should provide enough information to help users understand the problem without exposing sensitive system information.

Configuration

The Configuration module defines configurable upload behavior.

Features include:

  • Allowed file types
  • Maximum file sizes
  • Upload limits
  • Batch limits
  • Storage destination settings
  • Preview behavior
  • Validation rules
  • Security controls
  • Upload processing settings
  • Integration settings

Configuration should allow deployments to adapt PicPorter to different application requirements without modifying core functionality.

Integration

The Integration module defines how PicPorter can operate as part of larger platforms.

Features include:

  • Blog integration
  • Forum integration
  • Content management integration
  • Custom application integration
  • Embedded upload interfaces
  • API-based integration
  • Configurable upload destinations
  • Application-defined validation rules
  • Application-defined storage behavior

PicPorter should remain independent enough to serve as an upload component rather than requiring a specific type of host application.

Accessibility

The Accessibility module defines requirements for making the upload experience usable by a broad range of users.

Features include:

  • Keyboard-accessible file selection
  • Accessible upload controls
  • Clear status communication
  • Descriptive labels
  • Accessible error messaging
  • Non-pointer upload workflows
  • Responsive interface behavior
  • Clear visual distinction between upload states

Extensibility

The Extensibility module defines the mechanisms that allow PicPorter to grow without unnecessarily modifying its core behavior.

Features include:

  • Modular processing
  • Pluggable storage providers
  • Pluggable validation providers
  • Pluggable security services
  • Pluggable preview providers
  • Pluggable authentication integrations
  • Configurable processing stages
  • Extension points for application-specific behavior

Optional Plugin Modules

Cloud Storage Plugin

The Cloud Storage Plugin provides integrations for external storage services.

Features may include:

  • Cloud object storage
  • Remote file storage
  • Configurable storage containers
  • Storage provider selection
  • Remote storage authentication
  • Upload result synchronization

Upload Retry Plugin

The Upload Retry Plugin provides recovery for interrupted or failed uploads.

Features may include:

  • Automatic retry handling
  • Manual retry controls
  • Configurable retry limits
  • Retry status reporting
  • Recoverable failure detection
  • Batch retry handling

File Reordering Plugin

The File Reordering Plugin allows users to change the order of selected files.

Features may include:

  • Drag-and-drop file ordering
  • Manual file ordering
  • Batch ordering
  • Order preservation during processing
  • Application-defined ordering metadata

Thumbnail Plugin

The Thumbnail Plugin provides optional thumbnail generation.

Features may include:

  • Image thumbnail generation
  • Video thumbnail generation
  • Document thumbnail generation
  • Configurable thumbnail sizes
  • Multiple thumbnail profiles
  • Thumbnail storage handling

Authentication Plugin

The Authentication Plugin provides integration with external identity and access systems.

Features may include:

  • User authentication integration
  • Session validation
  • Upload authorization
  • User-specific storage rules
  • Permission-based upload controls
  • Account-based upload limits

Rate Limiting Plugin

The Rate Limiting Plugin provides configurable protection against excessive upload activity.

Features may include:

  • Request limits
  • Upload limits
  • User-based limits
  • Session-based limits
  • IP-based controls
  • Time-window configuration
  • Rate-limit notifications

Malware Scanning Plugin

The Malware Scanning Plugin provides optional integration with file security scanning services.

Features may include:

  • Pre-storage scanning
  • Post-upload scanning
  • Scan result handling
  • Infected file rejection
  • Quarantine workflows
  • Scan status reporting

Multilingual Plugin

The Multilingual Plugin provides localized user interface and messaging support.

Features may include:

  • Localized interface text
  • Localized validation messages
  • Localized error messages
  • Language selection
  • Application-defined language settings

Specification Branding License (SBL)

Standard

Optional

License & Notice Requirements

PicPorter is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

By contributing to this project, you agree that your contributions will also be released under this license.

Please note the following:

  • All contributions must comply with the AGPL-3.0+ terms.
  • Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to:
    Roxanne Ardary and roxanneardary.com.
  • PicPorter specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
  • The project’s notice.md file tracks attribution requirements and contributor acknowledgments.
    Any update that adds new contributors or modifies attribution should also update notice.md.
  • When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
  • Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.

For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.

Notice – PicPorter

Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.

Contributors

This file tracks contributors and their specific contributions to the project.

  • Roxanne Ardary, roxanneardary.com – April 3, 2026
    Created the repository for PicPorter. Designed and structured the initial open source architecture for a drag-and-drop uploader supporting images, videos, and file uploads for web platforms.
  • [Add other contributors here] – [Date]
    [Describe contribution in one sentence]

License – PicPorter

This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

Key Points:

  • You are free to use, modify, and distribute the code.
  • All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
  • The software is provided “as is,” without warranty of any kind.

For the full license text, see GNU AGPL-3.0 License.

Related posts:

Carenex

PersonaVenture

NextState