# 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](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
```

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
```

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.