Eve library

Athena — Systems Deep Dive

Guide

Revision 1

On this page

The libs/athena/ area: forty Nx libraries that implement Athena, the maker / workshop-manufacturing domain — parametric CAD, CAM/CNC, materials and craft intelligence (wood, metal, glass, upholstery, lutherie), simulation, IoT/firmware, ERP/production operations, and the gateway/data backbone that ties them together. This page is the entity-catalog view of the area.

What this area is#

Athena is Oshun's digital-fabrication domain: the software a furniture / musical -instrument / smart-object workshop would use to design a product, plan and run its manufacture, manage the business around it, and care for it after it ships. Rather than one monolith, it is decomposed into forty separate Nx libraries under libs/athena/, every one tagged scope:athena, each owning a coherent slice of that lifecycle (e.g. @athena/cad owns parametric modeling, @athena/cnc owns subtractive toolpath intelligence, @athena/erp owns business operations).

The libraries are overwhelmingly pure-TypeScript domain-logic packages, and the implementations are real, not scaffolds: each feature library carries a handful of implementation modules (e.g. acoustics/src/dsp-crossover.ts, luthiery/src/string-instrument-calculators.ts) holding dozens of exported functions with genuine engineering algorithms — Linkwitz-Riley/Butterworth crossover component synthesis, equal-temperament fret-position and string-tension calculation, linear-static FEA stress/von-Mises models, computer-vision defect taxonomies, and so on. Every src/index.ts follows the same convention: a self-describing doc comment, a typed capability registry (ATHENA_<NAME>_CAPABILITIES plus listAthena<Name>Capabilities / hasAthena<Name>Capability accessors), and export * re-exports of the implementation modules. One library, @athena/cad-topology-rust, is a Rust crate (athena-cad-topology) instead — a CAD geometry kernel plus SIMP topology optimization, compiled as rlib/cdylib.

How the area is shaped#

Five libraries form the backbone the rest compose against:

  • @athena/core — shared types, Zod schemas, engineering calculators, and the adhesive/material compatibility matrix;
  • @athena/api — the in-process REST + WebSocket gateway surface (route table, OpenAPI 3.1 spec, in-memory store, auth, rate-limit keys, health, metrics, circuit-breaker);
  • @athena/db — the Drizzle ORM Postgres / Timescale / pgvector schema, migrations, seed data, and connection config;
  • @athena/infrastructure — environment-key, MQTT-topic, Kafka-topic, MinIO -bucket, edge-node, Grafana, and Prometheus declarations;
  • @athena/integration — cross-domain adapters bridging Athena to other Oshun domains (Freya, Brigid, Seshat, Demeter, Maat, Asase, Aglaea, Cybele, Euterpe).

Around that backbone sit the design + manufacturing engines (cad, cam, cnc, additive, simulation, electronics, firmware, iot, robotics, materials, ai), the craft domains (woodcraft, metalcraft, glasscraft, upholstery, luthiery, finishing, acoustics), the living-product libraries (living, biome), and the operations / go-to-market layer (erp, production, quality, supply, workshop, marketplace, studio, apps, packaging, aftercare, compliance, sustainability, restoration, academy).

What these libraries are not#

These are deterministic, in-process domain-logic libraries. They model the protocols and control logic of physical systems as types and functions; they do not, on their own, drive real machines, cameras, or MQTT brokers — @athena/iot, @athena/firmware, and @athena/cnc describe device/protocol/toolpath structures rather than talking to hardware, and @athena/api's store is in-memory (createInMemoryAthenaApiStore). The honest reading is "a complete, testable software model of a maker workshop," with the live-infrastructure declarations centralized in @athena/infrastructure/@athena/db for whatever service layer wires them up.

How it fits the wider system#

