Prismatica Docs

Prismatica is the marketing-and-auth front door for Track Binocle, the Docker-first monorepo behind osionos — a Notion-style block editor that grew into a full collaborative workspace.

This documentation site is not built with a third-party static generator. Every page you are reading is authored in .xmd — an extended markdown dialect — and rendered by the project's own markengine, the exact parser that powers the live editor. Write a .xmd file in vault/, rebuild, and the shell you see updates.

What lives here

• Guides — get the stack running and understand how the three planes fit together.

• Reference — the markengine itself, and a full style showcase that exercises every block and inline type the engine understands.

The shell

Navigation is keyboard-first. The sidebar is a live listing of vault/, the breadcrumb is a shell pwd, and the whole thing is one self-contained page — so switching docs is instant, with zero network round-trips.

• Press ⌘K (or Ctrl K) to open the command palette.

• Press / to focus search.

• Use j / k (or the arrows) to move between docs.

Everything below is real, running documentation — start with Getting Started.

Getting Started

The entire development environment runs in containers. Never install dependencies on the host — the toolchain is Docker-only by design.

One command

make all is self-provisioning. From a clean clone it syncs submodules, pulls secrets, regenerates TLS certs, starts the grobase backend, restores demo data if the databases are empty, and builds the frontends with health validation.

# On a machine that holds the vault key, this reconstitutes everything:
make all

# Start the backend by hand only for a non-default edition:
make -C apps/grobase up EDITION=full

The front doors

Once the stack is healthy, these are the surfaces you can open:

Health checks

make healthcheck            # curls every front door + the BaaS /health
docker compose ps           # service status
docker compose logs -f osionos-app

Editing these docs

1. Add or edit a .xmd file under apps/opposite-osiris/vault/.

2. Rebuild the doc shell.

3. Reload — the sidebar and content reflect your change.

• Clone the repo
• Run make all
• Open :4322 and sign in
• Read the Architecture guide

Next: how the three language planes fit together → Architecture.

Architecture

Track Binocle follows a three-language plane pattern. Each plane owns a concern and speaks a language chosen for it.

The three planes

Shadow → parity → cutover

Major changes never flip a switch. New code runs in parallel with the old, validation precedes any cutover, and deletion is always last.

1. Shadow — the new path runs alongside the old, serving no real traffic yet.

2. Parity — identical requests return identical results through both paths.

3. Cutover — only once parity holds and CI is green does the new path take over.

Topology at a glance

The root compose stack is frontends-only. It joins a standalone backend — grobase — over an external Docker network, reaching it by container-name DNS.

 Browser
   │  HTTPS
   ▼
 local-https-proxy ──► opposite-osiris (Astro)     :4322
                   ├─► osionos          (React)    :3001
                   ├─► auth-gateway     (Go)        :8787
                   └─► osionos-bridge   (TS)        :4000
                            │
                            ▼  container DNS
                     grobase BaaS  (Kong :8000)
                     ├─ postgrest · gotrue · redis
                     └─ realtime  (Rust gateway)

Why a bridge?

osionos never talks to the BaaS directly. A Node bridge holds the service-role key and proxies data requests — the trust boundary lives in one place, not scattered across the client.

Read the engine that renders this page next → The markengine.

The markengine

The markengine is a standalone markdown library that lives inside the osionos app. It is framework-agnostic at its core: the parser, the AST, and the HTML and terminal renderers have zero external dependencies. Only the React renderer needs React.

The pipeline

import { parse, renderHtml } from "@/shared/lib/markengine/markdown";

const ast  = parse("# Hello\n\nSome **bold** text.");
const html = renderHtml(ast);

Three phases, no coupling between them:

1. Parser — a markdown string becomes an AST (BlockNode[]).

2. Renderers — the AST becomes an HTML string, React elements, or ANSI.

3. Shortcuts — block detection for the Notion-style block editor.

What .xmd adds

.xmd is not a new format — it is plain markengine markdown with a name that signals "render me with the real engine, not a generic parser." Two extras matter for documentation:

• Raw HTML blocks pass through. A bare <figure>, <iframe>, or now a <video> / <audio> / <img> / <picture> line renders as-is.

• Rich inline styles — highlight, underline, text/background colour, callouts, toggles, footnotes, and math — go beyond CommonMark.

The AST is the contract

Every renderer consumes the same BlockNode / InlineNode union. Add a block to the AST and every renderer must learn it — which keeps HTML, React, and terminal output in lockstep.

See all of it exercised at once → Style Showcase.

Style Showcase

This page deliberately uses every block and inline construct the markengine supports, and combines them, so the shell's styling is proven against the real engine output.

Headings

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

Inline text styles

Plain text, then bold, italic, and bold italic together. GFM strikethrough still works. In this engine __double underscores__ mean underline, not bold — a deliberate divergence from CommonMark. You can also use the tag forms: bold, italic, underline, strike, and a marked highlight. The ==equals== form also highlights.

Inline code sits mid-sentence, and the rich form keeps nested styles. Colour is available too: terracotta text and a warm highlight background. Styles nest — bold with coloured italics inside.

A hard line break comes from two trailing spaces: …and this sentence sits on the next line.

Emoji shortcodes render inline: ⚠️ ✅ 😄 👋

Links, footnotes, mentions

A regular link, a titled link, and a claim that needs a source.^[src] Internal page mentions look like getting-started — with no resolver they fall back to the raw id, which is itself a useful edge case to see.

Blockquote

A blockquote holds formatted text and can span multiple lines. It is the base of the callout and toggle constructs below.

Callouts

Callouts are > [!kind] title blocks. The engine passes the kind straight through as a class, so the shell can theme any of them:

Toggles

Hidden content lives here. It can hold formatting, code, and even lists:

• first hidden point

• second hidden point

Lists

Unordered, with nesting and mixed markers:

• First level

  • Second level (indented)

    1. Ordered inside unordered

    2. Second ordered item

• Back to first level with inline code

Ordered, starting mid-sequence:

3. Third

4. Fourth

5. Fifth

Task list:

• A completed task
• An open task with a link
• Another done item ✅

Table

Columns show left / centre / right alignment:

Code block

export function renderDocs(source: string): string {
  const ast = parse(source);          // markdown → BlockNode[]
  return renderHtml(ast, {            // BlockNode[] → HTML
    classPrefix: "md",
    externalLinks: true,
  });
}

Math

Inline math like E = mc^2 sits in a sentence. Block math stands alone:

Raw HTML and media

The engine now passes media tags straight through. Here an inline <svg> renders self-contained — no external asset:

Bare <video> and <audio> tags also survive parsing (they render empty players here because no asset is attached — real assets arrive with the screenshots):

Thematic break

Content above the rule.

Content below the rule.

Definition lists — a documented gap

The AST has a definition_list node, but there is no markdown syntax that produces it — it can only be constructed programmatically. So a term: def written here is just a paragraph. This is exactly the kind of edge case this page exists to surface. 💡

A Visual Tour

These are screenshots of the actual running application, not mockups. Each one is a real surface you reach after signing in through Prismatica.

The workspace

osionos opens as a VSCode-style shell: a page explorer on the left, channels and agents below it, and a tabbed, splittable editor grid in the centre. Everything — a note, a database, a chat channel, a profile — opens as a tab.

The Second Brain graph

Every note and database row becomes a node in a force-directed graph, rendered on Canvas2D with a Web-Worker layout. It stays smooth into the hundreds of thousands of nodes — semantic-zoom swaps dots for icons for cards as you zoom, and a console filters by node kind and database.

Live databases

Point osionos at a real database (Postgres, MySQL, Mongo, and more) and it renders the tables as Notion-style views — grid, board, and dashboards — writing straight back through the bridge.

Dashboards

Every view can become a dashboard widget: charts, counters, and maps composed on a canvas, with the numbers computed server-side across all rows.

The editor grid

Panes split horizontally and vertically; only the focused pane mounts the live editor, so a wall of open panes stays fast.

The front door

Prismatica — the marketing-and-auth website — in its warm-editorial theme.

This docs shell

And the site you are reading — light and dark, both authored in .xmd.

Ready to build? Start with Getting Started, or browse the Architecture.

Installation & Prerequisites

Track Binocle is Docker-first. Almost everything you need lives inside containers, so the host stays lean: no language toolchains, no node_modules, no database servers to install by hand.

What the host actually needs

Clone and run

# Submodules matter — clone recursively.
git clone --recursive <repo-url>
cd ft_transcendence

# One command reconstitutes the whole stack.
make all

That single command is self-provisioning — it starts the backend, restores demo data, and builds the frontends. See The make all pipeline.

The one optional secret

Everything above gets a machine running on its own. Sharing the team's secrets and demo data additionally needs the vault key — the one secret that lives in neither git nor the vault itself.

First-run checklist

• Docker + Compose v2 installed and the daemon running
• Repo cloned with --recursive
• (Optional) ~/.config/42ctl/ copied over for shared secrets
• make all run to completion
• make healthcheck reports the front doors green — see Health Checks

Several apps (the osionos editor, this website, mail, calendar, grobase) are git submodules. A plain clone leaves those directories empty; --recursive populates them. make all also runs a best-effort submodule sync, so a missed flag is recoverable.

The make all Pipeline

make all is the headline command. From a clean clone it reconstitutes the whole stack — backend, data, and frontends — with no manual sequencing. make all-local is a kept alias that runs the identical recipe.

make all

The stages, in order

The recipe runs these steps front to back. Each one is a no-op when its work is already done, so re-running make all is safe and cheap.

1. sync-submodules-soft — best-effort, fast-forward-only submodule sync. Never blocks the pipeline; skip it with SKIP_SYNC=1.

2. secrets-ensure — pulls the shared *.env tree from the vault when apps/grobase/.env is absent and a vault key is present.

3. certs — regenerates the local TLS certificates (delegated to grobase).

4. certs-trust-local — trusts the local CA in the system and browser stores.

5. backend-up — starts the grobase backend if it is down.

6. restore-if-empty — loads the demo-data snapshot only if the databases are confirmed empty.

7. frontends-up — builds and starts the frontend services with health validation.

8. healthcheck → showcase — verifies the front doors and prints the local URLs.

Two ways it can run

Both are covered in depth in The two make all modes.

When there is no root .env.local, an env-local-ensure step derives it from grobase's just-generated .env — copying the BaaS keys (they must match grobase's random secret) rather than inventing new ones. That is what lets a box with only Docker + git + the clone come up with no vault access.

Related entry points

• make bootstrap — a thin alias for this same self-provisioning flow.

• make -C apps/grobase up EDITION=full — start the backend by hand for a non-default edition.

Docker-First Development

The entire development environment runs in containers. This is not a preference — it is a constraint the tooling actively enforces.

Do / don't

• Run commands through make and docker compose
• Shell into a running service: docker compose exec <service> bash
• Let the containers own the dependencies
• npm install on your laptop
• Point an app at a host-installed Postgres or Redis
• Add an install-time lifecycle hook

Supply chain is locked down

Dependency installs are deliberately constrained so a compromised package can't run arbitrary code at install time.

Working inside a container

docker compose ps                    # what's running
docker compose logs -f osionos-app   # follow one service
docker compose exec osionos-app bash # a shell inside it

The trade you make is a slightly heavier first build in exchange for a machine that reproduces the team's environment exactly — the same reason a fresh clone plus make all works identically on any box.

Next, the command that ties all of this together → The root Makefile.

The Root Makefile

All lifecycle goes through the root Makefile. It is the authority: a thin coordinator that includes a tree of fragments under infrastructure/makes/, each owning one slice of the workflow.

The commands you reach for

Where the backend targets live

Editions, environment sanity checks, and other backend shapes are grobase targets — run them from apps/grobase/, not the root:

make -C apps/grobase up EDITION=query   # a specific edition
make -C apps/grobase editions           # list the known-good shapes
make -C apps/grobase doctor             # environment sanity check

See Grobase Editions for the full list.

The rule of thumb: if you're about to type docker compose by hand, first check whether a make target already does it — it almost always does, and it does it with the correct profiles and networks.

Health Checks & Quick Curls

Once make all finishes, a few commands tell you whether every front door is actually answering.

The two health targets

make healthcheck          # curls each front door + the BaaS health route
make check_health_apps    # UP/DOWN matrix per app, localhost AND production

• make healthcheck probes the BaaS auth health route, the bridge, osionos, the website (following the HTTP→HTTPS redirect), and the auth gateway's availability endpoint.

• make check_health_apps produces a per-app UP/DOWN table across both localhost and the deployed production URLs.

Poking a single surface

The local TLS certificates are self-signed by a local CA, so pass that CA to curl:

# Website
curl --cacert apps/grobase/certs/track-binocle-local-ca.pem https://localhost:4322

# osionos editor
curl --cacert apps/grobase/certs/track-binocle-local-ca.pem https://localhost:3001

Everyday inspection

Quick green-light checklist

• make healthcheck returns without errors
• docker compose ps shows services healthy (a few vestigial ones may lag)
• https://localhost:4322 serves the website
• https://localhost:8787/api/auth/availability answers

Compose Profiles

Compose profiles carve the service graph into logical subsets. A profile lets you bring up a coherent slice of the stack instead of every container at once.

Listing what a profile contains

COMPOSE_PROFILES=dev docker compose config --services

The dev profile is the default (set in the make fragments), and it is the one that includes the frontend surfaces you develop against.

Profiles you'll meet

A profile is a raw compose-level tag on a set of services. An edition is a named, known-good shape that combines profiles, storage engines, and isolation models into something guaranteed to come up green. Editions are a grobase concept — see Grobase Editions. Profiles are the lower-level primitive editions are built from.

Rule of thumb

• Use make targets for normal work — they set the profile for you.

• Reach for COMPOSE_PROFILES=… docker compose … only when you deliberately want a narrow slice, and always set the profile explicitly.

If a service you expected is missing, the first thing to check is whether the active profile includes it: docker compose config --services.

Grobase Editions Overview

The backend — grobase — can be brought up in several editions. An edition is a named, known-good shape that bundles compose profiles, storage engines, and isolation models into a combination guaranteed to come up green.

# From apps/grobase/
make editions            # list the known-good shapes
make up EDITION=query    # start a specific one
make doctor              # environment sanity check

The shapes

Why migrate is the default

make all uses migrate via GROBASE_EDITION. It brings up all snapshot storage engines plus the full app / control / data planes and realtime — but deliberately leaves out the monitoring and lakehouse extras that tend to come up unhealthy in a constrained environment. The result is a stack that is fully green out of the box.

# Override the edition make all boots:
make all GROBASE_EDITION=full

• Day-to-day frontend work → the default migrate (just run make all).

• Investigating a query or realtime path → the matching focused edition.

• Want everything, including the extras → full.

• Not sure the environment is sane → run make doctor first.

Editions are built on top of the lower-level compose profiles.

The Vault Key & Secrets Flow

Shared secrets are managed through the vault42 tooling. There is exactly one piece that lives in neither git nor the vault itself: the vault key on your machine.

How secrets reach the stack

1. make all runs secrets-ensure early in the pipeline.

2. If apps/grobase/.env is missing and a vault key is present, it pulls the shared *.env tree from vault42.

3. The frontends then derive their own env from the backend's secrets.

If there is no vault key, the pipeline doesn't stop — grobase self-generates its secrets and the root env is derived locally. See The two make all modes.

Pull vs push

What's dormant without the shared secrets

• Core login and editing — work fully local
• The live-database demo (needs a provisioned app key)
• Certain org-simulation permission sets

Those stay inert until their own seed steps run with the real secrets.

extracted; the root stubs remain only to redirect old muscle memory.

Never print a secret's value in a log, a commit, or a doc — names and set/unset status only.

Restoring Demo Data

A clean stack is an empty stack. make all can populate it from a snapshot — but it does so only when it is certain the databases are empty.

The fail-safe restore

The restore-if-empty step is deliberately conservative:

Because the backend starts detached, the step also waits for Docker health before probing, so it doesn't race the engines while they're still booting.

What the snapshot covers

The demo snapshot spans the stack's primary storage engines. Tooling to capture and load it lives with the backend:

The live-database demo

Separate from the empty-restore path, there's a deterministic demo dataset:

make seed-live-demo

• It generates a large, deterministic commerce + operations dataset (fixed PRNG seed) and is idempotent — safe to re-run.

• RESEED=1 make seed-live-demo wipes first, then regenerates.

• It rebuilds osionos with the BaaS environment baked in so the editor can read the live data.

restore-if-empty loads a captured snapshot only into an empty stack — it's about reconstituting a machine. seed-live-demo generates a fresh synthetic dataset on demand — it's about demonstrating the live-database features. They serve different jobs; you rarely need both at once.

If a restore is skipped when you expected data, the cause is almost always that the databases weren't actually empty — check Common Failure Modes.

Rebuilding a Single Frontend

When you've edited one app, you don't need to re-run the whole pipeline. Rebuild just that service.

