From 2751849af1b1c2c98aa3f5d90e2b289adf50add4 Mon Sep 17 00:00:00 2001
From: Albrecht Degering <albrecht@degering.name>
Date: Fri, 10 Jul 2026 12:51:22 +0200
Subject: [PATCH] chore: sync GovOPlaN module split state

---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8ffac9c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# GovOPlaN IDM
+
+`govoplan-idm` is the planned integration module for external identity
+management systems. It does not own GovOPlaN's internal identity, organization,
+account, role, or tenant tables; those remain with `govoplan-identity`,
+`govoplan-organizations`, `govoplan-access`, and `govoplan-tenancy`.
+
+The module's purpose is to connect GovOPlaN to upstream identity providers and
+directory-management processes without making the platform depend on a single
+vendor or protocol.
+
+## Boundary
+
+`govoplan-idm` should own:
+
+- inbound synchronization from external identity-management systems
+- identity lifecycle import, update, disable, and reconciliation jobs
+- mapping external identities, accounts, groups, organizational units,
+  functions, and attributes to GovOPlaN identity, organization, access, and
+  tenancy DTOs
+- provider-specific connectors for LDAP/AD, SCIM, OIDC profile claims, and
+  public-sector directory services once those targets are selected
+- dry-run previews, conflict reports, audit events, and rollback metadata for
+  identity synchronization
+
+It must not own:
+
+- password authentication, sessions, API keys, or CSRF behavior
+- GovOPlaN RBAC permission evaluation
+- tenant lifecycle storage
+- application-specific authorization rules
+- portal citizen identities unless that flow is explicitly delegated to an
+  identity-trust or portal module
+
+## Kernel Contract
+
+The module should integrate through kernel capabilities and access-owned public
+APIs:
+
+- read/write identities through `govoplan-identity` capability contracts
+- resolve organization units and functions through `govoplan-organizations`
+- resolve tenants through `govoplan-tenancy`
+- hand accepted role/right effects to `govoplan-access`
+- emit synchronization and conflict events through the shared event contract
+- write audit evidence through the audit sink capability
+- expose admin routes through module route contributions
+- contribute WebUI admin panels through module UI metadata
+
+No feature module should import IDM internals directly. Feature modules should
+ask access, tenancy, or future directory capabilities for normalized identity
+facts.
+
+## First Milestone
+
+The first useful milestone is a read-only synchronization preview:
+
+1. Configure one external directory source.
+2. Fetch users/groups/organizational units into a transient snapshot.
+3. Map the snapshot to GovOPlaN accounts, users, groups, and tenant bindings.
+4. Show creates, updates, disables, conflicts, and skipped records.
+5. Emit audit evidence for the preview run.
+
+Applying changes should come later, behind dry-run approval, conflict policy,
+rollback metadata, and maintenance-mode safeguards.