diff --git a/README.md b/README.md new file mode 100644 index 0000000..4a44196 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# GovOPlaN Addresses + +`govoplan-addresses` is the planned reusable address and recipient-source +module. It should own long-lived address directories and make them available to +campaigns, mail, forms, reporting, portal, and postbox modules through platform +capabilities. + +The campaign module may import campaign-local recipient tables, but reusable +address management belongs here. + +## Boundary + +`govoplan-addresses` should own: + +- Adrema-style person, organization, household, and postal-address records +- reusable email address lists and postal-letter recipient views +- segments and reusable recipient-source definitions +- consent, legal-basis, and communication-preference metadata +- deduplication, merge, and address quality workflows +- import/export of reusable address directories +- source provenance and change history + +It must not own: + +- campaign-local recipient snapshots +- delivery queues or send attempts +- SMTP/IMAP transport +- file storage +- global identity authentication or RBAC evaluation + +## First Capability + +The first useful contract should be a read-only recipient-source capability, +for example `addresses.recipientSource`. + +It should let a consumer request a stable snapshot containing: + +- source id and display label +- normalized recipient rows +- email and postal address fields +- legal-basis and consent metadata +- source update marker +- provenance fields suitable for audit and campaign reports + +Consumers must store their own immutable snapshot when they need historical +evidence. The addresses module remains the owner of the reusable source, not of +the consumer's historical records.