Seshat Domain — Architecture — Seshat domain

Architectural overview of the Seshat dwelling-arts domain: 11 TypeScript libraries, the domain-orchestration pattern, module organization, and the (deliberately minimal) dependency surface.

Seshat is the Dwelling Arts and Craftsmanship Intelligence Platform of the Oshun monorepo. Named after the ancient Egyptian goddess of writing, measurement, knowledge, and record-keeping — the divine scribe who measured the foundations of temples with a knotted cord — Seshat encodes millennia of accumulated human knowledge about how to build and inhabit space: the joinery of fine woodworking, the harmony traditions of Feng Shui and Vastu Shastra, the physics of digital fabrication, and the science of sustainable circular design.

The domain ships entirely as importable TypeScript libraries. There is no runtime service, no HTTP gateway, and no event bus. Consuming applications import Seshat library functions directly, compose them together, and own any persistence or network calls themselves. This keeps domain logic testable, deterministic, and decoupled from infrastructure concerns.

The eleven libraries are organized by domain expertise: a common foundation and orchestration core, plus nine specialist libraries covering every major aspect of dwelling design and craft practice. A new engineer can pick up only the libraries relevant to their feature — a woodworking tool needs @seshat/craft and @seshat/fabrication; a wellness feature needs @seshat/smart and @seshat/harmony — without pulling in unrelated code.

Design Principles#