The general form

docker compose up -d --build <service-name>

This rebuilds and restarts a single frontend in place while the rest of the stack keeps running.

The frontend services

make all builds this set of root frontends:

The osionos shortcut

For the editor specifically there's a dedicated target that rebuilds and hard-reloads it:

make update_web    # rebuild + restart osionos-app, then hard-reload :3001

After a rebuild

• docker compose ps shows the service healthy again
• Reload the app's URL (a hard reload for the editor)
• make healthcheck if you want the full green-light — see Health Checks

The osionos editor exposes an Update control that triggers a rebuild through a small host-side daemon. It's the same idea as make update_web, driven from inside the running app instead of the terminal.

For a full stack rebuild instead of a single service, just re-run make all — it's idempotent.

Common Failure Modes & Fixes

Most first-run problems fall into a handful of buckets. Here's how to recognize and resolve them.

Symptom → cause → fix

Backend won't start

# Start the backend by hand:
make -C apps/grobase up

Certificates

Certs are regenerated (via grobase) on every make all — that's intentional. If a browser complains:

make certs-trust-local   # trusts the local CA in the system + browser stores

Known-stale targets

When a restore didn't happen

If demo data didn't load, it's almost certainly because the databases weren't confirmed empty — the restore is fail-safe by design and skips on any uncertainty. Details in Restoring Demo Data.

If a host port a frontend wants is taken, stop whatever holds it (or stop the stack with docker compose down and restart). Because the ports are published by the proxy and a few service blocks, a conflict shows up as that one service failing to bind, not the whole stack.

The Two make all Modes

make all is one command with two behaviours, decided entirely by whether the machine holds the vault key.

Side by side

With the key — team parity

The machine pulls the shared secrets and restores the shared demo data, so it matches everyone else's environment. This is the path for a teammate who has copied ~/.config/42ctl/ across.

Without the key — fully local

The one host requirement for this path is openssl, which grobase's own secret-generation already uses.

What stays dormant locally

• Core login
• Document editing
• The live-database demo (needs a provisioned app key)
• Certain org-simulation permission sets

Those wake up only when their own seed steps run with real secrets.

When there's no root .env.local, an env-local-ensure step runs after the backend starts. It reads grobase's freshly generated .env, copies the BaaS keys that must match, mints the handful of app secrets it needs locally, and leaves optional cloud keys empty. That's the whole trick behind "works with no vault access."

For the mechanics of the pipeline itself, see The make all pipeline; for the key itself, see The vault key & secrets flow.

Editing These Docs

This documentation site is not a third-party static generator. Every page is authored in .xmd and rendered by the project's own markengine — the same parser that powers the live osionos editor. Write a file, rebuild, reload.

The loop

1. Add or edit a .xmd file under apps/opposite-osiris/vault/.

2. Rebuild the doc shell (a build script assembles vault/ into the page).

3. Reload — the sidebar and content reflect your change.

Filenames are kebab-case, and the folder structure under vault/ becomes the navigation tree.

Every page needs frontmatter

---
title: Human Readable Title
icon: ◆
order: 12
summary: One sentence describing the doc, shown in lists and the hero.
---

Linking between pages

Use a normal link with the target's path, relative to your file:

[Getting Started](../guides/getting-started.xmd)

Before you commit

• Frontmatter present and complete
• Filename is kebab-case
• order doesn't collide with a sibling
• Rebuilt and reloaded — it renders as expected

