Athenian File Management

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

Admin Workflow

Setup Workflow

1. Activate Athenian File Management.
2. Go to Media -> AFM Folders to create folder structures.
3. Go to Media -> AFM Settings to configure upload role defaults and WooCommerce behavior.
4. Optionally set the WooCommerce product media root folder name.
5. Use the Media Library, media modal, or Media -> AFM Explorer to begin organizing assets.

Daily Media Management Workflow

1. Open Media -> AFM Explorer.
2. Choose a cleanup collection or folder from the sidebar.
3. Search, filter, sort, and inspect media items.
4. Select items in grid or list view.
5. Move selected files into a target folder or unassign them.
6. Use the inspector panel to review alt text, dimensions, file size, uploader, and attachment state.

WooCommerce Product Media Workflow

1. Enable WooCommerce auto-organization in AFM settings.
2. Set a root folder such as Products.
3. Save or update a WooCommerce product with a featured image and/or gallery images.
4. AFM determines the best category path from the product's deepest assigned category.
5. AFM creates the folder path if it does not already exist.
6. AFM assigns the product's featured and gallery images to that folder.

---

Technical Architecture

File Structure

athenian-file-management.php
includes/
  class-afm-plugin.php
  class-afm-rest.php
  class-afm-ui.php
assets/
  css/afm-media.css
  js/afm-explorer.js
  js/afm-media-modal.js
  js/afm-media-sidebar.js
docs/
  afm-marketing-document.md
  athenian-platform-marketing.md
  athenian-platform-technical.md

Main Components

| Component | Responsibility | |---|---| | athenian-file-management.php | Plugin header, constants, class includes, bootstrapping on plugins_loaded. | | Athenian\\AFM\\Plugin | Taxonomy registration, settings, admin menus, Media Library integration, bulk actions, attachment edit fields, role defaults, WooCommerce product image auto-organization. | | Athenian\\AFM\\Rest | REST endpoints for explorer bootstrap data, folder tree data, collection definitions, assignment actions, and media queries. | | Athenian\\AFM\\UI | Conditional admin asset loading and JavaScript localization for Media Library, media modal, post screens, and AFM Explorer. | | afm-explorer.js | Dedicated desktop-style explorer app. | | afm-media-sidebar.js | Media Library sidebar injection and drag/drop wiring. | | afm-media-modal.js | WordPress media modal extension with folder/collection navigation and drag/drop assignment. | | afm-media.css | Admin styling for the explorer, modal, sidebar, and media-management surfaces. |

Boot Sequence

The plugin defines constants and loads class files in the main bootstrap file. On plugins_loaded, it calls:

\Athenian\AFM\Plugin::boot();

Plugin::boot() registers the primary runtime hooks, boots the REST layer, boots the UI layer, and attaches all Media Library, settings, upload, and WooCommerce integration hooks.

---

Data Model

Taxonomy

AFM uses a dedicated attachment taxonomy:

| Field | Value | |---|---| | Taxonomy | afm_folder | | Object Type | attachment | | Hierarchical | true | | Public | false | | REST Enabled | true | | Admin UI | true | | Rewrite | false | | Capabilities | upload_files for manage/edit/delete/assign terms |

This taxonomy powers folder organization while preserving WordPress's native media attachment model.

Options

AFM stores configuration in the afm_settings option.

Default settings:

[
    'role_defaults' => [],
    'wc_auto_product_folders' => 1,
    'wc_root_folder' => 'Products',
]

| Option Key | Purpose | |---|---| | role_defaults | Maps WordPress roles to AFM folder term IDs for upload-time routing. | | wc_auto_product_folders | Enables/disables automatic WooCommerce product image folder assignment. | | wc_root_folder | Root folder name used for WooCommerce product media paths. |

Attachment Metadata Used

AFM reads or uses the following attachment/product metadata:

| Meta Key | Purpose | |---|---| | _wp_attachment_image_alt | Used for missing-alt collection and inspector display. | | _product_image_gallery | Used to collect WooCommerce gallery image IDs for product image auto-organization. |

No Custom Database Tables Detected

The current plugin package does not create custom database tables. It relies on WordPress options, taxonomies, attachment posts, attachment metadata, and existing WooCommerce product metadata.

---

REST API

AFM registers REST endpoints under the afm/v1 namespace. All current routes require current_user_can('upload_files').

| Method | Route | Purpose | |---|---|---| | GET | /afm/v1/bootstrap | Returns folder tree, collection definitions, uploader list, and key admin URLs for the explorer. | | GET | /afm/v1/folders | Returns the AFM folder tree. | | POST | /afm/v1/assign | Assigns attachments to a folder or clears folder assignment. | | GET | /afm/v1/collections | Returns built-in/filterable collection definitions. | | GET | /afm/v1/query | Queries attachments with filters for folder, collection, search, mime group, uploader, date range, size, attachment state, sort, and pagination. |

/assign Request Model

The assignment route expects:

{
  "attachment_ids": [123, 456],
  "folder_id": 789,
  "unassign": 0
}

To clear folder assignment:

{
  "attachment_ids": [123, 456],
  "folder_id": 0,
  "unassign": 1
}

The route validates that attachment IDs are an array and that folder_id is present unless unassign is truthy. It then uses wp_set_object_terms() to update the afm_folder assignment.

/query Response Model

The query route returns media items with operational metadata such as:

