v1.0.0@ottili/foundation-framework · Source of Truth 57 chapters

One frontend runtime for every Ottili product.

Ottili Foundation is the shared product runtime behind Ottili ONE. Shell, design tokens, session and company context, navigation, search, Workbench, dashboards, deep white label, shared AI/Files/Flows surfaces, an extension host and desktop adapters — implemented once, consumed by HQ, LD3, Coder, AI Platform, Cloud, Console and Auth.

Test it live What it can do Impact on Ottili ONE

Press ⌘K for the palettePress ⌘` for the WorkbenchLive sandbox: foundation.test.ottili.one

packages

41 954

lines of runtime source

UI components

Unified API routes

design tokens

test suites

Positioning

A product runtime, not a template

The distinction matters because it decides who owns bugs. A template is copied and diverges immediately. A runtime is versioned, pinned and fixed in one place.

What it is not

a theme
a UI kit
a dashboard template to copy
a second backend
a remote-loaded live shell
product domain logic

What it is

a product runtime
a design token system
a session and tenant context
a manifest-driven navigation engine
a shared capability surface
an extension host

There is no centrally loaded live shell. A Foundation change identifies the affected products, runs their builds and tests, ships as a canary and then rolls out — so one bad release cannot take down every product at once.

Capabilities

What the runtime actually does

Nine areas the framework owns end to end. Everything below is implemented in the @ottili/foundation-framework package family, not planned.

Product shell

§15

Topbar, sidebar, inspector, mobile nav — once.

Every Ottili product gets the same frame: a 56px topbar, a 248px sidebar that collapses to 72px, a 360px inspector and a real mobile navigation. Products fill the content area; they never rebuild the chrome.

Company switcher, product switcher, account switcher
Breadcrumbs, favorites, recents, quick create
Collapsible sidebar with per-company customization
Inspector panel contract shared across products

@ottili/foundation-shell@ottili/foundation-navigation

Design system

§14, §47

Primitive → semantic → component tokens. No raw hex in product code.

A three-layer token system with light, dark and high-contrast themes, three densities and a clamped UI scale. Product code consumes semantic tokens only, which is exactly what makes deep white label possible without a fork.

Light / dark / system themes plus a high-contrast mode
Comfortable, compact and spacious density
Per-product accent with automatic text-contrast resolution
Reduced motion honoured globally, not per component

@ottili/foundation-ui

Auth & company context

§11, §12

Company scope comes from the verified token. Never from the URL.

SSO against auth.ottili.one with PKCE, a session state machine, silent refresh, a session-expired view, multi-tab coordination and account switching. Company-scoped URLs are validated server-side — the path is a hint, not an authority.

PKCE redirect + callback, refresh and expiry handling
Company-scoped routes under /c/{companySlug}/…
Context revision invalidates caches on switch
Cross-tab session and company coordination

@ottili/foundation-auth@ottili/foundation-context

Search, palette & Workbench

§20, §21, §45

Cmd+K to find. Cmd+` to act.

A global search with pluggable providers, a command palette, and the Ottili Workbench — a Stripe-style command surface for real, authorized customer actions with dry-run, preflight, step-up and approval before anything executes.

Typed command contract with risk level and approval policy
parse → resolve → validate → permission → preflight → dry run → execute → audit
Panels for API Explorer, Events, Logs, Runs, Approvals, Jobs
Never raw SQL, never a hidden superadmin shell

@ottili/foundation-command

Shared capabilities

§25

AI, Files, Flows, Approvals, Activity and Jobs are platform surfaces.

Products do not each build their own chat, file browser or workflow canvas. They configure the shared surface with profiles, roots, node packs and renderers, and inherit streaming, approvals, versioning and audit for free.

Ottili AI: streaming, tool-call UI, citations, editable proposed actions
Ottili Files: browser, versions, sharing, pickers, entity links
Ottili Flows: canvas, node palette, dry run, run history
Approvals, Activity/Audit and a background Task Center

@ottili/foundation-capabilities

Deep white label

§18, §48

Draft, preview, publish, roll back — versioned server-side.

Customization is an inheritance chain with a draft lifecycle, not a CSS override file. Every published version is stored, diffable and revertible, and validation runs identically in the browser and in the Unified API.

Inherited platform → product → company layers
Draft / preview / publish / rollback / history
Export and import a customization set
Mirrored validation so client and server never disagree

