From bd0a381b70cd38098bc4654cf9e129c7f127e84a Mon Sep 17 00:00:00 2001 From: zemion Date: Mon, 6 Jul 2026 21:53:05 +0200 Subject: [PATCH] Sync Repo-docs-MODULE-ARCHITECTURE from project files --- Repo-docs-MODULE-ARCHITECTURE.-.md | 56 +++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/Repo-docs-MODULE-ARCHITECTURE.-.md b/Repo-docs-MODULE-ARCHITECTURE.-.md index 6e6e36a..4ed5089 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.-.md +++ b/Repo-docs-MODULE-ARCHITECTURE.-.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -40,7 +40,14 @@ The kernel must not own product semantics such as users, tenants, RBAC decisions ## Current Compatibility Responsibilities -During the staged split, `govoplan-core` still contains compatibility surfaces for access, auth, tenancy, RBAC, governance, audit, CSRF/API helpers, and secret helpers. The extracted access seed implementation now lives in `govoplan-access`; core keeps import shims and live legacy routes/models until the remaining ownership moves finish. These paths are temporary compatibility surfaces until the matching platform modules exist: +During the staged split, `govoplan-core` still contains compatibility surfaces +for access, auth, tenancy, RBAC, governance, audit, CSRF/API helpers, and +secret helpers. The extracted access implementation now lives in +`govoplan-access`; live legacy ORM table definitions have been split across +their platform owners while retaining historical table names, and core keeps +import shims until all callers move to module-owned imports or kernel +capabilities. These paths are temporary compatibility surfaces until the +matching platform modules are fully self-contained: - `govoplan-access` - `govoplan-tenancy` @@ -85,17 +92,33 @@ Known access-related capability names are defined in `govoplan-access` currently registers `access.principalResolver`, `access.permissionEvaluator`, `access.directory`, and `access.tenantProvisioner`. `govoplan-tenancy` registers -`tenancy.tenantResolver`. Feature modules should prefer these capabilities over -direct reads of access/tenant ORM models when they need labels, group -membership, default access provisioning, or tenant metadata. +`tenancy.tenantResolver`. The minimal authenticated platform set is now +`tenancy` plus `access`; the registry inserts `tenancy` before `access` when +only feature modules are requested. Feature modules should prefer these +capabilities over direct reads of access/tenant ORM models when they need +labels, group membership, default access provisioning, or tenant metadata. + +Current live table ownership: + +- `govoplan-tenancy`: `tenants` +- `govoplan-access`: `accounts`, `users`, `groups`, `roles`, + `system_role_assignments`, `user_group_memberships`, + `user_role_assignments`, `group_role_assignments`, `api_keys`, + `auth_sessions` +- `govoplan-admin`: `governance_templates`, + `governance_template_assignments` +- `govoplan-audit`: `audit_log` +- `govoplan-core`: `system_settings` Cross-module feature contracts live under focused kernel contract modules. For example, `govoplan_core.core.campaigns` defines -`campaigns.mailPolicyContext` and `campaigns.access`. The campaign module -registers these capabilities so mail can resolve campaign owner/policy context -and files can validate campaign file-share access without importing campaign ORM -models. Keep these contracts small DTO/protocol surfaces and register concrete -behavior from the owning module. +`campaigns.access`, `campaigns.mailPolicyContext`, +`campaigns.policyContext`, `campaigns.deliveryTasks`, and +`campaigns.retention`. The campaign module registers these capabilities so mail +can resolve campaign owner/policy context and delivery tasks, files can validate +campaign file-share access, and core retention can call campaign-owned cleanup +logic without importing campaign ORM models. Keep these contracts small +DTO/protocol surfaces and register concrete behavior from the owning module. ## Module Responsibilities @@ -156,6 +179,9 @@ Rules: - Keep module-owned tables and migrations in the module repository. - Keep cross-module foreign-key assumptions explicit and conservative. - Register module metadata in `MigrationSpec` so core can discover it. +- Optional module migrations may create multiple Alembic heads. Verification + should compare the database heads to the configured script heads instead of + assuming one linear revision when multiple modules are enabled. ## WebUI Contract @@ -194,6 +220,7 @@ Modules must provide icon names with `iconName` in frontend nav contributions an Current core icon names include: - `activity` +- `admin` - `campaign` - `dashboard` - `file` @@ -206,6 +233,9 @@ Current core icon names include: If a module needs a new navigation icon, add the name-to-component mapping in core first, then use the name in backend and frontend metadata. +The access module uses the `admin` icon for its `/admin` route. Core only +resolves that icon name; it does not hard-code the admin route in the rail. + ## Shared Component Rules Use this rule of thumb: @@ -242,9 +272,11 @@ The repository includes `scripts/check_dependency_boundaries.py`. It enforces th - access source may not import files/mail/campaign internals - feature modules may not import access implementation internals - feature modules may not add new direct imports of sibling feature modules -- known transitional exceptions are listed in the script with a reason +- the transitional allowlist is expected to stay empty -Every exception is extraction debt. When a capability/API/event contract replaces an exception, remove it from the allowlist. +Any future exception is extraction debt and must be temporary, documented in the +script with a reason, and removed when a capability/API/event contract replaces +it. ## Build And Verification