Albrecht Degering
bfc882f0db
All checks were successful
Dependency Audit / dependency-audit (push) Successful in 1m43s
128 lines
7.2 KiB
Markdown
128 lines
7.2 KiB
Markdown
[](https://git.add-ideas.de/add-ideas/govoplan-core/actions?workflow=module-matrix.yml&actor=0&status=0)
|
|
[](https://git.add-ideas.de/add-ideas/govoplan-core/actions?workflow=release-integration.yml&actor=0&status=0)
|
|
[](https://git.add-ideas.de/add-ideas/govoplan-core/actions?workflow=dependency-audit.yml&actor=0&status=0)
|
|
|
|
# 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](docs/DOCUMENTATION_MAP.md)
|
|
- [ACCESS_RBAC_MODEL.md](docs/ACCESS_RBAC_MODEL.md)
|
|
- [GOVERNANCE_MODEL.md](docs/GOVERNANCE_MODEL.md)
|
|
- [MODULE_ARCHITECTURE.md](docs/MODULE_ARCHITECTURE.md)
|
|
- [DEPLOYMENT_OPERATOR_GUIDE.md](docs/DEPLOYMENT_OPERATOR_GUIDE.md)
|
|
- [CODEX_WORKFLOW.md](docs/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
|
|
|
|
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
|
|
```
|
|
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core
|
|
scripts/launch-production-like-dev.sh
|
|
```
|
|
|
|
See [dev/production-like/README.md](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:
|
|
|
|
```bash
|
|
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](docs/RELEASE_DEPENDENCIES.md).
|
|
|
|
For the install/runtime configuration contract and operator deployment flow, see [DEPLOYMENT_OPERATOR_GUIDE.md](docs/DEPLOYMENT_OPERATOR_GUIDE.md).
|
|
For self-hosted config bootstrap and validation:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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
|
|
```
|
|
|
|
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](docs/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](docs/MODULE_ARCHITECTURE.md) for the full module-building contract.
|