# Freya — Systems Deep Dive

> 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/core` type hub and
> a `@freya/db` persistence 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 reference

### @freya/core

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`.

### @freya/db

The persistence layer (`libs/freya/db/src`), tagged `type:database`. `schema.ts`
is a Drizzle schema of 24 `pgTable`s — 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.

### @freya/fashion

The 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.

### @freya/beauty

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.

### @freya/textiles

Textile 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.

### @freya/jewelry

Jewelry & 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.

### @freya/manufacturing

Manufacturing 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.

### @freya/ecommerce

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`.

### @freya/retail

Retail-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`.

### @freya/brand

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.

### @freya/academy

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.

### @freya/financials

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`.

### @freya/market-intel

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.

### @freya/sota

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.

### @freya/connectors

The 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.

### @freya/watches

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.

### @freya/perfumes

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.

### @freya/bridal-events

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.

### @freya/cleaning-products

A 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.

### @freya/hair-care

A 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.

### @freya/home-decor

A 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.

### @freya/footwear

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.

### @freya/eyewear

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.

### @freya/luggage-leather

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.

### @freya/personal-care

A 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.

### @freya/textile-finishing

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.