# Seshat — Systems Deep Dive

> The `libs/seshat/` area: eleven Nx libraries implementing the **dwelling arts
> & craftsmanship** domain — spatial harmony, interior design, woodworking,
> digital fabrication, smart-home, sustainability, learning, and workshop
> management — as deterministic TypeScript engines layered over one shared
> foundation.

## What this area is

Seshat (named for the Egyptian goddess of measurement and architecture) is a
single product domain split into eleven `scope:seshat` libraries, each tagged
`layer:domain` / `type:lib` and built with `@nx/js:tsc` + Vitest. Every package
declares only `zod` as a runtime dependency (plus `uuid` inside `@seshat/core`);
there are no upstream Oshun dependencies, so the whole area sits low in the
graph. The scope statement is written verbatim at the top of
`libs/seshat/common/src/index.ts`: a "Comprehensive platform for dwelling arts
and craftsmanship" spanning Spatial Harmony, Interior Design, the Craftsman's
Forge, the Maker's Academy, Smart Dwelling, Workshop Management, Digital
Fabrication, and Sustainability.

The area is genuinely implemented, not scaffold. Each library carries real
domain algorithms and data tables rather than CRUD shells: `@seshat/harmony`
computes Flying Star charts from a Lo Shu magic square, `@seshat/fabrication`
runs a bottom-left-fill bin-packing nester and CNC feeds-and-speeds math,
`@seshat/sustainability` carries embodied-carbon emission factors sourced from
the ICE/EPA/Ecoinvent databases, and `@seshat/craft` ships a database of
Japanese Sashimono joints with romanized/Japanese names, strength ratings, and
step-by-step cutting sequences. Every package also has a real `*.test.ts` spec
(and `harmony` adds a second, `feng-shui-remedy-effectiveness.test.ts`).

The dependency shape is a two-tier foundation plus a fan of domain engines.
`@seshat/common` is the bottom: branded ID types, measurement/geometry types,
the full cross-domain type vocabulary, shared constant databases
(`JOINT_DATABASE`, `BAGUA_AREAS`, `ELEMENT_CYCLES`, …), and pure utility
functions (geometry, unit conversion, color, proportions, scoring). The eight
subject-matter libraries (`academy`, `craft`, `design`, `fabrication`,
`harmony`, `smart`, `sustainability`, `workshop`) each `import` from
`@seshat/common` and own one slice of the product. `@seshat/core` is the
orchestration layer (project lifecycle, workflow DAG, config, logging, feature
flags). `@seshat/database` is the persistence-validation layer — it deliberately
re-declares the branded IDs as Zod schemas and depends only on `zod`, so storage
validation does not couple back to `@seshat/common`.

## How it fits the wider system

These are leaf domain libraries: the algorithms and Zod schemas are meant to be
composed by a Seshat service/BFF (project orchestration through `@seshat/core`,
persistence through `@seshat/database`) and surfaced to a client, but within the
tracked source the consumers are each other. The hard boundary is the `zod`-only
dependency rule: nothing here imports another Oshun scope, so the engines stay
portable and individually testable. To see who depends on a given node, walk the
"used by" edges on its card below — `@seshat/common` is the most heavily
consumed (every other library imports its types and constant tables).

## Entity reference

### @seshat/common

The shared foundation for the whole area (`libs/seshat/common/src`), depending
only on `zod`. `types.ts` is ~1800 lines of the cross-domain vocabulary: branded
nominal IDs (`ProjectId`, `RoomId`, `DeviceId`, …), measurement and 2D/3D
geometry types, and the full domain type surface for Feng Shui, Vastu Shastra,
design philosophy, materials, joinery, tools, projects, IoT, interior design,
sustainability, the academy, fabrication, and workshops. `constants.ts` holds
the shared lookup databases (e.g. `JOINT_DATABASE`, `BAGUA_AREAS`,
`ELEMENT_CYCLES`) and `utils.ts` exports pure helpers — geometry
(`pointInPolygon`, `polygonCentroid`), unit conversion (`convertLength`,
`boardFeetToVolume`), wood/material math (`calculateBoardFeet`,
`jankaHardnessCategory`), color (`hexToHsl`, `colorContrast`), proportions
(`isGoldenRatio`, `fibonacciSequence`), and scoring (`normalizeScore`,
`letterGrade`). Every other `@seshat/*` library builds on this.

