Domain · Features

Seshat Domain — Features

types that flow between libraries — a Room from @seshat/core can be passed directly into @seshat/harmony's Bagua analysis, and a WoodSpecies from

13sections36 minread
Markdown source
On this page
Supporting documentation. This domain also carries 3 operational supporting docs under docs/domains/seshat/ (API notes, ADRs, deep topic guides) — reconciled here by linking, kept beside the code as supporting material rather than a second canonical source (§2, §13).

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 and recorded the deeds of pharaohs — Seshat provides 11 libraries covering woodworking and craft knowledge, AI-powered interior design, digital fabrication pipelines (CNC routing, laser cutting, 3D printing), spatial harmony traditions (Feng Shui, Vastu Shastra, biophilic design, sacred geometry), smart dwelling IoT integration, sustainability and circular-economy design scoring, maker education, workshop management, and data persistence. The domain bridges millennia of accumulated wisdom about how to build and inhabit sacred space with the precision of modern digital fabrication technology.

Seshat ships as 11 TypeScript libraries (libs/seshat/*) of deterministic, pure-function domain logic plus a few in-memory stores. There is no runtime service, API gateway, or event bus; the only runtime dependency is zod.

Seshat addresses a real problem: the knowledge required to design, build, and inhabit a well-crafted space is deep, fragmented, and hard to encode in software. A single furnished room draws on materials science (wood species and seasonal movement), spatial harmony (Feng Shui sector analysis, Vastu orientation), colour psychology (emotional impact, accessibility contrast), digital fabrication (CNC toolpaths, laser cutting parameters), sustainability (embodied carbon, lifecycle assessment), and safety (ventilation, ergonomics). Seshat encodes each of these disciplines as domain-specific computational functions, so any application in the Oshun platform can compose them rather than reinventing them.

The eleven libraries are consumed directly by application code — there is no Seshat service to call over HTTP. This section describes what each library provides.

Common Foundation (@seshat/common)#

@seshat/common is the shared vocabulary of the entire domain. It defines the types that flow between libraries — a Room from @seshat/core can be passed directly into @seshat/harmony's Bagua analysis, and a WoodSpecies from @seshat/craft can be passed into @seshat/fabrication's feeds-and-speeds calculator, without any translation. It also ships the curated constant databases that every library draws on: wood species properties, joint strength ratings, Bagua areas, sacred geometry constants, and more.

  • Material Type System: Strongly typed representations of wood species, sheet goods, metals, polymers, textiles, stone, and composite materials. Each material type carries physical properties (density, hardness, workability) and fabrication compatibility flags (CNC-safe, laser-cuttable, 3D-printable), ensuring downstream pipelines receive only materials they can process.
  • Measurement and Unit Conversions: Consistent handling of imperial and metric measurements — essential in woodworking where US tools use inches and fractions while European tools use millimetres. Conversion utilities include fractional inch representation (e.g., 3/4 inch = 0.75 inch = 19.05 mm) to prevent the decimal-to-fraction errors that cause misfit joints.
  • Colour System Types: Hex, RGB, and HSL colour representations (RGBColor, HSLColor, DesignColor, ColorPalette) with conversion utilities and WCAG contrast calculation, used across the design and harmony subsystems.
  • Geometry Primitives: 2D types (Point2D, Vector2D, Polygon2D, LineSegment2D, BoundingBox2D, Dimensions2D) and 3D types (Point3D, Vector3D, BoundingBox3D, Dimensions3D, EulerAngles, Transform3D) shared by both the design and fabrication subsystems, avoiding parallel type hierarchies.

Domain Orchestration (@seshat/core)#

@seshat/core is the glue layer. It does not own any domain logic itself — that lives in the specialist libraries — but it provides the infrastructure that all of them rely on: a project lifecycle state machine, a workflow dependency graph engine, configuration, structured logging, and feature flags. Applications typically start here, creating a Project and a Workflow, then calling the specialist libraries as the workflow progresses.

  • Project Lifecycle Management: ProjectManager is an in-memory store for Seshat projects, tracking category, an eleven-phase lifecycle, priority, budget (in integer cents), collaborators, tags, and associated room IDs. Phase transitions are governed by an explicit state machine; budget expenditure is checked against the allocation. (Project file storage, version history, and branching are not implemented.)
  • Workflow DAG Engine: A dependency-graph engine builds and validates multi-step workflows — Kahn's-algorithm cycle detection and topological sort, step-readiness checks, blocker resolution, progress computation, and validated step-status transitions. WORKFLOW_TEMPLATES provides a default phase sequence per project category (woodworking, interior design, spatial harmony, smart dwelling, fabrication, craft, renovation, workshop setup).
  • Module Registry: A capability map (MODULE_CAPABILITIES) records which capabilities each Seshat module exposes. Core references the other libraries only as identifiers — it does not import them — so applications compose libraries directly.
  • Cross-Cutting Services: Section-oriented Zod-validated configuration (ConfigManager), a structured domain error hierarchy (SeshatError with numeric codes and severities), a self-contained structured logger (SeshatLogger), and a feature-flag system with deterministic percentage rollout (FeatureFlagManager, 10 defined flags).

Woodworking and Craft Knowledge (@seshat/craft)#

@seshat/craft is a woodworking knowledge engine: the accumulated expertise of master craftspeople encoded as deterministic functions. It covers every stage of a woodworking project — selecting species and joints, computing wood movement, choosing and sharpening tools, selecting and layering finishes, and planning cuts and timelines. All functions are pure: they take typed inputs and return typed results with no side effects.

Joinery Engineering#

Joinery is the art of connecting pieces of wood — the structural and aesthetic foundation of fine woodworking. The joint type chosen determines the strength, appearance, and longevity of a piece, and a single poor joint choice can cause catastrophic failure years after construction.

  • Joinery Catalogues: Three databases document the craft's joints. JOINT_DATABASE (in @seshat/common) covers 20 Western, universal, and Japanese joints with strength ratings, difficulty, tool requirements, and applications. SASHIMONO_JOINTS is a deep database of Japanese cabinetmaking joints (dovetail, sickle scarf, mortise-and-tenon, metal-ring splice, puzzle splice, and more) with romanized/Japanese/English names, step-by-step cutting sequences, common mistakes, and best use cases. KUMIKO_PATTERNS documents geometric lattice patterns with strip angles and symbolism.
  • Joint Strength Data: Each catalogue joint carries a JointStrength rating — tensile, shear, compression, racking, and overall on a 1–10 scale — reflecting real woodworking knowledge of how each joint resists load.
  • Joint Geometry Calculation: calculateDovetailLayout computes pin and tail positions for a dovetail; calculateMortiseTenonSize sizes a tenon (thickness, width, length, optional haunch) for a stock dimension and load type; calculateDrawboreOffset computes the drawbore pin offset; calculateBoxJoint lays out finger joints; calculateKumikoNotch computes kumiko half-lap notch geometry.
  • Joint Selection Wizard: selectJoint scores and ranks joint recommendations from JointSelectionCriteria — application, load type, skill level, available tools, aesthetic requirement, material thickness, and reversibility — returning each option with a score, reasoning, and warnings. findSashimonoJoint, findKumikoPattern, getJointsByTradition, and getJointsForApplication support catalogue lookup.

Materials Science#

  • Wood Species Database: Over 30 domestic and exotic hardwood and softwood species with scientifically accurate physical data — Janka hardness (the force required to embed a 0.444-inch steel ball to half its diameter into the wood face, the industry standard for hardness comparisons), density, grain pattern and texture, durability classification, and tangential and radial shrinkage coefficients from green to oven-dry moisture content (essential for calculating seasonal wood movement). Each species also carries nine per-operation workability ratings (sawing, planing, turning, carving, gluing, finishing, nailing, screwing, bending). Species lookup, fuzzy key resolution, side-by-side comparison, similar-species search, and project-driven recommendation are all provided.
  • Wood Movement Calculations: Wood expands and contracts seasonally as ambient humidity changes — a wide cherry tabletop can move 5–8 mm across its width from winter to summer in a heated interior. The library calculates equilibrium moisture content (Fahrenheit and Celsius variants), predicts seasonal movement, analyses current moisture state against an application's recommended range, and estimates kiln drying time — the foundation for joinery decisions that must accommodate wood movement without splitting.
  • Grain Orientation Analysis: analyzeCutOrientation classifies a board as quartersawn, flatsawn, or riftsawn from its ring angle and reports dimensional-stability implications and the tangential-to-radial shrinkage ratio.
  • Visual Wood Identification: identifyWood produces a ranked species match from observed visual characteristics (grain pattern, texture, colour, end-grain pore structure) with confidence scores.
  • Bill of Materials Generation: generateBOM turns a parts list into a costed bill of materials with board-feet totals, a waste factor, and a per-species breakdown.

Tool Management#

  • Tool Database: getToolDatabase exposes a tiered tool catalogue (TOOL_TIERS); suggestToolUpgrade recommends tool acquisitions for a maker's situation.
  • Feeds, Speeds & RPM: calculateFeedsAndSpeeds and calculateOptimalRPM compute recommended spindle speed, feed rate, chip load, depth of cut, and stepover for a tool-and-material combination (returned as a CNCFeedSpeed), enabling consistent, safe results.
  • Sharpening Assessment: getSharpnessAssessment evaluates an edge tool's condition (razor-sharp → damaged), recommends an action (strop, hone, sharpen, regrind), and reports the primary/secondary bevel angles and a grit progression to restore the edge.
  • Sanding Progression: calculateSandingProgression plans a grit sequence from a starting to a target grit for a wood type, and getFinishSandingGrit gives the recommended final grit for a finish.

Finishing Techniques#

  • Finish Database: FINISH_DATABASE is a catalogue of FinishProfile records covering all major finish categories — penetrating oils, wax, lacquer, shellac, oil-based and waterborne polyurethane, conversion varnish, and more — each with build type, sheen options, application methods, coat counts, dry and cure times, durability/water/heat/UV resistance ratings, food-safety, VOC level, recommended surfaces, known incompatibilities, and application tips.
  • Finish Lookup & Filtering: getFinish, getFinishesByType, getFoodSafeFinishes, and getLowVOCFinishes query the database by name, type, food-safety, or VOC level.
  • Finish Selection (selectFinish): Given selection criteria — indoor / outdoor use, food contact, water-exposure level, desired look, applicator skill, time constraint, low-VOC preference, and wood species — returns ranked finish recommendations with reasoning.
  • Finish Compatibility (checkFinishCompatibility): Checks whether two finishes can be layered, reporting issues, required preparation steps, and the recommended wait time between layers; getFinishSandingGritByKey gives the recommended sanding grit for a finish.

Project Planning#

  • Project Template Library: PROJECT_TEMPLATES is a curated catalogue of woodworking projects with dimensions, recommended species, joints used, required skills, and estimated hours. Templates are queryable by name, difficulty category, and joint type.
  • Cut List Generation: generateCutList turns a parts specification into a cut list, accounting for kerf — standard (0.125") and thin-kerf (0.09375") constants are provided — and joinery allowances.
  • Time Estimation: estimateProjectTime produces a phased estimate (design, milling, joinery, assembly, finishing hours) with a skill-level multiplier — helping makers commit to realistic project timelines.
  • Difficulty Assessment: assessDifficulty scores a project across seven weighted factors (joint complexity, joint variety, curved cuts, material difficulty, finishing complexity, assembly complexity, precision required) and returns an overall difficulty label with an experience recommendation.

Interior Design Intelligence (@seshat/design)#

@seshat/design is a library of deterministic, rule-based design analysis functions over structured inputs. It computes design intelligence — style classification, layout scoring, parametric geometry, budget estimation — from typed data. It does not generate images, run AI/ML models, or call external services; "visualisation" types describe a scene as structured data (RoomVisualization, RenderSettings, MaterialSurface, LightingSource), not a rendered picture.

Style Analysis#

  • Rule-Based Style Classification: classifyStyle scores a room's attributes (colours, materials, furniture styles, patterns) against STYLE_DATABASE — a record keyed by all 24 supported DesignStyle values (modern, contemporary, minimalist, Scandinavian, industrial, mid-century, Art Deco, bohemian, traditional, farmhouse, coastal, Japanese, Mediterranean, rustic, transitional, eclectic, Art Nouveau, brutalist, tropical, shabby chic, Memphis, Bauhaus, Wabi-Sabi, Hygge). Each entry carries era, notable designers, signature furniture, elements to avoid, and complementary/clashing styles. The classifier produces a weighted composite score and a confidence value.
  • Style Consistency Scoring: checkStyleConsistency detects stylistic clashes across multiple rooms — a Danish-modern sofa in a Baroque-influenced room scores low — identifies the offending rooms, grades the result A–F, and suggests transition strategies.
  • Style Interpolation: interpolateStyles blends two aesthetic directions at a configurable ratio, expressing the result as a colour palette, material list, furniture list, patterns, and key features, with a harmony score.
  • Style Lookup Helpers: getStyleInfo, getComplementaryStyles, and getClashingStyles expose the style database for discovery.

Parametric and Generative Design#

  • Parametric Furniture Definitions: createParametricDesign builds a parametric model from dimensional parameters with min/max/step constraints and dependency formulas; validateParametricConstraints checks a parameter set. Changing a parameter updates derived dimensions and component counts.
  • Topology Optimisation: optimizeTopology takes load definitions and support fixtures and computes a reduced-material structure, reporting volume reduction, strength-to-weight ratio, maximum stress, displacement, and a safety factor.
  • Genetic Design Evolution: evolveDesign runs a genetic algorithm over a population of DesignCandidates scored on a multi-objective DesignFitnessScore (cost, aesthetics, strength, sustainability, ergonomics), returning the best candidate, a convergence history, and the top candidates.
  • Pattern Generation: generateVoronoiPattern produces organic Voronoi cell patterns; generateShelvingSystem computes a complete shelving system (shelf positions, upright count, pin spacing, material volume, load capacity).

Floor Plan Intelligence#

  • Floor Plan Analysis: analyzeFloorPlan evaluates a set of Room objects for room proportions (golden-ratio proximity, squareness, usable-area ratio), natural light (window-to-floor ratio, estimated lux, daylight autonomy), and circulation efficiency, producing graded scores and suggestions.
  • Traffic Flow Analysis: analyzeTrafficFlow identifies circulation paths and bottlenecks, classifying paths as primary/secondary/service and reporting the circulation percentage.
  • Accessibility & Clearance Checks: checkAccessibility audits a layout against ADA-style requirements (path width, turning radius, door clearance, reach range); checkClearances reports clearance violations between furniture items and walls with severity grading.
  • Kitchen Work Triangle: analyzeWorkTriangle measures the sink–stove– fridge triangle, flags short-leg / long-leg / traffic-crossing violations, and grades efficiency.
  • Furniture Layout Generation: generateFurnitureLayout places furniture to balance clearance, visual balance, conversation grouping, focal point, and walkability; LAYOUT_PRESETS provides predefined arrangements queryable by room type, and recommendLayoutPreset suggests one.

Mood Board Analysis#

  • Mood Board Analysis: analyzeMoodBoard derives a design brief from a set of mood-board inputs — extracted colours with proportions and roles, detected styles, materials, patterns, mood descriptors, suggested room types, and a coherence score.
  • Palette Extraction: extractMoodBoardPalette produces a dominant ColorPalette; generateStyleTags assigns weighted style tags.
  • Natural-Language Brief Parsing: parseDesignBrief performs keyword-based extraction of design intent from free-form text — room type, style keywords (via a synonym dictionary), budget range, colour and material preferences, furniture mentions, constraints (pet-friendly, child-safe, wheelchair accessible, etc.), and aesthetic keywords, with a parse-confidence score.

Product Discovery#

  • Product Matching: matchProducts scores candidate products against a search specification (style fit, dimension fit, material fit, colour fit) and classifies a budget tier.
  • Budget Estimation: estimateRoomBudget produces a furnishing budget for a room and style across line items, with low/high ranges, tax, and delivery estimates; STYLE_MULTIPLIERS and QUALITY_MULTIPLIERS adjust pricing. compareBudgetTiers and classifyBudgetTier support tier analysis.

Design-to-Fabrication Pipeline (@seshat/fabrication)#

The fabrication library bridges the gap between a designed piece and the instructions needed to physically produce it on digital fabrication equipment. It takes dimensional inputs and material specifications and produces the control programs and parameter sets that drive CNC routers, laser cutters, and 3D printers — plus the nesting algorithms that minimize material waste.

CNC Toolpath Generation#

CNC (Computer Numerical Control) routers execute precise cutting paths based on G-code — a numerical control programming language specifying tool movements, feed rates, spindle speeds, and depths.

  • G-Code Output for 3-Axis CNC Routers: Generate production-ready G-code for the most common workshop configuration — three axes (X left-right, Y front-back, Z up-down). The library handles tool offset compensation, safe retract heights, and emergency stop positions.
  • Feeds and Speeds Calculation: The correct combination of spindle RPM and feed rate (movement speed) varies dramatically by material and tool type — too fast and the tool breaks or burns; too slow and finish quality degrades. The library computes optimal SFM (surface feet per minute, the speed at which the cutting edge contacts material), chip load (the amount of material each flute removes per revolution), and recommends RPM and feed rate for any material-tool combination.
  • Toolpath Optimisation: Minimise air cutting (time spent moving the tool when not in material), efficient part nesting on a single sheet, and optimal lead-in/lead-out strategies that avoid plunge marks. A 30-minute job can often be reduced to 20 minutes with good toolpath planning.
  • Kerf Compensation: The router bit removes material equal to its diameter. The library applies correct inside/outside offset compensation — inside cuts (pocket, slot) require the tool centre path to be larger than the finished dimension; outside (profile cut) smaller — ensuring parts fit as designed.
  • Machining Time Estimation: Predict job duration from toolpath length, feed rate, number of passes, and tool change time — essential for production scheduling and customer quoting.
  • Chip Load & SFM Tables: CHIP_LOAD_TABLE gives a min/max chip-load range per workpiece-material family (21 families — hardwoods, softwoods, plywood, MDF, aluminium alloys, steels, plastics, composites); SFM_TABLE and UNIT_POWER_TABLE supply surface speeds and unit power. The feeds-and-speeds calculator interpolates within these ranges, preventing tool breakage and surface-quality problems.

Laser Cutting Parameters#

  • Material-Specific Laser Settings (calculateLaserSettings): Computes power percentage, speed, pass count, kerf, focus offset, and air-assist for a material, thickness, machine spec, and operation mode. MATERIAL_PROFILES stores a per-material reference profile (LaserMaterial covers plywood, MDF, balsa, hardwood, acrylic, leather, cardboard, cork, fabric, anodized aluminium, and more) with reference power/speed/passes, CO₂ and diode kerf widths, and safety notes.
  • Operation Modes: The LaserOperationMode type distinguishes full-depth cuts from engraving, scoring, and marking; settings are computed per mode.
  • Pass Count for Thick Materials: The settings calculator increases pass count for materials beyond a single-pass thickness limit.
  • Kerf Compensation: MATERIAL_PROFILES records per-material kerf width; calculateLaserSettings reports the kerf so a consumer can compensate precision-fit joints. generateLaserToolpath orders cuts (interior before exterior); calculateLaserMaterialUsage reports sheet utilisation and waste.

3D Printing Specifications#

  • Print Settings Calculation (calculatePrintSettings): From a model mesh, print material, and quality preset, computes a PrintJobSettings — layer height, wall count, top/bottom layers, infill percentage and pattern, print and travel speeds, nozzle and bed temperatures, support strategy, adhesion type, retraction, and fan speed. LAYER_HEIGHTS and DEFAULT_INFILL provide presets.
  • Material Database: MATERIAL_DB profiles the supported PrintMaterial values — PLA, ABS, PETG, nylon, TPU, resin, wood-fill, carbon-fiber, and metal-fill — with their printing characteristics.
  • Print Time Estimation (estimatePrintTime): Estimates print duration as a breakdown of extrusion, travel, and layer-change time from the model and settings, reporting layer count and total path lengths.
  • Material Usage Estimation (estimatePrintMaterialUsage): Computes the volume of model fill, infill, walls, supports, and adhesion, with filament length, weight in grams, an estimated cost, and an applied waste factor.

2D Nesting and Sheet Optimisation#

Material sheets are expensive. The nesting algorithms maximise how many parts fit on each sheet, and enforce orientation constraints that preserve grain direction for wood and composite materials.

  • Bin-Packing (nestParts): Rectangular part nesting using a bottom-left-fill algorithm with multi-rotation support and kerf accounting, packing parts across as many sheets as needed to maximise material utilisation.
  • Grain Direction Constraint: A NestingPart flagged grainSensitive is restricted to grain-preserving rotations (0° and 180°), so wood and composite parts stay correctly oriented relative to the sheet's grain.
  • Cut Sequence Optimisation (optimizeCutSequence): Orders cuts so interior cuts (holes, pockets) precede the exterior profile — a large outer profile cut removing structural support before interior parts are complete would cause parts to shift mid-job.
  • Sheet Estimation & Waste Reporting: estimateSheetsRequired predicts the number of sheets needed; calculateWasteWithKerf and the NestingResult report per-sheet and overall utilisation and waste percentages including the kerf applied.

Spatial Harmony Engine (@seshat/harmony)#

The harmony library implements traditional spatial wisdom traditions as computational models, enabling systematic application of principles that have guided human habitation for millennia. It covers seven traditions — Feng Shui, Vastu Shastra, biophilic design, sacred geometry, colour psychology, Wabi-Sabi, and Hygge — and synthesizes them into a unified, weighted score that surfaces conflicts and agreements between traditions.

Feng Shui Analysis#

Feng Shui (literally "wind-water" in Chinese) is a 3,000-year-old tradition of arranging the built environment to harmonise the flow of qi (life energy) through a space. The tradition distinguishes between Form School (physical landscape and building orientation) and Compass School (directional calculations based on the occupant's personal data).

  • Bagua Map Overlay: The Bagua (eight trigrams from the I Ching) maps nine life areas — Wealth/Prosperity (southeast), Fame/Reputation (south), Love/Marriage (southwest), Family/Health (east), Centre/Wellbeing (centre), Creativity/Children (west), Knowledge/Self-Cultivation (northeast), Career (north), Helpful People/Travel (northwest) — onto the floor plan as a 3×3 grid aligned with either the compass (Classical Feng Shui) or the front door (BTB/Western Feng Shui). The library implements both alignment methods with explicit notation of which school is being applied.
  • Flying Stars Chart Generation (Xuan Kong): calculateFlyingStarChart casts the natal chart of a building from its 20-year period and facing direction — a 9-palace grid where each palace carries a period, mountain, and water star with a combined interpretation. getPeriodForYear maps a year to its period; calculateAnnualStar computes the annual visiting star for an optional annual overlay. (Monthly star overlays are not implemented.)
  • Kua Number Calculator: Each person has a personal Kua number calculated from birth year and biological sex. The Kua number assigns four favourable directions (Sheng Chi — growth; Tien Yi — health; Nien Yen — relationships; Fu Wei — stability) and four unfavourable directions (Ho Hai — mishaps; Wu Gui — five ghosts; Lui Sha — six killings; Chueh Ming — total loss). Sleeping with the head in a favourable direction and orienting the desk toward a favourable direction are key Kua-based recommendations.
  • Chi Flow Simulation: simulateChiFlow models qi flow with a simplified velocity-field grid computed over a room's polygon — chi enters through doors and windows, and the model identifies stagnation zones (dead chi), sha-chi sources (rushing chi, poison arrows), and entry/exit points, classifying the overall flow as meandering, moderate, rushing, or stagnant and proposing remedies. (This is a heuristic flow model, not a full CFD solver.)
  • Five Elements (Wu Xing) Analysis: The five elemental energies — Wood (growth; colours: green, blue), Fire (passion; colours: red, orange, purple), Earth (stability; colours: yellow, brown), Metal (precision; colours: white, grey), Water (wisdom; colours: black, deep blue) — interact in generating cycles (Wood feeds Fire, Fire creates Earth/ash, Earth produces Metal, Metal holds Water, Water nourishes Wood) and controlling cycles (Wood depletes Earth, Earth absorbs Water, Water quenches Fire, Fire melts Metal, Metal cuts Wood). Rooms are assessed for elemental balance, with recommendations for restoring harmony through colour, shape, material, and object selection.
  • Poison Arrow (Sha Chi) Detection: Sharp corners, exposed overhead beams, T-junction roads pointing at a building, and stairways aligned with entrance doors all direct cutting energy toward specific positions. The algorithm identifies these configurations in the floor plan and suggests remedies.
  • Room-Specific Analysis: Bedroom analysis focuses on bed placement in the "command position" (visible to the door but not directly in line with it); kitchen analysis focuses on stove position and avoiding stove facing the door; home office analysis optimises for career and creativity sectors.

Vastu Shastra Analysis#

Vastu Shastra (literally "science of dwelling" in Sanskrit) is the ancient Indian science of architecture, established in the Vedic period, that prescribes rules for building design, space organisation, and compass orientation to harmonise a structure with natural forces and cosmic energies.

  • Purusha Mandala Grid Overlay: The Purusha Mandala is a sacred geometric diagram — typically a 9×9 grid (81 squares) — representing the cosmic being Vastu Purusha whose body is mapped across the property. Different grid zones are presided over by different devas (divine forces), prescribing appropriate room functions for each zone: northeast (Ishanya) — sacred space, water features, and study; southeast (Agneya) — fire and kitchen; southwest (Nairiti) — master bedroom and heavy storage; northwest (Vayavya) — guest rooms and vehicles.
  • Cardinal Direction Room Placement: Vastu prescribes specific rooms for specific compass directions — the main entrance should face north or east; the kitchen should be in the southeast (fire quadrant); the master bedroom in the southwest; bathrooms in the northwest; pooja (prayer) room in the northeast. The library scores any floor plan against these prescriptions.
  • Element and Deity Zone Compliance Scoring: Score any floor plan against Vastu's zone prescriptions — each room's current function is compared against the Vastu-prescribed function for that zone, producing a compliance score and prioritised list of modifications ordered by impact.
  • Entrance Orientation Assessment: The direction the main door faces, the direction it swings open, and the features visible immediately upon entry are all significant in Vastu. The library scores entrance orientation and identifies common violations (toilet visible from entrance, staircase immediately opposite the entry, main door in the southwest).

Biophilic Design#

Biophilic design is grounded in the biophilia hypothesis — humans evolved in nature and retain an innate affinity for natural environments. Biophilic design incorporates natural patterns, materials, and sensory stimuli to reduce physiological stress, improve cognitive performance, and increase occupant wellbeing.

  • 14 Biophilic Design Patterns Assessment: assessBiophilicDesign scores a space against the 14 patterns of biophilic design (the Terrapin Bright Green framework) — visual and non-visual connection with nature, non-rhythmic sensory stimuli, thermal and airflow variability, presence of water, dynamic and diffuse light, connection with natural systems, biomorphic forms and patterns, material connection with nature, complexity and order, prospect, refuge, mystery, and risk/peril. Each pattern carries stress-reduction and cognitive-performance contribution scores (from BIOPHILIC_PATTERNS), and the result groups patterns into the three categories (nature in the space, natural analogues, nature of the space).
  • Plant Recommendation Engine: recommendPlants recommends indoor plants filtered by light requirement, maintenance tolerance, air-purification priority, and pet-safety, drawing on a built-in plant database (PlantRecommendation records with scientific names, watering needs, light tolerance, NASA Clean Air Study purification data, and Feng Shui element).
  • Air Quality Consideration: Plant recommendations carry NASA Clean Air Study purification ratings and the specific pollutants each species removes (benzene, formaldehyde, trichloroethylene), so air-quality priority feeds directly into the recommendation.

Sacred Geometry#

Sacred geometry applies geometric ratios found throughout nature to human environments — these proportions appear in phyllotaxis (leaf arrangement), shell growth spirals, and the architecture of sacred buildings across unrelated ancient cultures.

  • Proportion Analysis: analyzeProportions evaluates dimensions against the golden ratio and Fibonacci ratios, reporting golden-ratio deviation, the nearest Fibonacci ratio match, harmonic-proportion comparisons, an overall proportion score, and recommendations. isGoldenRatio and isFibonacciRatio are direct ratio tests.
  • Golden-Ratio Construction Helpers: goldenDivision splits a length at the golden section; goldenRectangleSubdivisions produces a recursive golden-rectangle subdivision sequence.
  • Sacred-Geometry Coordinate Generation: generateGoldenSpiralPoints, generateVesicaPiscis, and generateFlowerOfLife compute the point sets and circle centres for those figures, returning coordinate data (not rendered SVG or DXF files) that a consumer can draw or export.

Colour Psychology#

  • 60-30-10 Colour Rule: The dominant rule in interior colour composition — 60% dominant colour (typically walls), 30% secondary colour (typically large furniture), 10% accent colour (cushions, throws, artwork, accessories). The library validates any proposed colour scheme against this rule and suggests adjustments.
  • Emotional Impact Scoring: Empirical colour psychology research mapped to room function recommendations — blue and green (calming, productive — recommended for offices and bedrooms), yellow (stimulating and energising — recommended for kitchens and playrooms), red (increases appetite and excitement — effective for dining rooms), purple (creative and contemplative), white (spacious, clean), and warm neutrals (welcoming, grounded).
  • WCAG Contrast for Interior Signage: Accessibility compliance — wayfinding signs, room labels, and safety notices must meet WCAG 2.1 contrast ratios (4.5:1 for normal text, 3:1 for large text) to be readable by people with low vision.
  • Colour Temperature by Room Activity: Warm light (2700–3000 K, incandescent appearance) for relaxation spaces; neutral white (3500–4000 K) for kitchens and offices; cool daylight (5000–6500 K) for studios and retail displays — recommendations aligned with circadian rhythm support and functional lighting needs.

Multi-Tradition Synthesis#

When a space is analysed through multiple harmony traditions, they will sometimes agree (both Feng Shui and Vastu recommend unobstructed entrance areas) and sometimes conflict (Feng Shui's kitchen placement may differ from Vastu's). The synthesis layer resolves these intelligently rather than leaving the contradiction to the application developer.

  • Unified Harmony Report: synthesizeHarmony combines per-tradition scores across the seven supported HarmonyTradition values (Feng Shui, Vastu Shastra, Wabi-Sabi, Hygge, biophilic, sacred geometry, colour psychology) into a weighted composite HarmonySynthesis with an A–F grade and prioritised, de-duplicated recommendations.
  • Conflict & Agreement Detection: When traditions contradict, the synthesis surfaces each TraditionConflict with both recommendations and a resolution; it also records TraditionAgreements where traditions reinforce each other.
  • Configurable Tradition Weights: A SynthesisConfig selects which traditions to include and supplies optional per-tradition weights (equal weights are used by default), plus a recommendation score threshold.

Smart Dwelling Integration (@seshat/smart)#

@seshat/smart models the connected home as a coherent computational system. It manages the catalogue of IoT devices, processes the continuous stream of sensor data those devices produce, evaluates automation rules against that data, and computes wellness scores from environmental readings. All state is held in in-memory stores backed by plain TypeScript Maps; the application layer is responsible for persisting device registrations and automation rules to a database.

IoT Device Management#

  • Device Registry: DeviceRegistry catalogues smart-home devices with manufacturer, model, communication protocol, firmware version (with firmware history), room assignment, and capabilities. Devices can be grouped by room, function, or zone (groupDevices, addDeviceToGroup), and getDevicesNeedingAttention / checkDeviceHealth surface devices with low battery, poor signal, or stale firmware.
  • Protocol Support: Zigbee (mesh network, long range, battery-efficient — the dominant protocol for smart lighting and sensors), Z-Wave (similar to Zigbee on a different radio frequency, excellent reliability), Matter (the new unified standard backed by Apple, Google, Amazon, and Samsung — enables cross-brand interoperability without vendor lock-in), Thread (the IP-based networking layer that Matter uses), Wi-Fi (high bandwidth — cameras, displays), and Bluetooth (short range — locks, presence sensors, wearables).
  • Signal Quality Assessment: assessSignalQuality classifies a device's signal strength (dBm) into excellent/good/fair/poor/critical bands, and estimateBatteryDays projects remaining battery life from a drain rate.
  • Capability Detection: detectCapabilities derives a device's supported features from its type and protocol; validateProtocol and validateProtocolConfig check protocol settings.

Sensor Data Processing#

  • Real-Time Sensor Ingestion: Continuous ingestion of sensor readings — temperature (°C/°F), humidity (relative humidity %), CO₂ (ppm — the primary indoor air quality indicator, with 1,000 ppm indicating poor ventilation), VOC (ppb — volatile organic compounds from off-gassing materials and cleaning products), PM2.5 (fine particle count — relevant for wildfire smoke and cooking particulates), PM10, lux (light intensity), PIR motion, door/window contact state, and energy consumption (watts).
  • Unit Normalisation: Different sensors report the same physical quantity in different units or with different calibration offsets. The library normalises all readings to standard units with configurable calibration correction factors.
  • Anomaly Detection: detectAnomaly flags readings using a z-score test against a configurable threshold, classifying severity (mild/moderate/severe) and direction (above/below). evaluateThresholds raises alerts when readings cross configured SensorThresholds. Moving-average and exponential-moving- average helpers smooth a reading series.
  • Sensor Fusion: fuseSensorData combines multiple co-located sensor sources into a single higher-confidence value (weighted average), reporting a confidence score and each source's contribution.

Home Automation#

  • Scene Management: SceneManager defines, stores, and activates named multi-device scenes (createScene, updateScene, activateScene, listScenesByRoom, listScenesByTag) — a "Movie Night" scene dims lights, closes blinds, and sets the thermostat. activateScene applies each device state and reports a per-device ActionExecutionResult.
  • Rule Engine: AutomationEngine registers and evaluates automation rules. Triggers (AutomationTriggerExtended) cover time/cron, sensor thresholds with hysteresis and duration, device state, and geofence; rules support and/or trigger logic, conditions, priorities, cooldowns, and schedules. Pure evaluators — evaluateTrigger, evaluateCompoundTriggers, evaluateCondition, evaluateRule, evaluateRules — and async executors (executeAction, executeRuleActions) drive rule processing.
  • Circadian Lighting: calculateCircadianLighting recommends a colour temperature and brightness for the time of day across phases (wake-up, morning, midday, afternoon, evening, night, sleep) — bright cool light in the morning, warm dim light in the evening to support natural melatonin rise.

Wellness Monitoring#

  • Indoor Air Quality Scoring: assessAirQuality produces an air-quality score and CO₂ rating (excellent → hazardous) from CO₂ and optional VOC and PM2.5 readings, with recommendations when quality is poor.
  • Environmental Comfort: assessEnvironmentalComfort aggregates thermal, air-quality, humidity, and noise sub-assessments (assessHumidityComfort, assessNoiseComfort) into an overall comfort rating with recommendations.
  • Sleep Quality Assessment: assessSleepQuality scores a night from bed- sensor data (movement frequency, temperature stability, restless periods) and estimates deep-sleep percentage with coaching recommendations.
  • Ergonomic & Posture Analysis: analyzePosture, calculateWeightDistribution, calculateLeanAngle, and trackSittingDuration evaluate seated posture from pressure-map data and track sitting/standing time, flagging when a break is due.
  • Simplified Thermal Comfort: assessThermalComfort derives a PMV-like thermal-sensation estimate (cold → hot) from ambient temperature alone — a simplified model; full ASHRAE 55 PMV inputs (radiant temperature, air velocity, humidity, clothing, metabolic rate) are not modelled.
  • Wellness Report: WellnessReport composes sitting time, posture, sleep, environmental comfort, and circadian-lighting results into an overall wellness score with top recommendations.

Sustainability and Circular Design (@seshat/sustainability)#

@seshat/sustainability provides the environmental intelligence layer for Seshat. It implements formal LCA (Life Cycle Assessment) methodology following ISO 14040/14044, computes embodied carbon from peer-reviewed emission factors, scores designs against circular-economy principles, and tracks sustainability certifications. The numeric reference data (carbon factors, transport emission factors, grid emission intensities) is sourced from established databases — ICE (University of Bath), EPA, and Ecoinvent.

Carbon Footprint Calculation#

  • Material Carbon Calculation: calculateMaterialCarbon computes embodied carbon from MATERIAL_CARBON_FACTORS — per-material kgCO₂e/kg values sourced from the ICE database (University of Bath), EPA, and Ecoinvent (kiln-dried hardwood ≈0.46, virgin steel ≈1.95, primary aluminium ≈9.16, with recycled variants substantially lower). calculateTotalCarbon aggregates material, transport, manufacturing, use-phase, maintenance, and end-of-life carbon — including a wood sequestration credit — into a CarbonBreakdown.
  • Transportation Emissions: calculateTransportCarbon computes transport carbon from TRANSPORT_EMISSION_FACTORS for road, rail, sea, and air, with configurable load factors (DEFAULT_LOAD_FACTORS) and an optional return trip; calculateSupplyChainCarbon sums multiple transport legs.
  • Manufacturing & End-of-Life Carbon: calculateManufacturingCarbon uses per-process power draw (PROCESS_POWER_KW) and grid emission factors (GRID_EMISSION_FACTORS); calculateEndOfLifeCarbon accounts for disposal methods and recycling credits (END_OF_LIFE_FACTORS).
  • Carbon Payback & Sequestration: carbonPaybackPeriod computes how long a lower-emission replacement takes to pay back its upfront embodied-carbon difference. Carbon sequestration credits for wood are modelled explicitly (WOOD_CARBON_SEQUESTRATION_PER_KG, with eligible and partial-sequestration material sets), so the CarbonBreakdown reports a net total including stored carbon. compareMaterialCarbon and describeMaterialCarbon support material-substitution decisions.

Life Cycle Assessment (LCA)#

A formal LCA evaluates environmental impact across the entire product lifecycle — from raw material in the ground to end-of-life disposal — following ISO 14040/14044 standards.

  • Full LCA (performLCA): Follows ISO 14040/14044 methodology, computing a LCAResult with per-stage impacts (extraction, manufacturing, transport, use, maintenance, end-of-life), a full carbon breakdown, total energy, water, and waste, recyclability and biodegradability percentages, hotspots, improvement suggestions, and an overall sustainability rating.
  • Impact Categories: The ImpactCategory type names eight ISO 14044 categories — global warming potential, acidification, eutrophication, ozone depletion, photochemical ozone creation, abiotic depletion, water footprint, and land use.
  • Hotspot & Improvement Analysis: identifyHotspots lists life-cycle stages contributing more than a quarter of total impact; suggestImprovements proposes stage-specific improvements with estimated reductions, difficulty, and cost impact.
  • Comparative LCA (compareProducts): Side-by-side LCA for two products, reporting carbon/energy/water differences, per-stage comparisons, and a preferred product — answering "which version of this design is more sustainable?"

Circular Design Scoring#

Circular economy principles extend product lifetimes through design for disassembly, repairability, and material recovery — minimising waste and resource consumption.

  • Circularity Scoring (assessCircularity): Produces a CircularDesignScore with five subscore groups — durability, repairability, recyclability, reusability, and material efficiency — plus an overall 0–100 score and a sustainability rating. Recyclability depends on mono-material design, separable components, and marked materials; a traditional dovetailed drawer box scores higher than a glued, stapled one. quickCircularityScore gives a fast estimate.
  • Repairability Index (assessRepairability): Computes a repairability score on the French repairability-index model — documentation, disassembly ease, spare-parts availability, spare-parts price ratio, and product-specific features.
  • Design for Disassembly (designForDisassembly): Produces prioritised DfDRecommendations — replace adhesive joints with accessible mechanical fasteners, minimise fastener variety, mark materials per ISO 11469 — by analysing a product's JointInfo fasteners and material markings.

Certification Support#

  • Certification Record Tracking: createCertificationRecord and trackCertification manage certification records (across the ten supported CertificationType values — FSC, PEFC, Cradle to Cradle, GREENGUARD, LEED, BREEAM, WELL, Living Building Challenge, ENERGY STAR, Blue Angel) with status, issue/expiry dates, and scope. isCertificationValid, daysUntilExpiry, filterCertificationsByStatus, and getCertificationsExpiringSoon support lifecycle management.
  • FSC Chain-of-Custody Validation: validateChainOfCustody checks that a product's certified content meets its FSC claim threshold (FSC 100%, FSC Mix, FSC Recycled, FSC Controlled), reconciling input and output volumes and reporting validation errors. determineMaxFSCClaim computes the strongest claim a given set of inputs supports. (Validation is internal; there is no external FSC database lookup.)
  • LEED Contribution Assessment: assessLEEDContribution models which LEED credits a project's material choices earn, using LEED_LEVELS, LEED_CATEGORY_MAX_POINTS, and LEED_VOC_LIMITS, and returns a LEEDAssessment with a certification level.
  • Material Sustainability & Reporting: assessMaterialSustainability profiles a material's carbon intensity, embodied energy, water use, and recyclability; generateSustainabilityReport composes LCA, circular-design, certification, and supply-chain results into a single report.

Waste-audit data structures (WasteAudit, WasteEntry, WasteStream, WasteStreamSummary, WasteDiversionMethod) are defined as types, but no waste-audit computation function is implemented. Declare-label / Red-List chemical screening is not implemented.

Maker Academy (@seshat/academy)#

@seshat/academy is the learning platform layer of Seshat. It encodes the curriculum of maker education — skill assessment rubrics, course prerequisites, certification programs, and mentor–apprentice matching — as computable data structures and functions. The goal is to give any application the ability to assess where a student is, generate a personalised learning path to where they want to be, and certify when they have arrived.

Skill Assessment#

  • Multi-Dimensional Skill Matrix: Skill is tracked across a large set of named sub-skills (CraftSubSkill) grouped under 16 craft domains (CraftDomain — woodworking, joinery, turning, carving, furniture making, cabinet making, interior design, spatial harmony, finishing, upholstery, digital fabrication, sustainability, restoration, timber framing, marquetry, luthiery). Each sub-skill is independently scored, so a maker can be advanced at joinery but a beginner at finishing. buildSkillProfile aggregates per-domain levels into a StudentSkillProfile.
  • Rubric-Based Assessment: executeAssessment scores a practical skill test against a structured rubric (ASSESSMENT_RUBRICS) — weighted criteria with level descriptors, a passing score, time limit, and required tools/materials — producing per-criterion feedback, a total weighted score, a pass/fail result, and a resulting skill level. scoreToSkillLevel, skillLevelToScore, and meetsSkillRequirement map between numeric scores and qualitative levels.
  • Skill Gap Identification: identifySkillGaps compares a student's current proficiencies against target requirements and reports which skills fall short and by how much.
  • Progress Tracking: Per-domain skill records enable visualising improvement over time.

Learning Path Generation#

  • Personalised Learning Paths: generateLearningPath builds a sequenced curriculum of course nodes from a learner's goal and skill gaps, drawing on COURSE_CATALOG, with per-node estimated hours and dependency ordering.
  • Prerequisite Sequencing: checkPrerequisites, resolvePrerequisiteChain, and getPrerequisiteTree ensure foundational courses precede advanced ones — you cannot learn to cut a dovetail by hand until you can sharpen a chisel to a razor edge.
  • Course Discovery: findCoursesForSkills locates courses that teach a desired set of sub-skills.
  • Time-to-Competency Estimates: estimateProgressionHours gives realistic hour estimates for advancing between skill levels; TechniqueEntry records in the knowledge base carry per-technique practice-hours-to-competency.

Certification System#

  • Certification Programs: CERTIFICATION_PROGRAMS defines programs per craft domain, each with required sub-skill proficiencies, required courses, minimum practice hours, minimum completed projects, portfolio requirements, an exam rubric, a passing exam score, and a validity period.
  • Eligibility Checking: checkCertificationEligibility reports whether a student meets every program requirement, with an overall progress percentage and an estimate of remaining hours to eligibility.
  • Credential Issuance: issueCertification validates the exam score and issues a CertificationRecord with a generated certificate number and an expiry derived from the program's validity period. getRenewalStatus and isCertificationValid track renewal; getCertificationPathForDomain lists the certification ladder for a domain.

Mentorship Matching#

  • Mentor & Apprentice Profiles: MentorProfile captures expert sub-skills, certifications, teaching style, communication preferences, availability time slots, capacity, and ratings; ApprenticeProfile captures a student's skill profile, goals, learning style, and preferences.
  • Multi-Dimensional Matching: scoreMentorMatch produces a compatibility score across eight weighted dimensions — skill alignment, schedule compatibility, communication match, teaching/learning style compatibility, domain relevance, logistical fit, mentor availability, and reputation (DEFAULT_MATCHING_WEIGHTS sets the weights; each dimension has a dedicated scoring function). findBestMentors ranks candidate mentors for an apprentice, and validatePairingViability checks a proposed pairing.

Workshop Management (@seshat/workshop)#

@seshat/workshop models the physical workshop or makerspace as a managed resource. It handles the layout and safety of the physical space, the inventory of tools and materials, the scheduling of shared resources, and the engineering of dust collection and electrical systems. Like the other Seshat libraries that manage state, it uses in-memory stores; durable persistence is the caller's responsibility.

Layout Design#

  • Workshop Floor Plan Optimisation: Model a workshop space and arrange tools for optimal workflow — the "wood preparation to joinery to assembly to finishing" workflow should flow in one direction without backtracking. The library uses graph-based workflow optimisation to suggest layouts that minimise tool-to-tool travel distances for the most common operations.
  • Clearance Validation: MACHINE_CLEARANCES records the infeed/outfeed/left/right clearance each machine category needs; getMachineClearanceEnvelope computes a machine's required envelope and validateClearances reports clearance violations across a layout, graded as warning or violation.
  • Layout Analysis: designWorkshopLayout produces a LayoutAnalysis with an overall score, clearance violations, workflow analysis, space utilisation, natural-light coverage, and a safety score, plus recommendations.

Tool & Material Inventory Management#

  • Tool Catalogue with Maintenance History: An in-memory tool store (addTool, getTool, updateTool, removeTool, getAllTools, getToolsByCondition) tracks shop tools — purchase date, price, condition, ownership status, location, and a maintenance history. recordMaintenance appends MaintenanceRecord entries (blade changes, alignment, bearing replacement, etc.).
  • Maintenance Scheduling: scheduleMaintenance produces a MaintenanceSchedule with a next-due date and priority; checkMaintenanceDue surfaces tools that have reached or passed their maintenance interval.
  • Material Stock Tracking: A material store (trackMaterialStock, getMaterial, getMaterialsByType, deductMaterial, getMaterialUsageHistory) records on-hand quantities and usage; estimateReorderPoint and findLowStockMaterials flag stock that has dropped below its reorder point. calculateBoardFeetFromDimensions converts lumber dimensions to board feet.
  • Inventory Reporting: generateInventoryReport summarises tools by condition, tools needing maintenance, materials by type, total inventory value, low-stock items, and recent maintenance cost.

Safety Systems#

  • Per-Machine Safety Briefings: generateSafetyBriefing produces a MachineSafetyBriefing for a machine category — required PPE, a pre-use checklist, operating hazards (kickback, entanglement, dust inhalation), emergency procedures, prohibited actions, and whether hearing protection is mandatory. MACHINE_REQUIRED_PPE maps each machine category to its mandatory PPE.
  • Safety Compliance Assessment: assessSafetyCompliance scores a workshop layout's safety systems (emergency stops, fire suppression, first-aid and eye-wash stations, aisle widths, evacuation plan) and returns graded checks, critical issues, and warnings.
  • Incident Log and Near-Miss Tracking: An in-memory incident store (reportIncident, getAllIncidents, getIncidentsBySeverity, getIncidentsInRange) records injuries, near-misses, and property damage — classified across 14 incident categories and five severity levels (including near_miss). Near-miss tracking matters because near-misses precede serious injuries (Heinrich's Triangle).
  • Noise Exposure Calculation: calculateNoiseExposure computes an OSHA-style time-weighted average and noise dose from per-machine usage (OSHA_NOISE_LIMITS, maxPermissibleExposureHours), reporting whether hearing protection is required.

Scheduling and Booking#

  • Shared Resource Booking: An in-memory booking system (registerResource, createBooking, getBooking, cancelBooking, completeBooking, markNoShow) reserves machines, zones, workbenches, and classrooms for time slots. createBooking enforces resource availability windows, min/max durations, and a safety-orientation prerequisite.
  • Availability & Conflict Detection: checkAvailability finds open slots; detectConflicts reports overlapping bookings on the same resource with the overlap duration.
  • Utilisation Reporting: calculateUtilization computes a resource's utilisation percentage, booking count, average booking duration, and peak day/hour over a period — informing purchasing and scheduling decisions.

Dust Collection Planning#

Dust is the hidden hazard in woodworking: fine wood dust (especially MDF and finishing dust) contains respirable particles below OSHA permissible exposure limits, and accumulated dust is a fire and explosion risk. The dust collection functions encode the engineering required to size a safe system.

  • CFM Requirements Calculation: Every stationary power tool has a minimum air volume (CFM — cubic feet per minute) requirement for effective dust collection. A 12-inch planer requires approximately 800 CFM; a 10-inch table saw approximately 450 CFM. The library calculates total simultaneous CFM requirement and recommends dust collector capacity.
  • Duct Sizing and Velocity Calculations: Proper duct design maintains 3,500–4,000 FPM (feet per minute) minimum transport velocity — below this velocity, dust settles in horizontal ducts creating fire hazards. The library sizes main trunk ducts and branch ducts to maintain target velocity at the required flow rate.
  • Filtration Stage Design: Three-stage filtration design — cyclone pre-separator (removes more than 98% of heavy chips before the filter, extending filter life dramatically), bag filter (collects fine dust), and HEPA final stage (captures particles down to 0.3 microns — required for MDF and finishing dust which contain respirable particles below OSHA permissible exposure limits).

Electrical Planning#

  • Circuit Load & Requirements: calculateElectricalRequirements analyses a workshop's machine loads, voltages, and circuits — computing total connected load, per-circuit load percentages, and whether any circuit is overloaded (MACHINE_AMPERAGE provides per-machine draw). It helps prevent the common mistake of running too many tools on one circuit.
  • Wire & Breaker Sizing: recommendWireGauge selects an AWG wire gauge for an amperage and run length; calculateVoltageDrop computes the voltage-drop percentage over a run; recommendBreakerType chooses a standard/GFCI/AFCI breaker for a circuit.

Data Persistence (@seshat/database)#

@seshat/database is a schema-and-migration description layer, not a database client. It depends only on zod; it opens no connection and uses no ORM (Drizzle, Knex, or Prisma) at runtime. This library exists to provide a single source of truth for what the Seshat database schema looks like, and to generate the SQL needed to create it, without tying the domain libraries to any particular database driver or ORM.

The deliberate boundary here is that @seshat/database defines its own Zod schemas independently, without importing from @seshat/common. This means changes to the domain type vocabulary (how Seshat thinks about a room) do not automatically change the database schema (how Seshat stores a room), and vice-versa. The two can evolve at different paces, with explicit translation at the application layer.

  • Zod Row Schemas: Type-safe Zod schemas validate every persisted entity — buildings, floors, rooms, wood species, materials, tools, smart devices, sensor readings, automation rules, projects, courses, lessons, student progress, workshops, designs, Feng Shui analyses, Vastu analyses, and sustainability assessments. Each schema yields an inferred *Row type and an *InsertSchema variant (omitting createdAt/updatedAt). Branded UUID-validated ID schemas exist per entity. These schemas are defined independently and do not import @seshat/common, keeping persistence decoupled from the domain type vocabulary.
  • Declarative Migration Definitions: migration001_initial describes 18 tables — columns, types, nullability, defaults, foreign keys, and indexes — as plain objects (TableDefinition / MigrationDefinition). ALL_MIGRATIONS lists migrations in order; getTableDefinition, TABLE_NAMES, and TABLE_COUNT are derived helpers. generateMigrationSQL renders a migration into CREATE TABLE / ALTER TABLE / CREATE INDEX SQL strings — it produces SQL text but does not execute it.
  • Seed Data: Curated reference data for development and testing — ROOM_TYPES (26 room-type info records), WOOD_SPECIES_SEEDS (25 real wood species), and TOOL_SEEDS (20 real woodworking tools).

Sensor-reading and project-description tables exist as schema definitions, but TimescaleDB hypertable compression and pgvector semantic search are not implemented — those are described as future scope in the Phase 36 backlog.

Implementation Status#

Seshat is implemented as 11 TypeScript libraries under libs/seshat/. There is no apps/seshat or services/seshat, no HTTP API gateway, and no domain event bus — SeshatEventType / SeshatEvent are bare type declarations with no publisher or transport. The design library performs rule-based analysis, not AI image generation. The TODOS Phase 36 backlog describes an API gateway, event infrastructure, and an ORM-backed database as planned work that is not present in the workspace.

Cross-Domain: Real-Time Visualization (Phase 144, planned)#

Seshat's room and dwelling designs are a consumer of the Neith real-time visualization renderers (@neith/viz-*): design-library outputs render as walkthroughs, VR previews, and environment-lit presentations. Seshat owns the dwelling/design data model; Neith owns the renderer and presentation surface.