Nisaba — Architecture

Overview#

Nisaba is the Ancient Text Analysis and Cross-Tradition Scholarly Research domain. Its mission is to give scholars a single, coherent environment for working with pre-modern texts across every tradition — cuneiform tablets, Sanskrit manuscripts, Hebrew scrolls, Quranic codices, Greek papyri, Chinese classics, and dozens of other writing systems. The real-world problem Nisaba solves is fragmentation: primary sources, lexica, digital corpus platforms, annotation tools, and critical-edition software all live in separate silos with incompatible data models. Nisaba replaces that patchwork with a unified, typed, interoperable library stack.

The domain lives entirely in libs/nisaba/ within the Oshun Nx monorepo — there is no apps/nisaba or services/nisaba. It is organized as 22 independently publishable packages following the @nisaba/<name> convention. The platform serves scholars across biblical studies, classics, Assyriology, Indology, Buddhist textual studies, Quranic manuscript traditions, and any field engaged with pre-modern written heritage.

Because Nisaba ships as pure libraries (no app, no service), the packages are consumed by other Oshun domains (Tara, Arete, Veritas, Nyx) and by external scholarly tooling through the generated V1 REST contract. This design keeps the scholarly logic separate from UI and service concerns and allows each library to be versioned and published independently.

Library Organization#

The 22 packages form a layered stack ranging from low-level type vocabulary and Unicode utilities all the way up to client SDKs, mobile surfaces, and cross-domain bridges.

libs/nisaba/
├── schemas/       # @nisaba/schemas       — Zod validation schemas for domain entities
├── core/          # @nisaba/core          — Types, constants, utilities, error hierarchy
├── languages/     # @nisaba/languages     — Ancient writing system handlers
├── annotations/   # @nisaba/annotations   — W3C WADM standoff annotation engine
├── assistant/     # @nisaba/assistant     — AI translation commentary and variant evaluation
├── canon/         # @nisaba/canon         — Canonical text reference systems (all traditions)
├── client/        # @nisaba/client        — Scholarly SDK and React hooks
├── api-client/    # @nisaba/api-client    — Generated typed client for the V1 contract API
├── comparative/   # @nisaba/comparative   — Cross-tradition concept mapping and parallels
├── corpora/       # @nisaba/corpora       — Corpus connectors and ingestion pipeline
├── criticism/     # @nisaba/criticism     — Textual criticism: collation, stemma, apparatus
├── cross-domain/  # @nisaba/cross-domain  — Cross-domain bridge (Tara, Arete, Veritas, Nyx)
├── database/      # @nisaba/database      — Prisma client and schema
├── editions/      # @nisaba/editions      — Critical edition project management
├── geotemporal/   # @nisaba/geotemporal   — Geographic timeline and provenance mapping
├── mobile/        # @nisaba/mobile        — Mobile study surface definitions
├── paleography/   # @nisaba/paleography   — ML-assisted manuscript analysis
├── philology/     # @nisaba/philology     — Linguistic analysis: etymology, semantics, stylometry
├── standards/     # @nisaba/standards     — TEI, Linked Data, encoding standard compliance
├── study-plans/   # @nisaba/study-plans   — Study plan model and forecasting
├── translations/  # @nisaba/translations  — Translation comparison, alignment, divergence
└── workspace/     # @nisaba/workspace     — Research environment: split-pane layout, search

Dependency Layering#

Understanding the dependency graph matters when deciding where new code belongs. @nisaba/core is the single foundation: it carries the shared type vocabulary and the error hierarchy, and its only external dependency is @oshun/errors. The remaining Nisaba packages keep a deliberately shallow dependency graph — most either depend only on @nisaba/core or declare no intra-domain dependencies at all, which prevents circular imports and allows packages to be built and published independently.

The table below lists the actual intra-domain dependency edges, confirmed from package.json and source imports:

@nisaba/core         ← external: @oshun/errors  (no Nisaba deps)
@nisaba/schemas      ← external: zod;  Nisaba: @nisaba/core
@nisaba/languages    ← @nisaba/core
@nisaba/assistant    ← @nisaba/core
@nisaba/canon        ← @nisaba/core
@nisaba/criticism    ← @nisaba/core
@nisaba/geotemporal  ← @nisaba/core
@nisaba/paleography  ← @nisaba/core
@nisaba/philology    ← @nisaba/core
@nisaba/translations ← @nisaba/core
@nisaba/cross-domain ← @nisaba/study-plans
@nisaba/annotations  ← (no Nisaba deps)
@nisaba/comparative  ← (no Nisaba deps)
@nisaba/corpora      ← (no Nisaba deps)
@nisaba/editions     ← (no Nisaba deps)
@nisaba/standards    ← (no Nisaba deps)
@nisaba/workspace    ← (no Nisaba deps)
@nisaba/database     ← (no Nisaba deps)
@nisaba/client       ← (no Nisaba deps; zero-dependency SDK)
@nisaba/api-client   ← (no Nisaba deps; generated from the OpenAPI types)
@nisaba/mobile       ← (no Nisaba deps)
@nisaba/study-plans  ← (no Nisaba deps)