@ottili/foundation-customization

Dashboards & widgets

§22

A grid engine plus a widget runtime, per company.

A responsive dashboard grid with a widget runtime, saved views and an importer for legacy dashboard layouts, so the migration from the old dashboard does not throw away customer configuration.

Company-scoped dashboard persistence
Widget contribution from products and extensions
Saved views and page layout customization
Legacy layout importer

@ottili/foundation-dashboard

Extension host

§27, §34

HQ Apps, product add-ons and integrations — one runtime.

A signed, versioned manifest declares routes, navigation, widgets, commands, AI tools, flow nodes and settings. Third-party UI runs in a sandboxed iframe behind a scoped RPC bridge; third-party backend code never runs in the Unified API process.

Manifest validation, compatibility ranges and lifecycle
Sandboxed host, versioned bridge, CSP, origin allowlist
Console-driven installation, company-scoped activation
Stable @ottili/extension-sdk — no private internals exposed

@ottili/foundation-extensions@ottili/extension-sdk

Web, PWA, Tauri, Electron

§29

One adapter contract, four distribution targets.

Storage, secure storage, notifications, deep links, clipboard, filesystem, updater, windows, background tasks, auth transport and telemetry sit behind a single adapter interface, so a product becomes a desktop app without a second codebase.

Web is the full baseline — no native filesystem assumptions
PWA installability, safe offline cache, update prompt
Tauri is the preferred native wrapper
Electron supported through the same contract

@ottili/foundation-platform

Read the capability detail

Shell · SoT §15

Every product wears the same frame

Fixed metrics, fixed regions, fixed behaviour. Products own the content area and nothing else about the chrome. Hover a region to read what it carries.

hq.ottili.one/c/ottili/dashboard

Topbar56px
Product mark, company switcher, global search, quick create, notifications, help, account menu.
Sidebar248px → 72px
Manifest-driven navigation groups, favorites, recents, per-company customization and a collapsed rail.
Content24px padding
Product-owned. Breadcrumbs, page header, saved views and the product's own routes.
Inspector360px
Shared right-hand panel: record details, AI side panel, activity, approvals and extension inspector tabs.
Workbench320px
Bottom command surface toggled with Cmd+`. Shell, API Explorer, Events, Logs, Runs, Approvals, Jobs.

Design system · SoT §14

This page is rendered by the framework's own token layer

The stylesheet below is a verbatim copy of packages/foundation/ui/src/tokens/tokens.css, with 85 semantic tokens. Change the theme, the density, the contrast or the product accent and watch the entire site follow — exactly how a white-labelled Ottili product re-themes at runtime.

Theme (§14.3, §14.4)

Density (§14.11)

Accessibility (§14.17)

Product accent (§14.5)

data-theme="light"
data-density="comfortable"
data-contrast="normal"
--ott-color-accent: #7c3aed
--ott-color-accent-contrast: #ffffff (5.70:1 AA)

AccentSuccessWarningDanger

Button and field height, topbar height, table row height and content padding all move with the density attribute — not with a second stylesheet.

--ott-color-bg-canvas

--ott-color-bg-surface

--ott-color-bg-elevated

--ott-color-bg-muted

--ott-color-border-subtle

--ott-color-border-default

--ott-color-border-strong

--ott-color-accent

--ott-color-accent-hover

--ott-color-success

--ott-color-warning

--ott-color-danger

--ott-color-info

Workbench · SoT §21

Cmd+K to find. Cmd+` to act.

The Workbench is a command surface for real, authorized customer actions — not a hidden superadmin shell. Every command carries a risk level, an argument schema, required permissions and an approval policy, and a destructive command must pass preflight and dry run before it executes.

ottili>

