Skip to main content

Umbraculum documentation

Tier: Public

This folder is the canonical reference set for the Umbraculum platform. It is structured so that anyone — a new contributor, a self-hoster, a hosted-service customer, or a future maintainer — can find what they need without reading the whole repository.

Documents are grouped by purpose, not by physical location. Most files sit at the top level — they have not been moved into per-purpose subfolders in order to keep cross-links inside the existing codebase stable; this index provides the navigation. The exceptions are integrations/, calculators/ (pre-existing per-asset folders), archive/ (superseded revisions), and help/ (end-user / operator help, currently empty placeholder).

Audience tier. All documents in this folder are Tier: Public by default — written to be surfaceable when the repository flips public. The first content line of each doc carries an explicit **Tier:** Public marker for clarity. Other tier values reserved for future use: Partner-restricted, Customer-restricted. Documentation that is not public-tier lives outside this folder and outside any public-mirror flip; it is intentionally not indexed here.

Start here​

If you are new to the project, read these documents in order:

  1. NAVIGATE-MONOREPO.md — path map first (Magento mental model, four package tiers, PIM worked example). Read this when folder names feel ambiguous.
  2. GLOSSARY.md — terminology first (recommended if vertical, canonical, or brewery are unfamiliar): plain-language definitions, the brewery reference-vertical convention, and links to deeper docs.
  3. PLATFORM-ARCHITECTURE.md — the vision and shape: horizontal platform with vertical modules, AI consultant blueprint, BYOK + paid tier unlock, and the future managed-AI path.
  4. ROADMAP.md — the direction of travel: what is shipped, what is next, the 12–30 month trajectory.
  5. LICENSING.md — the licensing posture and reasoning: AGPLv3 core + MIT SDK, commercial dual license, and what these choices imply for contributors, self-hosters, module developers, and enterprises.

Student, capstone team, or university lab? ACADEMIC-AND-EXPERIMENTATION.md — free self-host experimentation, suggested project shapes, alpha expectations, and an honest fit filter (brochure entry point links here).

Building product X on Umbraculum (vertical ISV / integrator, not core contributor)? BUILDING-YOUR-VERTICAL.md — start your vertical, omit brewery, Magento sample-data parallel.

Cross-platform (web + native + Ubuntu Touch Morph webapp wrapper) boundaries: CROSS-PLATFORM-BOUNDARIES.md, design/ubuntu-touch-shell-strategy.md. The brewery reference vertical's product rules: modules/verticals/brewery/IMPLEMENTATION-LOG.md. Together they complement the platform-wide perspective above.

Repository structure​

Audience: new contributors, evaluators, prospective module developers, future maintainers running an orientation pass.

The spatial map of the monorepo — what every workspace is, which layer it sits in, what consumes it, and what it consumes. Read this once before diving into any specific module or slice.

  • REPOSITORY-STRUCTURE.md — the spatial map. Five-layer mental model (apps → services → horizontal infrastructure packages → contracts packages → module SDK + vertical-flavored packages), workspace inventory tables, β-layout walkthrough for a single module, Mermaid dependency diagram, and the canonical-for-now docs publishing URL (docs.umbraculum.dev). Complements NAVIGATE-MONOREPO.md (Magento map + worked example), MODULES.md (ecosystem), and PLATFORM-ARCHITECTURE.md (architecture).

Vision & strategy​

Audience: technical decision-makers, platform evaluators, future module developers.