### @seshat/core

The domain orchestration layer (`libs/seshat/core/src`). Its `index.ts`
re-exports `types`, `errors`, `config`, `logging`, `feature-flags`,
`project-manager`, and `workflow-engine`. `project-manager.ts` implements a real
project-lifecycle state machine — a `VALID_TRANSITIONS` table gates phase moves
(`concept → planning → design → … → completed/archived`, with rework paths back
to `planning`), backed by `uuid` id generation, Zod input validation
(`CreateProjectInputSchema`), and budget enforcement (`BudgetExceededError`).
`workflow-engine.ts` is a DAG executor with `detectCycle` implemented via Kahn's
topological sort, dependency-blocked step detection
(`WorkflowStepBlockedError`), and progress computation. This is the intended
composition point that ties the subject-matter engines into a project.

### @seshat/academy

The Maker's Academy learning engine (`libs/seshat/academy/src`), importing
`@seshat/common`. `index.ts` re-exports `skill-assessment`, `learning-path`,
`certification`, and `mentorship`. `skill-assessment.ts` is rubric-based, not a
shell: a `SKILL_LEVEL_THRESHOLDS` map and `scoreToSkillLevel` translate a 0-100
competency score into the six `SkillLevel` bands (novice → master), with the
thresholds documented against real apprenticeship standards. The module operates
over domain types like `AssessmentRubric`, `CraftDomain`, and
`StudentSkillProfile`, and the area's other learning concepts (paths,
certification ladders, mentor matching) live in their sibling modules.

### @seshat/craft

The Craftsman's Forge — a woodworking knowledge engine (`libs/seshat/craft/src`)
covering joinery, materials science, tools, finishing, and project planning.
`joinery.ts` ships `SASHIMONO_JOINTS`, a database of Japanese joints carrying
romanized and Japanese (`蟻継ぎ`) names, joint type, `JointDifficulty`, a
five-axis `JointStrength` rating (tensile/shear/compression/racking/overall),
required tool categories, and an ordered `cuttingSequence` of real workshop
steps (e.g. "Lay out the dovetail angle (typically 1:5 for Japanese joinery)").
It composes the shared `JOINT_DATABASE` from `@seshat/common` and adds Western
and Chinese traditions plus selection wizards (`JointSelectionCriteria` →
`JointSelectionResult`).

### @seshat/database

The persistence-validation layer (`libs/seshat/database/src`): `schema.ts`,
`migrations.ts`, and `seed.ts`, depending only on `zod`. `schema.ts` defines Zod
schemas for every storable entity — projects, rooms, materials, tools, devices,
courses/lessons, workshops, and designs. Notably it **re-declares** the branded
IDs as UUID-pattern Zod schemas (`ProjectIdSchema`, `MaterialIdSchema`, … each
`z.string().regex(uuidPattern, …)`) rather than importing them from
`@seshat/common`; the header comment is explicit that this is to keep
database-level validation decoupled from the common package. `migrations.ts` and
`seed.ts` provide the schema-evolution and seed-data surfaces.

### @seshat/design

The Interior Design Intelligence library (`libs/seshat/design/src`):
AI-room-visualization types, style analysis, parametric/generative design, floor
plan intelligence, mood-board analysis, and product discovery. `style-engine.ts`
exports `classifyStyle`/`checkStyleConsistency` over a `STYLE_DATABASE`;
`floor-plan.ts` implements `analyzeTrafficFlow`, `analyzeWorkTriangle`,
`checkAccessibility`, and `checkClearances` against `CLEARANCE_STANDARDS`;
`parametric.ts` is a genuine generative engine — constraint validation
(`validateParametricConstraints`), `optimizeTopology`, a genetic
`evolveDesign`/`FitnessFunction`, `generateVoronoiPattern`, and
`generateShelvingSystem`; and `product-discovery.ts` does budget estimation with
`QUALITY_MULTIPLIERS`/`STYLE_MULTIPLIERS`.

### @seshat/fabrication