The website ships a build script that turns vault/*.xmd into the self-contained shell, plus a verifier that sanity-checks the vault. You don't call the parser directly — you write .xmd, run the build, and read the result.

Curious how the rendering works? Read The markengine.

The Three Language Planes

Track Binocle is a Docker-first monorepo that deliberately spans three languages. Each language owns a plane — a horizontal slice of the system with one clear responsibility. The rule of thumb: pick the language that best fits the concern, not the concern that best fits one language.

The split at a glance

Each plane has its own page:

• The Application Plane — React, Astro, the bridges.

• The Control Plane — provisioning, auth, tenancy, metering.

• The Data Plane — query execution, DB drivers, realtime routing.

Why three languages, not one

• TypeScript (application) — the React block editor osionos, the Astro marketing-and-auth site opposite-osiris, the bridging services, and the Mail & Calendar apps.

• Go (control) — provisioning, the auth gateway, tenancy & secrets, metering and billing.

• Rust (data) — high-performance query execution, database drivers, transaction handling, and realtime event routing.

How the planes are wired

The application plane runs as the frontends-only root compose stack. The control and data planes live together inside grobase, a standalone backend-as-a-service the frontends reach over an external Docker network.

  ┌───────────────────────────────────────────┐
  │  Application plane  (TypeScript)           │
  │  osionos · opposite-osiris · bridges       │  root docker-compose.yml
  └───────────────────┬───────────────────────┘
                      │  container-name DNS
  ┌───────────────────▼───────────────────────┐
  │  grobase BaaS  (Kong front door)           │
  │  ├─ Control plane  (Go)                    │
  │  └─ Data plane     (Rust)                   │  separate docker project
  └───────────────────────────────────────────┘

The discipline that ties them together

Every major change across the planes follows one rule: shadow → parity → cutover. New code runs in parallel with the old, validation proves they behave identically, and only then does the new path take over. Deletion is always the last step.

The Application Plane

The application plane is written in TypeScript and is everything a user actually touches. In the deployment topology it is the frontends-only root compose stack — nothing in this plane holds a database or a service-role secret on its own; it reaches the control and data planes through the grobase backend.

What lives here

The compose service for the website is named opposite-osiris-web (it also publishes 4323 → 8080 directly for debugging).

osionos — the block editor

osionos is a React + Vite single-page app: a Notion-style block editor that grew into a full collaborative workspace. Its source uses a feature-sliced layout (app/ components/ data/ entities/ features/ pages/ services/ shared/ store/ types/ widgets/).

opposite-osiris — the website + auth landing

The Astro site is both marketing surface and the auth landing where a user signs in before being handed off to the editor. This documentation shell itself ships from opposite-osiris, rendered by the project's own markengine.

The bridges are part of this plane — but special

The *-bridge services are TypeScript, so they sit in the application plane, but they carry a trust boundary: osionos never talks to the BaaS directly. The bridge holds the service-role key and proxies data on the app's behalf.

• Bridge is TypeScript → application plane
• Bridge holds the privileged key → a trust boundary
• Bridge is not the control plane — it does not decide policy, it forwards

Not in this plane

Postgres, Kong, gotrue, postgrest, redis, and the realtime server are not application-plane services — they belong to grobase. The application plane only reaches them, by container-name DNS over an external network.

The Control Plane

The control plane is written in Go and decides who can do what. It is the plane that provisions tenants, authenticates callers, holds secrets, and meters usage. It lives inside the grobase backend, not in the root compose stack.

Responsibilities

• Provisioning — creating and shaping tenants and their resources.

• The auth gateway — authentication and session management.

• Tenancy & secrets — isolating tenants and holding their credentials.

• Metering & billing — measuring usage and turning it into charges.

How it is organised

The control plane is a large Go codebase — dozens of packages under internal/, each owning one concern. Named examples from the tree:

The auth gateway

The auth gateway is the one control-plane service that also runs as a root compose frontend (auth-gateway, host port 8787) — it fronts authentication and session management for the browser.

Tracks gate what the control plane exposes

Much of the control plane's surface is flag-gated OFF by default so the open-source edition stays byte-for-byte identical to the managed one:

• Track A — OSS self-host (shipped, always on).

• Track B — managed cloud: metering → billing → tenant self-service.

• Track D — enterprise: orgs / RBAC / SSO / SCIM / passkeys / audit / CMEK.

• Track E — parity: DB branching, push, read-replica.

The control plane sits above the data plane: it decides access, the data plane moves the bytes once access is granted.

The Data Plane

The data plane is written in Rust and does one thing: move bytes, fast and predictably. Once the control plane has decided a caller is allowed, the data plane executes the query, drives the database, and routes realtime events. It has no garbage-collection pauses on the hot path — that is the whole reason it is Rust.

What it owns

• Query execution — running the request against the target engine.

• Database drivers — talking each engine's wire protocol.

• Transaction handling — grouping operations atomically.

• Realtime event routing — fanning changes out to subscribers.

Two Rust workspaces

The realtime workspace is split into small crates, each a clean seam:

Capability-aware routing

The data plane is engine-agnostic by design: the same request can target different database engines, and the router forwards to the right adapter. The realtime workspace names its crate seams "-agnostic" for the same reason — Postgres and MongoDB are just two producers behind one engine.

   request ──► data-plane-router (Rust)
                    │  capability check
        ┌───────────┼───────────┬───────────┐
        ▼           ▼           ▼           ▼
     Postgres     MySQL       Mongo      … other engines

Forward routing vs the legacy path

The data plane is the subject of the project's migration story. A legacy TypeScript data path is being replaced by the Rust router under the shadow → parity → cutover discipline.

Shadow → Parity → Cutover

Track Binocle never flips a switch on a major change. New code runs in parallel with the old, validation precedes any cutover, and deletion is always last. This is the single discipline that makes cross-plane changes safe.

The three phases

1. Shadow — the new path is built and runs alongside the old one, serving no real traffic yet. It can be exercised, instrumented, and compared.

2. Parity — identical requests are sent through both paths and their results are compared. Parity holds only when the outputs match.

3. Cutover — once parity holds and CI is green with the new routing, the new path takes over real traffic. The old path stays until deletion is safe.

   ┌─ Shadow ─┐   ┌─ Parity ─┐   ┌─ Cutover ─┐   ┌─ Delete ─┐
   │ new runs │   │ identical│   │ new serves│   │ old code │
   │ beside   │──►│ results  │──►│ real      │──►│ removed  │
   │ old      │   │ proven   │   │ traffic   │   │ (last)   │
   └──────────┘   └──────────┘   └───────────┘   └──────────┘

Why parity comes before cutover

Parity is not a formality — it is the evidence that the cutover is safe. Without a proven parity comparison, a cutover is a guess.

Where you see it

• The data plane. The Rust query router shadows, then reaches parity with, the legacy TypeScript data path before any cutover. See the data plane.

• The deletion gates. Removing legacy code is the very last step, gated on live traffic, shadow parity, and green CI — the migration safety gates.

Checklist for a major change

• New path built and running in shadow (no real traffic)
• Identical requests compared — parity proven, not assumed
• CI green with the new routing enabled
• Only then: cutover
• Only after cutover is proven stable: delete the old path

Frontends-Only Root Compose

The root docker-compose.yml is a frontends-only orchestrator. It defines the application-plane services and joins the standalone grobase backend over an external Docker network — it does not define the backend itself.

What is — and is not — a root service

The TLS front door

A single local-https-proxy service is the TLS front door. It publishes the 8 primary frontend host ports behind HTTPS. Two services publish their own ports instead of going through the proxy: livekit (media), and opposite-osiris-web (its debug 4323 → 8080).

   Browser ── HTTPS ──► local-https-proxy
                          ├─► opposite-osiris-web   :4322
                          ├─► osionos               :3001
                          ├─► osionos-bridge        :4000
                          ├─► auth-gateway          :8787
                          ├─► mail / mail-bridge     :3002 / :4100
                          └─► calendar / cal-bridge  :3003 / :4200

Self-provisioning startup

The whole stack comes up from one command. make all is self-provisioning: from a clean clone it syncs submodules, ensures secrets, regenerates TLS certs, starts grobase, restores demo data when the databases are empty, then builds the frontends with health validation.

• make all starts the backend if it is down
• certs regenerate on every make all (intentional)
• demo data restores only when engines are confirmed empty (never wipes)

Two host-network simulations

Beyond the eight frontends, two host-network simulation services also exist: playground-simulation and agency-simulation. They are org/tenant simulations, not part of the primary user path.

Container-DNS Topology

The frontends and grobase run as two separate Docker projects. They talk over a shared external Docker network using container-name DNS — one container finds another by its name, and Docker's embedded DNS resolves it. No hard-coded IPs, no host localhost between services.

The names the frontends use

All BaaS and auth traffic is addressed by container name:

   ┌──────────── mini-baas_mini-baas (external network) ────────────┐
   │                                                                │
   │   osionos-bridge ──► mini-baas-kong:8000 ──► postgrest / gotrue│
   │   auth-gateway   ──► mini-baas-kong:8000                       │
   │   frontends      ──► mini-baas-realtime:4000                   │
   │                       mini-baas-redis:6379                     │
   └────────────────────────────────────────────────────────────────┘

Kong is the front door

Most traffic does not hit postgrest or gotrue directly — it goes through Kong at mini-baas-kong:8000, which gates and routes it. osionos consolidated on this single Kong backend on port :8000.

The localhost / IPv6 trap

Container-name DNS resolves cleanly inside the Docker network. The desktop (Electron) build is different: it runs on the host and reaches Kong over localhost — and there Chromium's net.fetch resolves localhost to IPv6 ::1, while mini-baas Kong is IPv4-only.

Why container DNS and not fixed IPs

• Portable — a container's IP changes between runs; its name does not.

• Decoupled — the frontends do not need to know grobase's internal addressing.

• Two-project friendly — the external network is the only contract between the frontends-only root compose and grobase.

The Node Bridge Trust Boundary

osionos never talks to the BaaS directly. A Node bridge — osionos-bridge, running on host port 4000 — sits between the editor and grobase. It holds the privileged service-role key and proxies data requests. The trust boundary lives in one place, not scattered across the browser client.

Why a bridge at all

If the browser held the service-role key, the key would be exposed to every user and every extension. The bridge keeps the secret server-side and only forwards requests it is willing to make.

• Secret stays server-side (never shipped to the browser)
• One trust boundary, one place to audit
• The client sends intent; the bridge decides what actually hits the DB

How privileged calls are made

   Browser (osionos)
     │  page read/write intent  (no service key here)
     ▼
   osionos-bridge (Node)  ── holds SERVICE_ROLE_KEY
     │  apikey + Bearer = service role
     ▼
   mini-baas-kong:8000 ──► postgrest ──► mini-baas-postgres

Bridge vs the direct client

osionos has two ways to reach the backend, and they are not the same trust level:

The two are compared in full on how osionos reaches the BaaS.

The bridge is application-plane, not control-plane

The bridge is TypeScript, so it belongs to the application plane. It is not the control plane: it does not decide policy or issue identities — it forwards data requests with a privileged key it is trusted to hold.

Submodule & Nested-Repo Layout

Track Binocle looks like one monorepo but is stitched together from Git submodules. The root repo records each submodule's commit SHA; the actual code lives in its own repository. One member — grobase — goes further: it is a nested independent repo with its own remote and its own authoritative docs.

The submodules

The root .gitmodules declares 10 entries:

grobase — a repo within the repo

Read grobase's own CLAUDE.md before substantial BaaS work — it is the source of truth for the backend's layout, flags, and gates.

Gotchas that look like breakage but aren't

Pulling and pushing across the boundary

• make pulls — fetch the submodules
• make pushes GIT_COMMIT_MESSAGE="…" — push submodules, then the root
• Never expect a root commit alone to carry submodule file changes

   root repo
     ├─ gitlink ─► apps/osionos/app        (own history)
     ├─ gitlink ─► apps/opposite-osiris     (own history)
     ├─ gitlink ─► apps/grobase             (own .git + remote + CLAUDE.md)
     └─ gitlink ─► vendor/*                 (side projects)

Monorepo Directory Map

A tour of the repository's top-level layout — enough to know where a thing lives without opening every folder. Only the non-obvious entries are called out.

apps/ — the products

Other top-level directories

• models/ — root-app SQL migrations (calendar + mail bridges, GDPR / RLS hardening, and the osionos messenger + social suite). Idempotent, with RLS.

• infrastructure/makes/ — the Makefile fragments the root Makefile includes.

• scripts/ — root dev helpers (health checks, the rebuild-server daemon).

• tools/seeds/ — seed helpers.

• playground/datas/ — tracked sample datasets used by the live-DB demo/seeders.

• dist-selfhost/ — a self-host scaffold.

• vendor/ — side-project submodules (not part of the runtime stack).

• wiki/ — a substantial human-authored doc set.

The authorities

A one-glance tree

   ft_transcendence/
   ├─ apps/
   │  ├─ grobase/          nested BaaS repo (Go + Rust + TS)
   │  ├─ osionos/app/      React editor (submodule)
   │  ├─ opposite-osiris/  Astro site (submodule, this doc)
   │  ├─ mail/ calendar/   bridge submodules
   │  ├─ osionos-desktop/  osionos-electron/
   │  └─ baas.bak/         untracked snapshot (noise)
   ├─ models/              root-app SQL migrations
   ├─ infrastructure/makes/  Makefile fragments
   ├─ scripts/  tools/  playground/datas/  vendor/  wiki/
   ├─ docker-compose.yml   frontends-only authority
   └─ Makefile             root coordinator

The lifecycle authority

• All lifecycle goes through the root Makefile — it is the authority.
• make all is self-provisioning (submodules → secrets → certs → backend → data → frontends → healthcheck).
• Do not drive the production paths with raw docker compose — see the profile gotcha.

Deletion & Migration Safety Gates

The riskiest step in the whole shadow → parity → cutover discipline is deletion — removing the legacy path for good. Track Binocle guards it with three explicit gates. All three must pass. If any is UNKNOWN, it counts as FAIL.

The three gates

1. m18 — Live Traffic. Rust serves real traffic with DATA_PLANE_ROUTER_PRODUCT_MODE=enabled. The new path is not a lab demo; it is carrying production requests.

2. Shadow Parity. Identical requests return identical results through the TypeScript path and the Rust path. Divergence blocks deletion.

3. CI Green with Forward Routing. No regressions; the gates explicitly PASS with forward routing on.

Why deletion is last, not first

Deleting the old path before proving the new one is how you lose the only working implementation. The gates exist so that by the time legacy code is removed, it has already been unused, in production, and proven redundant.

   Live traffic ─┐
   Shadow parity ─┼─ all PASS ──► safe to delete legacy TS path
   CI green      ─┘
        │
        └─ any UNKNOWN / FAIL ──► keep shadowing, do not delete

UNKNOWN = FAIL

The pre-deletion checklist

• Rust serving live traffic in product mode (m18)
• Shadow parity: identical results, both paths, on real requests
• CI green with forward routing — gates explicitly PASS
• Only when all three are green: remove the legacy TypeScript data-plane code

How osionos Reaches the BaaS — Bridge vs Kong

osionos reaches the grobase backend by two distinct routes, and confusing them is the source of many bugs. One goes through the server-side bridge; the other goes straight to Kong from the browser. They serve different purposes and carry different credentials.

The two routes side by side

Route 1 — the bridge (data)

Page loads and page writes go through the bridge, not the browser client. The bridge holds the service-role key, sends it as both apikey and Bearer to postgrest, and returns the data to osionos.

Route 2 — direct to Kong (auth)

For authentication, the browser talks to Kong at port :8000, which gates /auth/v1/* (gotrue) with key-auth.

   ┌── osionos (browser) ─────────────────────────────┐
   │                                                  │
   │  auth ────────────────────────► mini-baas-kong:8000 ──► gotrue
   │                                                  │
   │  page data ──► osionos-bridge ──► mini-baas-kong:8000 ──► postgrest
   │                (service key)                     │
   └──────────────────────────────────────────────────┘

Two failure modes to recognise

The takeaway

• Data problems → look at the bridge → postgrest path, not VITE_BAAS_*.

• Login problems → look at the browser → Kong → gotrue path and the anon key.

• The bridge is the trust boundary; Kong is the container-DNS front door.

Data Flow of a Page Edit

This page follows a single edit through all three planes: the application plane (the editor and the bridge), the control plane (Kong gating access), and the data plane (Postgres and realtime). It ties the whole architecture together in one concrete path.

The journey of one keystroke

1. You type. osionos updates its in-memory block model and serializes the affected page.

2. The client queues the write. osionos does not fire a request per keystroke — it batches writes to be sent to the bridge.

3. The bridge persists it. osionos-bridge (:4000) receives the write and, holding the service-role key, forwards it to postgrest through Kong.

4. Kong routes it. mini-baas-kong:8000 gates and forwards the request to postgrest.

5. Postgres stores it. postgrest writes the row into mini-baas-postgres under the osionos_* schema.

6. Realtime fans it out. A change notification propagates so other viewers of the page can update.

   keystroke
      │  serialize block model
      ▼
   osionos (browser) ── batched write
      │
      ▼
   osionos-bridge (Node, holds SERVICE_ROLE_KEY)
      │  apikey + Bearer
      ▼
   mini-baas-kong:8000  ──►  postgrest  ──►  mini-baas-postgres
                                                   │
                                       change notification
                                                   ▼
                                   realtime (Rust) ──► other viewers

Why the client batches

The realtime hop

The last step — fanning the change out to other viewers — is the Rust data plane's realtime router. Postgres emits a change, a realtime producer picks it up, and subscribers receive it.

Where each plane shows up

Recap

• The edit never leaves the browser with a service key — the bridge holds it.
• Every write crosses Kong, the single front door.
• The realtime hop is what makes the workspace collaborative.

What the Block Editor Is

osionos (npm name osionos-playground) is a Notion-style block editor that grew into a full collaborative workspace. It is a React 19 + Vite 6 + TypeScript app, served at https://localhost:3001, and it is one of the frontends of the Track Binocle monorepo.

Every piece of content on a page is a block: a paragraph, a heading, a callout, a table, an embedded database view. Blocks nest into a tree, and the same tree drives the editor, the read-only renderer, and the markdown you can round-trip out and back in.

More than a document editor

The editor is the centre of gravity, but the surfaces around it are real and sidebar-reachable — each opens as its own pane:

How "pages" open — no router

There is no react-router. Navigation is a VSCode-style tab and pane layout tree held in a zustand store. What renders inside a pane is decided by its tab.kind:

// widgets/page-renderer/ui/PaneContent.tsx — a guard chain, not a switch
if (tab.kind === 'home')     return <HomeTabView />;
if (tab.kind === 'database') return <DatabaseView />;
if (tab.kind === 'channel')  return <ChannelMessages />;
// …home / folder / trash / database / profile / console / channel
// default → an editable page (PageTabView)

Performance is a design constraint, not an afterthought

• Surfaces are code-split with React.lazy using deep import paths, never widget barrels — importing a barrel would staple the whole editor onto the warm chunk.

• Only the focused pane mounts the live editor. Unfocused splits render a cheap read-only preview instead.

Block Types Overview

A page is a tree of blocks. Each block has a type, its own content, and — if it is a container — a children array serialized as JSON. The type decides how the block renders, how Enter behaves inside it, and whether it can hold other blocks.

Two families

Blocks fall into two categories, defined in blockCategories.ts:

• Leaf blocks — hold text or a payload, but not other blocks. Paragraphs, headings, code, tables, equations, media, and the embedded graph_view.

• Container blocks — parentable, enterCreatesChild, and selfRendersChildren. They nest other blocks infinitely. Callouts and quotes are the canonical containers.

The catalogue

Rendering: two paths, one tree

The same block tree flows through two renderers, and both must understand every type:

• BlockEditor.tsx — the editable path (what you type into).

• ReadOnlyBlock.tsx — the read-only path (previews, unfocused panes, published views).

Slash Commands

There are two ways to get a block: ask for it with a slash command, or let the text convert itself with a markdown shortcut. Both end at the same place — a typed node in the block tree.

The slash menu

Type / at the start of an empty line and a menu appears, filtered as you type. Each entry inserts a block of a given type. The command set lives in the slash-commands feature, with human labels in SLASH_DESCRIPTIONS.

• /table → the block-editor grid, TableBlockEditor — see Tables.

• /layout (and /canvas) → the freeform builder — see Canvas & Layout.

• Headings, lists, to-dos, callouts, quotes, code, equations, media…

Markdown shortcuts — convert as you type

You don't have to open the menu. The typing parser (detectBlockType in shortcutsDetect.ts) watches the start of a line and transforms it in place:

Shortcuts nest inside containers

This is the subtle part. When you type a shortcut inside a callout or quote, applyMarkdownDetection (in usePlaygroundBlockEditor.ts) creates a child of the detected type — it does not convert the container away.

• Type / to open the menu
• Type # to get a heading with no menu at all
• Try > [!tip] to drop a tip callout in one keystroke run

The markengine in the Editor

The markengine (src/shared/lib/markengine/) is the bridge between markdown text and the block tree. The docs shell you are reading is rendered by it; the editor uses it for something more demanding — turning what you type or paste into live, editable blocks.

The AST is the contract. Markdown becomes BlockNode[], and every consumer — the typing shortcuts, the raw-mode importer, the read-only renderer — speaks that same shape.

Two parsers, on purpose

The editor deliberately runs two parsers, each tuned for a different moment:

1. detectBlockType (shortcutsDetect.ts) — the typing parser. Fast, line-oriented, forgiving. It reads > as a toggle and " / | as a quote, because that is what feels right mid-keystroke.

2. parseMarkdownToBlocks (markdown/shortcuts.ts → parse AST → astToBlocks) — the paste / raw-mode Save parser. A full CommonMark + GFM AST. Here > is a blockquote, toggles are > [>], and callouts are > [!kind].

How the editor imports it

The markengine has no package alias. It is pulled in through the generic @ → src alias:

import { parseMarkdownToBlocks } from "@/shared/lib/markengine";

Its core parser and renderers are pure Node functions with zero external dependencies, which is exactly why they can run in a build script, in a test, or in the browser without a DOM.

A quirk worth knowing

The markengine sub-tree is eslint-ignored by the app, yet all of lib/markengine still lives in the app's TypeScript compile graph — so a type error there can break the quality gate even though the linter never looks at it.

Raw-Mode Split-Pane Editing

Raw mode (features/raw-mode) is a split-pane markdown-source editor. On one side you see the page's blocks; on the other you edit the plain-markdown source of those same blocks. It is the escape hatch for people who would rather type markdown than click through a slash menu.

The round-trip, both directions

  blocks  ──serialize──▶  markdown source   (what you see in raw mode)
    ▲                          │
    └────── parse ◀────── you edit + Save

• Blocks → source is done by pageMarkdownSerialize.ts, which emits the markdown dialect the AST parser understands.

• Source → blocks is done by parseMarkdownToBlocks — the full CommonMark + GFM parser, not the typing parser.

What survives the trip

• Preserved: block type and content for headings, lists, to-dos, code (with language), quotes, callouts, toggles, equations, and GFM tables.

• Toggle heading level survives via the compact #{N}> opener.

• Lost by design: collapsed (pure view state) and a heading level set on a quote or callout — there is no clean markdown form, so they degrade gracefully to plain type + content.

The full accounting lives in Serialization & Round-Trip.

Why a separate parser at all

Typing > should feel like starting a toggle; pasting a document should read > as a quote the way every other markdown tool does. Raw mode sits firmly on the document side of that split, so it always uses the strict AST parser — never the keystroke heuristics.

The /canvas & /layout Builder

The /layout (and /canvas) slash command inserts one layout block that behaves like a Figma-style canvas: free-positioned cells, drag to move, drag to resize, align and distribute across a selection. Each cell can hold ordinary blocks — so a canvas is a page inside a block.

Two engines behind one flag

The builder ships as a dual model, gated by the osio.canvas.v2 flag:

The V2 render path

CanvasRoot ─▶ CanvasStage ─▶ CanvasCellView (memoized on cell identity)
     │              │
 canvasStore    interactionStore   (transient: guides, marquee)
 (persisted)    "cells never re-render during a drag"

• canvasStore.ts — a vanilla zustand store, refcounted per layout block, with a debounced write.

• canvasReducer.ts — every action: updateCell, updateCellFrames, setCellsZ, duplicate, remove, undo, redo.

• interactionStore.ts — transient gesture state that keeps the cells still.

Performance guardrails — do not break these

In-place editing, not an inspector

Selecting cells raises a floating toolbar (CanvasSelectionToolbar) anchored to the selection — fill colour, z-order, multi-select align and distribute (alignOps.ts), duplicate, delete. Collision resolves by push-down, not a silent revert.

Callouts & Citations

Callouts and quotes are the editor's two container blocks. They are not just styled paragraphs — they are parentable, they nest any block infinitely, and their children persist structurally as block.children JSON.

Semantic, typed callouts

A callout has a kind, and the kind drives everything visual. The presets live in entities/block/model/calloutTypes.ts:

note · info · tip · success · warning · danger · important

Each preset carries an icon, a label, and a tone token (--osio-block-tint-*). resolveCalloutType(color) maps an emoji, a word-kind, or nothing at all onto a single preset — so a markdown > [!warning] and a picked emoji resolve to the same look.

You pick or change a callout's type with CalloutTypePicker, which reuses the icon / emoji / SVG picker.

Quotes and citations

A quote renders as a semantic <blockquote>. If its content ends with an attribution line, that line becomes a proper <cite>:

> Nothing is lost, everything transforms.
> — Antoine Lavoisier

splitQuoteAttribution peels off the trailing — Source line and renders it as the citation, and it round-trips back as plain text so nothing is lost on save.

Two bugs this design fixed

1. Double render — the read-only path rendered the callout component and re-rendered its children, so children appeared twice. Because a callout self-renders its children, the duplicate pass was removed.

2. Multi-line serialize — the serializer only >-prefixed the first line of a quote or callout, so a multi-line body (and the — Source cite) split into a stray sibling paragraph. Now every line gets the prefix.

Markdown forms

Tables

The editor has a /table block: a lightweight, in-page grid you type directly into. It is the markdown table, made editable — arrow keys move between cells, you add rows and columns inline, and you drag rows to reorder them.

Two grids, do not confuse them

This is the single most important fact about tables in osionos.

What the block table gives you

• Keyboard grid — arrow keys move the caret cell to cell; the cells expose role="gridcell" for assistive tech.

• Add rows and columns inline, from the edges.

• Row drag handles to reorder.

• Focus mode for editing a single table without page noise.

Tables in markdown

Block tables serialize as GFM pipe tables, so they survive a raw-mode round-trip cleanly:

| Plane       | Language   | Owns             |
|:------------|:----------:|-----------------:|
| Application | TypeScript | What users touch |
| Data        | Rust       | Moving bytes     |

• Insert a table with /table
• Navigate cells with the arrow keys
• Round-trip it through raw mode and confirm the pipes survive

The Icon / Emoji / SVG Picker

Page icons, callout icons, avatars, workspace glyphs — they all come from one shared picker and store as one opaque string. The design goal was a single value model that is backward-compatible with the old bare-emoji world.

The value model

iconValue.ts (parseIconValue / serializeIconValue) encodes every icon as a single string in one of three forms, each with optional colour:

Optional suffixes: ;color=%23hex sets the icon stroke, ;bg=%23hex sets an emoji's chip background.

The renderer

IconValueView is a drop-in superset of the older AssetRenderer. It handles the new cases and delegates every legacy value straight through:

• img: → an <img>

• icon: → LucideGlyph, which loads the glyph via lucide-react/dynamicIconImports — a per-icon lazy import, so the main bundle stays lean

• emoji + ;bg → a coloured chip

The picker UI

IconPicker has three tabs plus a colour row:

1. Emoji — the default emoji set.

2. Icons — a curated common set, with full Lucide search.

3. Custom — paste <svg> markup, paste a URL, or upload a file (read as a data-uri).

Click-outside and Escape dismiss it, and a swatch row sets the colour.

Serialization & Round-Trip Fidelity

Round-trip means: take a page, serialize it to markdown, parse that markdown back, and get the same blocks. osionos achieves this for block type by making the serializer speak exactly the dialect its strict parser reads.

The two halves must agree

block tree ──pageMarkdownSerialize──▶ markdown ──parseMarkdownToBlocks──▶ block tree
             (services/page-actions)              (the AST parser)

The fix was to rewrite pageMarkdownSerialize.ts so it emits the AST parser's dialect — not the typing-shortcut dialect. Get this wrong and a > toggle serializes as a quote on the way out and parses back as a quote on the way in.

The emitted dialect

Toggle heading level survives

A toggle that carries a heading level serializes to the compact editor-native opener #{N}> (for example ##> summary), and the parser accepts both that and the plain > [>]. So a toggle heading round-trips, and pasting ##> foo also yields one.

What does not round-trip — and why that is fine

See the two parsers this all rests on in The markengine.

The Page Outline / TOC Rail

Long pages get a table-of-contents rail — PageOutlineRail, in the widgets/page-toc widget. It is a hover minimap pinned to the right of the reading column: the page's headings as a scannable strip, with the current section highlighted as you scroll.

Purely presentational

The rail is deliberately dumb, and that is its strength. It never fetches and holds no state of its own — it reads the page that is already on screen.

rendered editor DOM
   │  MutationObserver      → headings appear / change  → rebuild the rail
   │  IntersectionObserver  → which heading is in view   → scroll-spy highlight
   ▼
PageOutlineRail  (heading_1..3 only)

• A MutationObserver watches the rendered editor DOM and rebuilds the outline when headings are added, removed, or edited.

• An IntersectionObserver drives the scroll-spy that highlights the active section.

It only shows up when useful

The rail mounts in pages/notion-page/ui/NotionPage.tsx, and only when two conditions hold:

• The page has no full-page layout (a canvas page has its own geometry).
• The page has at least two headings to navigate between.

Otherwise the component returns null — no empty rail, no clutter on short pages.

Offline-First Outbox & Ledger Sync

Every edit you make is written locally first, then drained to the backend in the background. The backend is the source of truth; the store and localStorage are a cache, reconciled last-write-wins by updatedAt. The mechanism that moves edits out is an outbox guarded by a ledger.

The moving parts

edit ─▶ store + localStorage (instant)
             │
        pageOutbox  ─PATCH /api/pages/:id─▶  bridge ─▶ BaaS
             │                                   │
          ledger  ◀──────── advances ONLY ───────┘
                            on server confirm

• src/store/sync/ + src/shared/sync/outboxLedger.ts — the page outbox and its ledger.

• usePageSync mounts once at App.tsx: hydrate-then-outbox, an 800 ms debounce, and a retry that backs off from 15 s toward 120 s.

The invariants that keep it safe

Two more invariants protect data:

• Content is lazy. A page's stamp uses a CONTENT_UNLOADED sentinel, and the outbox omits content when a page's body isn't loaded — so an unloaded page can never wipe the server copy.

• The first flush is gated on hydrate completing, so the ledger is seeded before anything publishes.

The storm this design prevents

On a freshly seeded workspace the ledger wasn't seeded yet, so every page looked "pending." The old flush kept PATCHing the whole batch even after failures — all 429'd, the ledger never advanced, and the set retried every 15 s. Self-sustaining.

The fix was pure backpressure, no raised limits:

1. Break on the first transient failure, with exponential backoff.

2. Gate the first flush on hydrate, so the spurious mass-publish never happens.

3. Bound client concurrency and dedup identical in-flight GETs.

A second, parallel engine

The ≤200-Line Convention & Feature Slices

osionos is feature-sliced, and it holds itself to small files. Neither rule is exotic, but together they are why a 1,381-file app stays navigable.

The slice hierarchy

Dependencies point downward — a lower layer never imports an upper one:

app  ▶  pages  ▶  widgets  ▶  features  ▶  entities  ▶  shared

• A feature is one capability slice — block-editor, raw-mode, slash-commands, second-brain, settings, theme, and more.

• A widget is a page-level UI assembly that wires features, entities, and shared/ui into a mountable region — the sidebar, page-renderer, the routing-critical workspace-grid, page-toc, and others.

The size limit

The convention is ≤200 lines and ≤5 functions per file.

Splitting is the norm, not the exception

The page store shows the pattern — one concern, several small files:

The working rules that go with it

• Branch osionos work from develop — never commit to develop or main.
• Commit message is updated, with no co-author trailer.
• Never auto-push — changes are reviewed first.
• Keep new and edited files inside the size limit.

Graph Engine Overview

osionos ships its knowledge graph as a self-contained package, @osionos/graph-engine, living at packages/graph-engine/. It renders the "Second Brain" — every note and live-database record an account can reach — as an aurora-glass force graph: a Canvas2D scene laid out by a Web-Worker d3-force simulation.

Two halves, one firewall

The package is split so the expensive, portable part never leaks framework code.

The boundary is enforced, not just documented: an ESLint no-restricted-imports rule forbids @/* and react/react-dom inside core/**. It is the only import firewall in the whole osionos repo — a violation still type-checks but fails test:quality.

The facade

GraphEngine (core/engine.ts) owns the aurora background, the Canvas2D scene, and the worker layout controller, and exposes a small imperative API:

// core/engine.ts — no React, no data fetching
engine.setModel(model);      // a GraphModel the host assembled
engine.setControls(controls); // filters, physics, visual, search
engine.setTheme(root);        // resolve live --osio-* tokens
engine.camera; engine.search(query); engine.exportSvg();

What the host gets

The React side (src/react/) re-exports a batteries-included surface:

• GraphExplorer — the whole thing wired together

• GraphView + GraphConsole — canvas and the 4-panel control console

• Minimap, useControls, useGraphEngine, and indexModel

The console has four panels: Filters (per-database / tag recolor), Physics (live force sliders), Visual (LOD, glow, background), and Search + Export (to PNG and SVG).

How it is consumed

• Resolved via a Vite / tsconfig alias, not a node_modules install
• Ships as TypeScript source — no build step; consumers import its CSS explicitly
• NodeId == the BaaS global id, so layout stays stable across model rebuilds
• Reduced-motion aware, and theme-driven from the app's --osio-* tokens

Semantic-Zoom LOD

A node does not look the same at every zoom. The engine runs a level-of-detail mix driven purely by camera scale, so the graph reads as an overview when you are zoomed out and as a detailed board when you are zoomed in.

The three tiers

At the FAR tier, dots below roughly a 3.2px screen radius collapse into a single batched fill per colour — tens of thousands of them cost a handful of draw calls.

Camera-scale crossfades, not timers

core/render/lod.ts computes the mix from the camera scale with smoothstep crossfades — never a time-based animation. That is deliberate:

The bands nest inside the camera's zoom range (~0.15…5):

// core/render/lod.ts (real constants)
const ICON_IN_START = 0.45;  // icons begin fading in here
const ICON_IN_WIDTH = 0.35;
const CARD_IN_START  = 1.9;  // cards crossfade in, sprites out
const CARD_IN_WIDTH  = 0.7;

icon, card, and sprite are returned as three overlapping opacities, so the tiers blend rather than snap. Labels come in over roughly 0.75…2.

The escape hatch

Semantic zoom is on by default but toggleable from the console's Visual panel. Turned off, lodMix short-circuits to { icon: 0, card: 0, sprite: 1 } — the classic flat-dot graph, for anyone who prefers it.

• FAR dots · MID sprites · CLOSE cards
• Toggle in the Visual panel (semanticZoom)
• Nothing to configure per node — the tier follows the camera

Zooming way out crosses into a different regime entirely — see Cluster blobs & overview mode.

Cluster Blobs & Overview Mode

Drawing 100,000 individual nodes when they are each a fraction of a pixel is pure waste. Past a certain zoom-out on a large-enough graph, the engine stops rendering nodes and paints one translucent disc per database cluster instead.

The overview gate

core/render/renderFrame.ts checks two conditions at the top of the node pass:

// renderFrame.ts — enter overview aggregation
if (!f.focus && camera.scale < AGG_MAX_SCALE && f.state.count > AGG_MIN_NODES) {
  const blobs = f.state.clusterAggregates(!f.lowQuality);
  drawClusterBlobs(ctx, blobs, camera);
  return; // skip the per-node path entirely
}

The thresholds (core/render/clusterBlobs.ts):

Each blob is a centroid plus a spread, computed in a single O(visible) pass, so a 100k-node overview costs about the same as a 100-node one — the draw count is O(clusters), not O(nodes). Above scale 0.34, the normal per-node / dot-batch path runs, culled to the viewport.

Where clusters come from

Clusters are not a render-time invention — they exist in the layout. Every node already carries a source (its mount) and a databaseId. The layout keys a nodeGroups: Uint8Array on node.source (≤ 256 clusters) and adds a gentle forceX / forceY pull toward each cluster's centre at clusterStrength (default 0.09). The centres sit on a ring sized so the islands actually separate rather than overlapping into one central mass.

Why this matters

• One draw call per mount, not one per record

• Culling downstream is more effective once islands are spatially separated

• The layout settles and stops (bounded ticks + alpha decay) — no idle churn

Canvas2D drawImage tops out around 10–20k sprites per frame. Beyond that the next headroom lever is WebGL instancing and link aggregation at overview — noted as a direction, not yet shipped. The blob aggregation is what keeps today's 100k overview smooth.

Pair this with the spatial grid & label cache that keeps the zoomed-in path fast.

Spatial Grid & Label Cache

Two caches carry the zoomed-in render path: one answers "which nodes are on screen?" cheaply, the other stops the biggest per-frame text cost from ever recurring.

The spatial-hash grid

core/render/spatialGrid.ts builds a uniform grid over the columnar position arrays. It serves two jobs: frame culling (skip off-screen nodes) and pointer hit-testing (find the node under the cursor) at 10k+ nodes.

Its design keeps it allocation-free in steady state:

• Counting-sort into reused Int32Arrays — no per-frame garbage.

• Rebuilt lazily, only when the position version changes. Layout ticks bump the version; queries between ticks reuse the same build.

• Cell size is at least 64 world units, which keeps a point query to a 3×3 neighbourhood even at the maximum hit reach.

   position version changes ──► markStale()
                                    │
   next query ──► rebuild() (O(n) counting sort, reused buffers)
                                    │
   subsequent queries between ticks ──► reuse the same grid

The label cache

Text was the single biggest frame cost at scale. The old path drew every label with two shadow-blurred fillText calls per frame — shadow-blurred text costs about a millisecond each, so 480 labels was roughly half a second, every frame.

core/render/labelCache.ts bakes each unique label once — halo included — into a small canvas at the device pixel ratio. Frames then just drawImage the bitmap.

The cache also re-bakes when the theme colour, halo, or DPR changes (it clears and rebuilds), so labels stay crisp across light/dark and retina toggles.

• Grid: cull + hit-test, zero steady-state allocation
• Labels: bake once, blit forever, LRU + per-frame budget
• Both keyed off the columnar SceneState, not per-node objects

Frame Budget & DPR Cap

Retina displays render four times the pixels. The engine spends that budget only when it will be seen — full quality on the settled frame, reduced quality while you are moving.

Adaptive device pixel ratio

core/render/sceneCamera.ts derives two DPR values from the real one:

// sceneCamera.ts
this.qualityDpr     = Math.min(dpr, 2);            // crisp ceiling — capped at 2
this.interactiveDpr = Math.max(1, qualityDpr * 0.5); // half-res while in motion

Even a 3× display is capped at 2 for the crisp frame. During motion the canvas is resized to interactiveDpr (roughly half-resolution), then restored to qualityDpr for the final settle frame.

Motion vs. settle

Any pan, zoom, drag, or simulation tick bumps a motionUntil timestamp. While that window is live, the frame is marked lowQuality and skips the expensive decorative work:

Labels are the subtle part: they stay baked at qualityDpr and are blitted in screen space, so toggling the interactive DPR does not force a re-bake. Hover glow also stays crisp — an animating hover effect is not the same as camera motion.

The background has its own budget

The aurora "Warm Constellation" backdrop runs on a separate canvas and loop so it never competes with the graph:

• DPR clamped to 1 (Math.min(dpr, 1)) — the soft field is imperceptible at 1×.

• Redraw throttled to ~12fps via BG_FRAME_MS = 80; the field drifts a full cycle over many minutes, so 60fps would be wasted work.

The idle-stop loop

When nothing is moving and the layout has settled, the render loop stops entirely — no frames, no CPU. It wakes on the next interaction. Combined with the per-frame label bake budget of 6, the engine spends effort strictly in proportion to what is changing on screen.

• Half-res in motion, crisp on settle
• DPR capped at 2 (graph) / 1 (background)
• Loop halts at idle

Smoothness at 100k Nodes

The engine is built to stay smooth on graphs far larger than any real workspace. A synthetic benchmark pushes it to 100,000 nodes (behind ?graphBench=N) — and it was that benchmark that exposed the last big stall.

The symptom

At 100k nodes, zooming ran at ~2fps: about 564ms average per frame, with a p95 tail of 2666ms. Panning and idle were fine; only zoom fell off a cliff.

The cause

Once you zoom in past the overview density gate, the normal per-node path runs. core/render/renderFrame.ts was calling drawLinks (and its arrows) even on motion / low-quality frames. Links have only a node-count gate, no edge spatial cull — so every frame iterated all ~200,000 edges.

The fix

The edge pass now follows the same policy as the other decorative passes: on a large graph, defer it to the settled frame.

// renderFrame.ts — defer the full edge pass while moving on big graphs
if (!lq || f.state.count <= AGG_MIN_NODES) drawLinks(base);

Read plainly: draw all links either when the frame is high-quality (settled) or when the graph is small enough (<= 15000 nodes) that edges are cheap during motion. Big graphs simply skip the edge pass mid-zoom and paint it once you stop.

The result

Known residual

If you park zoomed in on a 100k graph and stop, the settled frame still iterates every edge each idle frame. The motion fix hides the cost during interaction; the proper fix is an edge cull using the existing CSR adjacency in sceneEdges.ts. Tracked as follow-up work.

• Zoom stall found by the 100k bench
• Full edge pass deferred off motion frames on graphs > 15000
• Steady-state edge cull via CSR adjacency (pending)

Node Peek & Open

The graph is navigable, not just decorative. Hold Ctrl and hover a node to peek at its content in a preview card; Ctrl-click to open that page as a tab in the workspace.

The wiring lives in src/widgets/graph-explorer/: GraphEngineExplorer.tsx, NodeHoverPreview.tsx, and nodePreview.ts.

Ctrl is tracked outside the engine

The engine core is React-firewalled, so its onHover / onSelect callbacks carry only a NodeId — never the DOM event. The modifier key is therefore tracked separately, via window keydown / keyup into a modRef, and the preview is debounced (~220ms) so a fast mouse-over doesn't fire a fetch per node.

The id is composite — never a bare page id

This is the crux of getting it right. A graph NodeId encodes where the node came from; it is not the raw page _id.

Resolve it with parseNodeId / pageIdFromNodeId before touching any page API — passing a composite id where a bare page id is expected was exactly the bug that broke this feature the first time.

Fetch on demand — the store only holds loaded pages

And opening has its own trap:

The flow

1. Ctrl held (modRef true) + hover → debounce → loadPageById → preview card.

2. Ctrl-click → resolve id → load page → openTab in the workspace layout.

3. Release Ctrl → preview dismisses.

• Preview card on Ctrl-hover
• Open-as-tab on Ctrl-click
• Composite-id resolution + on-demand fetch + layout-store open

See also The GraphModel projection for where these ids are minted, and Multi-engine graph for record nodes.

Multi-Engine Graph

The graph is not just your notes. It is the whole data ecosystem an account can reach: notes ⊕ live database records, plus the relations that span different engines — Postgres, MySQL, Mongo, and the other backends grobase drives.

One graph, many sources

  notes (osionos_pages) ─┐
  Postgres records       ─┤
  MySQL records          ─┼─► merge by id ─► one GraphModel ─► engine
  Mongo records          ─┤
  … other mounts         ─┘
        + cross-engine edges (e.g. a ticket → an order)

The bridge composes it: GET /api/graph/data?scope=workspace|account merges the note graph with a record graph pulled from the data plane. mergeGraphs de-dupes nodes by id and edges by id, so a note and the record it mirrors don't double up.

The data path (and a dead end)

Access is authorization-scoped

Which databases appear is derived from authoritative workspace membership, not from token claims alone. A join table, osionos_workspace_databases, records which mounts each workspace is associated with (engine, tables, edges table, label), under row-level security; the bridge is the enforcement point.

A verified run scoped to a workspace returned ~2,147 nodes — notes plus Postgres and MySQL records — with ~1,727 edges, including cross-engine ticket→order links; a non-member on the same request got 0 records.

Node identity

Record nodes use dbId:resource:pk as their id, and the mount's edges table must expose from / to / type columns for a relation to render. Because ids are global and stable, a record can also be opened as a note — the graph doubles as a launcher into the underlying data.

• Notes + live records in one model
• Cross-engine edges (ticket → order, review → product…)
• Per-user access, enforced at the bridge

Resolving those ids on click is covered in Node Peek & Open.

The GraphModel Projection

Everything the engine draws comes from one plain data structure: the GraphModel. The host builds it; the engine consumes it. That single seam is what keeps the engine framework-agnostic and backend-agnostic.

indexModel — one pass, every index

core/model/model.ts turns raw nodes and edges into a ready-to-render model in a single O(N + E) pass:

// core/model/model.ts
export function indexModel(rawNodes: GraphNode[], rawEdges: GraphEdge[]): GraphModel {
  // de-dupe nodes by id
  // drop dangling edges (both endpoints must exist)
  // build adjacency (for focus) and byDatabase (for filters)
}

That pass does three jobs at once:

1. De-dupe nodes by id — the first wins.

2. Drop dangling edges — an edge survives only if both endpoints resolved.

3. Build indexes — adjacency for focus/neighbourhood, byDatabase for filters.

A node is portable data

A GraphNode carries only what the engine needs to lay out and style it:

Stable ids, cheap diffs

Because NodeId == the BaaS global id, a node keeps the same identity across every model rebuild — so its layout position survives a refresh instead of jumping. And nodesEqual compares nodes by value (ignoring the lazy fields), so the engine can diff an incoming model against the current one and only touch what changed.

• One O(N+E) assembly pass
• De-dupe + dangling-edge drop + adjacency/byDatabase indexes
• Stable global ids → stable layout across rebuilds

The engine that receives this model is described in the Graph Engine Overview.

Theme Tokens & Color Resolution

The engine is framework-agnostic but not colour-agnostic. It has no hard-coded palette — every colour it paints is resolved from the app's live --osio-* design tokens, so the graph tracks the workspace's light/dark mode and warm-editorial theme without a second source of truth.

Resolved on the main thread, from the DOM

core/theme/tokens.ts reads the --osio-graph-* custom properties off a themeRoot element (usually document.documentElement) and assembles a SceneTheme. Token values may be any CSS colour format — hex, hsl, or oklch — so they are normalized to RGB through a scratch canvas, after which the engine applies its own alpha for edges, halos, and glow.

// core/engine.ts option — where tokens come from
themeRoot: document.documentElement; // live --osio-* variables

Because it touches the DOM, theme resolution happens on the main thread and the finished SceneTheme is handed to the renderer — the worker never reads CSS.

Light or dark, from luminance

Mode is not a flag the host passes — it is derived from the background token's luminance:

The "Warm Constellation" token block in global.css defines both palettes. A few of the graph-specific variables:

• --osio-graph-bg-0 / --osio-graph-bg-1 — the background ramp (and the luminance signal)

• --osio-graph-node-backing / -rim / -shadow — the sprite "moat" and edges

• --osio-graph-edge / -edge-tag / -edge-note / -edge-hier — relation colours by kind

• --osio-graph-select / -hover / -focus-thread — interaction accents

• --osio-graph-halo — the label halo that lifts text off the field

On light mode the aurora field is composited with multiply so it tints the paper instead of washing it out.

A single luminance check means the graph can never disagree with the page. Flip the app to dark, the background token darkens, luminance drops below 0.5, and the graph's node materials, halos, and glow all follow — no separate "graph theme" state to keep in sync.

• Live --osio-* tokens, resolved per theme change
• Any CSS colour format → RGB via scratch canvas
• Light/dark inferred from background luminance

Worker & In-Process Fallback

The force simulation is CPU-heavy, so it runs off the main thread in a Web Worker. But not every environment has a Worker — server-side rendering and the test harness don't — so the engine falls back to running the same simulation in-process, behind an identical API.

One controller, two backends

core/layout/layoutBridge.ts defines a LayoutController that owns exactly one of two things:

// layoutBridge.ts
const worker = createWorker();          // null when Worker is undefined
if (worker) { /* post messages to the worker */ }
else        { this.fallback = new LayoutEngine(msg => this.onOutbound(msg)); }