The high-level direction, business model, and license posture.

  • GLOSSARY.md — onboarding terminology — vertical, canonical, brewery (reference vertical), workspace web UI, and the doc convention for citing brewery.
  • PLATFORM-ARCHITECTURE.md — Platform vision, AI consultant, distribution model; §2.1 From practice, not theory (open backbone — practitioner rationale, cites Omnis case study).
  • ROADMAP.md — Living roadmap with 12–30 month trajectory.
  • LICENSING.md — Licensing rationale (AGPLv3 + MIT SDK, dual license, RFC change process).
  • TIER-PRICING-ANALYSIS.md — Base subscription tiers and pricing analysis (the current AI tier unlock and future managed-AI overlay are described in PLATFORM-ARCHITECTURE.md §7).
  • CORE-DEVELOPMENT-AND-COMMUNITY.md — How community proposals, collaborators, sponsors, and AI-compute support fit into core development without buying priority or governance rights; canonical channels at forum.umbraculum.dev (§4.6); bootstrap infra custody and entity-owned migration via backup + restore (§4.6.7); authentic representation in community discourse (§6.1 — no AI impersonation of members); donation rails and environmental accounting (Stripe Climate 1%, forest stewardship) in design/donation-channels.md §9.
  • design/ecosystem-case-study-omnis.md — Ecosystem lesson (Omnis). Good product; Core vs verticals governance, 2016 doc-site fragility (§3.4–§3.6); maps to community, open repos, and free-try commitments.
  • design/ecosystem-case-studies.md — Index for all practitioner ecosystem case studies (learnability, repositioning, no-cert policy).
  • design/ecosystem-case-study-business-central.md — Integration lesson (Business Central). Large partner ecosystem, opaque external API surface (OData vs REST vs custom API, version/wave maze, consultants who cannot advise integrators); maps to Umbraculum's contracts packages, module route docs, and alpha partial OpenAPI (API-OPENAPI.md).
  • design/ecosystem-case-study-sap.md — Learnability lesson (SAP ABAP). One language across verticals, but trials ≠ safe boat for repositioning; maps to free try, no certification program, expertise-over-badges (MANIFESTO.md §2.2).
  • design/ecosystem-case-study-teamsystem.md — Learnability lesson (TeamSystem). European ERP strength, partner-only experiment path; pairs with Omnis.
  • design/ecosystem-case-study-odoo.md — Learnability lesson (Odoo Community). Partial positive — Community Edition tryability; Umbraculum copies the ladder, not the cert/partner gate; §4.1 platform-shape vs Odoo (language, native, breadth).
  • design/ecosystem-case-study-adobe-magento.md — Stewardship lesson (Adobe → Magento). ece-tools deploy integration vs agency-owned CI (§3.5); Mage-OS fork; always-green public-repo CI (MANIFESTO.md §2.1).
  • design/ecosystem-case-study-drupal-wordpress.md — Stewardship positive (Drupal + WordPress). Modularity and community longevity; WordPress auth plugin hell → RFC-0001 Decision F; Drupal core-scale debate left open (§6).
  • design/ecosystem-case-study-custom-vertical-code.md — Code and empathy lesson (unnamed platforms). Agency delivery split; custom code as upgrade bottleneck; priesthood unmaintainability; client supplier-quality questions; Shopify contrast.
  • PUBLIC-ALPHA-ANNOUNCEMENT.md — Maintainer draft for the July 2026 public-alpha launch post (do not publish until flip).

Modules ecosystem​

Audience: anyone evaluating, contributing to, or building on top of the module set — the analog of drupal.org/project/project_module for Umbraculum.

  • BUILDING-YOUR-VERTICAL.md — foundational ISV path — "how do I build product X on Umbraculum?" and "how do I run without brewery?" (Magento sample-data parallel; today vs target).
  • MODULES.md — entry point for the module ecosystem. Vocabulary (package vs canonical module vs vertical configuration vs reserved canonical code vs module SDK), the catalog (canonical modules + vertical configurations + horizontal packages), the "I want to build a ___" decision tree, and a worked example. See also GLOSSARY.md for plain-language onboarding definitions.
  • modules/ — per-module pages linked from MODULES.md (one page per canonical module / vertical configuration as each ships; today: modules/canonical/automation.md, modules/canonical/pim.md, and the modules/verticals/brewery/ reference vertical docs).
  • modules/packages/README.md — package primer — horizontal infrastructure, canonical contracts, and vertical-flavored workspaces with links to each README.md.

AI consultant​

Audience: platform evaluators, hosted-service operators, module developers, end-users.

