# Freya — Systems Deep Dive

> The `apps/freya/` area: five Nx application projects that implement the
> customer- and operations-facing application surfaces of the **Freya
> luxury-goods domain** — an API/contract aggregation layer plus four
> business-unit front ends, each backed by in-process, `Map`-backed engines.

## What this area is

Freya is Oshun's luxury-goods domain. Its deep domain logic lives in the large
`libs/freya/*` library cluster (`@freya/core`, `@freya/ecommerce`,
`@freya/fashion`, `@freya/beauty`, and dozens more). The `apps/freya/` area is a
separate, smaller layer: five Nx **application** projects
(`projectType: "application"`, all tagged `scope:freya`) that model the
application surfaces sitting on top of that domain — one API/contract
aggregation project and four business-unit modules (manufacturing, retail,
online shop, design studio).

Despite being "applications," these are not running servers. Each is a
TypeScript ESM package whose `package.json` `exports["."]` points straight at
`./src/index.ts`, and whose `project.json` declares only `test` (vitest) and
`lint` (eslint) targets — there is no `build` or `serve` target, no HTTP
bootstrap, no database wiring. Their engines are **in-process and `Map`-backed**
(e.g. `private products = new Map<...>()` in
`apps/freya/api/src/product-routes.ts`, `private lines = new Map<...>()` in
`apps/freya/manufacturing/src/production-dashboard.ts`), which matches the
documented state of the domain: "Freya's engines are in-process and `Map`-backed
today." Only `@freya/api` declares a runtime dependency (`zod`); the other four
declare none.

What makes them real rather than CRUD scaffolds is domain-specific computation.
`apps/freya/manufacturing/src/quality-inspection.ts` implements AQL acceptance
sampling (AQL 2.5 major / 4.0 minor, an `AQL_SAMPLING_PLAN` table modelled on
ANSI/ASQ Z1.4 Level II) and `production-dashboard.ts` computes OEE as
`availability * performance * quality` with World-Class/Excellent/Good grade
bands. `apps/freya/studio/src/color-palette-studio.ts` carries real WCAG
relative-luminance and contrast-ratio math (sRGB-to-linear conversion, the
`0.2126/0.7152/0.0722` luminance coefficients, AA/AAA thresholds) plus curated
Pantone TCX seasonal presets. `apps/freya/shop/src/checkout-flow.ts` is a
multi-step checkout state machine with market-aware gateway routing
(`selectPaymentGateway`: Ghana→Paystack, Nigeria→Flutterwave, UK/EU/US→Stripe)
and per-market shipping tables. Each project ships a substantial co-located test
suite (`*.spec.ts`) with real assertions — 148, 102, 95, 74, and 66
`expect(...)` calls respectively.

### Relationship to `libs/freya/*` and the name collision

These app projects deliberately do **not** reuse the `@freya/*` package names
the way you might expect. `tsconfig.base.json` maps `@freya/manufacturing` and
`@freya/retail` (and the rest of the `@freya/*` aliases) to the
**`libs/freya/`** libraries, not to these apps. To avoid colliding with those,
the two overlapping app projects use distinct **Nx project names** —
`freya-manufacturing-app` and `freya-retail-app` — even though their
`package.json` `name` fields still read `@freya/manufacturing` /
`@freya/retail`. The other three keep `@freya/api`, `@freya/shop`, and
`@freya/studio` as project names, but none of those three is path-aliased in
`tsconfig.base.json` at all. The practical consequence: nothing imports these
app packages by alias from elsewhere in the monorepo (a repo-wide search for
`from '@freya/{api,shop,studio,manufacturing,retail}'` outside `apps/freya`
returns zero hits that resolve to these projects). They are self-contained,
tested in isolation, and do not depend on `@freya/contracts` — `@freya/api`
declares its own Zod schemas in `apps/freya/api/src/schemas.ts` rather than
importing the shared contract package.

## How it fits the wider system

Within the Oshun stack these projects represent the application/presentation
tier of the Freya domain, distinct from the `libs/freya/*` domain engines and
from the `@freya/contracts` wire-contract package. In their current form they
are self-standing logic modules: each exports a barrel of domain classes and
handler functions from `src/index.ts`, exercised by its own vitest suite. The
heavier, cross-business-unit domain implementations (and the boundary types that
downstream consumers such as the Aglaea styling domain read) live in
`libs/freya/*` and `libs/contracts/freya`, not here. The boundary to respect is
therefore: `apps/freya/*` is where the per-surface application logic and request
validation sit, kept intentionally free of database, transport, and
cross-workspace coupling.

## Entity reference

### @freya/api

