govoplan-core/README.md

govoplan-core

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.

Repository ownership

Core owns:

• 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

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.

Governance docs

Canonical policy documents live in docs/:

• RBAC_MANIFEST.md
• SYSTEM_GOVERNANCE_MANIFEST.md
• MODULE_ARCHITECTURE.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:

cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -r requirements-dev.txt

Run the platform server from core through the module-aware development runner. The default config loads the access/core module only; product configs can enable installed modules.

cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m govoplan_core.devserver \
  --config app.govoplan_config:get_server_config \
  --host 127.0.0.1 \
  --port 8000

The runner loads the same GovoplanServerConfig as govoplan_core.server.app:app, builds the platform registry, and passes core plus enabled module source roots to uvicorn as reload directories. After reinstalling the editable package, the same command is also available as govoplan-devserver.

Local devserver runs do not require Redis. CELERY_ENABLED defaults to false, so campaign queue actions update database state without publishing Celery tasks. Use the synchronous send flow for local send tests, or set CELERY_ENABLED=true only when a Redis broker and worker are running.

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:

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

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. Frontend nav icons must be supplied as core-resolved iconName strings, not imported icon components. See MODULE_ARCHITECTURE.md for the full module-building contract.