The workspace-scope AI consultant is the cornerstone the platform is organized around — every other structural choice (monorepo, one shell, canonical-module discipline, peer-module decomposition, vertical-configuration tier) is downstream of one principle: the consultant must see the workspace as one coherent thing. See PLATFORM-ARCHITECTURE.md §4.0 "AI-consultant context principle (cornerstone)" for the reasoning.

  • AI-CONSULTANT.md — Feature surface. What the consultant is, what it can do today (registered tools by module), what it cannot do yet, how modules contribute tools, BYOK + paid-tier unlock, per-workspace operational memory.
  • PLATFORM-ARCHITECTURE.md §4.0, §4.3, §6, §7 — Architecture depth: cornerstone principle, AI-platform sub-system, tools + prompt composition + memory + worked example, BYOK monetization model.
  • help/ — Operator-facing usage guides (see help/asking-umbraculum.md).

Stack & dependencies​

Audience: evaluators, future maintainers, partners — anyone who wants to know what the platform is built on and why each open-source choice was made.

  • OPEN-SOURCE-STACK.md — technology recap and per-dependency rationale. Exhaustive companion to MANIFESTO.md §1.4: for every load-bearing dependency (OS, runtime, data layer, backend, frontend web + native, validation, tests, lint, industrial automation, build, brewery-domain, docs/CI), answers three questions — role in the discipline-apparatus, why this over the proprietary alternative, what shrinks if swapped for closed source. Includes the single closed-source exception (Cursor itself) and the posture toward it.

Governance (RFCs)​

Audience: contributors, module developers, platform evaluators.

Public architectural and governance commitments. Process: LICENSING.md §10.

  • rfcs/README.md — RFC index entry point. One-line commit per RFC, the RFC anatomy (header → summary → motivation → decisions → alternatives → resolution), and the process for adding a new one.
  • rfcs/0001-modules-tiers-governance-and-automation-placement.md — Canonical-module rule, reserved codes (mrp, wms, crm, crp, automation), tier model, governance, consumption contract, automation placement (Accepted 2026-05-18).
  • rfcs/0002-canonical-module-physical-layout.md — Physical layout (β three-tree + per-module contracts package), naming conventions, module-sdk location, H1 2027 migration sequencing (Accepted 2026-05-19).
  • rfcs/0003-validation-library-adoption.md — Zod v4 as the internal validation library for contracts + Fastify routes; library-agnostic ValidatedSchema<T> interface in @umbraculum/module-sdk so third parties may use Zod, Valibot, TypeBox, or hand-rolled validators (Accepted 2026-05-19; F7 container-side bundle measurement closed 2026-06-02).
  • rfcs/0004-canonical-pim.md — Allocates pim as the 6th canonical-module reserved code (Akeneo / Pimcore class — products, variants, attribute sets, categories, media). Mini-RFC under RFC-0001 §6 Decision D (Accepted 2026-05-19).
  • rfcs/0005-docs-site.md — Documentation site generator (Docusaurus 3.10.x, v4-future-flagged) + canonical URL (docs.umbraculum.dev) + 9 publication / versioning / search / i18n / MDX-policy / CI commits. Scheduled for Week 2 of the late-H1-2026 tranche per ROADMAP.md (Accepted 2026-05-20).
  • rfcs/0006-amend-rfc-0002-brewery-file-move-acceleration.md — Narrow amendment to RFC-0002 Decision D: pulls the brewery file-move tranche forward from H1 2027 into Week 1 of the late-H1-2026 tranche (2026-05-20 → 2026-05-26), bundled with the web-route-shape audit. URLs preserved end-to-end (β semantics) (Accepted 2026-05-21).
  • rfcs/0007-canonical-document-rendering.md — Canonical document rendering pipeline and async job runner: @umbraculum/rendering, registerDocumentTemplate, Gotenberg / exceljs / fast-csv / bwip-js / xmlbuilder2 / eta / MJML, and BullMQ on existing Redis (Accepted 2026-05-21; implemented / closed 2026-05-25).
  • rfcs/0008-notifications-outbound-delivery.md — Notifications and outbound delivery boundary: email-ready rendering is composition only; provider transport, recipient policy, unsubscribe/compliance, audit logs, bounce/complaint handling, abuse/rate limits, and delivery billing are horizontal platform concerns (Accepted 2026-05-25).
  • rfcs/0009-workspace-billing-addons-and-entitlements.md — Workspace billing add-ons: modules declare addonCodes; platform owns WorkspaceBillingAddon persistence and Stripe/RevenueCat (contract Accepted 2026-05-28; implementation H1 2027). Companion: design/canonical-workspace-billing-addons-surface.md.
  • rfcs/0010-platform-brewery-postgres-schema-split.md — Closes RFC-0002 §11.4 deferral: horizontal models in platform.*, brewery domain tables in brewery.*; forward migration only; registerModule({ code: "brewery", prismaSchema: "brewery" }) required. Companion runbook: design/platform-brewery-postgres-schema-split.md (Accepted 2026-05-28).

