Whoobe - release documentation#

The documentation in this folder describes the product as it is delivered and operated. Everything here has been checked against the code at the time of the last reorganisation (see Status); the design history of the project stays in ../plans and is deliberately not part of a release.

Aligned to release: v0.1.0 (2026-10-14) - see release-process.md

Deployment model. One workspace per organisation. Divisions of the same entity share a workspace and are told apart with roles; different companies or legal entities get separate workspaces. Whoobe is not a shared multi-tenant platform (why).

1. Start here#

If you want to...	Read
understand what Whoobe is and why a platform like it	What Whoobe is (one page)
judge fit, cost and limits	Full overview
understand how it is built and why	Architecture overview, design decisions
read what is written for your role	Documentation by role: CEO, IT manager, operators, security and compliance, marketing, data owners, developers
learn to use it	User manual
install it	Operations: start here

2. The pillars#

The detailed documentation is organised by what Whoobe does. Each pillar has an index page.

Pillar	What it is	Index
Content	Websites, pages, snippets, themes, languages, documentation sites, publishing to sites, apps and headless	content/
Data (PIM, MDM)	Data Classes and Objects, relations, languages, publish workflow, import from Pimcore, using data in pages and apps	data/
Communication	Integrations, Automations, the Client Hub (API clients), forms and mail	communication/
DAM	The media library: storage, folders, visibility, transforms, CDN mirror	dam/
AI	Generating pages, snippets and images, translation, Figma import; your provider, your key	ai/
Settings	Configuration in the dashboard and in the environment	settings/
Security	Threat model, findings, data protection, test evidence, supply chain	security/
Operations	Install, configure, back up, upgrade, observe	operations/
Guides	The user manual and an index of every how-to	guides/

3. Other sections#

Section	What is in it
overview/	What Whoobe is, the full overview (what it does and does not do, costs, fit, by role), the dated executive summary
architecture/	Architecture overview, data and storage, authentication and authorization, and the design decisions
by-role/	Reading paths for CEO, IT manager, operators, security and compliance, marketing, data owners, developers
api/	API reference and openapi.yaml, both generated from one route table by gen-api-docs.py
whoobe-history.md	The story of Whoobe
credits.md	Thanks to the open-source projects Whoobe is built with and works with; the legal record is THIRD_PARTY_NOTICES.md
community/	Why sponsor and why contribute to open-source projects, and how to help Whoobe
release-process.md	How a release is made: versions, support policy, release gates, procedure
release-notes-0.1.0.md	What 0.1.0 contains, behaviour changes to check before installing over a development setup, known limits

Reading paths. Architect: architecture overview, data and storage, authentication, capacity. DevOps: creating workspaces, configuration reference, secrets and keys, backup/DR, upgrade, observability. Security / compliance: threat model, status summary and findings, data protection, supply chain, encryption. More in documentation by role.

What is not here#

• docs/plans/ - design documents and implementation plans, written before or while a feature was built. They explain why something is the way it is, and many code comments point to them, but they are not kept in step with the code and some describe work that was changed or not done. Read them as history.
• Early notes and one-off documents at the top of docs/ (initial notes and plan, the DAM implementation plan, Studio integration notes, an exported console log, a Figma export).

Rules for this folder#

1. Only current documents. A document is added here when it describes behaviour that exists in the code, and it leaves (back to plans/, or deleted) when it stops being true.
2. Facts that can be checked are checked. Paths, commands, environment variables, screen labels and route lists in these files must exist in the repository. The API reference and OpenAPI file are generated: edit the route table in api/gen-api-docs.py and run python3 docs/release/api/gen-api-docs.py. A route added to core-api without an entry there leaves the API documentation behind; compare with scripts/security/routes.expected.json (all 228 core-api routes are documented, checked by scripts/release/check-docs.py). The same script fails when an environment variable read by the services or listed in .env.example is missing from the configuration reference.
3. Changes are logged in the root CHANGES.md, as for any other file.

Status#

Reorganised on 2026-10-05; technical layer (architecture, operations, security reviews) added on 2026-10-09; restructured by pillar, with the platform overview, design decisions, reading paths by role and the pillars Data, AI and Settings, on 2026-10-13. The documentation gate of the release (./scripts/release.sh check, scripts/release/check-docs.py) passes: every core-api route documented, no broken link or quoted repository path, every environment variable documented.

What a documentation release still needs#

Item	State	Owner / next step
Alignment line (the release this documentation matches)	set by scripts/release.sh prepare	release manager
Technical set for architects, DevOps and security (architecture/, operations/, security/)	written 2026-10-09 from the code; statements that depend on running systems (TLS on a live host, upgrade, restore, load, multi-replica) are marked as untested	review by someone other than the author; rehearse the runbooks once (backup, upgrade)
Findings found by the review: F-055 to F-058	recorded in security/findings.md, open	fix before or accept explicitly in the release notes
Security status summary, DAST, manual security checklist	summary updated 2026-10-09; DAST and the manual checklist not repeated for the features of 2026-10-08/09	run on the release commit (release gate)
SBOM	scripts/release/sbom.sh works (CycloneDX, 669 components in the source tree); not attached automatically	attach to the GitHub Release; automate in release.yml
Image digests, signatures, provenance	not available (images are published by hand)	release.yml (release process section 7)
Bare-metal guides (operations/deployment.md, miniguide-deployment.md)	flagged as not re-verified; the container workspace is the tested path	rewrite or retire
User manual	partial by design: chapters listed in its table of contents are not written; no App Mode, thumbnail capture, documentation-site, form-upload chapters (the guides cover them)	write after the release
content/headless-sdk.md, content/dynamic-website-paths.md, publishing guides	names checked, not read line by line	review
Executive summary	positioning text dated 2026-09-18; not a technical reference	refresh before external use
Runbooks never rehearsed: restore on a new host, upgrade, workspace removal and re-creation	written, not run end to end	rehearse once and note the date here
Generated documentation sites	the product can publish this folder as a documentation site (Markdown, index, search); not set up for the release	optional: publish docs/release with the product's own documentation site feature
Languages	English only