feca-mailshots-plugin/requirements/top-level.md

Mailshot Top-Level Requirements

Document Context

This document is governed by requirements/environment.md and must be interpreted with that baseline in scope.

Purpose

Define the migration goals for delivering the Mailshot feature as a WordPress plugin capability in this repository, replacing the prior Node.js server/front-end implementation approach.

Inputs

Primary input specifications:

• ../feca2-app/requirements/mailshot.md
• ../feca2-app/requirements/mailshot_data_source.md

Local governing baseline:

• requirements/environment.md
• requirements/test_environments.md

Migration Direction

1. Re-platform

   • Move from the feca2-app Node.js runtime model to a WordPress plugin runtime model in this workspace.
   • Preserve business intent of the mailshot feature while adapting implementation to WordPress/PHP architecture.

2. Source-of-truth shift

   • Remove support for local database entities used previously as source-of-truth for mailshot data:
     • issue
     • page
     • article
     • advertiser
     • ads
   • Do not keep compatibility fallbacks for these local entities unless explicitly required later.

3. Data access model

   • Access accounts, contacts, and renewals directly from the remote WordPress-side database environment.
   • Remove dependency on local replicated data for those entities.

4. Mailshot persistence

   • Create a dedicated database on the remote server to hold mailshot-specific tables and assets.
   • Treat this remote mailshot database as authoritative for mailshot definitions/assets in the plugin implementation.

Environment and Testing Goals

1. Remote data path in testing

   • During testing, access remote database data via SSH tunnel.
   • Test environments must explicitly show tunnel configuration and expected connectivity validation.

2. Verification scope

   • Validate read access for accounts, contacts, and renewals from remote source.
   • Validate read/write access for mailshot tables/assets in the new remote mailshot database.
   • Validate that removed local-domain sources (issue/page/article/advertiser/ads) are not required by the migrated flow.

Access Control Policy

1. Plugin settings access

   • The plugin Setup/settings page is administrator-only.
   • WordPress capability required: manage_options.

2. Operational feature access

   • WordPress editors (and administrators) must be able to use all non-setup mailshot features.
   • This includes full CRUD where available for:
     • data sources
     • mailshots
     • attachments
     • PDF assets
   • Baseline WordPress capability for operational pages/endpoints: edit_pages.

Research Outcomes (2026-04-20)

1. PDF engine suitability (dompdf)

   • Outcome: Accepted: suitable with constraints.
   • Decision basis is recorded in:
     • results/dompdf_investigation_findings_2026-04-20.md
   • Accepted constraint:
     • non-appearing special characters are currently acceptable.

2. Nunjucks replacement

   • Outcome: Twig selected as the PHP-side replacement direction.
   • Decision basis is recorded in:
     • results/nunjucks_replacement_findings_2026-04-20.md
   • Template policy decision:
     • use a minimal-helper approach;
     • prefer inline template logic (for example {% if x is not empty %}...{% endif %});
     • avoid introducing helper functions unless explicitly required.

Deliverables from This Requirement

1. Confirmed architecture decision for remote-only data access (accounts/contacts/renewals).
2. Confirmed plan for remote mailshot database creation and usage.
3. Research findings for dompdf viability and decision outcome.
4. Research findings for Nunjucks replacement and decision outcome.

Out of Scope (Current Top-Level Phase)

• Detailed schema definitions for the new remote mailshot database.
• Full page-by-page UI requirements rewrite.
• Full implementation of the selected rendering/template stack.