commit bb6cd5d90e0127d61fea1e90fc80b88fe4a83c68 Author: Albrecht Degering Date: Tue Jul 7 21:08:39 2026 +0200 Sync wiki from project files diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md new file mode 100644 index 0000000..87a0270 --- /dev/null +++ b/Codex-Project-Index.md @@ -0,0 +1,9 @@ +# govoplan-postbox Project Wiki Index + + + +This page is generated from repository and product-directory project files. + +- [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-postbox/README.md` +- [Repo-docs-POSTBOX-BACKLOG](Repo-docs-POSTBOX-BACKLOG) - `/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_BACKLOG.md` +- [Repo-docs-POSTBOX-CONCEPT](Repo-docs-POSTBOX-CONCEPT) - `/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_CONCEPT.md` diff --git a/Repo-README.md b/Repo-README.md new file mode 100644 index 0000000..3259ae2 --- /dev/null +++ b/Repo-README.md @@ -0,0 +1,47 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-postbox/README.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# govoplan-postbox + +GovOPlaN Postbox provides platform-owned postboxes for internal work, portals, campaign flows, and role-bound organizational communication. + +## Ownership + +This repository owns: + +- backend module manifest `postbox` +- postbox permissions and policy checks +- postbox, binding, message, participant, attachment-reference, and audit-facing data models +- role-organization-bound access resolution for postboxes +- API routes for postbox directory, messages, access checks, and administration +- optional integration capabilities for campaign, files, portal, notification, and mail-facing workflows +- future WebUI package `@govoplan/postbox-webui` + +Core owns auth, tenants, RBAC evaluation, database/session primitives, module discovery, migrations, CSRF/API helpers, and shell layout. Access owns identities, users, groups, roles, memberships, and administrative RBAC surfaces. + +## Role-bound postboxes + +A role-bound postbox is linked to an organizational unit and one or more roles. A person can access that postbox while their identity has an effective matching role in that organizational unit. Access is not tied to a login mailbox, personal email address, or static user assignment. + +When the role assignment changes, postbox access changes with it. The postbox keeps durable message and evidence history, while authorization remains derived from current platform role state. + +## Module integration + +Backend entry point: + +```toml +[project.entry-points."govoplan.modules"] +postbox = "govoplan_postbox.backend.manifest:get_manifest" +``` + +Frontend package: + +```text +@govoplan/postbox-webui +``` + +Platform RBAC, module capability contracts, and governance rules are documented in `govoplan-core/docs/`. diff --git a/Repo-docs-POSTBOX-BACKLOG.md b/Repo-docs-POSTBOX-BACKLOG.md new file mode 100644 index 0000000..82a99b7 --- /dev/null +++ b/Repo-docs-POSTBOX-BACKLOG.md @@ -0,0 +1,34 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_BACKLOG.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Postbox Backlog + +## P1 Immediate + +- [ ] Define the `postbox` backend manifest, permissions, module metadata, and capability names. +- [ ] Design the postbox, binding, message, participant, attachment-reference, and audit-event data model. +- [ ] Implement role-organization-bound access checks through core/access contracts. +- [ ] Add API DTOs and routes for postbox directory, access checks, message listing, message creation, and binding administration. +- [ ] Create focused tests for access changes when role assignments are granted, revoked, or expire. + +## P2 Module Integration + +- [ ] Define optional campaign integration for sender context, response intake, and artifact handoff. +- [ ] Define optional files integration for postbox-visible file and evidence references. +- [ ] Define optional portal integration for portal-facing role-bound postboxes. +- [ ] Define optional mail bridge semantics without making postboxes login-bound mailboxes. + +## P2 WebUI + +- [ ] Build the postbox administration route contribution and navigation metadata. +- [ ] Build an inbox view for visible postboxes, messages, and role-bound access explanation. +- [ ] Build a binding editor for organization and role links with audit-visible changes. + +## P3 Governance + +- [ ] Document retention, audit, and privacy rules for postbox messages and evidence references. +- [ ] Document migration ownership and compatibility imports while postbox code is extracted from core if needed. diff --git a/Repo-docs-POSTBOX-CONCEPT.md b/Repo-docs-POSTBOX-CONCEPT.md new file mode 100644 index 0000000..0ed6c16 --- /dev/null +++ b/Repo-docs-POSTBOX-CONCEPT.md @@ -0,0 +1,110 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-postbox/docs/POSTBOX_CONCEPT.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Postbox Concept + +## Purpose + +GovOPlaN Postbox provides in-platform postboxes that are addressable containers for messages, files, workflow evidence, and operational handoff. They can be used internally, exposed through portals, and connected to campaign workflows. + +The key distinction from a mailbox is ownership. A mailbox is usually bound to a login, user credential, or external mail account. A GovOPlaN postbox is bound to platform context: organization, role, process, portal, campaign, or service responsibility. + +## Role-Organization-Bound Access + +The special access pattern is a postbox linked to an organizational unit and one or more roles. A person can access that postbox while their identity has an effective matching role in that organizational unit. + +Example: + +- Organizational unit: `District Office North` +- Required role: `Case Clerk` +- Postbox: `District Office North / Case Clerk Intake` + +Any identity currently holding the `Case Clerk` role for `District Office North` can see the postbox. When the role is removed or expires, access disappears without moving messages or reassigning a mailbox. + +This makes postboxes useful for responsibilities that outlive individuals: + +- intake desks +- role-based service queues +- campaign sender or response desks +- portal message inboxes for organizational responsibilities +- file or evidence drops linked to a role in an organization + +## Authorization Model + +Postbox authorization should be derived from access-owned identity and role data through core/access contracts. The postbox module stores postbox bindings and postbox-specific permissions, but it should not duplicate membership, group, or role resolution. + +The minimum authorization inputs are: + +- postbox id +- tenant id +- organizational unit id +- required role id or role key +- actor identity id +- current effective role assignments from the access module +- optional explicit administrative grants for postbox administration + +The expected result is a narrow access decision: + +- can discover +- can read +- can send or reply +- can attach or link files +- can administer bindings + +Access changes must be auditable because a person can gain or lose postbox visibility through role assignment changes rather than direct postbox membership edits. + +## Domain Objects + +The initial domain model should stay small: + +- `Postbox`: the addressable container. +- `PostboxBinding`: the binding to organization, role, portal, campaign, service, or explicit context. +- `PostboxMessage`: a platform-native message or message reference. +- `PostboxParticipant`: normalized sender, recipient, author, or actor reference. +- `PostboxAttachmentRef`: reference to a file, evidence item, generated campaign artifact, or external attachment. +- `PostboxAccessEvent`: auditable record of access-affecting changes and sensitive actions. + +Messages and files should be linked by stable ids and typed references. The postbox module should not import file, mail, or campaign internals. + +## Capability Boundaries + +Postbox should expose narrow capabilities through core: + +- `postbox.directory`: find postboxes visible to an actor. +- `postbox.access`: answer access decisions for a postbox/action pair. +- `postbox.messages`: create, list, and read postbox messages through DTOs. +- `postbox.delivery`: accept messages or delivery artifacts from other modules. +- `postbox.evidence`: link durable evidence references without owning the evidence store. + +Optional consumers: + +- Campaign can use postboxes for campaign sender context, reply intake, review queues, and role-bound access to campaign artifacts. +- Files can expose file references to a postbox when the actor's role grants access. +- Portal can show portal-facing postboxes without owning the postbox access model. +- Mail can bridge external mailbox delivery into postboxes when configured, without making postboxes mailbox-bound. + +## Operational Rules + +- Current role state controls current access. +- Historical message records remain durable even when no current person holds the role. +- Administration of bindings should require explicit postbox administration permission plus access/RBAC authority for the target organization. +- Sensitive access decisions and binding changes should emit audit events. +- Retention rules should be postbox-owned but able to reference campaign, file, and portal provenance. + +## First Implementation Shape + +The first implementation should define the backend manifest, permissions, DTOs, and migrations before building rich UI. A minimal API can then support directory lookup, access checks, message creation, message listing, and binding administration. + +The WebUI should start as an administration and inbox surface: + +- postbox directory +- role-bound access explanation +- message list and message detail +- binding editor for organization and role links +- audit-visible administrative actions + +Campaign, files, portal, and mail behavior should arrive as optional integrations after the core postbox model is stable.