The design-to-fabrication pipeline (`libs/seshat/fabrication/src`) for CNC,
laser cutting, 3D printing, and sheet nesting. `cnc.ts` computes real feeds and
speeds from `SFM_TABLE`/`CHIP_LOAD_TABLE`/`UNIT_POWER_TABLE`, generates G-code,
and does kerf compensation; `laser.ts` and `printing3d.ts` calculate machine
settings and material/time estimates from material profiles
(`MATERIAL_PROFILES`, `MATERIAL_DB`). `nesting.ts` is a 2D bin-packer:
`nestParts` uses a bottom-left-fill algorithm — expand by quantity, sort by
descending area, try each allowed rotation for the bottom-left position, open a
new sheet on overflow, and report oversized parts as unplaced — paired with
`optimizeCutSequence` that orders interior cuts before exterior cuts to prevent
part shifting.

### @seshat/harmony

The Spatial Harmony Engine (`libs/seshat/harmony/src`), the area's deepest
algorithmic library. `feng-shui.ts` implements Bagua-map analysis, a Five
Elements (Wu Xing) balance engine over generating/controlling/weakening cycles,
Flying Star (Xuan Kong) chart generation built on the Lo Shu magic square,
Kua-number East/West group directions, a simplified chi-flow fluid simulation,
and poison-arrow detection, plus room-specific analyzers
(`analyzeBedroom`/`analyzeKitchen`/`analyzeHomeOffice`). Sibling modules cover
Vastu Shastra (`createVastuMandala`, `detectVastuDefects`), design philosophy
(`assessWabiSabi`, `assessHygge`), Terrapin's 14 biophilic patterns
(`assessBiophilicDesign`), sacred geometry (golden ratio, Fibonacci, Vesica
Piscis, Flower of Life generators), and color psychology. `synthesis.ts`
(`synthesizeHarmony`) reconciles the traditions with weighted scoring and
conflict resolution — and the library uniquely carries a dedicated effectiveness
spec, `feng-shui-remedy-effectiveness.test.ts`.

### @seshat/smart

The Smart Dwelling integration library (`libs/seshat/smart/src`): IoT device
management, sensor processing, home automation, and wellness monitoring.
`device-registry.ts` handles protocol validation, signal-quality assessment,
battery-life estimation, and capability detection across the supported
`DeviceProtocol`s. `sensor-engine.ts` is real signal processing — linear
calibration, normalization, moving/exponential averages, z-score
`detectAnomaly`, multi-sensor `fuseSensorData`, threshold evaluation, and a full
table of per-`SensorType` default units and unit-conversion helpers.
`automation.ts` provides a rule engine (`evaluateTrigger`/`evaluateCondition`/
`evaluateRule`, `SceneManager`) with pluggable device/notification/webhook
handlers, and `wellness.ts` covers posture, sleep quality, circadian lighting,
and thermal/air/humidity/noise comfort scoring.

### @seshat/sustainability

The sustainability & circular-design library (`libs/seshat/sustainability/src`).
`carbon.ts` carries embodied-carbon emission factors per material
(`MATERIAL_CARBON_FACTORS`, e.g. hardwood 0.46, aluminum 9.16 kgCO2e/kg, cited
to ICE/EPA/Ecoinvent) plus transport, manufacturing, and end-of-life factors and
wood-sequestration credits, with calculators for each life-cycle stage.
`lifecycle.ts` runs full LCAs (`performLCA`, `identifyHotspots`,
`suggestImprovements`); `circular-design.ts` scores circularity, repairability,
and design-for-disassembly; and `certification.ts` tracks FSC chain-of-custody
(`validateChainOfCustody`, `determineMaxFSCClaim`), LEED contributions
(`LEED_VOC_LIMITS`, `LEED_CATEGORY_MAX_POINTS`), and expiry windows.

### @seshat/workshop

The workshop & makerspace management library (`libs/seshat/workshop/src`):
layout design, tool/material inventory, safety systems, and scheduling.
`scheduling.ts` is a space/equipment booking system backed by in-memory
`bookingStore`/`resourceStore` maps, with `registerResource` validating resource
invariants (non-empty id/name, ≥1 concurrent user,
`availableFrom < availableTo`) and conflict detection, availability checking,
and `ResourceUtilization` metrics. `layout.ts`, `inventory.ts`, and `safety.ts`
cover workshop-zone layout, material tracking, and safety planning over the
shared `WorkshopZone`/`InventoryItem` types from `@seshat/common`.