⌘ ` toggles the Workbenchparse → resolve → validate → permission → preflight → dry run → execute → audit

Typed commands

commandId, namespace, verb, aliases, argument and option schema, permissions, entitlements, risk, dry-run support, approval policy and a result renderer.

Approval before effect

Medium and high risk commands surface the resolved command, the arguments, the company, the side effects and the dry-run result before anything is executed — including when the AI proposed the command.

Hard boundaries

No raw SQL, no free-form Unified API URLs, no internal endpoints, no superadmin namespace, no secrets and no unrestricted shell.

Package family

24 packages, one dependency direction

The umbrella package is a convenience, not a monolith. Contracts depend on nothing, core depends on contracts, everything else layers upward — and circular dependencies are a build failure, not a code review comment.

Contracts

@ottili/foundation-contracts2 215 loc @ottili/product-contracts317 loc

Core logic

@ottili/foundation-core6 177 loc

Design system

@ottili/foundation-ui10 555 loc

Shell

@ottili/foundation-shell1 276 loc

Runtime

@ottili/foundation-auth837 loc @ottili/foundation-context671 loc @ottili/foundation-runtime507 loc @ottili/unified-api-client310 loc

Feature runtimes

@ottili/foundation-capabilities6 912 loc @ottili/foundation-command2 307 loc @ottili/foundation-customization1 632 loc @ottili/foundation-dashboard1 835 loc @ottili/foundation-extensions2 325 loc @ottili/foundation-integrations43 loc @ottili/foundation-navigation224 loc @ottili/foundation-notifications1 349 loc @ottili/foundation-settings93 loc

Distribution

@ottili/foundation-platform1 183 loc

Platform services

@ottili/foundation-observability66 loc

Extension SDK

@ottili/extension-sdk929 loc

Umbrella

@ottili/foundation-framework31 loc

Quality gates

@ottili/foundation-architecture7 loc @ottili/foundation-testing153 loc

Inspect every package

Impact

What changes inside Ottili ONE

Foundation is not an isolated frontend concern. It changed the Unified API surface, the tenant model, the branding pipeline, the extension story and the desktop strategy.

Frontend architecture

Before · Every app carried its own shell, its own theme handling and its own session plumbing. Fixing a session bug meant fixing it n times.

Now · One runtime, pinned per product. A shell or session fix ships once and rolls out through controlled rebuilds.

packages/foundation/*

Unified API

Before · A narrower /api/v1/ui/* runtime served the old dashboard and nothing else.

Now · A dedicated /api/v1/foundation/* surface serves bootstrap, manifests, navigation, widgets, commands, customization, dashboards, favorites, recents and actions for every consumer.

services/unified_api/foundation/

Tenant isolation

Before · Company scope was sometimes inferred from the first membership or the URL.

Now · Company scope is derived from the verified token, validated server-side, and every Foundation table is keyed by company_id.

docs/TENANT_ISOLATION_AND_COMPANY_CONTEXT.md

apps on Foundation today

foundation-lab, ottili-hq-dashboard, ottili-one-console

/api/v1/foundation routes

bootstrap, manifests, customization, actions

company-scoped tables

every one keyed by company_id

24 397

lines of test code

across 95 suites in the package family

See the full impact analysis

Try it

The framework runs live at the Foundation Lab.

The Lab is the reference consumer: the full shell, the component catalog, the white-label lifecycle, the policy states and the shared capability surfaces — plus a scenario inspector that lets you flip role, theme, backend health, data state and session state without touching a database.

https://foundation.test.ottili.one

Open the Foundation Lab What to look at first

Questions

The honest answers

Is this a remote shell that can break every product at once?

No. There is no centrally loaded live shell. Products pin a Foundation version and are rebuilt on purpose: a Foundation change identifies the affected products, runs their builds and tests, goes out as a canary and then rolls out in a controlled way.

Does every product now look identical?

No. The target is five products with the same platform rules and their own identity. HQ may feel like a modern ERP, LD3 like a publishing surface, Coder chat-first, AI Platform playground-shaped and Cloud table- and inspector-heavy. Foundation owns the rules, not the layout of every page.

Where does authorization actually happen?

On the server. Foundation resolves permission, entitlement and rollout into one feature state so the UI can render hidden, locked, upgrade-required or degraded consistently — but frontend permissions are never authoritative.

Can third parties run code inside Ottili ONE?

Third-party UI runs in a sandboxed iframe behind a scoped, versioned RPC bridge with CSP and an origin allowlist. Third-party backend code never runs inside the Unified API process.

What happens to the old dashboard?

It is kept as a regression corpus while its features are migrated. Its layouts can be imported by the dashboard engine so customer configuration is not thrown away.

Is the Foundation Lab a demo or a test surface?

Both, deliberately. It is the reference consumer used to prove the framework, and it carries a conformance matrix mapping each Source-of-Truth chapter to the screen that proves it.