Skip to content
Whity docs

Whity Core Framework

Welcome to the Whity Core documentation.

Section titled “Quick Links”

System documentation

Section titled “System documentation”
  • Architecture — Full system guide: request lifecycle, plugins, RBAC, multi-tenancy, schema, deployment (start here).
  • Running headless — Your own frontend on the API and MCP: deploying without the bundled admin, CORS_ALLOWED_ORIGINS + FRONTEND_URL, cookie vs token-mode auth, OpenAPI discovery.
  • Permission System — RBAC permissions, registry, role hierarchy, enforcement.
  • Tenant Isolation — Multi-tenancy, TenantContext, query scoping.
  • Monetization & Metering — Entitlements → plans → subscriptions → payment wall → rate limits: the one runtime access gate, per-tenant enforcement modes, and plan-driven throughput (the operator never walls themselves).
  • Customer sign-up for a workspace — Let customers join one workspace on their own: Off / Approval required / Open, customer-safe starting roles, allowed email domains, the approval queue, and how it differs from platform sign-up.
  • Sign in with Google (SSO) — End-to-end federated sign-in setup: Google OAuth client, provider config, trust tiers, first-login behaviour, troubleshooting.
  • Email (SMTP) Setup — Configure outbound email end to end: cPanel/SMTP credentials, the mail.* settings + write-only encrypted password, local Mailpit testing, troubleshooting.
  • Hook System — Plugin event/extension mechanism.
  • Offline PHP plugin host — the Tauri desktop template’s bundled FrankenPHP process that runs real, unmodified whity plugins fully offline (discovery, hooks, RBAC), plus Whity\Sdk\Testing\OfflinePluginHostConformanceTestCase (see sdk/README.md) for proving your own plugin works there.
  • Desktop plugin releases — the bin/desktop-plugin-release pipeline that source-obfuscates a plugin, packages it in the shape the desktop installer requires, and catalogues it in desktop_plugin_releases for GET /api/desktop-plugins.
  • Plugin UI Blocks — Server-driven UI: the platform-neutral block contract (display / data-bound / interactive) plugins declare and each platform renders.
  • Plugin Data Types — registerDataType: a plugin declares its records’ lifecycle (trashed ≠ retired) and reference graph as data; core owns the guard evaluation, the refusals, and the generated trash/restore/retire surface.
  • Family Relations — Person-node graph, relationship types, the relations API + admin hub.
  • Document & Label Designer (removed) — The old canvas designer was replaced by the document editor in 0.2.20: what the upgrade converts, what it leaves out, and what happens to documents issued from it.
  • Document themes — How a document’s print colour and letterhead are chosen: Whity’s standard theme, the workspace’s themes and the document’s own overrides, frozen when a template is published.
  • Document Render Service — Operating the optional whity_render PDF tier: the published ghcr.io/<repo>/render image, why its tag must match the app’s, the memory a render actually costs, and the settings that bound it.
  • Navigation Customization — Design for a customizable sidebar: tenant default layout + per-user overrides gated by a tenant setting; server resolves RBAC ∩ tenant ∩ user.
  • Internationalization — Translation keys derived from the code that renders them: t('key', 'English') → extracted catalogue → seeded rows → the console where a translator closes the gap. Includes the CI drift gate and how dynamic keys are declared.
  • Feature Flags — The SettingsRegistry-based capability toggle mechanism: how a flag gates code, the generic admin page, the recipe for adding a new one, and the current inventory.

Contributing

Section titled “Contributing”
  • Development Workflow — How work is planned and shipped: the Instruction Set (IS) and the Tasker flow (WC-XX numbering, task lifecycle, parallel execution).
  • Testing Against PostgreSQL — Closing the SQLite/PostgreSQL dialect gap: how to point core’s and a plugin’s suites at a real engine, and the catalogue of differences that pass silently on SQLite.
  • Package Releases — How the publishable packages (@whity/ui, the PHP plugin SDK) are versioned and released: monorepo + independently-versioned packages, changesets, version-gated publish.
  • CONTRIBUTING.md — Dev setup, coding standards, testing, and the PR process.
  • Plugin Development — Build plugins against PluginInterface.

What is Whity Core?

Section titled “What is Whity Core?”

Whity Core is a white-labeled multi-tenant PHP 8.4 framework for SaaS applications, served by FrankenPHP persistent workers over a shared PostgreSQL database.

Features:

  • ✅ Multi-tenant (shared PostgreSQL, tenant isolation via tenant_id + request-scoped context)
  • ✅ Extensible plugins (auto-discovery, hot-reload, lifecycle isolation)
  • ✅ Built-in RBAC security (resource:action permissions, role hierarchy)
  • ✅ FrankenPHP persistent workers

Status: 0.2.8, pre-1.0. It runs a live deployment, but the API is not frozen — a minor version can still change route shapes and schema. Pin an exact version, and read Core Update before upgrading.

Getting Started

Section titled “Getting Started”

Whity Core is a deployed application, not a library you pull into another project — there is no amroksaleh/whity-core package on Packagist. Clone it and bring the stack up:

Terminal window
git clone https://github.com/whity-org/whity-core.git
cd whity-core
composer install     # on the HOST first — the dev image ships no vendor/, and db-init exits 255 without one
docker compose up

See Installation for the environment variables, the db-init bootstrap and the first-run seed.

To deploy rather than develop, the release pipeline publishes versioned images — ghcr.io/whity-org/whity-core, …/web, and the optional …/render — whose tags must match each other. See Deployment Guide and Core Update.

License

Section titled “License”

AGPL-3.0-only with the Whity Plugin Exception (free software; plugins MIT)

Commercial licensing: amroksaleh@gmail.com