# AdreMa Capability Assessment And Distribution-List Roadmap ## Purpose This document records a behavior-level assessment of the historical AdreMa application supplied in `/mnt/DATA/tmp.tar`. The goal is not to reproduce its implementation or UI. The goal is to preserve the useful administrative capabilities while replacing hard-coded queries and output paths with governed, reusable GovOPlaN contracts. The archive was inspected as untrusted historical material. No archived code was executed. Generated documents and record-level output were excluded from the analysis. ## Evidence And Handling - Archive SHA-256: `328edbaf05df084f9c63cc3b9b36f7c5ae0c639942be4b7ad830efc0905a311b` - Compressed size: about 1.49 GB - Inventory: 8,966 files and 190 directories - Uncompressed payload: about 1.79 GB - The AdreMa selection UI contains 258 distinct segment variables, 265 query cases, 13 sort definitions, seven action definitions, and 24 department-specific forms. - The adjacent configurable list/report layer contains 47 ETI definitions. - The wider print-server archive contains 127 SQL files, 181 XSLT files, and 82 Python workflow sources. The archive contains generated person-level documents and embedded credentials. It must not be committed, copied into test fixtures, or treated as safe sample data. Any credential that could still be valid must be rotated. Future fixtures derived from this assessment must be synthetic. ## What AdreMa Actually Is AdreMa is not primarily a master address database. It is a role-specific audience selection and output application over authoritative institutional databases. Its main flow is: 1. Authenticate against a directory. 2. Show a menu of saved recipient selections permitted for the current user or department. 3. Run a fixed SQL selection against organization, person, employment, function, student, geography, and address data. 4. Apply a selected sort order and address variant. 5. Produce a table, spreadsheet, label preview, printable label file, or BCC mail draft. 6. Record a basic process log and recipient count. The broader print-server application adds SQL-to-XML extraction, XSLT transformation, HTML/Excel output, TeX/PDF generation, batch letters, PDF protection, and deployment-specific printer submission. This means an AdreMa replacement should not be one large Addresses feature. Distribution Lists is the core user-facing domain for audience definitions, expansion, and reusable `Verteiler`. It composes capabilities from Addresses, Organizations/IDM, Datasources, Connectors, and Dataflow, then supplies frozen results to Templates, Campaign, Files, Audit, Policy, Reporting, and Workflow. No separate Print module is required: Templates owns printable output and an optional printer endpoint is an export destination, not a new party or audience domain. ## Observed Functional Model ### Sources And Identities The application reads live authoritative data rather than maintaining a separate copy. Its selections use: - people and institutional units - functions and role assignments - employment and student state - effective dates and exclusions - internal and external organizations - geography, country, and postal-code ranges - source-specific person, registration, and unit identifiers Access to selections is hard-coded by user and department. Administrative users receive the union of those menus. ### Contact And Address Semantics Observed recipient fields include: - display name, given name, family name, title, and formal salutation - organization/unit and function context - phone, fax, email, and URL - `care of`/`for the attention of` lines - street, postal code, locality, country, and internal mail routing - person, registration, and organizational-unit identifiers - address purpose variants such as private, semester, home, business, service, and correspondence address - effective employment or membership data used to decide eligibility The legacy system also allows a requested number of labels for an individual recipient. That quantity belongs to an output job, not to the canonical address record. ### Recipient Selection Selections cover several distinct patterns: - static categories of institutional units - people assigned to a function or organizational level - current-state selections with effective-date rules and exclusions - geographic and demographic selections - combinations and unions of predefined audiences - explicit person or unit lookup by source identifier - department-specific variants of a shared audience - user-selected additional predicates and sort orders in the adjacent ETI report layer The important reusable abstraction is therefore a versioned, parameterized, permissioned segment definition. The 265 query branches must not become 265 new backend endpoints. ### Output The directly observed output modes are: - on-screen recipient table with contact and postal fields - spreadsheet export - plain-text label preview - generated label file - emailed label file - printable label output - BCC mail draft The adjacent print-server flows additionally produce: - formatted lists and grouped reports - personalized letters and notices - HTML, spreadsheet-compatible, TeX, PostScript, and PDF artifacts - printer-specific layouts and deployment-specific print submission - password-protected output and combined document bundles ### Configuration The ETI layer is an early configuration-driven report system. A definition can declare: - a SQL source - named optional filter predicates - named sort orders - list and label layouts - page, line, margin, repetition, and format settings - screen or spreadsheet output That is conceptually close to a GovOPlaN combination of a Dataflow template, typed output template, and Report/Campaign run configuration. ## Legacy Limitations We Should Not Reproduce - users, departments, permissions, query variants, and output paths are hard-coded - credentials are embedded in source files - request values are interpolated into SQL and shell commands - authentication, authorization, session transfer, and application routing are coupled - selection names do not carry version, owner, purpose, legal basis, or provenance - past output cannot be reproduced reliably after source data or query code changes - exclusions and exceptional recipients are hidden inside SQL - there is no first-class consent, suppression, address-quality, or duplicate resolution model - mail generation relies on client-side `mailto` BCC links - output submission has weak status and evidence handling - temporary files and generated artifacts are not governed records - the UI does not explain why a recipient was included, excluded, or inaccessible ## Current GovOPlaN Coverage | Capability | Current state | Primary owner | | --- | --- | --- | | Scoped address books and contacts | Implemented | Addresses | | Multiple email, phone, and postal contact points | Implemented | Addresses | | Static address lists | Implemented | Addresses | | vCard import/export and CardDAV sync | Implemented | Addresses | | Read-only lookup and immutable email-recipient snapshots | Implemented | Addresses | | Source provenance and sync conflicts | Implemented | Addresses | | Organization units and function definitions | Implemented | Organizations | | Effective-dated identity-to-function assignments | Implemented first slice | IDM | | Governed source catalogue, snapshots, and frozen states | Implemented first slice | Datasources | | Connector-backed tabular acquisition and preview | Implemented first slice | Connectors | | Graphical/SQL transformations, joins, filters, expressions, quality, and reconciliation | Implemented broad first slice | Dataflow | | Campaign snapshots, review, digital delivery, and evidence | Implemented first channel | Campaign | | Typed template library and document rendering | Scaffold/issue only | Templates | | BI reports and spreadsheet-grade exports | Scaffold/issue only | Reporting | | Mixed operational distribution lists and governed segments | Contract/implementation issues only | Distribution Lists | | Contact-point consent, suppression, and preferences | Open issue | Addresses/Policy | | Deduplication, merge, quality, and complete history | Open issue | Addresses | | Channel-neutral expansion and frozen postal targets | Missing | Distribution Lists/Addresses | | Printable label, envelope, and letter output | Open issue | Templates | | End-to-end guided AdreMa workflow | Missing | Workflow plus consuming modules | ## Target Architecture ### 1. Identities, Groups, Functions, And Contact Points The authoritative subject model is shared deliberately: - Organizations owns tenant-local units, structures, and function definitions. - IDM owns identities' effective-dated assignments to those functions and the typed group/membership relationships used as audience sources. - Addresses owns contact records and contact points, including formal addressing fields, postal purposes, validity, preference, and provenance. - Distribution Lists stores stable provider references and expansion evidence; it does not copy any provider's master records. An IDM identity status is a lifecycle indicator such as active, suspended, or retired. A business status used for selection is represented by a typed group, function, or effective-dated relationship. The two meanings must not share one field. Addresses still needs postal fields for care-of/addressee lines, PO boxes, country codes, internal-mail routes, and delivery instructions. It may preserve vCard `KIND`/`RELATED` data for round-trip compatibility, but it must not become a parallel party or organizational-relationship authority. Every provider remains optional. A deployment without IDM can still use local address contacts and raw targets; a deployment without Addresses can still expand identities, groups, functions, and provider-native targets. ### 2. Governed Distribution Lists And Segments Distribution Lists owns reusable audience definitions and their user experience. Dataflow evaluates complex tabular predicates, while Datasources and Connectors provide governed inputs. Addresses may expose simple contact search/filter capabilities, but a reusable segment is a Distribution List definition. A segment needs: - immutable definition revisions - system, tenant, group, and user scope - complete-flow versus reusable-template semantics - parameters with types, defaults, constraints, and permitted overrides - explicit include, exclude, and manual-override sets - source fingerprints and freshness requirements - preview, count, sample, and "why included/excluded" diagnostics - schedule/event refresh policy where materialization is wanted - owner, purpose, legal basis, retention, and policy provenance - materialized/frozen recipient snapshots for reproducible use Simple tag/contact predicates may be delegated to Addresses. Cross-source joins and complex expressions compile to a pinned Dataflow revision rather than creating a second query engine in Distribution Lists. ### 3. Expansion And Channel Resolution Distribution Lists orchestrates a versioned, channel-neutral expansion contract. Provider capabilities contribute identities, groups, function incumbents, contact-point candidates, or tabular rows. The expansion can resolve: - email targets - postal targets - internal-mail targets - digital portal targets when Campaign has such a delivery provider - unresolved or blocked targets with stable reason codes Resolution must consider: - requested channel and communication purpose - effective date - preferred address/contact point - explicit address-purpose selection and fallback rules - locale and international postal formatting - channel opt-in/preference, consent, legal basis, suppression, and Policy decisions - duplicate targets and household/organization grouping - source revision, selected contact-point ID, and complete provenance Addresses owns contact-point preference/consent facts; Policy decides what is permitted and explains provenance; Distribution Lists records the applied decision in its expansion result. Campaign then applies explicit hybrid-channel routing and freezes the result. A future Portal self-service surface may edit permitted preferences through these same contracts and receive Campaign output, but it is not required for the core AdreMa implementation. Consumers never retain only a live pointer to a list or segment. ### 4. Static And Operational Lists The existing split remains correct: - Addresses owns address books and simple classical groupings of contacts or contact points. - Distribution Lists owns static and dynamic operational `Verteiler` containing address records, IDM identities and typed groups, organization units, functions/effective incumbents, raw targets, Dataflow-backed rows, and nested distribution lists. - Workflow/Tasks owns an `Umlauf` with ordering, state, deadlines, escalation, and decisions. Distribution-list entries need stable IDs. A consumer stores an immutable expansion snapshot. Consumer-specific enrichment belongs to that consumer; reusable derived lists are separate, revision-pinned definitions. ### 5. Templates, Artifacts, And Delivery Templates should provide typed render contracts for: - labels and label sheets - envelopes - form and serial letters - email and other digital messages - list/report layouts Templates declare required fields and output capabilities. Rendering produces a managed Files artifact with template revision, input snapshot hash, renderer version, page/count summary, and diagnostics. Campaign should orchestrate postal batches with the same lifecycle as other delivery channels: freeze recipients, validate required fields, review exceptions, render, approve, deliver or export, reconcile outcomes, and retain evidence. Templates owns printable content and layout. Files persists approved artifacts, Campaign owns batch review and channel routing, and Audit records the evidence. Downloading or handing a generated PDF to the operating system is a complete supported path. If a deployment later needs an IPP/CUPS or managed print-server destination, Connectors can expose it as a governed artifact export provider; that does not require a separate Print module. Hybrid campaigns may choose email, printable postal output, or a portal-capable delivery target per recipient. Opt-in is an input to the Policy decision, never an implicit instruction to duplicate delivery across channels. Campaign must freeze the chosen route, fallback rule, and reason for every recipient. ### 6. Governance And Quality Parity is not sufficient without: - purpose- and channel-specific consent/legal-basis records - do-not-contact and returned/invalid-address suppression - normalization and validation with original-value preservation - duplicate candidates, survivorship rules, manual merge/split, and undo evidence - field-level provenance and source-of-truth precedence - stale-source and stale-segment warnings - field/row/export policy decisions with user-readable explanations - complete audit events for read, export, resolution, merge, rendering, and delivery - retention, legal hold, and deletion behavior for source records and frozen output evidence ### 7. Guided User Experience The default journey should be: 1. Choose or create a distribution list/segment. 2. Preview the authorized audience and inspect included, excluded, duplicate, invalid, and suppressed counts. 3. Select channel, address purpose/fallback, sort, and grouping. 4. Freeze a recipient snapshot. 5. Select a compatible template/output format. 6. Review individual exceptions and approve the run. 7. Export or deliver through available capabilities. 8. inspect progress, outcomes, returned items, and evidence. Workflow may package this as a reusable guided process and activate a focused View. Every underlying resource must remain independently accessible and permission-checked. ## Representative Golden Flow Before migrating any historical selection, build a synthetic AdreMa fixture covering: - people, organizations, units, functions, and effective-dated assignments - multiple postal-purpose variants and internal mail - a function-based segment - an organization-unit segment - a geography-based segment - a union of segments - explicit inclusion and exclusion - duplicate and suppressed recipients - deterministic sorting and address fallback - frozen postal and email snapshots - label, spreadsheet, and letter output expectations The fixture should assert exact recipient IDs, selected contact-point IDs, ordering, exclusion reasons, source fingerprints, and output hashes. It must contain no archived record-level data. ## Migration Strategy Do not translate the legacy source one query branch at a time into application code. 1. Inventory each still-relevant named selection with owner, purpose, legal basis, source systems, parameters, output type, and expected use frequency. 2. Retire obsolete and duplicate selections before migration. 3. Map source tables to governed Connector/Datasource definitions. 4. Convert reusable predicates into Distribution List definitions backed by pinned Dataflow templates or provider-native predicates. 5. Compare the new result against an authorized legacy run using counts and pseudonymized stable keys. 6. Approve and version the new segment. 7. Migrate output layouts into typed Templates. 8. Retain a migration report and decommission the corresponding legacy path. ## Recommended Delivery Order ### Priority 1: Functional Parity Foundation 1. Distribution-list DTOs, versioned definitions, expansion, and snapshot contracts. 2. Typed IDM groups and effective-dated identity/function relationships, with identity lifecycle status kept separate. 3. Channel-neutral contact-point candidates and preference/consent facts from Addresses, evaluated through Policy. 4. Dynamic governed segments through Dataflow, Datasources, and Connectors. 5. Synthetic AdreMa golden-flow fixture. 6. Typed label, envelope, and letter templates with managed artifacts. ### Priority 2: Operational Parity 1. Campaign hybrid-channel review, routing, and printable-output flow. 2. Spreadsheet/report exports with exact frozen-snapshot evidence. 3. Consent, suppression, preferences, deduplication, merge, and quality UI. 4. CSV/XLSX and directory/database migration profiles. 5. Distribution-list expansion and Campaign integration. ### Priority 3: Beyond AdreMa 1. Portal self-service for permitted channel opt-in and digital receipt. 2. Returned-mail and correction workflows. 3. Postal-provider/franking integration and delivery reconciliation. 4. Scheduled/event-driven segment refresh and recurring campaigns. 5. Address analytics, geocoding where policy permits, and quality trends. ## Completion Standard For The Umbrella Feature The AdreMa umbrella is complete when a user can define or reuse a permissioned Distribution List, explain and freeze the exact recipients and chosen channels, create reviewed label/letter or digital outputs, export or deliver through installed modules, and later prove exactly which source data, rules, template, actor, and delivery outcome were involved. The same flow must degrade cleanly for every optional provider or consumer module combination.