Design (pre-RFC / follow-on)​

Audience: core team, module authors implementing RFC decisions; also practitioner case studies that inform governance.

  • design/production-hosts.md — Production VPS repos (umbraculum-hosting-common, -forum, -demo), live hosts table (forum, demo, support, docs), local clone layout, volunteer routing; forum governance stays in design/community-forum-runbook.md §6–§7.
  • design/ecosystem-case-studies.md — Index for practitioner ecosystem case studies (failure-mode map, learnability, no-cert policy).
  • design/ecosystem-case-study-omnis.md — Practitioner case study (Omnis Studio). Good product, ecosystem never formed; Core/vertical dynamics and long-run migration fear (§3.4–§3.6); rewrite caution (§6).
  • design/ecosystem-case-study-business-central.md — Practitioner case study (Dynamics 365 Business Central). Strong ERP and partner channel, painful external integration discovery (OData vs REST API v2.0, release waves, docs by topic not by job); senior consultants often cannot advise API consumers; maps to Umbraculum contracts packages, public route tables, version handshake, and alpha partial OpenAPI (API-OPENAPI.md §4). Rewrite caution (§6).
  • design/ecosystem-case-study-sap.md — Practitioner case study (SAP ABAP). Repositioning in hard times; trials exist but are not a Magento-shaped safe boat; no Umbraculum certification counter-commitment. Rewrite caution (§6).
  • design/ecosystem-case-study-teamsystem.md — Practitioner case study (TeamSystem). Partner-only experiment path; expertise trapped inside integrator channel. Rewrite caution (§6).
  • design/ecosystem-case-study-odoo.md — Practitioner case study (Odoo Community). Partial positive on learnability; §4.1 Umbraculum vs Odoo platform-shape comparison; deliberate skip of certification economy. Rewrite caution (§5).
  • design/ecosystem-case-study-adobe-magento.md — Practitioner case study (Adobe → Magento). ece-tools deploy integration failure, agency bypass cost, untrue support (§3.5); Mage-OS fork. Rewrite caution (§7).
  • design/ecosystem-case-study-drupal-wordpress.md — Practitioner case study (Drupal + WordPress). Stewardship positives; WordPress horizontal hell; Drupal core/junior culture debate unsettled. Rewrite caution (§7).
  • design/ecosystem-case-study-custom-vertical-code.md — Practitioner case study (unnamed platforms). Delivery vs craft; custom code ~90% of upgrade pain; Shopify contrast; SOLID/SRP as code-shape mechanism (§4.4, yeastEditor example). Rewrite caution (§7).
  • design/application-surfaces-vs-platform-backbone.md — Terminology + layering (2026-05-28). What "backend" means in this repo; four product layers (platform backbone, modules, workspace web UI, optional audience-specific apps); Drupal-style admin/storefront vs ERP-style workspace web UI; @umbraculum/module-sdk as the backbone SDK vs the reserved/unused @umbraculum/core npm name.
  • design/ubuntu-touch-shell-strategy.md — Ubuntu Touch delivery (2026-05-31). Decision-of-record: Lomiri Click Morph webapp wrapper reuses apps/web + Tamagui (no Qt rewrite); OpenStore presence; online-first on UT; native offline guarantees remain iOS/Android-only. Reference: packaging/ubuntu-touch/umbraculum-reference/.
  • design/canonical-workspace-billing-addons-surface.md — Workspace billing add-ons boundary (RFC-0009). addonCodes registry, tier_only vs tier_and_addons enforcement, H1 2027 implementation backlog; no WorkspaceBillingAddon table in public α.
  • design/canonical-automation-module-surface.md — Canonical automation module surface (RFC-0001 Decision E §7.2): adapter SDK, Vessel vs EquipmentProfile, OpenPLC seam, AI tools, tier limits (Accepted design 2026-05-19; implementation phased per doc §9).
  • design/web-route-group-audit.md — Decision-of-record for the web route-shape audit (Accepted 2026-05-21). Ratifies the two β disciplines (no (<code>)/page.tsx, no (<code>)/[<dynamic>]/page.tsx at the route-group root), the URL-segment registry surface in @umbraculum/module-sdk (registerWebModule({ ownedUrlSegments, navEntry }) + CI gate scripts/check-web-url-segments.ts), and the per-module URL corrections (/en/automation → /en/vessels, /en/pim/* → /en/products / /en/categories / /en/attribute-sets, brewery URLs preserved). Pairs with RFC-0006 (governance amendment to RFC-0002 D) and the Cursor plugin rule 46-web-route-shape.mdc in umbraculum-platform-tsjs-cursor-assistant v0.5.0.
  • design/openplc-mailbox-emitter-pr-shape.md — sister-repo PR shape for the mailbox-artifact emitter (Phase A step 4 hand-off; pairs with packages/canonical/automation/contracts/).

Product​

Audience: product readers, evaluators, hosted-service operators.

User-facing product surfaces and operational concerns at the product level.

  • ROLLOUT.md — Rollout plan and staged-launch notes.
  • WEBSITE.md — Public web surfaces: brochure (umbraculum.dev) vs docs (docs.umbraculum.dev), Cloudflare Pages deploy, flip-day coordination.
  • SEO.md — SEO posture for the marketing/public surfaces.
  • AGENTIC-JOBS.md — Agentic / scheduled-job notes.

Architecture — platform-wide​

Audience: contributors, self-hosting operators, module developers.

Cross-cutting architectural decisions that apply to every module.

Architecture — auth & security​

Audience: contributors, self-hosting operators, module developers.

Architecture — data & infrastructure​

Audience: contributors, self-hosting operators, module developers.

Architecture — billing​

Audience: contributors, hosted-service operators.

Domain — brewery vertical​

Audience: brewery-vertical contributors and operators. These docs live under the brewery vertical module area so Docusaurus and GitHub both present them as vertical-specific material, not platform-core architecture.

Brewery-specific modeling, data formats, and analytical models.

Engineering — development​

Audience: contributors only.

Day-to-day engineering conventions and runbooks.

  • ACADEMIC-AND-EXPERIMENTATION.md — Students and university labs. Free self-host experimentation, capstone-friendly project shapes, alpha expectations, fit filter vs production ERP.
  • GETTING-STARTED.md — First-time contributor tutorial. Linear walkthrough from "Ubuntu laptop, nothing installed" to "first commit landing with the apparatus running". Targets the MANIFESTO.md §1.4 gap directly. Read this if you have never opened the repo before.
  • FOUNDATION-HARDENING.md — Synthesis layer for the four-slice foundation-hardening pass (lint + types + tests + docs) plus the orthogonal validation axis. Single entry point for the bird's-eye narrative; per-slice docs below remain the sources of truth. Includes the plugin-pack handoff manifest (slice → rule/skill/subagent mapping).
  • CODING-STANDARDS.md — Coding standards (TypeScript, conventions, file layout).
  • CI-PARITY.md — Pre-push static-analysis gate (npx @umbraculum/ci-parity); manifest at .umbraculum/ci-parity.json; four local-vs-CI divergence mechanisms.
  • design/ci-parity-npm-trusted-publishing.md — npm OIDC trusted publishing for @umbraculum/ci-parity (replaces 90-day NPM_TOKEN rotation).
  • LINTING.md — ESLint setup, scope tiers (HIGH-light → HIGH-staged → HIGH-full), value/cost analysis, and how to extend the strict gate.
  • TYPING.md — TypeScript strict-flag rollout, per-workspace tsc --noEmit baseline + canonical measurement methodology, the 6 candidate stricter flags + their rollout state, and the per-workspace CI typecheck gate.
  • TAMAGUI.md — Tamagui type-system caveats, our adaptation strategy, and what to watch upstream.
  • CONTRACTS-VALIDATION-STRATEGY.md — Why packages/platform/contracts uses hand-rolled validators today, candidate libraries (Zod, Valibot, TypeBox), trigger criteria for revisiting, and migration mechanics if we go.
  • TESTING.md — Test layers, frameworks, conventions; see also the plugin-shipped 20-tests-must-follow-changes.mdc rule.
  • DOCS-README-STANDARDS.md — Module-level README standard (template + audit checklist) and the structural CI gate (scripts/docs/check-readmes.py + .github/workflows/docs-readmes.yml).
  • DEVELOPMENT-ACCESSIBILITY.md — Accessibility constraints (hard requirements).
  • DEVELOPMENT-NATIVE-LOCAL.md — Local development for the native app.
  • I18N-AUDIT.md — Internationalization audit and guardrails.
  • CORE-DEVELOPMENT-AND-COMMUNITY.md — Community proposal mechanism, sponsorship principles (including the AI-compute capacity ask), canonical channels at forum.umbraculum.dev (§4.6), donation rails design/donation-channels.md.

Help & guides (operator-facing)​

Audience: workspace members and admins using the app's UI to perform operational work, regardless of whether their workspace is on free, paid, or self-hosted infrastructure.

  • help/ — End-user / operator help documentation. Currently empty placeholder; content lands here as the brewery vertical UI matures and as additional vertical configurations land.

Integrations​

Audience: integration developers, hardware vendors, module developers.

Per-integration design notes.

Reference​

Audience: contributors, archaeology readers.

  • calculators/ — Calculator references and source materials (e.g. BrunWater spreadsheet, mash-pH paper).
  • archive/ — Superseded architecture revisions (Rev00, Rev01) and the canonical architecture-revision PDF (archive/architecture-Rev02.pdf). Kept for historical reference; not load-bearing for current decisions.

Contributing to the documentation​

  • Documentation lives in this folder (docs/); top-level files (DEVELOPMENT.md, DEVELOPMENT-LOCAL.md, repository README.md) cover repo-level mechanics and link back here for everything platform-level.
  • When adding a new document, also add a link to it from this index in the appropriate category. Each category is intended to stay small enough to scan.
  • URL moves and removals (non-negotiable). When a published doc moves or is removed from the docs site (docs.umbraculum.dev), the same PR must include either a permanent redirect to the replacement URL or a deliberate stub page that explains why the content no longer exists and where readers should go instead. Silent 404s — bookmarks, forum posts, and colleague links that die without explanation — are not acceptable. In-repo relative links must be updated in the same change; site-level redirects cover external bookmarks to old URLs. Lesson from design/ecosystem-case-study-omnis.md §3.5.
  • New documents should follow the existing tone: precise about decisions, honest about trade-offs, and explicit about what is not settled.
  • For any document that may be surfaced publicly in the future (Vision & strategy, License, parts of Architecture), assume the audience is technically literate but not specialist, and define terms on first use.
  • Substantive licensing or governance changes follow the RFC process described in LICENSING.md §10.

Audience for this set​

This documentation is written with three audiences in mind, in approximately this priority order:

  1. Future maintainers and contributors — the people who will keep this project alive across decades. The docs are the durable artifact; the chat history is not.
  2. Self-hosting operators and platform evaluators — technical decision-makers assessing Umbraculum as a long-term dependency.
  3. Prospective module developers — partners building verticals or integrations on top of the platform.

If a document does not serve at least one of these audiences clearly, it should be revised or moved out of the docs tree.