DOCSEARCHbyAlgolia
Submit Docs

Umbraculum Documentation

website·Indexed 31 days ago

https://docs.umbraculum.dev

Technical documentation for the Umbraculum project, covering its monorepo structure, module SDK, and foundation hardening strategy. Includes guides on native development, multi-tenant billing with Stripe and RevenueCat, testing hierarchies (T0-T2), and the canonical module ecosystem. Features detailed RFCs, architectural decisions for vertical configurations like brewery modules, and developer onboarding for Ubuntu environments.

Tokens
311.3K
Snippets
983
Records
2.2K
Agent score
50%

What's inside Umbraculum

  1. Overview of the AI Reporting DSL

    The reporting DSL enables AI models to answer bounded analytics questions by emitting a typed query AST. This AST is validated by the server and executed against curated, read-only Postgres views. To ensure security and performance, the following invariants are enforced:

    • No raw SQL: Only Zod-validated ASTs are converted to parameterized SQL.
    • Row Limits: Maximum limit of 100 rows; queries exceeding this are rejected.
    • Mandatory Date Range: Every query must include dateFrom and dateTo.
    • Workspace Isolation: Every view includes workspace_id, and the executor binds the current $workspaceId.
    • Timeouts: A 5-second statement timeout is applied to the executor connection.
    • PII Protection: Views exclude sensitive data (email/phone) unless explicitly allowlisted.

  2. Overview of @umbraculum/native-shell

    @umbraculum/native-shell is a platform-classified native shell layer used by Expo app workspaces (such as @umbraculum/native-brewery). It centralizes cross-app bootstrap logic, secure-token authentication wiring, locale persistence, shared color tokens, and basic React Native/Tamagui UI shims. Navigation stacks and vertical screens are excluded from this package and remain within the specific app workspaces under apps/native/<app-code>/.

  3. Overview of the automation canonical module

    The automation module is a workspace-scoped runtime control surface for physical equipment. It is a Tier 1 core canonical module licensed under AGPLv3.

    Key Responsibilities:

    • Maintains a typed inventory of vessels (e.g., fermenters, kettles, HLT) identified by workspace-unique codes.
    • Defines the adapter SDK contract for all hardware connectors.
    • Manages the Modbus mailbox mirror used by adapters (e.g., the brewery.openplc.v1 adapter).
    • Provides AI tools for workspace AI consultants to read vessel state.
    • Implements tier-limits to gate the number of vessels and connected adapters per workspace.

    Scope Boundary: This module does NOT handle scheduling, capacity planning, or 'next planned use' views; those are managed by the crp canonical module.

  4. Overview of the Foundation Hardening Slices

    The foundation hardening strategy consists of five specialized slices that ensure the codebase remains stable and self-enforcing. Each slice is managed via a canonical document, a CI gate for detection, and a plugin-pack for prevention.

  5. Overview of the WMS canonical module

    The WMS (Warehouse Management System) canonical module is a Tier 1 core module designed to manage physical stock, locations, and provenance. It is currently in the 'Open door' status (not yet implemented) and is scheduled for the H2 2027 tranche. It is licensed under AGPLv3. The module is responsible for:

    • Locations hierarchy (warehouses, bays, bins).
    • Stock-on-hand tracking by SKU, location, and lot/serial.
    • Receipt, issue, and transfer movements with audit trails.
    • Lot and serial tracking for traceability and compliance.

  6. Overview of @umbraculum/brewery-core

    @umbraculum/brewery-core is a leaf package containing pure JavaScript brewing calculations. It is used by the brewery vertical's web app, native app, API importers, and the @umbraculum/brewery-beerjson package. It contains no React components, no I/O, and no BeerJSON schema types, making it safe for use in services and tests.

  7. Overview of the CRP (Capacity Requirements Planning) module

    The crp module is the canonical capacity-planning kernel responsible for managing resources, work centers, calendars, scheduled operations, capacity load, and conflict detection. It consumes production operations from the mrp module and resource/vessel references from the automation and brewery modules. It does not own the production-order lifecycle or live controller state.

  8. Overview of @umbraculum/brewery-media-assets

    The @umbraculum/brewery-media-assets package provides shared PNG assets (such as yeast help images located in assets/yeast/) and a generated manifest with hashed public paths located under /media/**. It is consumed by apps/web (via sync-media) and apps/native (via RemoteImage and brewery screens).

  9. Overview of @umbraculum/ui platform primitives

    The @umbraculum/ui package provides a platform-neutral UI primitives layer used by both apps/web (Next.js) and apps/native (React Native + Expo). It contains Tamagui-based primitives and generic compound components. It is intentionally domain-free; any domain-specific UI (such as recipe editors or water pages) is located in @umbraculum/brewery-recipes-ui.

  10. Overview of Umbraculum Vertical Configurations

    A vertical configuration is a Tier 6 (permissionless) industry-specific layer (e.g., distillery, cosmetics, fragrance) that targets a specific industry. It consumes canonical modules (like automation, mrp, wms, crp, or crm) and adds industry-specific data, prompts, and UI flows. Verticals must not reimplement canonical-domain semantics or platform horizontal services.

    Unlike canonical modules, verticals are typically shipped in the developer's own repository and deployment, pinned to @umbraculum/module-sdk, rather than as a PR to the core umbraculum-dev monorepo.

  11. Overview of the Umbraculum Brewery Native App

    The brewery native application is a mobile tool (iOS and Android) designed for brew-day reliability. It is built using React Native 0.81, Expo 54, and Tamagui. It shares UI components with the web application via @umbraculum/ui (primitives) and @umbraculum/brewery-recipes-ui (domain UI).

    Key technical implementations include:

    • Authentication: Bearer tokens stored in expo-secure-store and refreshed via @umbraculum/api-client against services/api.
    • Localization: Handled by @umbraculum/i18n-react using @umbraculum/i18n.
    • Data Visualization: Uses victory-native and react-native-svg for charts.
    • Scope: Currently focuses exclusively on brewery brew-day flows; other modules (MRP, CRP, PIM, automation) are web-only.

  12. Overview of the Canonical PIM Module Surface

    The pim module serves as the sixth canonical module of the platform. Its primary purpose is to maintain master product data and an enterprise-grade attribute modeling framework to prevent data duplication and attribute drift across different platform consumers (e.g., brewery recipes, commerce channels, MRP/WMS planning). It owns the master product identity, the attribute-set framework, and the reference-by-id contract, ensuring that storefront projections remain read-only consumers of the master data.