nateledford.com / piwigo-dam-workspace
A large plugin that adds lightweight DAM interface to Piwigo
Star 0
Fork 0
Watch
PHP 64%
TypeScript 20%
Svelte 8%
JavaScript 3%
Shell 2%
Gherkin <1%
Just <1%
Fluent <1%
CSS <1%
HTML <1%
<1%
620 2 0
.impeccable
build
dev
docs
just
ops
plugins
scripts
tests
themes
tools
.dockerignore
.gitignore
.php-cs-fixer.dist.php
AGENTS.md
biome.json
CLAUDE.md
compose.dev.yml
composer.json
composer.lock
CONTRIBUTING.md
DESIGN.md
Justfile
mise.toml
phpcs.xml.dist
phpmd.xml
phpstan.neon.dist
phpunit.xml
PRODUCT.md
README.md
README.md

Piwigo DAM Workspace #

Piwigo DAM Workspace is an internal, administrator-only hobbyist curation workspace for the official Piwigo 16.4 container and its PHP 8.4.20 runtime. Piwigo remains authoritative for authentication, permissions, CSRF tokens, catalog visibility, derivatives, and persistent catalog state. Workspace organization is private, owner-scoped, and non-destructive: ordinary browsing and Collections do not alter photos, albums, tags, ratings, or original files.

The Maintenance control plane is deliberately narrow. It submits protected, administrator commands to the existing durable worker; it does not become a second catalog, filesystem browser, or worker implementation. The local and production-hosted containers are development environments; the latter provide real-world, read-only data for MVP testing. Its operator procedures are authoritative in docs/maintenance-worker-architecture.md and docs/maintenance-worker-runbook.md.

Delivery and ownership #

plugins/dam-workspace/frontend/ is the sole Node package. It owns the Svelte 5/SvelteKit 2 client, TypeScript, plugin-wrapped Bits UI primitives, Tailwind CSS, and client tests. Its static build is emitted to plugins/dam-workspace/assets/app/.

Piwigo owns the document boundary:

  1. An administrator opens plugins/dam-workspace/app/index.php.
  2. PiwigoWorkspaceDocumentController performs the server-side administrator and GET-only checks.
  3. WorkspaceRuntimeDocument serves the generated, guarded app-shell.php, substitutes the per-request runtime values, and supplies the browser client.
  4. The client calls same-origin ws.php?method=dam.v1.*; PHP remains the authority for every read and mutation.

The browser may register a narrowly scoped PWA worker and open the authenticated app/events.php invalidation stream. Both are best effort: the worker never caches private workspace data, and bounded JSON refreshes remain authoritative. See PWA operation and event-stream operation.

The static client uses hash routing because Piwigo owns the pathname. It is not a Node production service and does not provide an alternative authorization, catalog, or persistence layer. The generated shell is not directly executable; hashed assets under assets/app/_app/ are public static assets.

JavaScript is required for the workspace. Without it, the document presents a short explanation and a Return to Gallery link; there is no server-rendered or HTML-form workspace fallback.

PHP runtime policy #

PHP 8.4.20 is the exact supported runtime because it is supplied by the official piwigo/piwigo:16.4.0 image used by development and production. mise.toml and Composer resolution pin that patch. This repository does not build or publish a custom Piwigo image; upgrade PHP only with an explicit, verified official-image compatibility decision and synchronized deployment.

Local commands #

Run mise install before any recipe. The repository pins PHP 8.4.20, Node 26.7.0, and Just 1.58.0; invoke recipes through mise exec -- just.

mise install
mise exec -- just install
mise exec -- just check-fast
XDEBUG_MODE=coverage mise exec -- just check
mise exec -- just browser-check
mise exec -- just fixture-browser-check
mise exec -- just package all
mise exec -- just dev-deploy

just check requires PCOV or XDEBUG_MODE=coverage; check-fast is the driver-free iteration lane.

just dev-deploy builds the frontend and syncs both extensions into the disposable local Docker/Colima fixture at http://127.0.0.1:8088 (started by just dev-up), for iterating against a running local Piwigo.

just dev-bootstrap builds and syncs the extensions, installs Piwigo into a fresh fixture, uploads one disposable photo, and activates DAM Workspace, logging in as dam-admin with the deliberately weak fixture-only password password unless DAM_FIXTURE_ADMIN_PASSWORD is set. This fixture never holds production or sensitive data, so a known, insecure default is intentional. It refuses to run against an already-installed fixture; run just dev-down first to start over.

just frontend-build generates the guarded shell and immutable asset graph. Do not edit assets/app/ by hand. just package all stages both archives; just package plugin and just package theme stage only the selected archive. Plugin packaging excludes frontend/, node_modules, .svelte-kit, test/coverage artifacts, transient index.html, and source maps.

After explicit human authorization immediately before a production write, use just deploy-prod <plugin|theme|all>. Plugin/all deploys migrate and recreate Piwigo plus both workers; theme deploys only the theme. Originals remain unchanged because their mount is read-only.

just data-snapshot records read-only table/count/hash invariants for a development comparison. It never writes media or catalog rows.

Installation and route access #

  1. Build and package the plugin.
  2. Install and activate dam-workspace.zip in Piwigo Administration.
  3. Sign in as an administrator and open the DAM Workspace button or plugins/dam-workspace/app/index.php.

Guests and non-administrators are denied by Piwigo before the client document is served. The workspace route rejects non-GET requests. Browser mutations instead use the v1 API described in docs/workspace-api-v1.md and its Zod 4.5 boundary modernization.

Product boundaries #

  • Browse permission-visible Albums, Collections, Tags, and derivatives; use search, deterministic sorting, keyset pagination, previews, and stable shuffles without exposing originals.
  • Create and manage owner-scoped Collection Sets, Manual Collections, Smart Collections, and Manual Memberships. Collection writes are versioned and Piwigo-authorized.
  • Apply workspace-only album folder labels. They do not modify Piwigo album metadata or media.
  • Use Maintenance only for its exposed, safe job and physical-album reconciliation actions. Refer to the linked worker documentation for operational semantics and original-preservation rules.

themes/dam-dark remains an optional Piwigo child theme. It is independent of the workspace document, which is always rendered as a dark, self-contained application.

Plugin removal #

Disabling the plugin removes the route and entry point while preserving plugin-owned collection data. Uninstalling removes plugin-owned workspace data. Neither operation changes Piwigo catalog data or original files.