Domain expertise encoded as libraries — Each library encodes deep domain knowledge (joinery mechanics, spatial harmony traditions, fabrication physics) as reusable TypeScript modules, not generic CRUD.
Composable modules — The 11 libraries are independent and loosely coupled. A project can use only woodworking libraries, only smart home libraries, or any combination.
Core orchestration layer — @seshat/core provides project lifecycle management and cross-module coordination without owning domain logic. Domain logic lives in the specialist libraries.
Pure functions for calculations — All computational functions (joinery strength, carbon footprint, G-code generation, Feng Shui analysis) are pure functions: deterministic, side-effect-free, and independently testable.
TypeScript throughout — Library-only domain with no runtime services, no API gateway, and no event bus. Clients import and call library functions directly. The only runtime dependency across all eleven libraries is zod (@seshat/core additionally uses uuid); no library depends on any @oshun/* package.

Architecture Overview#

The diagram below shows how @seshat/core sits at the top of the dependency hierarchy as the project-lifecycle orchestrator, while the nine specialist libraries hang beneath it in three thematic columns. @seshat/database is a leaf node — a schema-description layer that the specialist libraries do not depend on at runtime.

text

                         ┌─────────────────────────────┐
                         │         @seshat/core         │
                         │  Project lifecycle           │
                         │  Cross-module orchestration  │
                         │  Config, logging, flags      │
                         └──────────────┬──────────────┘
                                        │
         ┌──────────────────────────────┼──────────────────────────────┐
         ▼                              ▼                              ▼
┌─────────────────┐         ┌─────────────────────┐         ┌─────────────────┐
│  @seshat/craft  │         │  @seshat/design      │         │ @seshat/harmony │
│  Woodworking    │         │  Interior design     │         │ Spatial harmony │
│  knowledge      │         │  intelligence        │         │ traditions      │
└─────────────────┘         └─────────────────────┘         └─────────────────┘
         ▼                              ▼                              ▼
┌─────────────────┐         ┌─────────────────────┐         ┌─────────────────┐
│@seshat/fabricat.│         │   @seshat/smart      │         │@seshat/sustainab│
│ CNC, laser, 3D  │         │  IoT + automation    │         │ Carbon, LCA,    │
│ printing, nesting│         │                     │         │ circular design │
└─────────────────┘         └─────────────────────┘         └─────────────────┘
         ▼                              ▼                              ▼
┌─────────────────┐         ┌─────────────────────┐         ┌─────────────────┐
│@seshat/workshop │         │  @seshat/academy     │         │ @seshat/common  │
│ Layout, safety, │         │  Learning paths,     │         │ Shared types,   │
│ tool inventory  │         │  certification       │         │ validation,units│
└─────────────────┘         └─────────────────────┘         └─────────────────┘
                                        │
                         ┌──────────────┴──────────────┐
                         │       @seshat/database       │
                         │  Zod row schemas and         │
                         │  declarative migrations      │
                         └─────────────────────────────┘

Library Organization#

The source tree under libs/seshat/ maps one-to-one with the architecture diagram. Each library is a self-contained TypeScript package that exports its own types and functions. The annotations below identify each file's primary responsibility.

text

libs/seshat/
├── core/           # Domain orchestration, project manager, workflow engine
│   ├── types.ts           # Project, config, feature flag types
│   ├── errors.ts          # Domain error hierarchy
│   ├── config.ts          # Configuration loading and validation
│   ├── logging.ts         # Logging context setup
│   ├── feature-flags.ts   # Runtime feature flag evaluation
│   ├── project-manager.ts # Project CRUD and state machine
│   └── workflow-engine.ts # Multi-step workflow orchestration
│
├── common/         # Cross-library shared utilities
│   ├── types.ts
│   ├── validation.ts
│   └── units.ts    # Unit conversion utilities
│
├── craft/          # Woodworking knowledge engine
│   ├── types.ts
│   ├── joinery.ts          # Joint calculations and strength estimates
│   ├── materials.ts        # Wood species database and properties
│   ├── tools.ts            # Tool catalog and settings
│   ├── finishing.ts        # Finish selection and application
│   └── projects.ts         # Material takeoff and assembly planning
│
├── design/         # Interior design intelligence
│   ├── types.ts
│   ├── style-engine.ts        # Style classification, consistency, interpolation
│   ├── floor-plan.ts          # Floor plan, traffic, work-triangle, clearances
│   ├── parametric.ts          # Parametric/genetic design, topology, Voronoi
│   ├── mood-board.ts          # Palette extraction and brief parsing
│   └── product-discovery.ts   # Product matching and budget estimation
│
├── fabrication/    # Design-to-fabrication pipeline
│   ├── types.ts
│   ├── cnc.ts              # G-code generation, feeds/speeds
│   ├── laser.ts            # Laser cutting parameter calculation
│   ├── printing3d.ts       # FDM/resin settings and estimation
│   └── nesting.ts          # 2D bin-packing, sheet & cut-sequence optimization
│
├── harmony/        # Spatial harmony engine
│   ├── types.ts
│   ├── feng-shui.ts         # Bagua, Flying Stars, chi flow, Kua numbers
│   ├── vastu-shastra.ts     # Purusha Mandala, direction analysis
│   ├── biophilic-design.ts  # 14 biophilic design patterns, plant recs
│   ├── sacred-geometry.ts   # Golden ratio, proportions, pattern generation
│   ├── color-psychology.ts  # 60-30-10, emotional impact, accessibility
│   ├── design-philosophy.ts # Wabi-Sabi and Hygge assessment
│   └── synthesis.ts         # Multi-tradition conflict resolution and scoring
│
├── smart/          # Smart dwelling integration
│   ├── types.ts
│   ├── device-registry.ts   # IoT device catalog and management
│   ├── sensor-engine.ts     # Sensor stream processing and anomaly detection
│   ├── automation.ts        # Scene management and trigger rules
│   └── wellness.ts          # Air quality, circadian, thermal/ergonomic comfort
│
├── sustainability/ # Sustainability and circular design
│   ├── types.ts
│   ├── carbon.ts            # Embodied carbon calculation
│   ├── lifecycle.ts         # Full life cycle assessment
│   ├── circular-design.ts   # Circular design scoring and DfD
│   └── certification.ts     # FSC, PEFC, LEED compliance and waste audit
│
├── academy/        # Maker's Academy learning platform
│   ├── types.ts
│   ├── skill-assessment.ts  # Multi-dimensional skill matrix
│   ├── learning-path.ts     # Personalized path generation
│   ├── certification.ts     # Competency levels and badge issuance
│   └── mentorship.ts        # Mentor matching and session tracking
│
├── workshop/       # Workshop and makerspace management
│   ├── types.ts
│   ├── layout.ts            # Floor plan optimization for workflow/safety
│   ├── inventory.ts         # Tool catalog, checkout, maintenance
│   ├── safety.ts            # Hazard identification, inspection checklists
│   └── scheduling.ts        # Booking system for shared tools and spaces
│
└── database/       # Persistence layer
    ├── schema.ts            # Zod row schemas + inferred row types
    ├── migrations.ts        # Declarative table/migration definitions + SQL generator
    └── seed.ts              # Curated seed data (wood species, tools, room types)

Module Design Patterns#

Seshat uses three distinct module patterns depending on whether a capability is stateless computation, stateful in-memory management, or controlled feature delivery.

Pure Function Modules#

Domain computation modules — @seshat/craft, @seshat/fabrication, @seshat/harmony, and @seshat/sustainability — export only pure functions and their types. A pure function always produces the same output for the same input and has no side effects: no global state, no I/O, no mutation of arguments. This design makes the computations trivially testable in isolation and composable in any order. For example, from @seshat/craft:

typescript

// Pure function: same inputs → same outputs, no side effects
export function calculateJointStrength(
  joint: JointType,
  species: WoodSpecies,
  dimensions: JointDimensions,
  loadType: LoadType
): JointStrengthResult { ... }

Database-Free Computation#

The computational libraries (@seshat/craft, @seshat/design, @seshat/harmony, @seshat/fabrication, @seshat/sustainability) have no database dependency. They operate entirely on data passed to them as function arguments — the caller fetches or constructs the input data, and the library computes the result. This separation means the libraries work equally well in a browser, a serverless function, or a background job.

Persistence-related code lives in @seshat/database, which itself ships only Zod row schemas, declarative migration definitions, and seed data. It does not open a database connection or depend on an ORM. This keeps schema definitions close to the domain without introducing a runtime database dependency into the computation libraries.

In-Memory Stores#

A few libraries provide in-memory stateful stores rather than pure functions, for capabilities that inherently require tracking changing state. These stores are:

@seshat/core's ProjectManager — tracks project lifecycle across multi-step state machine transitions.
@seshat/smart's DeviceRegistry, SensorEngine, AutomationEngine, and SceneManager — maintain live device catalogs and rule state.
@seshat/workshop's tool, material, scheduling, and incident stores — record inventory and booking state.

Each store exposes a clear-style reset method for test isolation, making it straightforward to start from a blank slate between test cases. Durable persistence (writing to a database) is always the caller's responsibility; these stores act as the domain's working memory, not its long-term storage.

Feature Flag Integration#

@seshat/core provides a feature flag system (FeatureFlagManager, SESHAT_FEATURES) with deterministic hash-based percentage rollout and manual overrides. It controls which capabilities are exposed without branching library code. This means individual library functions remain unconditionally implemented; the flag system decides whether a capability is surfaced to a given user at the application layer, not inside the library itself.

Cross-Domain Boundaries#

Seshat has no cross-domain runtime dependencies. Every libs/seshat/*/package.json declares exactly one runtime dependency, zod (and @seshat/core imports uuid). This is a deliberate architectural boundary: Seshat is a self-contained domain of dwelling knowledge, and it should not need to know about auth, payments, media storage, or any other Oshun domain to compute a joinery strength, a Feng Shui chi flow, or a carbon footprint.

Within the domain, each library imports type definitions from @seshat/common — this is the shared vocabulary that allows, for example, a Room object produced by @seshat/core to be passed directly to @seshat/harmony's analyzeBagua without any data transformation. The @seshat/database library deliberately defines its own Zod schemas without importing @seshat/common (documented in its source header) to keep the persistence layer decoupled — changes to the domain type vocabulary should not force a migration, and changes to the database schema should not force changes to domain computation types.

There is no integration with @oshun/* shared packages, an auth service, a storage service, or an event bus. When Seshat libraries are called from an application that does use those services, the application layer is responsible for bridging the two worlds — fetching data from storage, passing it to Seshat functions, and persisting the results.

The SeshatEventType and SeshatEvent types are declared in @seshat/common as a 12-value union describing the domain events Seshat could emit, but no publisher, subscriber, or transport is implemented. This is part of the Phase 36 backlog.