Athena's own @athena/api library is the canonical gateway contract for the domain — its ATHENA_ROUTE_DEFINITIONS table and ATHENA_API_OPENAPI_SPEC describe every REST endpoint, and createAthenaRestApi provides a runnable reference over the in-memory store. Feature libraries depend on @athena/core for shared engineering primitives and on @athena/db for persistence shapes. Other Oshun domains reach Athena through @athena/integration, which holds one adapter module per counterpart domain (so a textiles hand-off to Freya or a BIM coordination with Cybele is an explicit, typed bridge rather than an ad-hoc import). Walk the "used by" edges on any node below to see exactly who depends on it.

Entity reference#

@athena/core#

The shared foundation (libs/athena/core/src): the barrel re-exports types.js, schemas.js, material-compatibility.js, and calculators.js. It owns the cross-cutting primitives the whole domain reuses — MoneySchema, Dimension3DSchema, ToleranceSchema (Zod, in schemas.ts), unit converters and engineering calculators (convertLength, calculateStressMpa, estimateEquilibriumMoistureContent, in calculators.ts), and the MATERIAL_COMPATIBILITY_MATRIX of adhesive/material-family bonding rules. Tagged type:core; it is the bottom of the Athena dependency graph.

@athena/api#

The domain's gateway surface (libs/athena/api/src/index.ts, ~1,245 lines, tagged type:api). It defines the REST route table (ATHENA_ROUTE_DEFINITIONS), an OpenAPI 3.1 spec object (ATHENA_API_OPENAPI_SPEC), Zod request schemas for CAD/production/inventory/procurement/IoT, role-based authorization (authorizeAthenaRole), rate-limit key derivation, health summarization, an in-memory store (createInMemoryAthenaApiStore) and a runnable REST facade (createAthenaRestApi), plus a WebSocket server, Prometheus metric names, structured logging, and a circuit-breaker helper. It is a complete in-process reference implementation of the Athena API, not just type declarations.

@athena/db#

The persistence layer (libs/athena/db/src, tagged type:data). schema.ts declares the Drizzle ORM Postgres schema — pgEnum/pgTable definitions with jsonb, numeric, vector (pgvector) and timestamp columns and indexes for products, work orders, machines, and more — and the barrel also exports migrations.js, seed.js, and connection.js. connection.ts resolves pooled and direct database URLs (with a pgbouncer-style :6432 default) and pool/ timeout settings from the environment via getAthenaDatabaseConnectionConfig.

@athena/infrastructure#

The runtime-topology declarations (libs/athena/infrastructure/src/index.ts, tagged type:infra). It enumerates the domain's ATHENA_ENVIRONMENT_KEYS, MQTT topic patterns (ATHENA_MQTT_TOPICS — machine/furniture/living telemetry, device commands, OTA status), Kafka topic definitions with partition/retention, ATHENA_MINIO_BUCKETS, edge-node service maps, Grafana dashboard specs, and a Prometheus scrape config, plus helpers like getMissingAthenaEnvironmentKeys and getAthenaBucketPolicy. It is the single source of truth for "what external services Athena expects and how they are configured."

@athena/integration#

