# 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.