Table of Contents

govoplan-campaign

Ownership
Dependencies
Development
Module integration
Operations
Release packaging

Mirrored from /mnt/DATA/git/govoplan-campaign/README.md. Origin: repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.

govoplan-campaign

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, /address-book, and /templates

Core owns auth, tenants, RBAC evaluation, database/session primitives, CSRF/API helpers, shell layout, and route rendering. 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. Without it, campaigns can still use legacy/local attachment paths where configured.
govoplan-mail enables reusable mail profiles, delivery policy checks, SMTP sending, and IMAP append behavior. Without it, campaigns can still be authored, validated, built, and reported, but real delivery/profile features are unavailable.

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 delivery runbook covers queueing, local vs Celery operation, retries, reconciliation, reports, and the live SMTP/IMAP test checklist.
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.