Seed postbox workflow and concept docs

docs/POSTBOX_CONCEPT.md

@@ -0,0 +1,103 @@
+# 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.