// createWorker() — real guard
function createWorker(): Worker | null {
  if (typeof Worker === "undefined") return null;  // SSR / tests
  return new Worker(new URL("./layout.worker.ts", import.meta.url), { type: "module" });
}

The caller can't tell which is running. Sending a message either posts it to the worker or hands it to the in-process engine; ticks come back the same way.

Physics is defined once

        forceLayout.ts  (d3-force setup)
                 │
        layoutEngine.ts (tick driver)
             ┌───┴───┐
   layout.worker.ts   in-process fallback
       (browser)      (SSR / tests)

Live, without a restart

Layout parameters — charge, link distance, collision, cluster strength — can be reshaped while the simulation runs. The controller forwards a params update to whichever backend is active; the console's Physics panel drives it live, and the graph re-settles without a rebuild.

• Web Worker when available
• In-process LayoutEngine otherwise (SSR / tests)
• Shared tick-driver — physics defined exactly once
• Live parameter updates on either backend

The tunable parameters themselves are listed in Performance Tuning Knobs.

Performance Tuning Knobs

The graph exposes two kinds of dial: live controls you can move from the console, and internal constants that gate the render fast-paths. This page collects both.

Physics defaults

core/layout/params.ts sets the force simulation's starting point — every value is a live slider in the console's Physics panel:

Visual defaults

core/state/controls.ts holds the Visual panel state:

• nodeScale 1 · linkScale 1 · glow 1

• labelDensity 0.5

• semanticZoom true — the LOD tiers

• background "aurora-calm" — one of aurora · aurora-calm · flat

Internal thresholds

These are not user-facing; they are the constants that decide which fast path runs.

Data-shape knob

The record graph is bounded by an env variable so a huge mount can't flood the model:

# per-table record cap in the bridge graph composer
OSIONOS_GRAPH_RECORD_LIMIT=5000

• Physics + visual defaults, all live in the console
• Render fast-path thresholds documented
• Record-count cap for the multi-engine graph

Live Databases

osionos is a Notion-style block editor, but its Database plane does something Notion cannot: it renders and edits rows that live in your own external databases — Postgres, MySQL, MongoDB, and more — in real time. Nothing is imported or duplicated. The grid you see is a live projection of the engine.

How the data reaches you

osionos never talks to a database directly from the browser. Every request goes through a Node bridge that holds the backend credentials and enforces access, so the client never sees a service key.

 Browser (osionos)
    │  app-session token (Bearer)
    ▼
 osionos-bridge  ── holds the service-role key, checks access
    │  /api/databases/...
    ▼
 grobase query-router (Rust data plane)
    │
    ▼
 Postgres · MySQL · Mongo · DynamoDB · SQLite · MSSQL

• Reads and writes flow over the bridge — the trust boundary.

