The
libs/freya/area: 26 Nx libraries implementing the Freya luxury-goods & fashion intelligence domain — an Africa/Ghana-centred luxury conglomerate model spanning 19 business units, built on a shared@freya/coretype hub and a@freya/dbpersistence layer.
What this area is#
Freya models a vertically-integrated luxury-goods group: fashion, textiles,
jewelry, beauty, perfumes, watches, footwear, eyewear, leather goods, retail,
e-commerce, manufacturing, a design academy, and the supporting financial and
market-intelligence functions. Every library is tagged scope:freya; the source
comments and module banners are numbered against a 57.x task tree (e.g.
57.3.x for fashion, 57.16.x for the SOTA tech layer), so the area reads as
one coherent domain build rather than a grab-bag of packages.
The area has a clear shape. @freya/core is the hub every other library
imports: it owns the foundational types (product-types.ts,
material-types.ts, supply-chain-types.ts, brand-customer-types.ts,
beauty-types.ts), the FREYA_BUSINESS_UNIT_CATALOG of 19 business-unit
profiles (business-units.ts), and shared utilities (utilities.ts) such as
generateSKU, ΔE colour distance, and the EXCHANGE_RATES_TO_GHS table that
the financials, jewelry, and e-commerce libraries all build pricing on.
@freya/db is the persistence layer: a Drizzle schema of 24 pgTable
definitions (with a pgvector embedding column), plus Redis caching strategy, a
PgBouncer-aware connection pool, MinIO/S3 bucket config, OpenTelemetry
observability, seed reference data, and a generated SQL migration.
The remaining libraries split into two honest tiers. Rich engine libraries
(fashion, beauty, textiles, jewelry, manufacturing, ecommerce,
retail, brand, academy, financials, market-intel, sota,
connectors) each carry several thousand lines of domain-specific code across
multiple modules — colour-fastness ΔE dye recipes, size-grading rules, gold
karat/purity and Fairmined premiums, OEE/Muda manufacturing math, trend-decay
scoring, COGS and unit-economics models, and so on — backed by substantial spec
suites. Thin business-unit façade libraries (watches, perfumes,
bridal-events, hair-care, home-decor, footwear, eyewear,
luggage-leather, personal-care, cleaning-products, textile-finishing)
are ~18–20 lines each: a single src/index.ts that wraps
getFreyaBusinessUnitProfile(code) from @freya/core to expose that unit's
profile, capability checks, and key-metric list. These are real, tested
delegating code — not empty scaffolds — but they hold no domain engine of their
own; where a category needs deep modelling it lives in a rich library (e.g.
hair-care, personal-care, fragrance, and detergent formulation logic all live in
@freya/beauty, and finishing logic in @freya/textiles).
How it fits the wider system#
These are in-process domain libraries — Map/object-backed engines and typed
models — consumed by Freya services and apps, and by other Oshun domains through
the dedicated bridge library. The runtime wire contracts for Freya are not
here: they live in @freya/contracts under libs/contracts/freya (covered on
the Contracts systems page), keeping Freya's Zod boundary types separate from
its business logic. @freya/connectors is the explicit cross-domain seam,
carrying typed adapters to Asase (agriculture/shea), Brigid (manufacturing
automation), Cybele (retail construction), Saraswati (logistics), and Maat
(strategic-intelligence dashboards). @freya/sota is the cross-cutting
technology layer (AI design, virtual try-on, analytics, computer-vision QC, NLP,
blockchain authentication) that the product libraries can opt into. The
dependency arrow is consistent: everything points down at @freya/core (and,
for persistence, @freya/db), and the leaf business-unit façades point only at
@freya/core.
Entity catalog (26)#
The 26 tracked Nx projects in freya, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 26 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
unclassified (26)#
Fashion-design academy management (libs/freya/academy/src): curriculum.ts
(course definitions across certificate/diploma/degree levels with
Bloom's-taxonomy levels and specialisation tracks including African and
sustainable fashion), student-management.ts, and academy-operations.ts, plus
a curriculum-internals.ts helper module. Real education-domain logic with a
large spec suite.
The beauty & personal-care formulation library (libs/freya/beauty/src, the
largest in the area at ~5K source LOC). Six modules cover skincare
(skincare-formulation.ts, with a SkincareFormulator enforcing a validated
formulation-lifecycle state machine), cosmetics, hair-care, fragrance, stability
& regulatory dossiers, and personal-care/detergent development. Note that the
substantive hair-care, personal-care, perfume, and cleaning-product science
lives here, even though thin business-unit façade libraries of those names also
exist.
Brand-management intelligence (libs/freya/brand/src, tasks 57.6.1–57.6.3):
brand-architecture.ts, digital-presence.ts, and heritage-storytelling.ts
(African artisan profiles with craft lineage, GPS, production capacity, and
income/livelihood fields feeding ArtisanStory content). Real, domain-specific
modelling with a substantial spec suite.
A thin business-unit façade (libs/freya/bridal-events/src/index.ts, ~20 LOC)
wrapping getFreyaBusinessUnitProfile('bridal-events') with the standard
accessors. Real but minimal; its capabilities and metrics come from the core
catalog rather than a dedicated engine.
bridalEventsBusinessUnitCode5bridalEventsBusinessUnitProfile6getBridalEventsBusinessUnitProfile10hasBridalEventsOperatingCapability14listBridalEventsKeyMetrics18A thin business-unit façade (libs/freya/cleaning-products/src/index.ts, ~20
LOC) over getFreyaBusinessUnitProfile('cleaning-products'). The
detergent/cleaning formulation logic itself is implemented in @freya/beauty's
personal-care-detergent.ts; this library only surfaces the business-unit
profile.
cleaningProductsBusinessUnitCode5cleaningProductsBusinessUnitProfile6getCleaningProductsBusinessUnitProfile10hasCleaningProductsOperatingCapability14listCleaningProductsKeyMetrics18The cross-domain bridge library (libs/freya/connectors/src, tasks
57.14.1–57.14.5): typed adapters to Asase (agriculture/shea grades), Brigid
(manufacturing automation ROI), Cybele (FlagshipStoreDesign retail
construction — traffic, dwell-time, zoning, and construction-cost estimation),
Saraswati (logistics service levels), and Maat (maat-connectors.ts
dashboard/BU-data sync). This is where Freya's outward integrations to the rest
of the Oshun domain graph live.
The foundational hub (libs/freya/core/src) that every other Freya library
imports. It defines the branded product/material/supply-chain/brand-customer/
beauty type system, the FREYA_BUSINESS_UNIT_CATALOG of 19
FreyaBusinessUnitProfile records with the getFreyaBusinessUnitProfile(code)
accessor (business-units.ts), and shared utilities (utilities.ts) including
generateSKU (the BU-CAT-YY-SSSS scheme), colour ΔE helpers, and the
EXCHANGE_RATES_TO_GHS currency table downstream pricing depends on. Tagged
type:core; the index re-exports each types module and aliases computeDeltaE
→ computeMaterialDeltaE to avoid a collision with utilities.
validateFiberComposition6computeBlendDescription6classifyTextileWeight6computeMaterialDeltaE6getAfricanPrintsByType6validateHexColor6The persistence layer (libs/freya/db/src), tagged type:database. schema.ts
is a Drizzle schema of 24 pgTables — products, variants, collections,
materials, suppliers, artisans, manufacturing orders, customers, retail
locations, orders/carts/wishlists, virtual-try-on sessions, brands and
campaigns, quality inspections, academy students/courses/enrollments,
formulations, trend signals, financial records, inventory valuations — using
pgEnum status/business-unit enums and a vector embedding column. Alongside
it sit redis-config.ts (TTL/key-namespace caching strategy), connection.ts
(PgBouncer transaction-mode pooling), s3-config.ts (MinIO buckets for design
assets, product imagery, manufacturing docs), observability.ts
(OpenTelemetry + circuit breakers), seed.ts (fabric/INCI/gemstone/Pantone
reference data), and a generated migration under db/drizzle/. Its targets
include db:generate, db:migrate, and db:push via drizzle-kit.
E-commerce & diaspora DTC (libs/freya/ecommerce/src, tasks 57.7.1–57.7.3):
catalog-inventory.ts, diaspora-commerce.ts (per-country market configs for
the USA/UK/Canada/EU/Caribbean diaspora, multi-currency via
EXCHANGE_RATES_TO_GHS, carrier and language options), and
social-personalization.ts. It imports FreyaValidationError and
currency/category types from @freya/core.
A thin business-unit façade (libs/freya/eyewear/src/index.ts, ~18 LOC)
wrapping getFreyaBusinessUnitProfile('eyewear') with
getEyewearBusinessUnitProfile, hasEyewearOperatingCapability, and
listEyewearKeyMetrics. Real but minimal.
eyewearBusinessUnitCode5eyewearBusinessUnitProfile6getEyewearBusinessUnitProfile8hasEyewearOperatingCapability12listEyewearKeyMetrics16The fashion design & production engine (libs/freya/fashion/src, tasks
57.3.1–57.3.6). Six modules: design-pipeline.ts, collection-planner.ts,
size-grading.ts (US/EU/UK/African size systems with body-measurement grading
rules including a traditional_kente garment type), trend-forecasting.ts,
production-scheduler.ts, and african-print-library.ts (Ankara and Kente
pattern models with cultural-provenance, symbolism, and sacred-use restriction
fields). A genuine multi-thousand-line engine with a large spec suite; the index
re-exports KentePattern explicitly to disambiguate a duplicate re-export.
Financial models for all 19 business units (libs/freya/financials/src):
startup-investment.ts (per-BU startup capex, phased planning, WACC, ROI),
unit-economics.ts (per-unit COGS and pricing models for garments, cosmetics,
jewelry, retail, e-commerce, academy, etc., in GHS), and financial-planning.ts
(P&L, consolidation, margin/inventory/working-capital, transfer pricing,
breakeven, cash flow). Real finance math anchored on EXCHANGE_RATES_TO_GHS.
A thin business-unit façade (libs/freya/footwear/src/index.ts, ~18 LOC) over
getFreyaBusinessUnitProfile('footwear'), exposing
profile/capability/key-metric accessors. Footwear appears in the core
SKU/category system and unit-economics models, but this library carries no
engine itself.
footwearBusinessUnitCode5footwearBusinessUnitProfile6getFootwearBusinessUnitProfile8hasFootwearOperatingCapability12listFootwearKeyMetrics16A thin business-unit façade (libs/freya/hair-care/src/index.ts, ~18 LOC) over
getFreyaBusinessUnitProfile('hair-care'). The real hair-care formulation
engine is @freya/beauty's haircare-development.ts; this node only exposes
the profile, capability checks, and key metrics.
hairCareBusinessUnitCode5hairCareBusinessUnitProfile6getHairCareBusinessUnitProfile8hasHairCareOperatingCapability12listHairCareKeyMetrics16A thin business-unit façade (libs/freya/home-decor/src/index.ts, ~18 LOC)
wrapping getFreyaBusinessUnitProfile('home-decor') with the standard
accessors. Real delegating code with a spec; no domain engine of its own.
homeDecorBusinessUnitCode5homeDecorBusinessUnitProfile6getHomeDecorBusinessUnitProfile8hasHomeDecorOperatingCapability12listHomeDecorKeyMetrics16Jewelry & accessories intelligence (libs/freya/jewelry/src).
gold-management.ts models Ghana gold sourcing with real constants —
KARAT_PURITY, HALLMARK_STAMPS, troy-ounce conversion, Fairmined/Fairtrade
premiums, and named mines — and reads EXCHANGE_RATES_TO_GHS from
@freya/core. Paired with jewelry-production.ts and craft-preservation.ts.
Domain-specific and tested, not generic CRUD.
A thin business-unit façade (libs/freya/luggage-leather/src/index.ts, ~20 LOC)
over getFreyaBusinessUnitProfile('luggage-leather'). Leather material types
are defined in @freya/core's material-types.ts; this node only surfaces the
business-unit profile via the standard accessors.
luggageLeatherBusinessUnitCode5luggageLeatherBusinessUnitProfile6getLuggageLeatherBusinessUnitProfile10hasLuggageLeatherOperatingCapability14listLuggageLeatherKeyMetrics18Manufacturing operations (libs/freya/manufacturing/src, tasks 57.8.1–57.8.4):
textile-manufacturing.ts, cosmetics-manufacturing.ts,
assembly-manufacturing.ts, and cross-manufacturing.ts — the last modelling
OEE loss categories, the eight Muda waste types, maintenance regimes, ISO
compliance standards, and waste/energy streams. Real lean/operations-engineering
content with a large spec suite.
Fashion & beauty market intelligence (libs/freya/market-intel/src):
trend-monitoring.ts (typed trend signals — runway, street-style, celebrity,
hashtag, search-spike, retailer-buyout — scored with a half-life decay model and
a lifecycle stage machine), competitive-intelligence.ts, and
market-research.ts. Real scoring algorithms, not placeholder counters.
A thin business-unit façade (libs/freya/perfumes/src/index.ts, ~18 LOC) over
getFreyaBusinessUnitProfile('perfumes'), exposing the standard
profile/capability/key-metric accessors. The substantive fragrance science
(accord design, IFRA, maceration) lives in @freya/beauty's
fragrance-development.ts, not here.
perfumesBusinessUnitCode5perfumesBusinessUnitProfile6getPerfumesBusinessUnitProfile8hasPerfumesOperatingCapability12listPerfumesKeyMetrics16A thin business-unit façade (libs/freya/personal-care/src/index.ts, ~20 LOC)
over getFreyaBusinessUnitProfile('personal-care'). The substantive
personal-care formulation logic lives in @freya/beauty's
personal-care-detergent.ts; this library is the profile-accessor surface only.
personalCareBusinessUnitCode5personalCareBusinessUnitProfile6getPersonalCareBusinessUnitProfile10hasPersonalCareOperatingCapability14listPersonalCareKeyMetrics18Retail-chain management (libs/freya/retail/src): store-operations.ts (a
typed FLAGSHIP_STORES registry of named Accra/Kumasi/Lagos locations with
square-footage and hours), portfolio-management.ts, and
customer-experience.ts. Uses FreyaProductId/FreyaCustomerId branded IDs
from @freya/core.
The cross-cutting state-of-the-art technology layer (libs/freya/sota/src,
tasks 57.16.1–57.16.6): ai-design.ts, virtual-tryon.ts (body-scan + AR),
ai-analytics.ts (trend prediction), computer-vision.ts (fabric-defect
grading with defects-per-100m and premium/standard/second/reject grades),
nlp.ts, and blockchain-auth.ts (authentication tokens, serial verification,
and digital product passports). These are deterministic, typed models of the
respective techniques — the in-process domain logic, not live ML/chain
integrations.
A thin business-unit façade (libs/freya/textile-finishing/src/index.ts, ~20
LOC) wrapping getFreyaBusinessUnitProfile('textile-finishing') with the
standard accessors. The actual finishing-process engine is @freya/textiles'
finishing-operations.ts; this node only exposes the business-unit profile.
textileFinishingBusinessUnitCode5textileFinishingBusinessUnitProfile6getTextileFinishingBusinessUnitProfile10hasTextileFinishingOperatingCapability14listTextileFinishingKeyMetrics18Textile operations intelligence (libs/freya/textiles/src, tasks
57.4.1–57.4.4): dye-management.ts (dye-class/fabric chemistry, recipe
temperature/pH/liquor ratios, and a target ΔE colour-fastness model with
LabColor math), print-operations.ts, finishing-operations.ts, and
vertical-integration.ts. Real process-engineering domain logic with a
substantial spec suite.
A thin business-unit façade (libs/freya/watches/src/index.ts, ~18 LOC). It
wraps getFreyaBusinessUnitProfile('watches') from @freya/core and exposes
getWatchesBusinessUnitProfile, hasWatchesOperatingCapability, and
listWatchesKeyMetrics. Real delegating code with a spec, but no domain engine
of its own — the watch business-unit profile (movements, authentication,
allocation metrics) is defined in the core catalog.
watchesBusinessUnitCode5watchesBusinessUnitProfile6getWatchesBusinessUnitProfile8hasWatchesOperatingCapability12listWatchesKeyMetrics16