Deployment patterns

@@ -3,7 +3,7 @@ schema: foundry-doc-v1
title: "Deployment patterns"
slug: deployment-patterns
category: patterns
type: concept
type: topic
content_type: topic
quality: complete
index_group: deployment-and-configuration
@@ -14,6 +14,7 @@ bcsc_class: public-disclosure-safe
language_protocol: PROSE-TOPIC
last_edited: 2026-08-24
editor: pointsav-engineering
cites: []
paired_with: deployment-patterns.es.md
references:
  - id: 1
@@ -26,6 +27,8 @@ references:

Deployment patterns describes the six canonical configurations in which the PointSav substrate is deployed across different institutional contexts, each built on the [[three-ring-architecture|three-ring architecture]]. Each configuration rests on the same five primitives — People, Communications, Drafts, Records, Money — and the same [[os-console|Command Ledger]] surface; what changes per configuration is the [[archetypes-and-chart-of-accounts|Chart of Accounts]] and the compliance surface. The substrate does not fork across segments; it adapts. By the end of this article, a reader will understand the Companion positioning, the six canonical patterns, and the compile-time cartridge isolation model that makes independent-versioning practical across all six.

**Why it matters:** a fix or feature built for one configuration carries over to all six automatically — there is no separate codebase per segment to keep in sync.

## Five primitives that span every institutional context [^2]

Every context in which institutional users operate maps to the same five primitive categories of records. A regulated professional managing patient files, a litigator managing case discovery, and a household managing tax receipts each maintain documents that fall into exactly these categories:
@@ -40,6 +43,8 @@ Every context in which institutional users operate maps to the same five primiti

The [[os-console|Command Ledger]] exposes each primitive as a dedicated F-key surface. The operator presses a key; the chassis loads the relevant plugin; the plugin displays the records for that primitive within the current [[totebox-os|Totebox]] context. No context switch between segments requires a different architecture — the five primitives are universal.

**Why it matters:** an operator who has learned the five-key layout at a real-property firm already knows the layout at a law firm or a household — the surface never has to be relearned when the underlying business changes.

## How the platform operates alongside incumbent tools

The platform is positioned as a complementary engine, not a replacement for existing operational tools. Customers continue to use the professional and productivity applications they already operate; the substrate runs alongside, routing records from those applications into sovereign [[totebox-os|Totebox]] archives.
@@ -50,10 +55,12 @@ The platform is positioned as a complementary engine, not a replacement for exis
| Spreadsheet applications | The intended sovereign spreadsheet surface stores executed financial models in the [[worm-ledger-design|WORM ledger]] |
| Word-processing applications | The intended sovereign word-processing surface uses Typst for print-fidelity output; F4 in the [[os-console|Command Ledger]] synthesises content from structured records |
| Professional networking platforms | [[service-people]] is intended to harvest verified contact data into the Totebox identity ledger |
| Corporate document repositories | service-minutebook cryptographically seals signed records against the [[worm-ledger-design|WORM ledger]] substrate |
| Corporate document repositories | service-minutebook is intended to cryptographically seal signed records against the [[worm-ledger-design|WORM ledger]] substrate |

The customer is not asked to abandon any working tool. The substrate operates in the background; the Command Ledger provides a sovereign view over the records the incumbent tools produce.

**Why it matters:** a customer never faces a forced migration off the tools their staff already know — the substrate adds a sovereign record underneath, it does not replace the working front end.

## Six canonical deployment configurations

The six configurations represent distinct GUIDE families in the fleet-deployment catalogue. Each is a configuration, not a separate product; the underlying [[totebox-os]], [[os-console|os-console]], and services are identical across all six.
@@ -69,6 +76,8 @@ The six configurations represent distinct GUIDE families in the fleet-deployment

Each row is a configuration, provisioned from a named template in the fleet-deployment catalogue. The pattern for a real-property deployment differs from the pattern for a law firm only in its Chart of Accounts configuration and compliance surface — the underlying substrate components are identical.

**Why it matters:** a new configuration for a segment not yet listed here is a Chart of Accounts exercise, not a new engineering effort — the substrate underneath does not need to be rebuilt.

## Cartridge isolation inside the Command Ledger

The [[os-console|Command Ledger]] is a terminal application, not a web surface — it is built on `ratatui`/`crossterm`, with no HTTP layer and no HTML, CSS, or JavaScript anywhere in it. **Each function key loads a fully separate, independently compiled piece of code.** No plugin can accidentally read another plugin's state — that separation is enforced by the compiler, not by a runtime permission check. The chassis is an empty shell that registers a fixed set of Rust trait objects — one per plugin — into an in-process registry at startup. When the operator presses F2, the chassis dispatches to the already-registered People cartridge; F3 dispatches to Email; each function key maps to its own compiled cartridge object living in the same process the whole time.
@@ -82,6 +91,8 @@ The [[os-console|Command Ledger]] is a terminal application, not a web surface 

This isolation model achieves the same practical goal a browser-based micro-frontend architecture[^1] pursues: independently versioned, mutually isolated feature modules behind a shared shell. The mechanism differs — Rust's module and trait system, enforced at compile time, rather than separate HTML/JS bundles isolated by the browser at runtime. The isolation here is structural, a property of how the binary is built, not a security policy that has to be enforced while the program is running.

**Why it matters:** a bug in one cartridge cannot corrupt or read another cartridge's data even in principle — the guarantee holds because the compiler enforces it, not because a runtime check happened to catch it this time.

## How deployment templates map to the fleet catalogue

Each canonical configuration has a corresponding subdirectory under the fleet-deployment catalogue. The customer-facing catalogue is the public record of how the substrate is operated for each configuration type.
@@ -94,12 +105,16 @@ Each canonical configuration has a corresponding subdirectory under the fleet-de

Templates in the Showcase Layer correspond to numbered instances in the Instance Layer — private to the operator, gitignored from all public repositories. See [[three-layer-architecture]] for the three-layer model.

**Why it matters:** a customer can browse the full template catalogue publicly without any private instance data — pricing, credentials, or tenant identity — ever being exposed alongside it.

## The visible-operational-first deployment cadence

Deployment patterns are launched with a visible-operational-first cadence: the URL resolves and a recognisable surface answers before any polish or hardening work begins. A pattern that has not yet been provisioned as a working deployment is described in planning terms, not as live infrastructure.

This cadence prevents two common failure modes: designs that are specced but never built, and builds that are technically complete but never publicly visible. The definition of "operational" is strict — the URL must resolve to a surface a human can use — and that bar is cleared before any configuration is described as deployed.

**Why it matters:** a reader who sees a configuration described as "deployed" can trust that claim literally — a real URL resolves to a real, usable surface, not a specification waiting to be built.

## See also

- [[three-ring-architecture]] — the ring architecture that each configuration deploys