• Realtime updates (so a neighbour's edit appears in your grid) arrive over a separate live channel, degrading to short-interval polling when no token resolves.

What you can do with a live database

• Browse every connected database from a left-sidebar navigator
• Render a table as a virtualized Notion grid — thousands of rows
• Regroup the same data as a Board (kanban), gallery, or list
• Edit cells inline; changes persist straight back to the source engine
• Follow relations — a foreign key shows the related record's title, not a raw id
• Plot the data as charts and assemble dashboards
• Map rows with location columns on an interactive map

Where to go next

Supported Engines

A single osionos database view can front several very different engines. The Rust data plane inside grobase owns one connection pool per engine and exposes each behind a uniform contract, so the grid does not care whether a table lives in Postgres or DynamoDB — it asks the same questions and gets the same shapes back.

The engines

Capabilities drive the UI

Each engine advertises what it can do. The view reads these flags and adapts — rather than guessing and failing.

• Introspect — can the engine describe a table's columns? All six can.

• Schema DDL — can osionos create or drop a table here? SQL Server and DynamoDB say no, so for those engines the lifecycle is op-based on tables that already exist (insert / update / delete), with no create-or-drop step.

• Aggregate — can the engine compute grouped totals server-side? This powers "Live · all rows" charts; where it is unavailable the client aggregates a sample.

Isolation is not a capability — it is a guarantee

Bounded, owner-scoped sampling is the rule for every inferred engine — see Per-Account Database Isolation for the whole story.

Next: how editing works uniformly across all of these → CRUD Across Engines.

CRUD Across Engines

The live grid is fully read-write. Editing a cell, adding a row, or deleting one persists straight back to the source engine — Postgres, MySQL, SQLite, MongoDB, DynamoDB or SQL Server — through one uniform path.

Every write goes through the bridge

Writes do not go from the browser to the backend gateway directly — that path is not authorized for the anonymous key and would be rejected. Instead the write client posts to the bridge, which carries the credential and proxies to the Rust query-router:

POST /api/databases/<dbId>/tables/<table>
Authorization: Bearer <app-session token>
{ "op": "update", ... }        // op ∈ insert | update | delete | upsert

The bridge preserves the query-router's status verbatim, so the client sees the engine's true answer.

One write is one operation

osionos deliberately does not wrap single-cell edits in a multi-statement transaction. Each edit is exactly one operation against the source table — the same per-cell save model Notion uses. A single cell change never needed multi-op atomicity, and avoiding the pinned-transaction path removed a whole class of "my edit reverted" failures (see Live-Write Resilience).

The lifecycle, by engine capability

• Relational engines that allow DDL (Postgres, MySQL, SQLite) run the full lifecycle: create_table → insert → get → update → delete → drop_table.

• Engines without DDL (SQL Server, DynamoDB) are op-based — you insert, read, update and delete rows on tables that already exist, but osionos will not create or drop the table for you.

Two rules the write path lives by

What a relation or a place writes back

Some column types present richly but persist plainly:

This keeps the presentation friendly while the stored value stays a correct, minimal engine value.

The Grid (Table) View

The default way to look at a live database is the grid — a Notion-style table where columns are typed, the header is sticky, and rows scroll by the thousand without stalling the browser.

Virtualization: thousands of rows, a handful of DOM nodes

A naïve table with ten thousand <tr> elements would crawl. The grid instead uses row virtualization: only the rows currently in the viewport are mounted, with spacer rows above and below standing in for the rest. Scroll, and the window of real rows slides along.

What the grid gives you

• Sticky header — column names stay pinned as you scroll a long table.

• Typed cells — text, number, date, checkbox, select, relation and place each render and edit in their own way.

• Keyboard navigation — move the selection cell to cell; the view scrolls to keep it in sight.

• Fill-drag — drag a cell's value down a column.

• Inline editing — commit a cell and it writes straight back to the engine.

Dates never crash the view

Live tables hold messy values — a MySQL 0000-00-00, a NULL where the schema inferred a date, a free-text field the sampler guessed wrong. A strict date formatter would throw on these and take the whole database block down.

Your view settings survive a reload

The live adapter rebuilds a table's default views every time it loads. Left alone, that would erase any view you customised the moment you refreshed.

Relations render as their target's title

A column that is a foreign key does not show a bare number. The grid resolves the referenced row and shows its title as a clickable tag — see Relations & Foreign Keys for how the link is found and what an edit writes back.

The same rows, regrouped as cards → The Board View.

The Board (Kanban) View

The Board view takes the same live rows the grid shows and lays them out as kanban-style cards, grouped into columns. Drag a card to another column and the change is written back to the source database.

Group by (almost) any column

Notion-style boards usually only let you group by an enum-like property — select, status, checkbox. But a live table imported from an external engine often has no such column: a restaurant table might have plain-text cuisine and city and nothing else. So the Board opens grouping up.

The grouping engine already knew how to bucket any type — select and status become their options, a checkbox becomes checked/unchecked, and anything else groups by its distinct values. Boards simply stopped blocking those columns.

Dragging a card persists

Moving a card from one column to another is not a cosmetic reshuffle — it sets the grouped property on that record and writes it to the engine, exactly like editing the same cell in the grid.

• Drag Pad Thai from the French column onto Thai
• The record's cuisine value changes French → Thai
• The write persists — reload and the card stays put

Empty values are a real column too

When a row's grouped value is blank, the Board files it under a dedicated unassigned column. Dropping a card onto that column clears the value — so the board is a two-way editor, not just a viewer, even for emptiness.

Boards, tables and galleries are all just views over the same source — configure them from Dashboards & View Settings.

The Databases Navigator

The Databases panel is a left-sidebar rail item that lists every external database you are allowed to see and lets you open any of its tables as a live grid in one click. Discovery is read-only, so it works like auto-connect: if you can read a mount, it simply appears.

What it shows

• Every registered mount the tenant exposes, filtered to the ones you can access.

• Per-mount tables (with a column count) drawn from live schema introspection.

• Clear states when something is off: unconfigured, empty, or a per-mount error — so a broken connection is debuggable, not silent.

Click a row and the panel opens that table as a database tab — the same virtualized Notion grid used everywhere else.

Discovery goes through the bridge, not the gateway

The catalog, schema and rows are not fetched from the backend gateway by the browser — that route rejects the anonymous key with a 401. Instead the panel calls the bridge, which proxies server-side to the adapter registry and query-router with the real credentials:

GET /api/databases?tenant=<tenant>     → adapter registry (list of mounts)
GET /api/databases/<dbId>/schema        → query-router  (columns per table)
POST /api/databases/<dbId>/tables/<t>   → query-router  (rows / writes)

Discovery is scoped to you

The navigator is not a god-view of the tenant. What it returns is intersected with the databases your account can actually reach.

It scales to large tables

Opening a table does not choke on volume — the grid it hands you is virtualized, so a table with thousands of rows renders a small window of DOM nodes and streams the rest as you scroll (The Grid View).

Listing mounts and reading schema mutate nothing. Because discovery only ever reads, there is no destructive action to confirm — so the panel can populate itself the moment you open it, with writes still gated behind explicit edits.

Relations & Foreign Keys

A foreign key in a live table does not show up as a bare number. osionos renders it as a relation: a clickable tag carrying the title of the record it points to, just like a Notion linked-record property. Editing it means picking a related row, and what gets written back is the plain key value.

Two ways a link is discovered

Not every engine reports its foreign keys, so osionos finds them two ways:

1. Real constraints — Postgres and MySQL expose their foreign keys through the information schema, so those links are exact and authoritative.

2. Naming heuristic — SQLite, SQL Server, MongoDB and DynamoDB don't hand over constraint metadata, so a convention-based inference kicks in.

Resolving the title

Showing a link is only half the job — the grid also has to display the target record's name, which means the referenced rows have to be in hand.

Relations can cross database boundaries

A foreign key's target table sometimes lives in a different mount entirely — an IoT device.product_ref pointing at a products table in a separate commerce database.

Editing a relation

Picking a related record is friendlier than typing a number, and it stays write-safe:

So the reading experience is "linked records", but the stored value is always a correct, minimal foreign-key value — the source table never learns it is being presented as a relation.

Location columns get the same treatment as relations — see Places, Maps & Geocoding.

Places, Maps & Geocoding

A column full of city names is a location, not a dropdown. osionos recognises this, retypes such columns as place attributes, geocodes them to coordinates, and offers a Map view — all while writing only the plain place name back to the source table.

Auto-detected, not configured

When a live table loads, columns whose names read like places — city, country, region, province, location, place and friends — are retyped to the place type automatically. No setup, no picker.

Two-tier geocoding

Turning a name into lat/lng happens in two tiers, fast path first:

1. Offline centroids — bundled tables of country, region and major-city coordinates resolve common places instantly, with no network call.

2. Online lookup — anything the offline tables miss (a smaller town, a full street address) is resolved through the bridge's geocode endpoint, which queries OpenStreetMap Nominatim and returns a single best match.

The Map view

When a table has a place column, a Map view is offered automatically. It gathers the place values, resolves any that lack offline coordinates online, and drops a marker per row. A place that can't be resolved at all simply shows no marker rather than breaking the map.

What actually gets stored

This is the write-safety heart of the feature:

Location is one of several ways the interpretation layer re-reads engine data — see also Relations & Foreign Keys.

Record Sub-Items

Notion lets a database row expand into nested sub-items. osionos brings that to a live external record in any engine — a Postgres row, a MongoDB document, a DynamoDB item — and does it without writing to the source database at all.

A record becomes a page

Open a record and it gains an editable note page: it keeps its column values and becomes a document you can write in. Under that record you can attach hand-created child notes, or — where the engine allows — promote a note into a real child record.

Three ways to work with sub-items

1. In-page panel — open a record as a page and a Sub-items section lists its children, with inline "new sub-item" and (where possible) "new child record".

2. Inline nested rows — expand a record right in the grid. Sub-items render as real, column-aligned table rows (Notion's "nested in a toggle"): child records fill every column; note-only children show a title. A connector marker anchors on the title column, or the first visible column when the title is hidden.

3. Promote to a real child record — only offered when the table has a self-referencing foreign key (an org chart's manager_id, for example). Then "new child record" inserts an actual row into the engine.

Two id spaces, one deterministic map

Where a sub-item is created matters

Opening a sub-item

Clicking a freshly created sub-item used to do nothing, because the note wasn't yet registered in the page store. Now osionos registers the note first, then opens it — so a new sub-item is clickable immediately.

• Attach a note under any record, in any engine
• Expand a record inline as column-aligned child rows
• Promote to a real child record where a self-FK exists
• Nothing written to the source engine for pure notes

Dashboards & View Settings

Every view of a live database — table, board, chart, gallery, calendar — shares one settings surface. Dashboards assemble those views into a grid where each widget is itself a view, so a dashboard is a composition of the same building blocks, not a separate feature.

Widgets are views

A dashboard row holds up to four widgets, up to twelve in total, each one a live view rendered compactly. Switch between Edit and View modes, drag a widget to reflow the grid, and rename or hide any widget's title.

Picking and managing data sources

A view has a source picker backed by a catalog that composes three kinds of source into one list:

"Manage data sources" then gives Notion-style container semantics — a primary source plus linked and derived sources, each showing where it is used. A source you don't own is read-only: edits apply in the view but do not persist to a foreign engine.

Conditional colour

A row, card or chart series can be tinted by rule:

Global filters

A dashboard can filter across its widgets by property name and type, so one control narrows every view that shares that field — a simple cross-source filter, in the spirit of Notion's.

Automations run server-side

Rules that react to a write — set a property, send a notification, call a webhook — run in the query-router, not the browser:

• Stored server-side and evaluated on the write path
• Fire after both single-op and transactional writes
• A set property action re-enters the query once (no runaway chaining)
• Webhooks are HTTPS-only with a guard against private-host targets

The chart engine that powers dashboard widgets has its own page → Charts.

Charts

Any live database view can become a chart. Under the hood sits a small pure aggregation engine — no rendering, just grouping and maths — feeding a large gallery of chart presets. The same aggregation logic runs on both the client and the server, so the two paths agree.

The aggregation engine

Charts are computed, not hard-coded. The engine handles:

• Grouping — including multi-select and relation multi-membership.

• Aggregates — count, sum, average, min, max, median.

• Breakdown — a second dimension → stacked or multi-series.

• Date bucketing — auto, day, week, month, quarter, year.

• Shaping — sort modes, omit-zero, cumulative running totals.

• Caps — a ceiling on groups and sub-groups, with the overflow folded into an "Other" bucket so a chart never explodes into thousands of slices.

Two engines, one result

Chart presets render through two libraries, both consuming the same computed result:

Server truth for live data

Aggregating only the first few hundred sampled rows would lie about a 25,000-row table. So where the engine supports it, charts push the aggregation down to the database:

Colour by rule

Chart categories and series honour the same conditional-colour rules the tables and boards use, so a status that is red in the grid is red in the chart. See Dashboards & View Settings for how those rules are written.

Exporting a chart

A rendered chart can leave osionos three ways:

• PNG — a raster image of the chart
• SVG — the vector the chart already renders as
• CSV — the underlying aggregated numbers

No extra dependency is pulled in for this — export reuses the browser's own serialization and canvas.

Keeping grouping and maths as pure functions — separate from any renderer or network call — means the client sample path and the server "all rows" path can share the exact same sort, cap and cumulative logic. That shared core is what keeps the two paths in parity rather than quietly disagreeing.

Live-Write Resilience

Editing a live database means writing over a network to a real engine, where a write can occasionally fail. The hard problem is not the rare failure — it is making sure a single failed write cannot take your other edits down with it. This is the story of how osionos made live cell edits stick.

The symptom

Users saw their edits revert after about eight changes: a handful of edits, then cell write dropped after 8 failed attempts — reloading server truth, and cells snapping back to their old values.

The amplifier: one stuck write reverted everything

The retry policy itself was fine — a write retries on a server-side failure up to eight attempts with a growing back-off. The damage came from what happened on give-up.

The fix: reconcile one row, never the mount

The durable fix: one operation per cell

The failures traced back to a fragile multi-statement transaction path used for some engines, where a begin and an execute shared a pinned connection that could go stale in between.

Two guards that keep the fix honest

This is why the Board card-move and every grid edit persist reliably today.

People on a Live Database

The database machinery isn't only for external SQL — osionos turns it inward. The Settings → People panel is rebuilt as a set of live database views over the workspace's real social data: contacts, the org directory, groups, guests and members, each a Notion-style table or gallery with full read and write.

Every tab is a database view

The panel used to be a hand-rolled static table with dead tabs that showed a count of zero even when real data existed. Now each tab is a genuine database view bound to an existing data client — no new backend, just a projection over data that was already there.

Read projections, write through actions

There is a deliberate design choice here worth calling out.

This keeps a read-heavy panel from ever mistaking a refresh for an edit.

Identity from the real user base

The panel first looked "empty of anything relevant" because it was reading a sparse local cache of only the people who had logged into osionos.

Access to any of these views is still scoped per account — see Per-Account Database Isolation.

Per-Account Database Isolation

A workspace tool is only as trustworthy as its boundaries. osionos scopes every live-database request to the account making it: you see and touch only the databases your account belongs to, enforced on the server, not just hidden in the UI.

The relation that grants access

Access is not a flat allow-list — it follows a chain of memberships that already existed in the data model:

user
  └─ workspace member         (which workspaces am I in?)
       └─ workspace           (what does that workspace own?)
            └─ workspace database   (which mounts are linked here?)

Two doors that were closed

A security pass found two independent ways an account could over-reach, and shut both.

An empty navigator is the system working

Denials don't storm

A stale browser tab pointing at a database you can no longer access used to retry forever, hammering the server with 403s.

Messenger Overview

osionos grew from a Notion-style block editor into a full collaborative workspace, and the messenger is the social half of that. It feels like a LinkedIn thread for the message column and a WhatsApp panel for the conversation list — but every surface opens as a workspace tab, right next to your pages and databases.

What ships

• Channels & communities — grouped conversations, member-scoped.

• Direct messages — 1:1 threads with an opt-in end-to-end encryption seam.

• Rich media — images, video, files, links, and voice messages with a live waveform.

• Threads — reply under any message without derailing the main flow.

• @mentions — autocomplete that resolves against channel members.

• Unread & read state — badges, an unread divider, and a "new messages" pill.

• Search — membership-scoped full-text search across your messages.

• Video — self-hosted LiveKit rooms and an in-channel call panel.

How it fits together

The messenger never talks to the backend directly. Two transports do the work, and they must never be conflated:

 You  ──►  osionos UI  ──►  bridge (bridge-chat …)  ──►  grobase / Postgres
                │                     │
                │  live events        └─ server-side publish ──► Rust realtime gateway
                ▼                                                        │
        Kong /realtime/v1/ws  ◄──────────────────────────────────────────┘

The model, split for clarity

The channel view isn't one giant hook. It splits along responsibility — history loading, live subscription, send actions, and channel metadata are separate concerns, each testable on its own.

Start with Channels, or jump to Rich-media messages for the fun part.

Channels & Communities

A channel is a room. Membership decides who can read and write it — the messenger never shows you a channel you aren't a member of, and every read and write is scoped to your identity at the bridge.

The channel list

The left rail lists what you can see, in a deliberate order:

1. Communities — named collections of channels, pinned at the top.

2. Groups — multi-person channels below the communities.

3. Direct messages — 1:1 conversations (their own list — see Direct Messages).

Inside a channel

Opening a channel mounts the message column. It is built for long histories and fast scanning:

• Author grouping — consecutive messages from the same person collapse into one visual block, so a back-and-forth reads as a conversation, not a wall.

• Date dividers — a subtle separator marks each new day.

• Smart auto-scroll — you stick to the bottom while you're there, but scrolling up to read history doesn't yank you back down when a new message lands.

• A "new messages" pill — when you're scrolled up, a "↓ N new" chip tells you how many arrived and jumps you to them.

Drafts that survive

Sending

• Enter sends the message.

• Shift + Enter inserts a newline.

The composer is more than a text box — it opens a slash menu and a media toolbar. That's covered in Rich-media messages.

Direct Messages

Direct messages are the private, 1:1 side of the messenger. They live in their own list (dm-list) separate from channels, so a personal conversation never gets lost among the rooms.

Opening a conversation

You start a DM from the people directory or a person's profile. Under the hood a DM is just a two-member channel — which means it inherits everything channels already do: history, drafts, threads, media, mentions, and read state.

Blocking is enforced, not cosmetic

Opt-in end-to-end encryption

DMs carry an opt-in end-to-end encryption seam. When enabled for a conversation, messages are sealed on your device and opened on the recipient's — the bridge and database only ever see ciphertext.

• Keys are derived per conversation from an elliptic-curve exchange.

• The private key is non-extractable and stays on-device.

• Encryption is per-DM and opt-in — it is not on by default.

What a DM shares with channels

Next: the media you can actually send → Rich-media messages.

Rich-media Messages

The composer is where the messenger earns its keep. Beyond plain text it sends images, video, audio, files, and links — and captures voice messages with a real, tonality-tracking waveform.

Two ways in

There are two entry points to attaching media, and they complement each other:

1. The slash composer — type / to open a focused launcher: /image, /video, /audio, /url, /file.

2. The media toolbar — a row of buttons under the input: image, attach, GIF, emoji, and the microphone.

 ┌───────────────────────────────────────────────┐
 │  Type a message…                               │
 ├───────────────────────────────────────────────┤
 │  🖼  📎  GIF  🙂  🎙   ← media toolbar          │
 └───────────────────────────────────────────────┘
    /image  /video  /audio  /url  /file   ← slash menu

Voice messages

Voice isn't a single tap-and-send — it's a proper recording flow:

• Record — with live, real-amplitude bars that follow your voice.
• Pause / resume — the timer is pause-aware.
• Stop, then review — play it back before you commit.
• Send — or discard and try again.

The waveform you draw while recording is the same one the recipient sees, and it advances as the clip plays — a proper scrubber, not decoration.

The media gallery

Every conversation keeps a "Media, links & docs" gallery in its contact info, so a shared image or file from weeks ago is one click away instead of a scroll-hunt.

Links, GIFs, and emoji

• GIFs come from an in-app picker; the chosen GIF flows through the normal upload path (so it's stored and deduplicated like any attachment).

• Emoji insert from the toolbar picker.

The lightbox

Click an image and it opens full-screen: wheel-zoom anchored on the cursor, drag-to-pan, and keyboard controls (+ / - to zoom, arrows to pan, 0 to reset, Esc to close). It reuses the already-loaded image — no re-download.

Where the bytes live

Serving a private attachment requires your session, so media is never a naked public URL — see Security & UX hardening.

Threads

A busy channel turns into noise when every side-conversation happens inline. Threads fix that: reply under a message and the exchange collapses into a focused branch, leaving the main flow readable.

How a thread forms

Any message can be the root of a thread. Replies point back at that root, and a reply to a reply still resolves to the same root — a thread is always one level deep by design, never a nested tree.

 Main channel
 ├─ "Ship the fix?"            ← thread root
 │    💬 3 replies             ← reply count, live
 ├─ "Deploy went out"
 └─ "Standup at 10"
        └─ (open the root to see the 3 replies in a side panel)

The reply count

Each root carries a reply count that updates as replies land. On the message row it shows as a compact affordance — "💬 N replies" — and clicking it opens the thread.

The thread panel

Opening a thread doesn't navigate away. The thread panel slides in beside the channel, so you keep the room in view while you read and reply to the branch.

• The panel shows the root message, then its replies in order.

• Replying from the panel adds to the same thread.

• Closing it returns you to exactly where you were in the channel.

Threads and the rest of the messenger

• Threaded replies deliver in realtime like any message.

• They respect membership — you only see threads in channels you belong to.

• A reply can carry rich media, just like a top-level message.

Related: Rich-media messages · Realtime delivery.

@Mentions

Type @ and the messenger helps you name someone. Mentions turn a message into a directed signal — the person you named knows it was meant for them.

Autocomplete

As you type @, an inline picker suggests people, matching by handle. It reuses the workspace's people search, so the same directory that powers the rest of the app powers mentions too.

What a mention looks like

• In the composer, the picked name becomes a @handle chip.

• In the rendered message, the mention renders as an accented @handle.

• A message that mentions you gets its whole row accented, so it stands out when you're scanning back through history.

The parsing is careful

Mentions drive notifications

A resolved mention is one of the events that produces a notification for the named person — alongside replies and new DMs. Notifications are deduplicated and never fire for your own actions.

Quick reference

• @ opens autocomplete
• Resolves against channel members only
• Self-mentions are dropped
• Per-message mention cap
• Cross-channel mentions — not supported by design

See how the named person finds the message later → Message search.

Unread & Read Receipts

Nothing kills a chat app faster than not knowing what you've missed. The messenger tracks read state per channel, per person, and surfaces it in three places.

Unread badges

Each channel and DM in the sidebar carries an unread badge — a live count of messages you haven't seen. The counts seed when the app loads and update as messages arrive, so the rail is an at-a-glance inbox.

The unread divider

Open a channel with unread messages and a divider marks the exact line where "already read" ends and "new to you" begins. You drop straight into the first thing you missed, not the top or the bottom.

   … earlier messages you've seen …
 ──────────  New messages  ──────────   ← the unread divider
   the first message you haven't read
   and everything after it

The "new messages" pill

If you're scrolled up reading history when new messages land, a "↓ N new" pill appears. Click it to jump to the newest and clear the backlog. (This is the same pill described in Channels — it does double duty for unread.)

Read markers

When you view a channel, your read position advances — which is what powers everyone else's read state and clears your own badge. Reading is the act that marks messages read; there's no separate "mark as read" chore.

The lifecycle

1. A message arrives in a channel you're a member of.

2. Your unread count for that channel increments.

3. You open the channel — the divider shows where you left off.

4. Viewing it advances your read marker.

5. The badge clears.

Related: Realtime delivery keeps these counts live.

Message Search

Conversation history is only useful if you can find things in it. The messenger ships full-text search backed by a proper text index, scoped tightly to what you're allowed to see.

Where you search from

A search control lives in the channel header. Open it and you get a query box with a scope toggle:

• This channel — search only the current conversation.

• Everywhere — search across all the channels you belong to.

Results you can act on

Matches come back as snippets — a highlighted excerpt with the author and channel — so you can recognise the message before you open it. Clicking a result takes you to it in context.

Membership is the hard boundary

What isn't searchable

In short

• Full-text, index-backed
• This-channel or everywhere
• Membership-scoped — no cross-channel leaks
• Highlighted snippets with author + channel
• Encrypted DM contents — not indexed, by design

Realtime Delivery

When someone sends a message, you should see it now — not on your next refresh. The messenger delivers over a WebSocket, but it's engineered so that a missing token or a flaky connection degrades instead of breaking.

Two separate transports

How an event travels

 Sender ──► bridge ──► write to Postgres
                 └──► publishes the event server-side
                          to the Rust realtime gateway
                                     │
                                     ▼
   Recipient's browser  ◄── Kong /realtime/v1/ws ── event fan-out

The bridge publishes each event server-side (best-effort) to the Rust realtime gateway, which fans it out to subscribed clients over the Kong socket. The client subscribes per channel and per user, so it hears new messages, mentions, and notifications on the topics that concern it.

Graceful degradation

The live socket is gated on a valid session credential. When one isn't available, the client doesn't fail — it falls back to polling on a short interval. You still get your messages; they just arrive on the poll instead of the instant push.

The same-tab echo

Underneath the network transport, a same-tab broadcast always runs. When you send a message, other views in your own browser hear it immediately over an in-browser channel — additive to the network path, never a replacement for it.

De-duplication

Because a message can reach you two ways (the send response and the live echo), the client de-duplicates by message id — first arrival wins, the second is dropped. You never see a doubled message, even when the socket beats the HTTP response.

Related: Unread & read receipts ride the same live events.

Video Rooms (LiveKit)

The messenger's video is self-hosted. There's no third-party meeting vendor — osionos runs its own LiveKit media server as a compose service, and the app connects to it directly.

Getting into a room

Joining is a two-step handshake:

1. The client asks the bridge for a room grant — POST /api/rtc/token (served by bridge-rtc). This mints a scoped LiveKit access token.

2. With the grant, livekit-client connects to the local media server over WebRTC at the loopback address ws://127.0.0.1:7880.

 osionos ──► bridge  POST /api/rtc/token  ──► LiveKit grant (scoped token)
     │
     └──► livekit-client ──► ws://127.0.0.1:7880 (self-hosted SFU) ──► peers

In the room

• Active-speaker ring — the tile of whoever's talking gets a highlight, so a busy room is easy to follow.

• Raise hand — a ✋ badge on your tile, signalled peer-to-peer over the room's data channel (the grant includes data-publish permission).

• Device picker — switch camera and microphone mid-call by enumerating devices and swapping the active one without leaving the room.

Loaded only when you need it

Where the room lives

Video can open as its own video-room surface, or embed directly inside a channel as a call panel — same media stack, different framing. The embedded form is covered in In-channel call panel.

In-channel Call Panel

Sometimes a message thread just needs to become a call. The call panel lets a channel spin up a live video room in place, so nobody has to context-switch to a separate meeting surface.

Same stack, embedded framing

The call panel isn't a second video implementation — it's the same LiveKit media stack described in Video Rooms, rendered inside the channel instead of as a standalone room.

• Same grant flow (POST /api/rtc/token via bridge-rtc).

• Same self-hosted media server over loopback WebRTC.

• Same in-room features: active-speaker highlighting, raise-hand, device switching.

Loaded on demand

 Channel view
 ├─ message column      ← always mounted, lightweight
 └─ [ Start call ] ─────► call panel mounts
                          └─► lazy-loads livekit-client
                          └─► joins the room, tiles appear inline

When to use which

Both connect to the same room infrastructure, so participants can be in the same call regardless of which entry point they used.

Recap

• Video without leaving the channel
• Reuses the LiveKit grant + media stack
• Deep lazy import keeps the warm bundle small
• Interoperates with the standalone video room

Security & UX Hardening

A messenger is a wide, untrusted surface — user text, uploads, links, and identities all flow through it. The osionos messenger treats the bridge as the trust boundary and hardens every edge that touches it.

Rate limiting at the door

Bursty or abusive traffic is capped with token-bucket rate limits on the sensitive operations — sending messages, reacting, and uploading each have their own budget. Exceed it and the bridge answers 429 rather than absorbing the flood.

Everything is membership-scoped

Uploads are sanitized

• Metadata is sanitized before it's stored — dimensions, durations, and waveform data are clamped to sane bounds, so a crafted payload can't smuggle oversized or malformed metadata through.

• Size ceilings are enforced per media type on the way in.

• Images are compressed client-side before upload.

• Serving a private attachment requires your session — media is never a naked public URL that anyone with the link could fetch.

Link previews are SSRF-guarded

Blocks and E2E

• A block is enforced with a 403 at the bridge, not hidden in the client (Direct Messages).

• End-to-end encrypted DMs use a non-extractable, on-device key — the server only ever sees ciphertext, at the deliberate cost of search and previews.

The UX side of "solid"

Hardening isn't only security — it's also the friction the messenger removes:

Back to the start → Messenger Overview.

The Social Layer

osionos started life as a Notion-style block editor. It grew a full social network: the surfaces you'd expect from LinkedIn and WhatsApp — a people directory, connection requests, 1:1 and group chat with read receipts, an activity feed, live presence, and profiles — all wired into the same workspace shell, each opening as a tab pane.

The surfaces

What shipped

• Connections with a request/accept lifecycle and block/report
• A global people directory with trigram, semantic, and full-text search
• 1:1 DMs, group chat, read/seen receipts, and typing indicators
• Live presence (a 45-second heartbeat marks you online)
• Realtime delivery over the Rust gateway, degrading to polling
• A pinned AI contact dock

The data model

The social schema is additive. models/osionos-social-migration.sql adds the connections, message_receipts, user_blocks, user_reports, and join_requests tables, and extends identities with a username, a directory_opt_out flag, a bio_embedding vector(384), and a search_doc tsvector. It leans on two Postgres extensions — pg_trgm for fuzzy name matching and pgvector for semantic search.

Where to go next

• Connections & follows — the request lifecycle.

• The people directory — how search actually works.

• DMs, channels & the feed — the three messaging shapes.

• Shared live collaboration — co-presence.

Connections & Follows

Connecting with someone in osionos works like a LinkedIn invite: you send a request, they accept, and you become mutual connections. There is no silent one-way follow — every edge is consented on both sides.

The lifecycle

1. You send a request → the edge is pending.

2. The other person accepts → accepted (you are now connected).

3. …or declines → declined.

4. You can withdraw a pending request → withdrawn.

A withdrawn or declined edge is not a dead end — sending again reactivates the same row back to pending, so the addressee gets a fresh invitation to accept.

        send                accept
  ──────────────►  pending ─────────► accepted
                     │  ▲
            withdraw │  │ resend
                     ▼  │
                 withdrawn / declined

The endpoints

Every route lives on the bridge and is scoped to the caller's session token.

The edge shape

Each edge carries a nested peer object — the person on the other side — not a bare id:

{
  "connection": {
    "id": "…",
    "status": "pending",
    "peer": { "id": "…", "name": "Amara Diallo", "avatar": "…" }
  }
}

When a request is created, the bridge publishes a connection_requested event to the addressee's personal topic (user:<id>), so their notification bell lights up live without a refresh.

A connection is a single row keyed by an unordered pair of user ids, so A→B and B→A resolve to the same edge. A duplicate request only conflicts (409) while the edge is pending or accepted; once it's withdrawn or declined, sending again simply flips it back to pending.

Blocking and reporting are separate, deliberate actions — see POST /api/social/reports and DELETE /api/social/blocks.

The People Directory

The directory is how you find people to connect with. Type a name, a username, or a phrase from someone's headline, and results rank across three kinds of search working together.

Three ways to match

The fuzzy filter runs ILIKE across display_name, username, and the headline, while the search_doc column drives a websearch_to_tsquery full-text pass. Semantic matching compares a 384-dimension bio_embedding.

One view, not a scatter of tables

Search reads a single Postgres view — public.osionos_people_directory — rather than joining raw tables per query. The view stitches together the authoritative user base from three sources:

public.users              → id, name, username
public.user_profiles      → display_name, avatar_url
osionos_bridge_identities → headline, last_seen_at, directory_opt_out
        │
        ▼
public.osionos_people_directory   (one authorized read surface)

local identity cache) is what made search return the real 42 user base instead of only the handful of people who had logged in.

Presence and opt-out

• Online is derived from last_seen_at — a fresh heartbeat within the last ~90 seconds shows a green dot.

• Opt-out is honored: anyone with directory_opt_out = true is filtered from results entirely.

Search endpoint: GET /api/directory/search.

The Feed

The feed is the workspace's activity stream — a scrollable surface of what people are doing and sharing, distinct from the point-to-point delivery of DMs and channels. Where a DM is a conversation, the feed is a broadcast timeline.

How it fits

The feed is one of osionos's realtime surfaces, alongside chat and the live-DB views. It is served by the bridge (bridge-feed) and, like chat, gets its freshness from the Rust realtime gateway — falling back to periodic polling when no realtime credential is available.

Interacting

The feed carries an action bar (FeedActionBar) for reacting to and engaging with items. An individual item can be removed via the bridge:

Feed as a view preset

Because osionos treats views as first-class, an organization can present its feed as a tailored database view. In the agency simulation, for instance, a reports feed is one of the packaged view presets — the same feed machinery, themed for a specific team's workflow.

Groups

A group is a named, many-person room. Where a DM is opened ad-hoc between two people, a group has an identity — an avatar, a description, and an explicit membership — and everyone in it sees the same conversation.

Two flavours

osionos ships two group-like constructs that share the chat plumbing:

• Group channels — a channel of kind = 'group', created via the chat bridge. Extended with an avatar and a description on top of the base channel schema.

• Communities — larger, standalone spaces served by their own bridge module (bridge-communities), listed and joined separately.

Both appear in the People panel's Groups tab, grouped by kind, so a single surface lists the rooms you belong to regardless of which flavour they are.

Membership is the gate

Access to a group's messages is governed by membership rows (osionos_channel_members), not by which workspace you happen to be in. If you're a member you see the history and receive live messages; if you're not, the listing and the messages simply aren't returned to you.

What a group conversation carries

Creating one

• Pick a name (and optionally an avatar + description)
• Create it — createChannel for a group channel, or createCommunity
• Add members — membership rows control who's in
• Invite-by-link and public join flows vary by construct

Profiles & Presence

Every person has a profile page, reachable from the directory or from any mention of them. It's the canonical "who is this" surface: their name, avatar, headline, and a connect action.

What a profile shows

The profile widget (widgets/profile-page, ProfileView) also hosts avatar upload (ImageAvatarUpload → POST /api/profile/avatar).

Presence is a heartbeat

Presence isn't guessed — it's measured. While your tab is open, a refcounted singleton posts a heartbeat every ~45 seconds, which bumps last_seen_at. Anyone whose last heartbeat landed within the online window shows as online.

  your open tab ──(every ~45s)──► POST /api/profile/heartbeat
                                        │
                                        ▼
                          osionos_bridge_identities.last_seen_at
                                        │
                     online  ⇔  last_seen_at within ~90s

Endpoints: POST /api/profile/avatar, POST /api/profile/heartbeat. Profile route: /people/:userId.

"Shared" Live Collaboration

A Shared space adds live co-presence to a workspace: you see who else is here, where their keyboard caret is, what they're focused on, and you can summon them to a page. It is an awareness layer, not a co-editing engine.

What travels between clients

Exactly one message type per event, validated at the boundary before it reaches any reducer or the render path. Mouse position is never sent.

type CollabEvent =
  | { t: 'caret';     actor: string; seq: number; caret: CaretState }
  | { t: 'selection'; actor: string; seq: number; range: SelectionRange | null }
  | { t: 'focus';     actor: string; seq: number; elementId: string | null }
  | { t: 'activity';  actor: string; seq: number; kind: ActivityKind; targetId: string }
  | { t: 'nav';       actor: string; seq: number; route: string }
  | { t: 'note';      actor: string; noteId: string; op: NoteOp; anchor: Anchor }
  | { t: 'file';      actor: string; fileId: string; op: FileOp; name: string };

The building blocks

• Presence roster — avatars of who's in the space, each assigned a stable, WCAG-safe colour (var(--collab-1..8)).

• Remote carets — a portal layer paints each person's keyboard caret; it never re-renders the editable content.

• Active-control pulse — a soft pulse marks what a peer is focused on.

• Summon — tap a peer to ask them to come to your page; they must consent (a prompt with a 30-second auto-decline). Nothing moves anyone without a tap.

• Shared files — bytes upload durably first, then an ephemeral announce goes out. No file bytes ever cross the presence channel.

Built hexagonally

The design keeps the transport at arm's length. The domain and the collab store depend on a single port (realtimeTransport.port.ts) and nothing else; exactly one adapter binds that port to the grobase realtime WebSocket. Swap the transport and the domain never notices.

  collab domain / store ──► realtimeTransport.port  (transport-free)
                                     ▲
                                     │  the ONE adapter
                          realtimeTransportGrobase.adapter
                                     │
                            grobase realtime gateway (WS)

Next: how co-presence maps onto the gateway.

Namespace Isolation & the Collab Gate

Live co-presence is only safe if a non-member can't quietly subscribe and watch. Getting that guarantee right took a specific fix at two layers — the bridge that mints tokens, and the Rust gateway that authorizes them.

The gap it closes

The fix, in two parts

1 — A membership-gated, scoped token (bridge). The bridge mints a short realtime token whose namespaces claim is exactly the spaces you belong to. A collab:<spaceId> topic has no /, so its whole string is its namespace — meaning the token grants precisely one space, nothing wider.

2 — Protected namespaces (gateway). A "*" wildcard grant no longer covers a configured protected prefix. Reaching a protected namespace requires an exact grant. Members already present their scoped ["collab:<id>"] token, so they're unaffected; everyone else loses wildcard reach into collab: — and only collab:.

REALTIME_PROTECTED_NAMESPACES=collab:

Verified behaviour

With REALTIME_PROTECTED_NAMESPACES=collab: set, a live WebSocket smoke test confirmed all four cases:

• wildcard token → a collab: topic — denied
• member-scoped token → its own collab: topic — subscribed
• wildcard token → chat / live-DB topics — still works (unaffected)
• member token → a different collab space — denied

ABAC Permission Masks

Beyond "can you open this page", an organization needs "which columns can you see". osionos answers that with attribute-based access control (ABAC) and per-field masks, proven end-to-end by the agency org simulation.

Roles and policies

The agency tenant is provisioned with a real policy set:

Policies are compiled into a bundle the data plane can evaluate. osionos fetches the current bundle from the control plane:

GET /permissions/bundles/latest   →   the Rust evaluator (parity proven)

The chmod-cycle UI

Permissions are edited in a matrix in Settings, using a chmod-style cycle — a cell toggles through access levels the way chmod cycles Unix bits — plus the field masks and a View-as control that re-renders the surface as another role would see it. The point of View-as is to check your work: apply a mask, then look through someone else's eyes before you trust it.

How a decision flows

1. A role carries attributes; a resource carries attributes.

2. A policy in the bundle matches the pair and yields allow/deny + a field mask.

3. The Rust evaluator returns the decision — proven at parity with the reference.

4. The UI renders only the fields the mask permits.

See it running in the agency org simulation.

DMs vs Channels vs Feed

osionos has three ways to reach people, and it's worth being precise about which is which. They share the bridge and the realtime gateway, but their audience and membership model differ.

At a glance

DMs — reach anyone

Opening a DM starts (or resumes) a 1:1 channel with the person you pick. Access is governed by channel membership, not by a shared workspace — so you can DM someone even if you have no workspace in common. If there's no shared workspace, the conversation is simply anchored to your own.

Channels & groups — reach a room

A channel is a named room with an explicit member list. Group channels add an avatar and a description. Everyone in the room sees the same history and receives live messages; receipts track who's seen what. See Groups.

Feed — see what's happening

The feed isn't a conversation you send into; it's a timeline you watch. It surfaces activity across a scope and, like chat, refreshes over realtime with a polling fallback. See The feed.

The Agency Org Simulation

To prove the whole stack hangs together — social, ABAC, chat, video, feed, wikis — osionos ships a lived-in organization: the Binocle Intelligence Agency, an owner plus twenty employees, with real accounts, real data, and real policies.

What exists

• A live tenant (agency) with ~11 tables and ~950 rows in its own database.

• 21 gotrue accounts — one owner, twenty employees — each a real login.

• An org workspace, plus ABAC: 11 agency:* roles and 48 policies with field masks (see ABAC permission masks).

• Chat channels, DMs, a feed, self-hosted video rooms, and wiki pages with live database embeds.

• Packaged view presets — a cases board, a timeline, a dashboard, a locations map, a reports feed, and an evidence gallery.

Running it

The whole simulation is driven from make targets at the repo root:

make agency-all              # provision + seed the whole org
make agency-verify           # foundation gate
make agency-verify-platform  # platform gate (multiple sections)
make agency-sim              # the Playwright scenario suite

The verification result

The two WARNs are architectural and documented, not failures:

• 10 scenarios cover accounts, connections, chat, video, permissions, presets
• Field masks enforce at the decision endpoint, but live reads use the tenant key — so per-user data-plane masking is not yet exercised
• The cross-client live-edit assert is verified at the event level, not the rendered embed

Nothing here is a mock: 21 real accounts, ~950 seeded rows, a live tenant, and a policy bundle the Rust evaluator enforces at parity. The simulation is the proof.

Co-presence on the Realtime Gateway

The awareness layer speaks one protocol: the Rust realtime-agnostic gateway's JSON WebSocket frames. This is how each co-presence concept lands on a real frame.

The protocol frames

The gateway defines a fixed set of tagged JSON frames. Clients send some; the server sends others.

Each frame's payload is capped at 64 KB.

The mapping

Co-presence concepts map cleanly — and where the gateway lacks a primitive, the adapter synthesizes one instead of inventing a wire feature:

The handshake

The one adapter follows a strict order — auth first, then subscribe to the space's topic, then start tracking presence:

open socket
  └─► AUTH { token }                        (MUST be the first frame)
        └─► AUTH_OK
              └─► SUBSCRIBE { topic: "collab:<spaceId>" }
                    └─► SUBSCRIBED
                          └─► TRACK { topic, meta: presence }
                                └─► server PRESENCE snapshots flow in

The topic is always collab:<spaceId>. The token comes from the membership-gated bridge endpoint, so the subscribe is scoped to exactly that one space (see Namespace isolation & the collab gate).

Resilience

If the socket drops, the adapter reconnects with capped exponential backoff, then re-auths, re-subscribes, re-tracks presence, and flushes any queued outbound frames — so a blip doesn't strand you as a ghost in the roster.

The Workspace Shell

osionos started life as a Notion-style block editor and grew into a full collaborative workspace. The chrome around the editor is modelled on an IDE: a persistent top bar, a sidebar tree, and a content area that is a splittable grid of tabbed panes rather than one active document.

This section documents that shell — the pieces you interact with before you type a single block.

The three regions

What makes it "IDE-like"

• Everything opens as a tab. A page, a folder, the Home dashboard, the Trash, a database view, a chat channel, a profile, the BaaS console — each is a tab.kind rendered inside a pane.

• Panes split like editor groups. Drag a tab (or a sidebar row) to a pane's edge and it splits; drop it in the centre and it becomes a tab there.

• State survives reload. The whole layout tree is persisted to localStorage, so your split arrangement comes back when you return.

No router under the hood

There is no react-router. "Routing" is a zustand store — the layout tree — and a dispatch chain that decides what each tab renders. The URL is used only for deep-links (like ?home= or a bridge_token hand-off), never for navigation.

Read next → The layout tree, then the splittable grid.

The Tab / Pane Layout Tree

osionos has no react-router. What would be routing in a normal single-page app is instead a layout tree held in a zustand store, plus a dispatch chain that maps each open tab to a view.

The store

The render source of truth is the useWorkspaceLayout store — a small module under src/widgets/workspace-grid/model/:

The tree shape

Every node is one of two things:

// a leaf: a strip of tabs with one active tab
type PaneNode = { tabs: Tab[]; activeTabId: string };

// a branch: children laid out in a row or column
type SplitNode = {
  direction: "row" | "column";
  children: LayoutNode[];
  sizes: number[];
};

Splitting a pane replaces a PaneNode with a SplitNode whose children are the old pane and the new one. Closing the last tab in a pane collapses it back out of the tree.

The dispatch chain

A tab does not know how to render itself — a single component decides. In widgets/page-renderer/ui/PaneContent.tsx, PaneContentImpl runs an if (tab.kind === …) guard chain:

• home → the Home dashboard
• folder → a folder listing
• trash → the Trash
• database → a live database view
• profile · console · channel → collab / BaaS surfaces
• default → an editable page (PageTabView)

Two sources of truth, kept in sync

For historical reasons "the open page" lives in two places: the layout store and the legacy usePageStore.activePage. They mirror each other, in both directions but through two different seams:

1. tab → activePage via layoutSync.ts:mirrorActiveTab (fired from the store's commit).

2. activePage → tab via syncFromActivePage + pageToTab.ts:activePageToTab, committed with mirror=false so the sync does not loop back.

The Splittable Editor Grid

The whole content area of osionos is one recursive widget: widgets/workspace-grid/. It renders the layout tree as a grid of tabbed panes you can split, resize, and shuffle tabs between — the same muscle memory as splitting editor groups in an IDE.

The component tree

WorkspaceGrid  (recursive over the layout tree)
└─ PaneView
   ├─ TabStrip ── TabButton …      (drag tabs between panes)
   ├─ PaneContent                  (the dispatch chain)
   ├─ PaneDropOverlay              (centre + 4 edge drop zones)
   └─ active-pane ring
PaneSplitter  (pointer-drag resize between siblings)

MainContent.tsx stays deliberately thin: it keeps the Home dashboard seed effect and renders <WorkspaceGrid/>.

Splitting and moving

Dropping decides the outcome, and paneDropZone.ts:computeDropZone does the geometry:

• Centre of a pane → the tab is added to that pane's strip.

• One of the 4 edges → the pane splits and the tab opens in the new half.

Tabs carry a MIME type (application/x-osionos-tab) so they can be dragged between panes. Sidebar rows join the same choreography: a page row sets text/plain=pageId, so dropping a sidebar file on a pane centre opens a new tab and dropping it on an edge splits.

Only the focused pane runs a live editor

Mounting a full editor in every visible split would be ruinous. So the grid is selective, driven by the focus check in PaneContent.tsx:

const isFocusedPane = !paneId || activePaneId === paneId;

• The focused pane mounts the live, editable page (LazyOsionosPage).

• Unfocused splits render a cheap read-only preview (PageBlocksRenderer).

Per-pane editor / database / channel / console chunks are code-split via React.lazy in widgets/page-renderer/ui/lazyViews.tsx, always through deep import paths — importing a widget barrel would staple the whole ~1.1 MB editor onto the warm chunk.

Resize is DOM-only

Dragging a PaneSplitter used to commit the entire layout tree to the store — and serialize it to localStorage — on every pointer-move, which could crash the app with two views of the same page open. It was rebuilt to be DOM-only:

• drag writes flexBasis straight onto the two adjacent cells
• the store is touched once, on pointer-up
• off-screen cells get content-visibility: auto only during the drag
• regression bench: scripts/pane-resize-bench.mjs (12-pane seed, real drags)

The Global Top Bar

Across the top of the osionos shell sits a VSCode-style chrome bar, mounted in App.tsx above the content. It is its own widget, widgets/top-bar/, and it appears on both surfaces: the osionos editor and the opposite-osiris website.

What's on the bar

Left to right:

1. Logo

2. Menus — File · Edit · Selection · View · Help (native Electron menu sync on the desktop build)

3. Centre search / command bar — page search by default; type > to switch to command mode

4. Update button — see the Update/rebuild button

5. Window controls — minimise / maximise / close, desktop only

Widget layout

The widget splits cleanly into model and UI:

Its own theme tokens — --osio-topbar-{h,bg,border} — were added to global.css, so the bar restyles with the rest of the theme rather than carrying hard-coded colours.

Search that reaches your whole workspace

The centre bar started as a client-side search over the pages already loaded in the store. That missed most real content: nested child pages are not all held in the client cache, so search "only found Untitled".

It was moved server-side:

Window controls only on desktop

WindowControls renders only when running inside the Electron desktop shell (isDesktop()), where it calls the already-wired IPC bridge — window.osionosDesktop.{minimize, toggleMaximize, close}. In the browser it renders nothing.

Continue → The ⌘K command palette.

The ⌘K Command Palette

The top bar's centre input is a two-in-one: a page search and a command palette. Which one you get depends on a single character.

Two modes, one input

The > prefix is the switch — the same convention VSCode uses. Because command mode is detected only inside this input, it never collides with the editor's in-document slash (/) menu or its formatting chords.

Opening it

• ⌘K (or Ctrl K) — focus the bar in search mode

• ⌘⇧P — open it straight into command mode

⌘K was chosen precisely because it was free: the editor already owns ⌘B / ⌘I / ⌘U / ⌘E, ⌘⇧L (link), and ⌘⇧X, so the palette claims a chord that steps on nothing.

One result shape

Search and commands render through a single PaletteResult shape. That is the design's leverage point:

// The bar renders results, not sources. Swap the source,
// keep the shape, and the UI doesn't change.
interface PaletteResult {
  id: string;
  title: string;
  // …kind, icon, and an action to run on select
}

Behaviour

• debounced remote query (so typing doesn't flood the bridge)
• an instant local fallback while the network is in flight
• a visible "Searching…" state
• keyboard-first selection

The palette's model lives in widgets/top-bar/model/ (commands.ts, search.ts, usePalette.ts); the UI is TopBarSearch.

Sidebar Tree Drag-and-Drop

The sidebar is a live tree of your workspace pages and folders, and it supports HTML5 drag-and-drop reparenting — drag a page onto a folder to nest it, or between two rows to make it a sibling.

The moving parts

• model/sidebarTreeDnd.ts — a tiny zustand store holding the drag state: draggingId, dropTargetId, dropMode (inside | before | after), and a collapseToken (bumped to collapse everything at once).

• ui/usePageRowDnd.ts — a per-row hook that runs the drop-zone math and, on drop, calls the store's movePage.

• ui/PageTreeItem.tsx — the row itself: the label <button> is the drag source, the outer <div> is the drop target.

Where you drop decides what happens

The hook's computeDropMode reads the pointer's vertical position over a row:

┌──────────────────────────┐
│  top 30%   → before      │   ← sibling, above
│                          │
│  middle 40% → inside      │   ← child of this row
│                          │
│  bottom 30% → after      │   ← sibling, below
└──────────────────────────┘

Visually: an inside target tints and rings the whole row; before / after draw a blue insertion line.

Spring-loaded folders

Hover a collapsed folder mid-drag and hold for 650 ms — it springs open so you can drop deeper without letting go. The collapse-all toolbar button works the other way, broadcasting a collapseToken that every row listens for:

useEffect(() => setExpanded(false), [collapseToken]);

Moves are cycle-safe

movePage runs isValidMove first, which blocks two illegal moves:

1. dropping a node onto itself, and

2. dropping a node into its own descendant (which would orphan the subtree).

Everything under the moved node follows for free, because children are keyed on parentPageId — reparenting the node reparents the whole subtree.

The toolbar

SidebarTreeToolbar.tsx replaced the old ··· overflow on the Private and Shared sections with four explicit IconButtons:

Home Variants

Home in osionos is not a single fixed page. It is a kind:"home" tab (opened by the Home button in the shell) that can present one of several variants, backed by the widgets/home-variants widget.

The four faces

Picking a variant

The variant is chosen by a deep-link query parameter:

/?home=dashboard   →  the curated dashboard
/?home=graph       →  the force graph
/?home=database    →  a live database surface
/?home=workspace   →  the workspace overview

These four values are exactly what the Lighthouse gate probes — the perf script scripts/lighthouse-categories.mjs walks /?home=dashboard|graph|database|workspace across mobile and desktop and fails if any category dips below 90.

Why variants at all

Deep-linking details → Deep-links.

The Default Home

The default Home variant — dashboard — is not a hard-coded screen. It is an editable surface:"home" layout-block canvas: real blocks you can rearrange, seeded on first load and re-seeded when the layout version bumps.

The seed is built by createHomeLayout / createHomeLayoutContent (in widgets/database-view/model/databaseViewCatalog.ts) and mounted from MainContent.tsx, gated by homeDashboardNeedsRefresh against a HOME_DASHBOARD_VERSION constant.

The six sections

1. Greeting — a heading_1 that reads the time of day and the active persona.

2. Recently visited — a horizontal carousel of recent pages.

3. Learn — a carousel of learning material.

4. Upcoming events — a list view.

5. Home views launcher — a new home_views block (HomeViewsBlock): curated views grouped by database, separated by dividers, each row carrying a status pill and opening that exact view.

6. Featured templates — a carousel of starter templates.

Reusable tools that fell out of it

Building Home upgraded several primitives that any page can now use:

Featured templates

Six starter templates ship as their own copies (never Notion's text), themed with --osio-* tokens, seeded as isTemplate pages:

• Student dashboard
• To-do list
• Class notes
• Grade calculator — with a real formula column, prop("Weight") * prop("Score") / 100
• Club homepage
• Resume

Marketplace & Template System

osionos ships a VS Code-style Marketplace: developers add apps, users browse and install them, and each app opens as a rich detail page. The whole thing reuses the workspace's own primitives — records are pages.

Apps are pages

Each marketplace app is a child page in osionos_pages with a databaseId. It opens full-page through the normal database-block path (DatabaseBlock.tsx → NotionPage.tsx) and carries child sub-pages — Details · Features · Changelog · Installation · Categories · Resources — becoming read-only once published.

The catalog is a shared, system-owned workspace, read across workspaces via a service-role bridge endpoint:

The header-template engine

Instead of one fixed page header, a marketplace app renders a data-driven header. The engine lives in entities/page/model/ (headerTemplate.ts, recordTemplate.ts, templateRegistry.ts):

HeaderTemplate
└─ regions:  aside | main | meta | actions
   └─ slots:  media · title · author · link · stat · rating · text · badge · action
      └─ each slot binds a property key or a core field

The registry is keyed by databaseId; a null entry falls back to the classic header. PageHeader.tsx early-returns the TemplateHeader when one resolves.

Functional install

Installing is not cosmetic — apps actually launch. An installed app opens as a kind:"embed" iframe tab (EmbedAppView) at its launch URL, and the sidebar + activity rail grow install-driven launchers.

Install is a three-state control:

• Install → then Open / Deactivate / Uninstall
• Auto-Update toggle
• Activate again when deactivated

Three apps ship in the seed: Mail, Calendar, and Desktop — each with its six child sub-pages and a real install count (no fabricated ratings or downloads).

The bridge surface

The modular bridge exposes the marketplace over HTTP:

Applying a Database Template by Default

A workspace database can carry templates — real osionos pages flagged isTemplate, one of them marked isDefaultTemplate. The promise is simple: click + New and your default template's content is there, not a blank page. Getting that promise to hold everywhere took a fix.

How templates are stored

Templates are ordinary pages, and the live osionos_pages table already has the columns:

The bridge persists and returns these, and /api/pages/all lists with no is_template filter, so templates reload with the rest of the tree.

The controller

The split + New button (TopBarActions.tsx) shows a chevron → a TemplatesDropdown ("Templates for <db>") only when a templates controller is present. WorkspaceDatabaseBlock.tsx provides that controller via useWorkspaceTemplatesController() — but only for workspace pages-databases.

The bug: in-grid "+ New" bypassed the default

The top-bar split button applied the default correctly, but every view's own in-grid "+ New" — Table, Board, List, Gallery, Feed, Map — called the store's addPage(database.id) directly, skipping the controller. Result: blank pages, "as always".

The fix

A new hook, components/views/useDefaultTemplateCreate.ts, wraps the blank create:

// runs the default template when one exists, else a blank create
const create = useDefaultTemplateCreate(blankCreate);

• wired into the generic view footers
• context-specific creates (board column, calendar day, timeline start) stay blank on purpose — they pre-fill their own props
• a null controller (live / standalone databases) → blank, unchanged

Template content itself was already sound: createPageFromTemplate awaits fetchPageContent, then instantiateTemplateContent clones the blocks and resets placeholders.

A payload gotcha fixed alongside

Saving a page config could hit 413 Payload Too Large, because a PageConfig carries versions[] and translations[] with full block snapshots:

• pageConfigStore.ts gained shrinkConfigForApi() — over a 5 MB soft limit it sheds version and non-active translation content (settings always sync).

• the bridge's JSON body limit was raised from 2 MB to 6 MB, so a config between those two thresholds no longer 413s.

Folders & Trash

Two navigational surfaces — folders and the Trash — are not separate screens bolted onto the app. Each is a tab.kind in the layout tree, opened into a pane and rendered by the same dispatch chain as everything else.

Folders

Dragging a folder from the sidebar onto a pane opens a folder tab, rendered by page-renderer/ui/FolderTabView.tsx. It is a readable listing of the folder's children, folders first. Click a child and it opens in the same pane:

openTab(pageEntryToTab(child), paneId);

A few rules make folders behave as their own kind:

• pageEntryToTab returns kind:"folder" when the entry's surface === "folder".

• tabToActivePage returns null for folders — a folder is a listing, not an editable page, so it never becomes the mirrored activePage.

• TabButton shows a folder icon; PaneContent takes the paneId so children open in place rather than spawning tabs elsewhere.

Trash

The Trash is a trash tab. The shell opens it directly — App.tsx's Trash button calls openTab(trashTab()), exactly mirroring how the Home button calls openTab(homeTab()). From there it is dispatched by the tab.kind === 'trash' guard in PaneContent.tsx, giving deleted items their own dedicated surface inside a pane.

Every surface is a kind

Both fit the shell's core idea: the content area renders kinds, and folders and trash are simply two of them.

Deep-Links

osionos has no react-router. Navigation is the in-memory layout tree, so the URL carries no route. It is used for exactly one thing: deep-links — a small set of query parameters that seed the initial view or hand off a session.

The parameters

?home= — pick a landing surface

/?home=dashboard   /?home=graph   /?home=database   /?home=workspace

These four values are the Home variants, and they double as the Lighthouse gate's probe set — perf is measured per variant across mobile and desktop.

?view= — jump to a view

A database view has an id, and ?view= opens it directly. Internally this is the same mechanism the Home views launcher uses: each launcher row opens its exact view through a tab's viewId. A deep-link is just that action, driven from the URL instead of a click.

bridge_token — the website hand-off

The opposite-osiris website and the osionos editor are separate apps. When you sign in on the website and cross into the editor, the session travels as a bridge_token on the URL.

Why so few

A router would encode application state in the URL and force every view to be reconstructable from it. osionos deliberately keeps state in the store and the URL thin — so the only things worth putting in a link are an entry point (?home=, ?view=) or a credential hand-off (bridge_token).

The Update / Rebuild Button

The top bar carries a blue Update button. In the containerised dev stack it does something genuinely useful: it triggers a full rebuild of the running app and reloads — without you leaving the browser.

The problem it solves

The osionos containers bake their source at build time (the live container is nginx-static). So editing app code and refreshing the page shows nothing new — you have to rebuild the image. But a browser button cannot run docker or make on the host; it lives in a sandbox.

The host daemon

The bridge is a tiny host-side daemon, scripts/dev-rebuild-server.py:

• Python, not Node — the host has python3, make, docker, and bash, but no host Node on purpose. Zero-dependency http.server from the stdlib.

• Listens on 127.0.0.1:7799 (loopback is exempt from mixed-content blocking, the same trick the LiveKit video rooms use).

• POST /rebuild runs make all and streams the output back; CORS is open so the page can call it.

You start it in a terminal once:

make rebuild-server     # runs scripts/dev-rebuild-server.py on 127.0.0.1:7799

What the button does

The client logic in widgets/top-bar/model/rebuild.ts (rebuildServerUp, runHostRebuild) drives UpdateButton:

1. Probe the daemon.

2. Daemon up → confirm with the user → POST /rebuild (make all) → reload on success.

3. Daemon down → fall back to a live-data refresh (fetchPages) and show a hint on how to enable full rebuilds.

[Update] ──probe──► 127.0.0.1:7799
   │  up                         │  down
   ▼                             ▼
 confirm → make all → reload   fetchPages() + hint

Design System Overview

Track Binocle's look is warm and editorial — a cream canvas, serif headings, a single terracotta accent. But the important thing is not the colours; it is that every colour, radius, shadow, and font in osionos resolves through one layer of CSS custom properties. Change the layer, and the whole workspace re-skins itself without touching a single component.

The pieces, top to bottom

Two axes, not one dropdown

Most apps ship "light / dark". osionos separates mode from palette:

• data-theme = light or dark — the luminance mode.

• data-palette = mono, nord, midnight, … — the colour family.

They multiply. Nord-dark and Nord-light are the same palette in two modes; Nord and Solarized are two palettes that each honour whichever mode you're in. See The palette axis for why this is orthogonal by design.

What each doc in this folder covers

• Token architecture — the --osio-* naming and families.

• The warm-editorial default — terracotta, cream, serif.

• Colour palettes — all eight, with swatches.

• Light & dark theming · Palette axis.

• Tailwind v4 CSS-first · Style-token guard.

• Accessibility & contrast.

• Website token layers — the Astro site's own --brand-*/--system-*.

• Web performance · CSP architecture.

The payoff

Because colour values exist in exactly one place, adding a ninth palette is a new attribute block — not a sweep across hundreds of components. And because a dependency-free guard fails the build on any raw hex that escapes that file, the discipline holds even under pressure.

Token Architecture

Every visual value in osionos is a CSS custom property named --osio-*, and they all live in exactly one file: src/app/styles/global.css. That file is the single source of truth for colour, typography, spacing, radius, shadow, and motion. Everything else in the app references it with var(--osio-…).

Token families

The names read as semantic roles, not raw colours — you reach for --osio-fg-default, never "the dark grey".