The cross-domain hub (libs/athena/integration/src, tagged type:integration, ~69 exported functions). It carries one adapter module per counterpart Oshun domain — freya-integration.ts, brigid-integration.ts, seshat-integration.ts, demeter-integration.ts, maat-integration.ts, asase-integration.ts, aglaea-cybele-integration.ts, euterpe-integration.ts, and an additional-domain-integration.ts catch-all — each declaring typed "bridge" surfaces (e.g. Freya's freya-metalcraft-bridge / freya-leatherwork-bridge). The capability registry in index.ts names every bridge, and the integration contracts are exercised by integration-contracts.test.ts.

@athena/cad-topology-rust#

The one Rust crate in the area (libs/athena/cad-topology-rust, package athena-cad-topology, tagged lang:rust, crate-type = ["rlib", "cdylib"]). src/kernel.rs is a 2D/3D CAD geometry kernel (Point2/Point3 with distance, lerp, and an EPSILON tolerance constant); src/lib.rs adds a SIMP (Solid Isotropic Material with Penalization) topology-optimization solver — SimpInput/SimpResult over a voxel grid with fixed supports, loads, target volume fraction, penalization, and a per-iteration compliance/volume history. A standalone real Rust crate (geometry kernel + SIMP topology optimizer) referenced by name as a contract in @athena/cad (rustKernelContract), but not yet wired into the TS CAD execution path via WASM/native bindings.

@athena/cad#

The parametric 3D CAD engine (libs/athena/cad/src, ~85 exported functions). Its modules cover geometry.ts, modeling.ts, parametric.ts, assembly.ts, drawing.ts, history.ts, generative.ts, and formats.ts — i.e. the data structures and operations for building, parameterizing, assembling, and exporting designs (STEP/IGES/STL/OBJ/3MF and the native athena-parametric format named in @athena/api's schemas). Self-described as "parametric 3D CAD engine and design data structures."

@athena/cam#

Computer-aided manufacturing (libs/athena/cam/src, ~51 exported functions): toolpaths.ts, tool-management.ts, postprocessing.ts, and simulation.ts. It takes CAD geometry to machine instructions — toolpath generation, tool libraries, post-processing to machine dialects, and cut simulation — described as "computer-aided manufacturing and toolpath generation."

@athena/cnc#

Subtractive-manufacturing intelligence (libs/athena/cnc/src, ~50 exported functions), organized by process: cnc-milling.ts, cnc-turning.ts, cnc-routing.ts, cnc-laser.ts, cnc-waterjet-plasma.ts, and cnc-controller.ts. It models the parameters and control logic of each machine class ("CNC and subtractive manufacturing intelligence"); it computes/structures programs rather than driving a physical controller.

@athena/additive#

Additive manufacturing and slicing (libs/athena/additive/src, ~31 exported functions): fdm-printing.ts, resin-printing.ts, powder-metal-printing.ts, and slicer-support.ts. It covers the three main AM process families plus support-generation/slicer intelligence — "additive manufacturing and slicer intelligence."

@athena/simulation#

The analysis suite (libs/athena/simulation/src, ~51 exported functions): structural-fea.ts, acoustic-simulation.ts, thermal-fluid-simulation.ts, ergonomic-simulation.ts, manufacturing-process-simulation.ts, and workshop-digital-twin.ts. structural-fea.ts defines mesh-plan, linear-static stress (axial/bending/von-Mises/principal), orthotropic wood material, buckling, fatigue, and standard-test surfaces — real FEA modeling, not a stub. Described as "FEA, acoustic, thermal, ergonomic, process, and digital twin simulation."

@athena/electronics#

PCB / electronics design (libs/athena/electronics/src, ~40 exported functions): schematic-capture.ts, pcb-layout.ts, component-library.ts, design-rule-verification.ts, and manufacturing-output.ts. It spans the EDA flow from schematic through DRC to fabrication output — "PCB design, schematic capture, component libraries, and verification."

@athena/firmware#

The embedded-firmware platform (libs/athena/firmware/src, ~59 exported functions): rtos-foundation.ts, peripheral-drivers.ts, communication-stacks.ts, dsp-audio-firmware.ts, ota-update-system.ts, and testing-debugging.ts. It models RTOS scheduling, drivers, comms stacks, DSP/ audio firmware, and OTA for "embedded workshop devices" — as software structures and logic, not a compiled target image.

@athena/iot#

Smart-furniture IoT (libs/athena/iot/src, ~59 exported functions): hardware-abstraction-layer.ts, sensor-integration.ts, actuator-control.ts, connectivity-protocols.ts, power-management.ts, and smart-home-integration.ts. It models device management, telemetry, and control for connected furniture; the actual broker/topic wiring lives in @athena/infrastructure. Described as "smart furniture IoT device management, telemetry, and control."

@athena/robotics#

Workshop robotics (libs/athena/robotics/src, ~41 exported functions): robot-arm-programming.ts, collaborative-robotics.ts, vision-guided-robotics.ts, automated-material-handling.ts, and robotic-finishing-assembly.ts. It covers arm programming, cobot cells, vision-guided picking, material handling, and robotic finishing/assembly — "workshop robotics, cobots, cell planning, and automation."

@athena/materials#

Material-science intelligence (libs/athena/materials/src, ~65 exported functions, ~5,957 LOC): wood-science.ts, metal-science.ts, glass-science.ts, composite-bio-materials.ts, adhesive-fastener-science.ts, and a material-selection-engine.ts. It is the materials knowledge base and selection engine behind the craft domains — "material science intelligence for workshop fabrication."

@athena/ai#

The ML/AI layer (libs/athena/ai/src, ~37 exported functions): computer-vision-quality.ts, generative-design-ai.ts, demand-forecasting-ai.ts, design-brief-nlp.ts, material-recognition-ai.ts, predictive-maintenance-ai.ts, and acoustic-ai.ts. The modules define rich domain taxonomies (e.g. surface/wood/weld/glass defect classes and bounding-box detection types in computer-vision-quality.ts) and the logic around them; they are model-agnostic intelligence surfaces rather than bundled trained weights. Described as "AI and machine learning for vision QA, generative design, forecasting, and NLP."

@athena/woodcraft#

Woodworking intelligence (libs/athena/woodcraft/src, ~63 exported functions, ~5,143 LOC): joinery-intelligence.ts, lumber-processing.ts, wood-turning.ts, wood-carving-sculpting.ts, steam-laminate-bending.ts, and veneering-marquetry.ts. It is the deepest craft library by far — joinery planning, lumber processing, turning/carving, steam-bending, and veneer/marquetry — "woodworking intelligence and joinery planning."

@athena/metalcraft#

Metalworking intelligence (libs/athena/metalcraft/src, ~51 exported functions): forging-casting.ts, welding-intelligence.ts, sheet-metal-fabrication.ts, machining-intelligence.ts, and surface-treatment.ts. It spans forging/casting, welding, sheet-metal, machining, and surface treatment — "metalworking, machining, welding, forging, and finishing intelligence."

@athena/glasscraft#

Glasswork intelligence (libs/athena/glasscraft/src, ~36 exported functions): glass-blowing-hot-working.ts, kiln-forming-fusing.ts, lampworking-scientific-glass.ts, and stained-architectural-glass.ts — the four major glass process families. Described as "glasswork, kiln, lampworking, and architectural glass intelligence."

@athena/upholstery#

Upholstery and soft-goods intelligence (libs/athena/upholstery/src, ~? functions across cushion-foam-engineering.ts, fabric-leather-intelligence.ts, pattern-making-cutting.ts, and sewing-assembly.ts). It covers foam/cushion engineering, fabric/leather selection, pattern cutting, and sewing/assembly — "upholstery, textiles, foam, pattern cutting, and sewing intelligence."

@athena/luthiery#

Musical-instrument making (libs/athena/luthiery/src, ~81 exported functions, ~8,394 LOC — the largest feature library). Modules cover string-instrument-design.ts + string-instrument-calculators.ts (fret-position plans by temperament, string-tension from gauge/scale/pitch, truss-rod logic), wind-instrument-design.ts/-calculators.ts, keyboard-instrument-design.ts, percussion-instrument-design.ts, electronic-instrument-components.ts, tonewood-acoustic-analysis.ts, instrument-setup-adjustment.ts, and instrument-restoration.ts. Genuine acoustic-engineering math — "musical instrument making, setup, acoustics, and restoration intelligence."

@athena/finishing#

Surface finishing (libs/athena/finishing/src, ~35 exported functions): wood-finishing.ts, metal-finishing.ts, glass-finishing.ts, spray-booth.ts, and color-science.ts. It covers per-material finishing processes, spray-booth operation, and color science — "surface finishing, coating, spray booth, and color science intelligence."

@athena/acoustics#

Acoustic engineering (libs/athena/acoustics/src, ~46 exported functions): speaker-design.ts, enclosure-design.ts, dsp-crossover.ts, room-acoustics.ts, and instrument-acoustics.ts. dsp-crossover.ts synthesizes passive (Linkwitz-Riley/Butterworth/Bessel) and active (IIR-biquad/FIR) crossover networks with component values, L-pads, Zobel networks, baffle-step compensation, and time alignment — real DSP/loudspeaker math. Described as "speaker, room, and instrument acoustic engineering."

@athena/living#

Living-furniture systems (libs/athena/living/src, ~52 exported functions, ~6,639 LOC): hydroponic-furniture-systems.ts, aquarium-furniture-systems.ts, terrarium-bioactive-systems.ts, aquaponic-integration.ts, automated-life-support-systems.ts, and a plant-aquatic-species-database.ts. It models furniture that hosts living organisms — hydroponics, aquariums, terrariums, aquaponics, and their life-support — "living furniture systems for hydroponics, aquariums, terrariums, and aquaponics."

@athena/biome#

Factory-biome intelligence (libs/athena/biome/src, ~55 exported functions): biophilic-factory-design.ts, phytoremediation-air-bioremediation.ts, acoustic-bioremediation.ts, factory-ecosystem-management.ts, biome-iot-environmental-monitoring.ts, plus worker-wellbeing-integration.ts and safety-hazard-integration.ts that tie into the workshop/safety libraries. It is the "living workshop" counterpart to @athena/living — "factory biome and living workshop intelligence."

@athena/erp#

Business-operations / ERP (libs/athena/erp/src, ~44 exported functions, ~4,691 LOC): order-management.ts, crm-client-management.ts, costing-pricing-engine.ts, financial-integration.ts, hr-workforce.ts, and project-management.ts. It is the back-office engine — orders, CRM, costing/ pricing, finance, HR, and projects — "business operations, CRM, orders, costing, HR, and workforce intelligence."

@athena/production#

Manufacturing execution (libs/athena/production/src, ~54 exported functions): work-order-management.ts, production-scheduling.ts, capacity-planning.ts, bom-management.ts, lean-manufacturing.ts, and quality-control.ts. It is the MES layer — work orders, routing/scheduling, capacity, BOMs, lean, and shop-floor quality control — "MES, work orders, routing, scheduling, lean, and capacity management."

@athena/quality#

Quality assurance (libs/athena/quality/src, ~32 exported functions): dimensional-inspection.ts, material-testing.ts, durability-environmental-testing.ts, acoustic-quality-testing.ts, and metrology-calibration.ts. It covers dimensional/SPC inspection, material and durability testing, acoustic QA, and metrology/calibration — "quality assurance, inspection, testing, SPC, and metrology."

@athena/supply#

Supply-chain management (libs/athena/supply/src, ~38 exported functions): procurement-purchasing.ts, supplier-management.ts, inventory-management.ts, logistics-shipping.ts, and material-traceability.ts. It spans procurement, suppliers, inventory, logistics, and lot/material traceability — "supply chain, procurement, inventory, logistics, and traceability."

@athena/workshop#

Workshop operations (libs/athena/workshop/src, ~45 exported functions): space-planning-layout.ts, tool-inventory-tracking.ts, safety-systems.ts, environmental-controls.ts, and energy-management.ts. It is the facility layer — layout, tool inventory, safety, HVAC/environment, and energy — "workshop operations, space management, tools, safety, and energy."

@athena/marketplace#

E-commerce / sales (libs/athena/marketplace/src, ~32 exported functions): product-catalog.ts, multi-channel-sales.ts, pricing-engine.ts, custom-order-pipeline.ts, and product-3d-viewer.ts. It covers catalog, multi-channel sales, pricing, custom-order intake, and 3D product viewing — "e-commerce, catalog, sales, pricing, and custom order workflows."

@athena/studio#

Design-studio collaboration (libs/athena/studio/src, ~38 exported functions): client-collaboration-portal.ts, photorealistic-rendering.ts, product-configurator.ts, portfolio-management.ts, and ar-vr-experience.ts. It models the client-facing creative front — collaboration portal, rendering, configurator, portfolio, and AR/VR — "design studio collaboration, rendering, configurator, and client portal models."

@athena/apps#

Application-suite models (libs/athena/apps/src, ~42 exported functions): one module per app — workshop-management-app.ts, quality-inspection-app.ts, inventory-scanner-app.ts, ar-assembly-guide-app.ts, smart-furniture-control-app.ts, living-furniture-monitor-app.ts, and customer-portal-app.ts. Each defines the app's screen surfaces, view-model types, and supporting logic (e.g. workshop-management-app.ts models dashboard/ work-order/maintenance/safety surfaces and machine/work-order state). Described as "application suite contracts for mobile and web Athena experiences."

@athena/packaging#

Packaging engineering (libs/athena/packaging/src, ~23 exported functions): flat-pack-design.ts, custom-crating-protection.ts, assembly-instruction-generation.ts, ar-assembly-guidance.ts. It covers flat-pack design, protective crating, generated assembly instructions, and AR assembly guidance — "packaging engineering, flat-pack, crating, and assembly instructions."

@athena/aftercare#

After-sales service (libs/athena/aftercare/src, ~28 exported functions): warranty-management.ts, repair-maintenance.ts, spare-parts-management.ts, iot-monitoring-ota.ts, and living-furniture-care.ts. It is the post-purchase lifecycle — warranty, repair, spares, IoT/OTA monitoring, and care of living furniture — "after-sales service, warranty, repair, spare parts, and living-system care."

@athena/compliance#

Regulatory compliance (libs/athena/compliance/src, ~31 exported functions): furniture-safety-standards.ts, electrical-safety.ts, environmental-regulations.ts, workshop-safety-regulations.ts, and musical-instrument-standards.ts. It encodes the standards each product/process must satisfy — "furniture, electrical, environmental, workshop, and instrument compliance."

@athena/sustainability#

Sustainability engineering (libs/athena/sustainability/src, ~30 exported functions): lifecycle-assessment.ts, carbon-footprint-tracking.ts, circular-economy.ts, certification-management.ts, and waste-management.ts. It covers LCA, carbon tracking, circularity, eco-certifications, and waste — "sustainability, lifecycle assessment, circularity, certifications, and waste."

@athena/restoration#

Restoration / conservation (libs/athena/restoration/src, ~24 exported functions): antique-furniture-restoration.ts, instrument-restoration.ts, historical-period-analysis.ts, and scanning-reverse-engineering.ts. It is the conservation domain — antique furniture and instrument restoration, period analysis, and scan-based reverse engineering — "restoration and conservation intelligence for furniture and instruments."

@athena/academy#

Knowledge / training (libs/athena/academy/src, ~35 exported functions): safety-training.ts, apprenticeship-programs.ts, machine-operation-training.ts, technique-database.ts, and video-interactive-tutorials.ts. It is the workforce-development layer — safety training, apprenticeships, machine-operation curricula, a technique database, and interactive tutorials — "knowledge management, safety training, apprenticeship, and tutorials."

@athena/gis#

GIS analysis toolkit for the Athena CAD/EDA/CAM/GIS kernel (libs/athena/gis/src): CRS handling and transformCoordinate (projection), a GisRTree spatial index, vector/raster analysis, shortestNetworkPath/calculateNetworkServiceArea network analysis, and interpolateIdw/interpolateOrdinaryKriging/interpolateThinPlateSpline surface interpolation — all in-process TypeScript, no external GIS engine.