diff --git a/Repo-README.-.md b/Repo-README.-.md new file mode 100644 index 0000000..d78b475 --- /dev/null +++ b/Repo-README.-.md @@ -0,0 +1,178 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/README.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# govoplan-core + + +**Repository type:** system (kernel). + + +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 + +The shared DataGrid sizing and resize invariants are specified in +[`docs/DATAGRID_SIZING_CONTRACT.md`](docs/DATAGRID_SIZING_CONTRACT.md). + +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 + +For whole-product development, create the virtualenv from the meta repository: + +```bash +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 the modules listed by `govoplan_core.settings.Settings.enabled_modules`, including Views when its package is installed; set `ENABLED_MODULES` explicitly when testing a smaller module permutation. + +```bash +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: + +```bash +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`. + +For focused backend work, keep the complete module graph active while watching +only the module being edited. Core/config sources and explicit `--reload-dir` +paths remain watched: + +```bash +/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver \ + --reload-module calendar \ + --reload-module campaign +``` + +Use `--reload-core-only` when no optional module source tree should trigger a +restart. Omitting both options preserves the broad default and watches every +enabled module. Startup, migration, and compatibility checks still run against +the complete enabled graph whenever the backend restarts. + +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 +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](docs/SECURITY_AUDIT.md) for the operating model. + +```bash +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 use the separate, expiring single-use flow exposed by `python -m govoplan_core.commands.first_admin`; it cannot enable or consume development bootstrap credentials. + +To verify the effective runtime paths and bootstrap behavior without starting uvicorn, run the smoke mode: + +```bash +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](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 +/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: + +```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). + +Production builds lazy-load enabled module descriptors and enforce initial and +asynchronous JavaScript budgets. See +[WEBUI_BUNDLE_BUDGETS.md](docs/WEBUI_BUNDLE_BUDGETS.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.