From 2782130705bcc02795b9ff00902e890f69346c3d Mon Sep 17 00:00:00 2001 From: zemion Date: Mon, 6 Jul 2026 14:32:44 +0200 Subject: [PATCH] Sync Repo-README from project files --- Repo-README.-.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 Repo-README.-.md diff --git a/Repo-README.-.md b/Repo-README.-.md new file mode 100644 index 0000000..d4a686d --- /dev/null +++ b/Repo-README.-.md @@ -0,0 +1,77 @@ + + +> 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. + +## Development + +Install through the core environment: + +```bash +cd /mnt/DATA/git/govoplan-core +./.venv/bin/python -m pip install -r requirements-dev.txt +``` + +Run the WebUI from the core host: + +```bash +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: + +```toml +[project.entry-points."govoplan.modules"] +campaigns = "govoplan_campaign.backend.manifest:get_manifest" +``` + +Frontend package: + +```text +@govoplan/campaign-webui +``` + +Platform RBAC and governance rules are documented in `govoplan-core/docs/`. + +## Operations + +- [Campaign delivery runbook](docs/CAMPAIGN_DELIVERY_RUNBOOK.md) covers queueing, local vs Celery operation, retries, reconciliation, reports, and the live SMTP/IMAP test checklist. + +## 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.