WebUI module split; docs

README.md

@@ -1,32 +1,68 @@
 # govoplan-core
 
-Reusable core components for the Government Operational Platform GovOPlaN.
+GovOPlaN core is the platform runner and shared foundation. It owns the server entry point, database/session primitives, tenant and RBAC infrastructure, governance policy, audit/auth helpers, module discovery, migration registration, and the shared WebUI shell. Feature code is supplied by installed modules.
 
-This repository owns platform-level contracts and infrastructure that should not be coupled to a consuming product module:
+## Repository ownership
 
-- backend module manifests and registry validation
-- server runner integration for routes, metadata and module availability
-- database session/base primitives and module migration registration
-- tenant/access/RBAC models and permission evaluation
-- stable principal DTOs, token helpers and tenant datastore abstractions
-- shared WebUI package `@govoplan/core-webui` for API/CSRF/auth helpers, core types, generic UI components, login UI and shell layout primitives
+Core owns:
 
-Modules register backend routes, permissions, nav items, frontend package metadata, SQLAlchemy metadata and migration locations through their `govoplan.modules` manifest. The core runner aggregates those contributions and exposes the combined platform.
+- `govoplan_core.server.app:app`, the FastAPI entry point used by uvicorn
+- `GovoplanServerConfig`, module discovery, registry validation, and route aggregation
+- SQLAlchemy base/session helpers and module migration registration
+- tenant/account/session/RBAC/governance/audit models and services
+- core API routes for auth, admin, platform metadata, audit, and system health
+- `@govoplan/core-webui`, including login, CSRF/API helpers, shell layout, generic UI components, IconRail, DataGrid, access boundaries, and module route/nav contracts
 
-## Development
+Feature modules own their backend routers, models, migrations, permissions, frontend packages, nav items, and route contributions. Core should not import feature pages directly; it imports module manifests and renders their route contributions.
 
-Install the backend core and module checkouts through the core development environment:
+## Governance docs
+
+Canonical policy documents live in `docs/`:
+
+- [RBAC_MANIFEST.md](docs/RBAC_MANIFEST.md)
+- [SYSTEM_GOVERNANCE_MANIFEST.md](docs/SYSTEM_GOVERNANCE_MANIFEST.md)
+
+Modules may define module-specific permissions and policy behavior, but the platform-level permission model and governance hierarchy belong here.
+
+## Backend development
+
+Create or activate the core virtual environment, then install core and sibling modules from this repository:
 
 ```bash
 cd /mnt/DATA/git/govoplan-core
 ./.venv/bin/python -m pip install -r requirements-dev.txt
 ```
 
-Install WebUI dependencies from the core WebUI runner, which links the module WebUI packages from the neighboring module repositories:
+Run the platform server from core. The default config loads the access/core module only; product configs can enable installed modules.
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+GOVOPLAN_SERVER_CONFIG=app.govoplan_config:get_server_config \
+  ./.venv/bin/python -m uvicorn govoplan_core.server.app:app --reload --host 127.0.0.1 --port 8000
+```
+
+`requirements-dev.txt` currently links the local `govoplan-files`, `govoplan-mail`, and `govoplan-campaign` checkouts for development. Production deployments should use tagged git dependencies or published packages.
+
+## WebUI development
+
+Install and run from the core WebUI host:
 
 ```bash
 cd /mnt/DATA/git/govoplan-core/webui
 PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm install
+PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev
 ```
 
-Production deployments should use tagged git dependencies or published package versions, not runtime file copying.
+The host links sibling module WebUI packages through local file dependencies and Vite filesystem allowances.
+
+## Module contract
+
+Backend modules register through the `govoplan.modules` entry point and return a `ModuleManifest`. A manifest can contribute:
+
+- permissions and role templates
+- API routers
+- SQLAlchemy metadata and migration locations
+- nav metadata and frontend package metadata
+- resource ACL providers and tenant summary/delete-veto providers
+
+WebUI modules export a `PlatformWebModule` with nav items and route contributions. Core renders those routes with `settings` and `auth` context.