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 catalog (5)#
The 5 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. 5 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
unclassified (5)#
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.
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.
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.
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.
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.