Packages listed as "no Nisaba deps" are presently self-contained — their package.json declares no @nisaba/* dependency and their source does not import one. This layering is not yet enforced by an ESLint boundary rule.

Core Package Design#

@nisaba/core#

@nisaba/core is the type vocabulary shared across the entire domain. It provides the enums, interfaces, utility functions, and error classes that every other Nisaba package builds on. New code that needs a shared type should add it here rather than duplicating definitions across packages. Its internal structure:

core/src/
├── types/
│   ├── writing-systems.ts    — WritingSystem enum (ISO 15924), ScriptDirection, WritingSystemMetadata
│   ├── morphology.ts         — PartOfSpeech, VerbStem, MorphologicalParse, grammatical-feature unions
│   ├── reference.ts          — ReferenceSystemType, CanonicalRef, CanonicalRefRange, CanonicalReferenceSystem
│   ├── traditions.ts         — Tradition enum, TraditionMetadata
│   ├── manuscript.ts         — ManuscriptMaterialType, VariantClassificationType
│   ├── apparatus.ts          — ApparatusFormatType, VariantClassification, ApparatusEntry, ApparatusReading
│   ├── annotations.ts        — AnnotationTypeValue, AnnotationMotivation, W3C selectors
│   ├── lexicon.ts            — LexiconEntry, LexicalSense, LexicalCrossRef
│   ├── transliteration.ts    — TransliterationScheme enum, TransliterationConfig
│   └── comparative.ts        — SimilarityTaxonomy, EvidenceGradeType, ConsensusLevelType, ComparativeEvidence
├── constants/
│   ├── script-metadata.ts    — SCRIPT_METADATA registry per WritingSystem
│   ├── unicode-ranges.ts     — UNICODE_RANGES per writing system
│   └── tradition-metadata.ts — TRADITION_METADATA registry
├── utils/
│   ├── unicode.ts            — NFC normalization, range checks, script detection
│   ├── offsets.ts            — Byte/character offset conversions
│   ├── dates.ts              — Approximate BCE/CE date parsing
│   ├── confidence.ts         — Confidence scoring utilities
│   ├── citations.ts          — Citation formatting
│   └── references.ts         — nisaba:// URI parsing and construction
└── errors.ts                 — NISABA_ERROR_CODES registry + NisabaError classes (on @oshun/errors)

@nisaba/core depends on @oshun/errors; it has no other external or intra-domain dependencies.

@nisaba/schemas#

Zod validation schemas for the domain entities that cross trust boundaries — for example, data arriving from external corpus connectors, user-submitted manuscripts, and API request bodies. Validated data is always preferable to raw input because Zod schemas generate both runtime validation and TypeScript types from a single source of truth.

@nisaba/schemas depends on zod and @nisaba/core. Its modules are: manuscript.ts, variant.ts, apparatus.ts, annotation.ts, reference.ts, tradition.ts, corpus.ts, geotemporal.ts. Each exports schemas plus inferred types and Create* variants. See specifications.md §3 for the full field-level breakdown.

@nisaba/languages#

The language engine handles the 29 ancient writing systems that Nisaba supports. Each script gets its own subdirectory implementing a common ScriptHandler interface, which ensures that higher-level code (morphological analysis, transliteration, tokenization) can work with any writing system through the same API surface.

The internal layout:

languages/src/
├── interfaces/
│   ├── script-handler.ts          — ScriptHandler base interface
│   └── tokenizer.ts               — Tokenizer interface
├── hebrew/  ancient-greek/  arabic/  aramaic/  syriac/  coptic/
├── cuneiform/  ugaritic/  old-persian/  avestan/
├── egyptian-hieroglyphic/  egyptian-hieratic/  egyptian-demotic/
├── devanagari/  grantha/  tamil-brahmi/  kharoshthi/  prakrit/
├── pali/  tibetan/  latin/  linear-b/  classical-chinese/
├── old-church-slavonic/  runic/  ethiopic/  phoenician/  samaritan/
├── tokenization/                  — base tokenizer
├── transliteration/               — transliteration engine
└── lexicon/                       — lexicon integration adapters

The 29 per-script directories above are the language subdirectories actually present under languages/src/. Each typically holds handler.ts, classifier.ts, clusters.ts, vocalization.ts, and (where applicable) transliteration.ts and script-specific analysis files.

Every language directory implements ScriptHandler with the following operations, all of which accept and return properly-typed Unicode text:

• classify(char) — character classification within the script
• decompose(cluster) — cluster decomposition into constituent elements
• normalize(text) — language-specific Unicode normalization
• vocalize(text, scheme) — vocalization handling
• tokenize(text, granularity) — position-preserving tokenizer

Key Domain Package Internals#

@nisaba/criticism#

The textual criticism engine is responsible for collating multiple manuscript witnesses, identifying and classifying variant readings, constructing stemmata, and generating critical apparatus entries. It is one of the most algorithmically complex packages in the domain because it implements established scholarly methods (Needleman-Wunsch alignment, CBGM, Lachmannian stemmatic reconstruction) rather than generic data processing.

The full set of 24 modules under criticism/src/:

@nisaba/translations#

The translations package handles everything needed to compare multiple translations of the same source text — from automated statistical alignment algorithms, through neural alignment models, to multiple display modes for human readers.

translations/src/
├── alignment/        — gale-church, ibm-model1, neural-alignment, manual-alignment, anchor-index, anchor-utils
├── divergence/       — equivalence-scoring, semantic-divergence, theological-divergence, omission-detection, translation-history
├── views/            — side-by-side, synoptic, interlinear, reverse-interlinear, scroll-sync
└── types/            — segments, views type definitions

@nisaba/comparative#

The comparative package maps concepts and passages across religious and philosophical traditions. It is careful to distinguish genetic relationships (where one text directly depends on another), typological parallels (independent development of similar ideas), and contested comparisons (where scholarly opinion is divided).

@nisaba/workspace#

The workspace package defines the scholar's primary research environment — the surface that brings together search, reading, annotations, and project management in a configurable split-pane layout.

Client Architecture#

Nisaba ships two distinct client packages that serve different audiences and purposes. A new engineer should understand the difference before choosing which to use.

@nisaba/api-client — generated V1 contract client#

This client is machine-generated from the OpenAPI specification and covers the 13-resource V1 contract REST API mounted at /api/v1/nisaba/*. It is the right choice when integrating with the standard Oshun REST gateway.

api-client/src/client.ts exposes createNisabaApiClient, a thin generated client over the OpenAPI types in api-client/src/generated/openapi.ts. It covers list, create, get, upsert, and tombstone operations for passages, manuscripts, editions, translations, lexicon-entries, morphology-entries, annotations, concept-graph-nodes, concept-graph-edges, notebooks, study-plans, citations, and scholar-profiles. Both this file and the OpenAPI spec are generated by libs/openapi/scripts/generate-oshun-v1-api-clients.ts.

@nisaba/client — scholarly SDK#

This is a hand-written, zero-dependency SDK (NisabaClient, built via NisabaClientBuilder) targeting a broader scholarly API surface than the generated V1 client. It is the right choice for application code that needs richer scholarly operations — collation, stemma, full annotation management, comparative concept maps, and the AI assistant.

client/src/api-client.ts covers manuscripts and witnesses, collation and stemma, annotations, editions, canonical references, corpus search, comparative concept maps, the AI assistant, batch requests, and WebSocket channels. It provides automatic retry with exponential backoff, request/response interceptors, an in-memory response cache with TTL, offset and cursor pagination, and structured NisabaApiError errors. client/src/react-hooks.ts adds React bindings including CRDT collaboration primitives. See specifications.md §5 for the full SDK method/endpoint map.

The two clients do not share an endpoint surface. The V1 contract API in §4 of the specification is the generated-and-served REST surface; the @nisaba/client SDK targets a richer scholarly API that is not yet unified with it. The boundary exists because the V1 contract is a stable public API governed by the Oshun contract process, while the scholarly SDK is a more agile surface that can evolve as scholarly requirements develop.

Technology Stack#

The choices below reflect Nisaba's primary constraints: strict Unicode correctness for dozens of non-Latin scripts, standards compliance with TEI and W3C WADM, and interoperability with digital humanities infrastructure.

Adding a New Writing System#

Supporting a new ancient script requires touching four packages in order. Follow these steps to ensure that the new script integrates with all existing consumers (morphology, transliteration, search, corpus ingestion):

1. Add Unicode range constants to @nisaba/core/src/constants/unicode-ranges.ts
2. Register the ISO 15924 code in the WritingSystem enum (@nisaba/core/src/types/writing-systems.ts)
3. Register metadata (name, direction, combining characters, ligatures) in SCRIPT_METADATA (@nisaba/core/src/constants/script-metadata.ts)
4. Create a language handler directory in @nisaba/languages/src/<script-name>/
5. Implement the ScriptHandler interface (languages/src/interfaces/script-handler.ts)
6. Register the handler in the languages index
7. Write comprehensive tests covering classification, tokenization, normalization, and transliteration

Adding a New Corpus Connector#

Corpus connectors live in @nisaba/corpora, grouped by family: classical-corpus-connectors.ts, religious-corpus-connectors.ts, specialized-corpus-connectors.ts. These sit alongside the format parsers (tei-xml-parser.ts, atf-parser.ts, scripture-format-parsers.ts) and the ingestion-pipeline.ts. The key challenge when adding a new corpus is mapping its native citation scheme to Nisaba's canonical URI format — without this mapping, cross-corpus search and reference resolution will not work.

To add a new corpus:

1. Add the connector to the relevant *-corpus-connectors.ts module
2. Implement metadata ingestion, text retrieval, and reference mapping
3. Map the corpus's native reference system to Nisaba canonical URIs
4. Register the connector in the corpora index
5. Write ingestion and retrieval tests

Build & Test#

• Unit tests: Vitest, per library (*.spec.ts co-located with sources)
• Integration tests: schemas/src/__integration__/ covers textual-criticism, corpus-ingestion, translation-comparison, and comparative-traditions workflows plus cross-domain (sophia-dependency) and performance benchmarks
• Build: Nx with tsup/esbuild; type-check via tsc --noEmit
• CI/CD reference: A reference pipeline is documented in docs/domains/nisaba/nisaba-ci-cd-pipeline.yaml

Scope#

This architecture document reflects libs/nisaba/* (22 packages) plus the canonical V1 contracts in libs/contracts/src/nisaba/. Nisaba ships as libraries and generated API contracts; there is no apps/nisaba or services/nisaba. The scholarly-text responsibilities described here remain in Nisaba and are not duplicated in Calliope.