The API/contract aggregation surface for the domain (`apps/freya/api/src`, the
only project here with a `zod` dependency). It bundles, behind a single
`src/index.ts` barrel: request/response Zod schemas spanning product, order,
customer, manufacturing, retail, brand, formulation, analytics, and webhook
payloads (`schemas.ts`); in-memory handler logic with real validation, search
filtering, and pagination (`product-routes.ts`, `order-routes.ts`,
`customer-routes.ts`, `other-routes.ts`); RBAC, rate-limiting, and JWT-style
token middleware (`middleware.ts` — its token validation is explicitly a
crypto-free test seam, with a real per-role `ROLE_PERMISSIONS` table and
`:own`-ownership enforcement); a CloudEvents 1.0 event envelope plus Kafka topic
routing and consumer-group config (`event-bus.ts`); and GraphQL, gRPC,
WebSocket, and OpenAPI surface definitions (`graphql-schema.ts`,
`grpc-services.ts`, `websocket.ts`, `openapi-spec.ts`). It is the largest of the
five (its spec alone has ~1,000 lines) and is real handler/validation logic, not
a wired HTTP server.

### freya-manufacturing-app

The production-floor business unit (`apps/freya/manufacturing/src`; Nx project
`freya-manufacturing-app`, package `@freya/manufacturing`). Its
`QualityInspectionPortal` (`quality-inspection.ts`) implements AQL acceptance
sampling against an ANSI/ASQ Z1.4-style `AQL_SAMPLING_PLAN` table (AQL 2.5 major
/ 4.0 minor, lot-size→sample-size→accept/reject mapping) and tracks
non-conformances through an OPEN→IN_PROGRESS→RESOLVED lifecycle. Its
`ProductionDashboard` (`production-dashboard.ts`) computes OEE as
`availability × performance × quality` with graded thresholds and
threshold-based alerting. The barrel also exports order management,
batch-record, equipment, and waste-reporting modules. All state is `Map`-backed
in-process; the suite has 74 assertions. The Nx project name is suffixed `-app`
to avoid colliding with the path-aliased `libs/freya/manufacturing` library.

### freya-retail-app

The brick-and-mortar retail business unit (`apps/freya/retail/src`; Nx project
`freya-retail-app`, package `@freya/retail`). Its `ClientelingApp`
(`clienteling-app.ts`) maintains customer profiles, interaction history, and a
`VIP_THRESHOLD_GHS = 5000` tier flag, and produces ranked product
recommendations via a confidence-scoring heuristic (base 40, +30 on favourite-
colour match, +20 VIP premium for higher-priced items, top-5 by confidence). The
barrel adds store-dashboard KPIs, inventory lookup/transfer, visual
merchandising, and staff-performance modules. State is in-memory `Map`-backed;
the suite has 66 assertions. Like the manufacturing app, its Nx project name is
`-app`-suffixed because `@freya/retail` is aliased to the `libs/freya/retail`
library.

### @freya/shop

The online-storefront business unit (`apps/freya/shop/src`). Its `CheckoutFlow`
(`checkout-flow.ts`) is a real multi-step state machine
(address→shipping→payment→review→confirm) with `assertStep` guards, address
validation, market-aware gateway selection (`selectPaymentGateway`), per-market
`SHIPPING_OPTIONS` tables, and `FRY-`-prefixed order-number minting on confirm.
The barrel also exports product listing/detail, shopping cart, customer account,
subscription box, and a `VirtualTryOnPage` (`virtual-tryon.ts`) — the latter
models the try-on **session lifecycle** as a state machine
(INITIALIZING→READY→ACTIVE→CAPTURED→ENDED) with capture and wishlist hooks; it
is an honest session/state model, not a real AR/camera engine (initialization is
a synchronous status flip). 102 assertions. `@freya/shop` is not path-aliased in
`tsconfig.base.json`, so it is consumed only by its own tests.

### @freya/studio

The design-studio business unit (`apps/freya/studio/src`). Its
`ColorPaletteStudio` (`color-palette-studio.ts`) carries genuine WCAG colour
math — `relativeLuminance` (sRGB-to-linear with the standard
`0.2126/0.7152/0.0722` coefficients), `contrastRatio`, AA/AAA/AA-Large
thresholds, a full pairwise contrast matrix, and curated Pantone TCX seasonal
preset palettes. Its `DesignWorkspace` (`design-workspace.ts`) models design
projects through a DRAFT→SKETCH→REVIEW→APPROVED→PRODUCTION stage machine with
stage history and mood-board/tech-pack attachment. The barrel adds collection
dashboard, tech-pack editor, trend board, textile library, and
design-approval-board modules. State is `Map`-backed in-process; the suite has
95 assertions. `@freya/studio` is not path-aliased, so it stands alone,
exercised by its own vitest suite.