govoplan-core

GovOPlaN core is the platform runner and shared foundation. It owns the server entry point, database/session primitives, module discovery, migration orchestration, capability contracts, install/uninstall orchestration, and the shared WebUI shell. Platform and feature behavior 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
kernel APIs for platform metadata, module lifecycle, health, and development diagnostics
@govoplan/core-webui, including login, CSRF/API helpers, shell layout, generic UI components, IconRail, DataGrid, access boundaries, and module route/nav contracts

Platform and feature modules own their backend routers, models, migrations, permissions, frontend packages, nav items, and route contributions. Access, tenancy, policy, audit, and admin behavior live in their owning platform modules. Core should not import feature pages directly; it imports module manifests and renders their route contributions.

Governance docs

Canonical policy documents live in docs/:

Modules define module-specific permissions and policy behavior. Shared DTOs and composition rules live in core only where they are stable kernel contracts.

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 reads ENABLED_MODULES and discovers installed module entry points. Local development defaults to tenancy,organizations,identity,access,admin,dashboard,policy,audit,campaigns,files,mail,calendar,docs,ops; set ENABLED_MODULES explicitly when testing a smaller module permutation.

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

For example, to test campaign without files or mail:

cd /mnt/DATA/git/govoplan-core
ENABLED_MODULES=access,campaigns ./.venv/bin/python -m govoplan_core.devserver \
  --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.

The default development database is PostgreSQL at postgresql+psycopg://govoplan_dev@127.0.0.1:5432/govoplan_dev. Store the password in ~/.pgpass. To force the disposable SQLite fallback, run with GOVOPLAN_DEV_DATABASE_BACKEND=sqlite; that database lives below runtime/.

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.

To run the production-like local profile with PostgreSQL, Redis, a Celery worker, explicit module configuration, and persistent local file storage:

cd /mnt/DATA/git/govoplan-core
scripts/launch-production-like-dev.sh

See dev/production-like/README.md for ports, environment overrides, and cleanup commands.

govoplan_core.devserver enables the development bootstrap before loading settings. In dev, startup migrations create or upgrade the schema and the bootstrap creates the default development login if needed. Explicitly setting DEV_BOOTSTRAP_ENABLED=false disables this convenience. Production deployments should use migrations and managed database provisioning instead.

To verify the effective runtime paths and bootstrap behavior without starting uvicorn, run the smoke mode:

cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m govoplan_core.devserver --smoke --no-reload

The smoke mode prints the effective config, runtime root, database URL, modules, reload state, and bootstrap decision, then creates the ASGI app and runs startup once.

requirements-dev.txt links local GovOPlaN module checkouts for development. requirements-release.txt installs the packaged modules from tagged git refs for release builds. See RELEASE_DEPENDENCIES.md.

For the install/runtime configuration contract and operator deployment flow, see DEPLOYMENT_OPERATOR_GUIDE.md. For self-hosted config bootstrap and validation:

cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m govoplan_core.commands.config env-template --profile self-hosted --generate-secrets
./.venv/bin/python -m govoplan_core.commands.config validate --profile self-hosted

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 local host links sibling module WebUI packages through local file dependencies and Vite filesystem allowances. Release builds should use webui/package.release.json, which points WebUI module packages at tagged git refs. See RELEASE_DEPENDENCIES.md.

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.

7.2 KiB Raw Blame History