• Attachment ID
• Title
• Filename
• File URL
• Medium thumbnail URL
• MIME type
• MIME label
• Upload date
• Modified date
• File size in bytes
• Uploader ID/name
• Image dimensions
• Alt text
• Folder summary
• Attached parent post ID/title
• Image flag

This response powers the AFM Explorer grid, list, and inspector panel.

---

WordPress Hooks and Integration Points

Actions

| Hook | Purpose | |---|---| | plugins_loaded | Boots the plugin classes. | | init | Registers the afm_folder attachment taxonomy. | | restrict_manage_posts | Adds the AFM folder filter dropdown to the Media Library. | | admin_notices | Displays move success notices and folder-selection prompts. | | admin_menu | Adds AFM Explorer, AFM Folders, and AFM Settings under Media. | | admin_init | Registers AFM settings and settings fields. | | add_attachment | Applies role-based default folder assignment on upload. | | save_post_product | Auto-organizes WooCommerce product featured/gallery images. | | rest_api_init | Registers AFM REST endpoints. | | admin_enqueue_scripts | Loads AFM admin styles/scripts on supported screens. |

Filters

| Filter | Purpose | |---|---| | manage_upload_columns | Adds the AFM Folder column to the Media Library list table. | | manage_media_custom_column | Renders folder path values in the Media Library column. | | parse_query | Applies AFM folder, unassigned, and selected smart-collection filters to the Media Library query. | | ajax_query_attachments_args | Applies folder/unassigned filters to media modal AJAX attachment queries. | | bulk_actions-upload | Adds the Move to AFM Folder... bulk action. | | handle_bulk_actions-upload | Processes bulk folder assignment for selected media. | | attachment_fields_to_edit | Adds the AFM folder selector to attachment edit forms. | | attachment_fields_to_save | Saves AFM folder selection from attachment edit forms. | | afm_explorer_collections | Allows developers to modify or extend explorer smart collections. |

---

WooCommerce Integration

AFM integrates with WooCommerce product media through save_post_product.

When enabled, the plugin:

1. Checks whether WooCommerce functions are available.
2. Reads the product featured image ID.
3. Reads gallery image IDs from _product_image_gallery.
4. Builds a category path using the product's deepest assigned product_cat term.
5. Prefixes the path with the configured root folder name.
6. Creates missing AFM folders along the path.
7. Assigns the featured/gallery attachments to the generated folder.

This feature is useful for stores where product imagery needs to remain organized by catalog hierarchy.

---

Security and Permissions

AFM is implemented as an admin-side media operations plugin. The inspected package uses these core safety patterns:

• REST routes require current_user_can('upload_files').
• Admin screens require upload_files capability.
• Taxonomy manage/edit/delete/assign capabilities are mapped to upload_files.
• Settings values are sanitized before being saved.
• Folder IDs and attachment IDs are cast to integers before assignment.
• REST requests from admin JavaScript are sent with X-WP-Nonce.
• Media assignment is restricted to posts whose post type is attachment.

Security Notes for Future Hardening

• Consider adding more explicit nonce/capability checks to bulk action prompt handling if this workflow expands.
• Consider validating that a submitted folder_id exists in afm_folder before assignment.
• Consider adding activity logging for high-risk media operations such as bulk reassignment and unassignment.
• Consider adding role-specific permission controls for who can create folders versus only assign media.

---

Technical Notes and Observations

Native-First Design

AFM works with native WordPress attachments instead of replacing the Media Library. Folder organization is represented as taxonomy assignment, which keeps existing media URLs, metadata, thumbnails, attachment IDs, WooCommerce product relationships, and media modal behavior intact.

Single-Folder Attachment Model

The current code behaves like a single-folder-per-attachment manager by replacing folder terms with the selected target folder. This is clean for file-system-style organization, but future versions could add optional multi-folder tagging if needed.

Large File Filtering

The large collection uses a minimum size threshold of 5 MB in the REST query flow. Size filtering is performed after the attachment query by checking the attached file path with filesize(). This is practical for the current explorer but may need indexing or cached file-size metadata for very large libraries.

Query Result Count

The REST query response returns found as the count of returned items after local filtering rather than the full WordPress query total. This is sufficient for the current explorer display but should be revisited if exact totals or advanced pagination counts are required.

Media Modal Coverage

The media modal currently handles folder/unassigned filtering and simple type-based collections. Some cleanup collections, such as large files and missing alt text, are better represented in the dedicated REST-powered explorer.

No Public Shortcodes Detected

No public-facing shortcodes were detected in the current source package. AFM is currently an admin/media operations plugin.

No WP-CLI Commands Detected

No WP-CLI command registration was detected in the current package. This would be a valuable future addition for large media libraries and migration workflows.

---

Implementation Checklist

Before publishing or deploying AFM broadly, confirm:

• Folder taxonomy appears correctly under Media -> AFM Folders.
• Media -> AFM Explorer loads and queries attachments successfully.
• REST nonce handling works for the current admin environment.
• Drag-and-drop movement works in the explorer, Media Library, and media modal.
• Bulk move workflow handles selected upload.php items as expected.
• Role default folders are saved and applied on upload.
• WooCommerce product image auto-organization creates expected folder paths.
• Large libraries perform acceptably with current REST query and size-filter behavior.
• Media modal layout remains compatible with the active admin/theme/plugin stack.

---