govoplan-core/README.md

govoplan-core

Repository type: system (kernel).

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/:

• DOCUMENTATION_MAP.md
• ACCESS_RBAC_MODEL.md
• GOVERNANCE_MODEL.md
• MODULE_ARCHITECTURE.md
• DEPLOYMENT_OPERATOR_GUIDE.md
• CODEX_WORKFLOW.md

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

For whole-product development, create the virtualenv from the meta repository:

cd /mnt/DATA/git/govoplan
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.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
/mnt/DATA/git/govoplan/.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 /mnt/DATA/git/govoplan/.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
tools/launch/launch-production-like-dev.sh

See /mnt/DATA/git/govoplan/dev/production-like/README.md for ports, environment overrides, and cleanup commands. Core keeps wrapper commands during the migration, but whole-product profiles are owned by the meta repository.

Security audit

The repository includes a containerized audit toolbox for SAST, secret scanning, dependency checks, filesystem misconfiguration scans, duplication, and complexity reports. See SECURITY_AUDIT.md for the operating model.

cd /mnt/DATA/git/govoplan
tools/checks/security-audit/run.sh --mode ci --scope govoplan
tools/checks/security-audit/run.sh --mode full --scope govoplan

CI runs the ci profile in report-only mode and uploads audit-reports/ as an artifact. Once the baseline is clean, set SECURITY_AUDIT_FAIL_ON_FINDINGS=1 or pass --strict locally to turn findings into a failing gate.

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
/mnt/DATA/git/govoplan/.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.

The meta repository owns whole-product requirements-dev.txt, requirements-release.txt, and the root .env.example operator template. Core keeps package metadata and runtime commands. 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
/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.commands.config env-template --profile self-hosted --generate-secrets
/mnt/DATA/git/govoplan/.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.