# Toshokann architecture

Toshokann is the generalized, unbranded foundation of the BOSS library application. Its architectural rule is intentionally narrow: preserve the reusable BOSS mechanics and extract only product identity, holdings, domain vocabulary, prompts, provider/model policy, support details, palette, and other organization-specific decisions.

## Runtime surfaces

| Area | Location | Responsibility |
| --- | --- | --- |
| Documentation site | Root documentation HTML pages and `docs/site.css` | Public project explanation; it does not run the library or open DBOPFS |
| Librarian chat | `app.html` | Shared Arcane chat, library context injection, tools, first-run state, provider readiness, and accessible feedback |
| Library browser | `library.html` | Search, access/category/organization filters, pagination, preview, and librarian handoff |
| First-run setup | `library-setup.html`, `components/import-terminal.html` | Inspect and seed packaged Markdown into DBOPFS with visible bounded progress |
| Profile/providers | `profile.html`, `src/ai-preferences.js`, `src/ai-profile-models.js` | User profile, appearance, provider credentials, preference tuple, and optional installed-model discovery |
| Backup/restore | `export.html`, `import.html` | Full DBOPFS compressed-PNG export and restore |
| Navigation | `components/nav.html` | Common application routes and product-owned identity seam |
| Library runtime | `src/library.js` | BOSS-compatible manifest normalization, ranking, filters, raw Markdown hydration, context construction, user-document merge, seed inspection, import, and refresh |
| Application data | `arcane/modules/AppDataScope.js`, `DBOPFS.js`, `DBOPFSWorker.js` | Canonical `apps/<application-id>` OPFS scope, shared table/file API, worker fallback, and backup format |
| Composition | `src/active-extension.js`, `src/core/extension.js`, `extensions/empty/` | Select and validate one product policy/corpus extension; default to zero holdings |
| Shared Arcane runtime | `arcane/`, `node_modules/strong-type/` | The same generic components, entities, modules, styles, icons, and validation dependency used by BOSS |

The documentation package is separate from the runtime package. GitHub Pages publishes the reviewed explanatory site. Runnable derivatives package the application surfaces and their complete shared runtime closure.

## Preserved BOSS mechanics

Toshokann retains the behavior a BOSS extension depends on:

- the DBOPFS `documents` table contains raw Markdown;
- packaged holdings use stable managed filenames and one manifest-version sentinel;
- arbitrary non-managed user Markdown remains discoverable;
- first-run inspection distinguishes complete, missing, stale, incomplete, and unavailable states;
- seeding is batched, observable, retryable, idempotent after success, and scoped to the managed prefix;
- search normalizes flexible record fields, applies structured filters, weights relevant fields, and supports extension synonym groups;
- matched static or user Markdown is hydrated under per-document and total character limits;
- context is escaped and marked as retrieved reference data;
- the librarian chat, provider readiness, profile preferences, file manager, and full database backup/restore use the shared Arcane contracts.

The empty extension has no managed holdings, synonyms, model aliases, provider credentials, support address, or organization policy. A zero-record catalog is complete immediately and does not manufacture a setup task or marker.

## Extension boundary

An extension may supply:

- product and organization identity;
- catalog URL and holdings;
- managed seed prefix, version marker, and refresh event;
- domain synonym groups and filter vocabulary;
- approved navigation additions and appearance accents;
- librarian prompt, tool descriptions, handoff rules, provider/model adapters, and regulated-domain policy;
- integration setup that the neutral declarative contract cannot express.

The core continues to own storage mechanics, seeding, user Markdown handling, search/ranking, context bounds, chat contracts, common profile behavior, file management, and backup format. A BOSS extension can therefore reintroduce BOSS identity, its existing corpus and managed namespace, business-specific synonyms, prompt, provider/model aliases, palette, logo, and support policy without forking Toshokann.

## Storage boundary

DBOPFS opens the origin's OPFS root and then `apps/<canonical-application-id>`. In a browser-only deployment the application ID is declared before the storage module loads. A supported native host may bind the identity authoritatively and place the app in a separate WebView profile.

The directory prevents accidental table collisions. It is not authorization between pages sharing an origin. Records are not encrypted by DBOPFS. The compressed-PNG export is compressed JSON and is plaintext-equivalent. Browser retention is not guaranteed; persistence requests can be denied and users can clear site data. See [`security.md`](security.md).

## Retrieval boundary

The neutral runtime preserves BOSS-compatible search and context mechanics. It bounds ranked results and included characters and escapes the context envelope. It treats retrieved Markdown as data, not system instructions.

The inherited runtime does not itself verify a cryptographic manifest digest during Markdown hydration. It must not be described as proving provenance, approval, authenticity, or release authorization. A derivative needing signed releases or hash-bound objects must add a versioned, tested release control without silently changing the compatible record semantics.

## Packaging boundary

The docs package uses a positive allowlist, rejects links and special entries, hashes every published file, and writes a deterministic receipt. The receipt is inventory evidence, not a signature or authorization.

A runtime derivative must positively include every shared dependency required by the BOSS-equivalent surfaces and exactly one product extension. It must exclude other extensions, development corpora, originals not approved for release, conversion inputs, credentials, tests, and tools unless deliberately published as corresponding source.

## Accessibility and responsiveness

The generalized shell inherits Arcane semantic controls, labels, dialogs, live regions, keyboard-native operation, theme preferences, and responsive components. A derivative owns the accessibility consequences of its logo, copy, palette, new navigation, documents, prompt, and integrations. Product policy must not weaken the shared behavior.