GovOPlaN Campaign is the campaign authoring, validation, review, sending-control, and reporting module. It bundles backend campaign APIs with the campaign WebUI package.

Ownership

This repository owns:

backend module manifest campaigns
campaign, recipient, report, and campaign-audit permissions
campaign/version/job/issue/send-attempt/append-attempt models and migrations
campaign JSON schema, validation, message building, attachment resolution, ZIP handling, reports, queue/control services, and mock-send paths
WebUI package @govoplan/campaign-webui
route contributions for /campaigns, /campaigns/:campaignId/*, /operator, /reports, and /templates

Core owns the auth facade, RBAC/capability contracts, database/session primitives, CSRF/API helpers, shell layout, and route rendering. Tenancy is an optional platform module for tenant administration and tenant resolver behavior. Files and mail own their respective storage and transport capabilities.

Dependencies

The module has one required runtime dependency:

govoplan-core for platform services, auth, RBAC, DB/session lifecycle, migrations, and WebUI shell integration

Files and mail are optional module integrations declared in the campaign manifest:

govoplan-files enables managed attachment selection, frozen file-version evidence, and managed-file usage tracking. Server/API campaigns require this integration for attachments and never resolve caller-supplied local filesystem paths. Legacy file-oriented loading remains available only to explicitly trusted operator/library workflows.
govoplan-mail owns reusable profiles, encrypted SMTP/IMAP credentials, delivery policy checks, connection tests, and transport execution. Campaign JSON stores only server.mail_profile_id; inline transport settings and credentials are rejected. Without Mail, campaigns can still be authored, but profile validation and real delivery are unavailable.

Public campaign, version, job, and report responses expose business data and delivery evidence, but never process-local paths, storage-backend keys, or worker claim tokens. Operational troubleshooting uses the dedicated job diagnostics endpoint and requires the tenant-level campaigns:diagnostic:read permission. The campaign sender role receives this permission; tenant-wide administrator scopes continue to grant it through the standard policy evaluator.

Backend optional behavior is accessed through core-provided capabilities, not direct required imports. WebUI optional behavior uses core module metadata/capabilities so campaign pages can build and run without files or mail WebUI packages installed.

Campaign also provides narrow kernel capabilities so other modules and core services can cooperate without importing campaign internals:

campaigns.access for campaign share/existence checks
campaigns.mailPolicyContext for campaign-scoped mail policy and owner context
campaigns.policyContext for retention/policy provenance
campaigns.deliveryTasks for queued send and append-to-Sent workers
campaigns.retention for campaign-owned retention cleanup

Keep these capability payloads narrow: stable ids, policy payloads, and task results only.

Development

Install through the core environment:

cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -r requirements-dev.txt

Run the WebUI from the core host:

cd /mnt/DATA/git/govoplan-core/webui
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev

Module integration

Backend entry point:

[project.entry-points."govoplan.modules"]
campaigns = "govoplan_campaign.backend.manifest:get_manifest"

Frontend package:

@govoplan/campaign-webui

Platform RBAC and governance rules are documented in govoplan-core/docs/.

Operations

Campaign handbook provides the adaptive user, process, governance, technical, and operations perspectives.
Campaign delivery runbook covers queueing, local vs Celery operation, retries, reconciliation, reports, and the live SMTP/IMAP test checklist.
Immediate delivery is bounded to 25 exact eligible recipient jobs by default. Deployments may set GOVOPLAN_CAMPAIGN_SYNCHRONOUS_SEND_MAX_RECIPIENTS (0–500), and tenants may narrow that ceiling through campaign_delivery_policy.synchronous_send_max_recipients in tenant settings.
Report-email preview uses the selected version's stored v5 Mail-profile evidence. Live report email fails closed until govoplan-mail#17 provides a durable, idempotent Mail-owned outbox and transport-attempt ledger; per-job CSV is off by default and requires campaigns:recipient:export when requested.
Campaign/Mail profile boundary defines profile-only delivery, runtime resolution, execution evidence, and the fail-closed legacy migration path.
Recipient import guide covers user/admin workflows, mapping profiles, validation, and import evidence.
Recipient and address boundary defines the split between campaign-local recipients and future reusable address management.
Example campaigns and release checklist defines the maintained example scenarios and release gates.
Campaign examples is the credential-free scenario catalogue that release fixtures must follow.
SMTP/IMAP test bed provides the GreenMail Docker Compose setup and transport smoke for dedicated non-production delivery tests.

Release packaging

The repository root includes a package.json for git-based WebUI installs. It exports the package @govoplan/campaign-webui from webui/src so release builds can depend on tagged git refs instead of local file: paths. Files and mail WebUI packages remain optional product-composition dependencies supplied by the core host build, not required campaign package dependencies.

README.md Unescape Escape

govoplan-campaign