Freya Domain - Technical Specifications

Luxury Goods and Fashion Intelligence. Implemented workspace domain — 26 capability/foundation libraries under libs/freya/*, the @freya/contracts package under libs/contracts/freya, and five applications under apps/freya/*. TODO Phase 57.

This specification documents what is implemented in code. Every schema, enum, state machine, endpoint, and event below is grounded in a named source file in the Freya workspace. Where a capability is described in features.md or TODOS/phase-57.md but not yet built, it is marked (planned).

The specification is organized to follow a reader top-down: package topology first, then the foundation layer (@freya/core types and @freya/db persistence), then the API surface, then the capability libraries, then the applications, configuration, requirements, and domain boundaries.

Package Topology#

Libraries (libs/freya/*)#

Twenty-six packages, all published under the @freya/* scope at version 0.1.0. Two are foundation packages; the rest are capability libraries owning one business unit each.

@freya/contracts (libs/contracts/freya, version 0.1.0) is a separate contracts package holding the Zod request/response schemas shared across the API and consuming services.

Applications (apps/freya/*)#

Five applications, all published at version 0.0.1. Their package.json names collide with library names by design (the apps are not consumed as libraries).

Foundation: @freya/core#

@freya/core (libs/freya/core/src/index.ts) is the type and utility foundation every capability library imports. Its source modules are product-types.ts, material-types.ts, supply-chain-types.ts, brand-customer-types.ts, beauty-types.ts, business-units.ts, and utilities.ts.

Branded ID Types#

From product-types.ts, six template-literal branded ID types prevent cross-entity reference confusion at compile time. Each carries a fixed prefix that makes IDs self-documenting and ensures the TypeScript compiler rejects a FreyaOrderId where a FreyaProductId is expected.

The ID generators (generateProductId, generateCollectionId, generateOrderId, generateCustomerId, generateVariantId) build IDs as PREFIX{hexTimestamp}-{6-hex-sequence}-{4-hex-random}. The monotonic sequence wraps at 0x1000000.

Product-Domain Enums (product-types.ts)#

These enums define the shared vocabulary for product lifecycle, markets, currencies, seasons, and categories. All capability libraries and the API use these same values.

• ProductStatus — the product lifecycle: Concept, InDevelopment, Sampling, PreProduction, InProduction, ReadyToShip, Active, Discontinued.
• FashionSeason — SS (Spring/Summer), FW (Fall/Winter), Resort, PreFall, Capsule, Perennial.
• FreyaCurrency — GHS, NGN, USD, GBP, EUR, CAD, ZAR.
• MarketRegion — Ghana, Nigeria, UK, USA, Canada, Germany, Netherlands, Pan_Africa.
• ProductCategory — nineteen values: fashion_rtw, fashion_couture, watches, textiles_fabric, textiles_finished, skincare, cosmetics, perfume, hair_care, personal_care, detergent, bridal, jewelry, footwear, eyewear, luggage, interior_textiles, accessories, educational.

Product Entity#

Product (product-types.ts) is the central entity. The table below documents every field and its meaning.

ProductVariant carries per-SKU details: variantId (FreyaVariantId), sku (FreyaSkuId), optional barcode, optional size/color/material, stockByLocation (Record<string, number> — quantity keyed by location), costGhs, optional weight, and optional dimensions ({ length, width, height }).

PricingTier models multi-tier, multi-currency pricing: tierId, tierName (one of retail, wholesale, vip, diaspora_premium, trade), prices (a MultiCurrencyPrice map of currency-code → amount), minimumOrderQuantity, discountPct.

getPriceForMarket(product, market, tier, currency) resolves a price by looking up the named tier, preferring the requested currency, and falling back to the market's default currency via a fixed market→currency map (Ghana→GHS, Nigeria→NGN, UK→GBP, USA→USD, Canada→CAD, Germany/Netherlands→EUR, Pan_Africa→GHS).

Collection Entity#

Collection (product-types.ts) groups related products for a season. It carries: collectionId (FreyaCollectionId), name, brand, season (FashionSeason), year, theme, optional culturalInspiration, productIds (array of FreyaProductId), launchDate, targetMarkets, priceRangeGhs ({ min, max }), numberOfLooks, designerName, and a status of concept, design, production, launched, or archived.

LimitedEdition tracks numbered drops: productId, editionName, totalUnits, remainingUnits, authenticationCode (8-hex), numbering, premiumPct, launchAt, optional expiresAt. buildLimitedEdition constructs it with remainingUnits equal to totalUnits and numbering of 1/{totalUnits}.

Material and Textile Types (material-types.ts)#

These enums and types model the physical materials that go into a luxury product. They cover textiles, leathers, metals, gemstones, chemicals, and botanical ingredients.

Enums:

• FiberType — cotton, silk, wool, polyester, viscose, bamboo, hemp, kente_silk, ashanti_cotton, linen, nylon, acrylic, lurex.
• TextileFinish — wax_print, batik, tie_dye, digital_print, screen_print, embroidery, beading, smocking, applique, plain.
• AfricanPrintType — Ankara, Kente, Adinkra, Bogolan, Shweshwe, Aso_Oke, Kuba, Brocade.
• LeatherType — full_grain, top_grain, genuine, bonded, vegan_pu, vegan_cork, suede.
• MaterialGradeScore — A+, A, B, C, Reject.

Material is the core material record: materialId, name, type (textile, leather, metal, gemstone, chemical, botanical, packaging), gradeScore (MaterialGradeScore), supplierId, pricePerUnitGhs, unit (metre, kg, litre, piece, carat), minimumOrderUnits, leadTimeDays, certifications, sustainabilityScore.

Textile extends material for woven and knitted fabrics: textileId, name, composition (array of FiberComposition), weaveType (plain, twill, satin, jacquard, knit, nonwoven, lace), weightGSM, widthCm, optional countOrDenier, origin, certifications, sustainabilityRating, priceGhsPerMeter.

FiberComposition records a single fiber's contribution: fiberType, percentagePct. Colorway models the precise color specification for a dye lot: colorwayId, name, pantoneCode, hexCode, rgbValues, dyeFormula, colorToleranceDeltaE, and four colorfastness ratings (fastnessCrockWet, fastnessCrockDry, fastnessWash, fastnessLight).

AfricanPrint captures culturally significant textile patterns: printId, printType, name, culturalOrigin, culturalSignificance, colorways, repeatPatternCm, minimumOrderMeters, leadTimeDays, optional artisanCoopName, geoprotectionApplied.

TextileTest records a fabric quality test against a laboratory standard: testId, textileId, testType (tensile_strength, colorfastness, shrinkage, pilling, abrasion, bursting_strength), standard, result, unit, passFailThreshold, passed, testedAt, labName.

Three algorithmic invariants are enforced in code. validateFiberComposition requires fiber percentages to sum to 100% within ±0.5. classifyTextileWeight buckets GSM as ultra_light (<100), light (<200), medium (<350), heavy (≤500), extra_heavy (>500). computeDeltaE is a simplified CIE76-style RGB color difference calculation used to evaluate colorway matching.

Supply-Chain and Manufacturing Types (supply-chain-types.ts)#

These types model the supplier tier structure, manufacturing order lifecycle, AQL quality inspection logic, and shipment tracking.

Enums:

• SupplierTier — tier_1, tier_2, tier_3.
• SupplierCertification — ISO9001, OEKO_TEX, GOTS, Fairtrade, SEDEX, SA8000, WRAP, FSC.
• OrderStatus (supply-chain order) — draft, placed, confirmed, in_production, quality_check, ready, shipped, delivered, cancelled.
• InspectionResult — pass, conditional_pass, fail, pending.

Supplier records everything Freya needs to evaluate and manage a supply relationship: supplierId, name, country, city, tier, capabilities, certifications (array of SupplierCertification), leadTimeDays, minimumOrderValue, currency, performanceScore, onTimeDeliveryPct, qualityPassRatePct, contactEmail, optional activeContractEnd.

Artisan tracks individual craft practitioners: artisanId, name, craft, communityName, region, skillLevel (apprentice, journeyman, master, grandmaster), yearsExperience, dailyCapacityUnits, rateGhsPerDay, portfolioUrls, fairtradeRegistered.

BOMLine captures one line of a bill of materials: materialId, materialName, quantityPerUnit, unit, wastageAllowancePct, totalQuantityRequired, unitCostGhs, totalCostGhs.

ManufacturingOrder (core type) is the production instruction for one product variant: orderId, productId (FreyaProductId), variantId (FreyaVariantId), quantity, supplierId, bom (array of BOMLine), totalBOMCostGhs, manufacturingCostGhs, totalCostGhs, targetStartDate, targetCompletionDate, status (OrderStatus), qualityInspections (array of inspection IDs), lotNumber.

QualityInspection records AQL sampling evidence for a batch: inspectionId, orderId, productId, inspectionType (incoming, in_process, final, shipment), inspectedUnits, acceptableQualityLevel, defectsFound (array of { category, severity: critical|major|minor, count }), result (InspectionResult), inspectorId, inspectedAt, notes.

ShipmentTracking records a physical shipment's movement through customs and delivery: shipmentId, orderId, carrier, trackingNumber, origin, destination, optional departedAt, estimatedArrivalAt, optional actualArrivalAt, customsStatus (not_required, filed, under_review, cleared, held), status (pending, in_transit, at_customs, delivered, exception), insuranceValueGhs.

Three AQL quality functions are implemented. computeAQLSampleSize returns standard sample sizes per lot size (lot <50→5, ≤90→8, ≤150→13, ≤280→20, ≤500→32, ≤1200→50, else 80). evaluateQualityResult returns fail on any critical defect or majors exceeding the AQL threshold, conditional_pass on minors exceeding twice that threshold, and pass otherwise. computeSupplierScore is a weighted aggregate: performanceScore × 0.4 + onTimeDeliveryPct × 0.3 + qualityPassRatePct × 0.3.

Brand and Customer Types (brand-customer-types.ts)#

These types model brand positioning hierarchies and customer segmentation, which together drive pricing, campaign targeting, and loyalty management.

Enums:

• CustomerSegment — fashionista, conscious_consumer, heritage_seeker, luxury_buyer, diaspora_elite, mass_market.
• LoyaltyTier — bronze, silver, gold, platinum, obsidian.

Brand models a brand's identity and market position: brandId, name, optional parentBrand, positioning (ultra_luxury, luxury, premium, accessible_premium, mass), targetSegments, heritageStory, foundingYear, foundingCountry, designerName, optional logoUrl, brandColors, brandFonts, optional instagramFollowers, sustainabilityCommitments.

Customer carries the full profile needed for personalization and loyalty: customerId (FreyaCustomerId), firstName, lastName, email, optional phoneNumber, country, city, segment, loyaltyTier, loyaltyPoints, lifeTimeValueGhs, preferredCurrency, preferredCategories, sizes (Record<string, string>), optional skinTone/hairType, purchaseCount, optional lastPurchaseAt, registeredAt.

DiasporaMarket, LoyaltyProgram, and InfluencerPartnership are also defined here. classifyCustomerSegment derives a segment algorithmically from lifetime value, purchase count, and category affinity, using the following rules: luxury affinity + LTV ≥ 50000 → luxury_buyer; LTV ≥ 20000 with ≥10 purchases → diaspora_elite; heritage affinity with ≥3 purchases → heritage_seeker; beauty affinity with ≥5 purchases → fashionista; LTV ≥ 5000 with ≥5 purchases → conscious_consumer; otherwise mass_market.

Beauty and Formulation Types (beauty-types.ts)#

These types model the scientific and regulatory dimension of beauty product development, covering ingredient chemistry, stability testing, and regulatory submission.

Enums:

• FragranceFamily — floral, oriental, woody, fresh, fougere, chypre, gourmand, aquatic.
• HairType — the twelve Andre Walker classes 1A–4C.
• SkinType — normal, dry, oily, combination, sensitive, mature.
• FitzpatrickScale — numeric 1–6.
• FormulationStatus — concept, development, stability_testing, approved, production, discontinued.

INCIIngredient records a single ingredient per the INCI naming convention: inciName, commonName, percentagePct, function (array of strings), origin (natural, synthetic, nature_identical, biotechnology), supplierId, safetyAssessmentRef, isActiveIngredient, optional regulatoryRestriction.

Formulation is the versioned formulation record for a beauty product: formulationId, name, category (skincare, cosmetics, hair_care, fragrance, personal_care, detergent), ingredients (array of INCIIngredient), phRange ({ min, max }), optional viscosityCps, appearanceDescription, shelfLifeMonths, storageConditions, status (FormulationStatus), version, createdAt, optional regulatoryRef.

FragranceNote records one ingredient's role in a fragrance accord: ingredientId, inciName, noteType (top, heart, base), family, odorIntensity, longevityHours, percentageInAccord.

StabilityTest records a time-point stability test result: testId, formulationId, protocol (ICH_Q1A, accelerated_40C, cycling, photo_stability), timePointWeeks, conditions, parameters (record of { value, specification, passed }), overallResult (pass, fail, pending), testedAt.

RegulatorySubmission tracks market-specific regulatory filing: submissionId, formulationId, market, regulatoryBody (Ghana_FDA, EU_SCCS, US_FDA, NAFDAC), submissionType (registration, notification, cpsr, renewal), status (draft, submitted, under_review, approved, rejected), optional submittedAt, approvedAt, expiryAt, registrationNumber.

Three algorithmic functions are provided. validateINCISum enforces ingredient percentages summing to 100% ±0.5. computeFragranceAccordStrength weights base notes ×1.5, heart ×1.2, top ×1.0. getHairTypeRecommendations and getSkinTypeIngredients return domain-specific product/ingredient guidance per hair type and skin type.

Business-Unit Catalog (business-units.ts)#

FreyaBusinessUnitCode enumerates the nineteen business units that Freya manages: fashion, watches, textiles, beauty, perfumes, bridal-events, ecommerce, manufacturing, hair-care, home-decor, jewelry, footwear, eyewear, academy, luggage-leather, personal-care, retail, cleaning-products, textile-finishing.

FREYA_BUSINESS_UNIT_CATALOG is a frozen array of nineteen FreyaBusinessUnitProfile records. Each profile carries code, packageName (@freya/...), displayName, summary, primaryCategories, operatingCapabilities, productionModels, commercialChannels, and keyMetrics. The assertion assertCompleteFreyaBusinessUnitCatalog enforces exactly nineteen entries with unique codes and packages, protecting the catalog against accidental omission.

Core Utilities (utilities.ts)#

utilities.ts provides deterministic helpers used across the capability libraries so each library does not implement its own version of common calculations.

• SKU generation — generateSKU(buCode, category, year, sequence) builds FSKU-{BU}-{CAT}-{YY}-{SSSS} using a fixed category→3-letter abbreviation map (fashion_rtw→RTW, jewelry→JWL, etc.).
• Barcodes — generateEAN13/validateEAN13Checksum and generateUPCA/validateUPCAChecksum implement the standard EAN-13 and UPC-A check-digit algorithms.
• Currency — EXCHANGE_RATES_TO_GHS holds fixed GHS conversion rates for every FreyaCurrency; convertToGHS, convertFromGHS, and formatCurrency (with per-currency symbols) operate on it.
• Textile conversions — yardsToMeters, metersToYards, gsmToOzPerSqYard, denierToTex, threadCountToGSM.
• Pantone matching — GHANA_FASHION_PALETTE is a twelve-color Kente/Ankara palette; findNearestPantone returns the closest palette color by simplified Delta-E distance.
• Error types — FreyaError (base class, with code and optional buCode), FreyaValidationError (FREYA_VALIDATION_ERROR), FreyaNotFoundError (FREYA_NOT_FOUND), FreyaBusinessRuleError (FREYA_BUSINESS_RULE_VIOLATION).

Persistence: @freya/db#

@freya/db (libs/freya/db/src) owns all persistence infrastructure for the Freya domain. Source modules: schema.ts, connection.ts, redis-config.ts, s3-config.ts, observability.ts, seed.ts. Capability libraries import from this package to get schema types; they never construct their own database connections.

PostgreSQL Schema (schema.ts)#

All tables and enums are prefixed freya_. The Drizzle migration filter is tablesFilter: ['freya_*'] (connection.ts). Tables use UUID primary keys (uuid('id').defaultRandom()), timezone-aware created_at/updated_at timestamps, and jsonb columns for nested structures. The pgvector extension provides vector(1536) embedding columns for catalog, collection, recommendation, and trend-clustering similarity search.

Schema Enums#

schema.ts declares the following Postgres enums. Note that the Drizzle enum value sets differ from the @freya/core string-union sets by design: @freya/core types model in-process domain logic with PascalCase values; schema.ts enums model persisted Postgres columns with snake_case values. The two are not kept textually identical.

• freya_product_status — concept, in_development, sampling, pre_production, in_production, ready_to_ship, active, discontinued.
• freya_business_unit — fashion, textiles, beauty, skincare, haircare, fragrance, jewelry, footwear, eyewear, home_decor, luggage, personal_care, detergent, academy, retail, ecommerce, bridal, watches (eighteen values).
• freya_product_category — sixty-two values grouped by domain: fashion (dress, top, trouser, skirt, jacket, coat, suit, jumpsuit, swimwear, sportswear); accessories (bag, wallet, belt, hat, scarf, gloves, sunglasses, watch); shoes (heels, flats, sandals, boots, sneakers, loafers, oxfords); beauty (foundation, lipstick, eyeshadow, mascara, blush, serum, moisturizer, cleanser, toner, sunscreen); haircare (shampoo, conditioner, treatment, styling, tools, extensions); fragrance (eau_de_parfum, eau_de_toilette, body_mist, candle, diffuser); jewelry (necklace, ring, earring, bracelet, anklet, brooch, cufflinks); home (bedding, curtains, cushion, throw, rug, lampshade); personal care (soap, lotion, deodorant, sanitizer, dental, shaving); detergent (laundry_powder, laundry_liquid, fabric_softener, dishwashing, floor_cleaner).
• freya_season — SS, FW, Resort, PreFall, Capsule, Bridal, Couture.
• freya_collection_type — seasonal, capsule, collaboration, limited_edition, bridal, couture.
• freya_material_type — textile, leather, metal, gemstone, botanical, chemical, synthetic.
• freya_fiber_type — cotton, silk, wool, polyester, viscose, bamboo, hemp, linen, kente_silk, local_cotton, cashmere, mohair, lyocell, nylon, acrylic.
• freya_textile_finish — wax_print, batik, tie_dye, digital_print, screen_print, embroidery, beading, smocking, applique, laser_cut, pleating, quilting, burnout.
• freya_order_status — pending, confirmed, processing, shipped, delivered, cancelled, refunded, return_requested, returned.
• freya_manufacturing_status — planned, in_progress, quality_check, completed, on_hold, cancelled.
• freya_quality_result — passed, failed, conditional_pass, pending_retest.
• freya_customer_segment — vip, premium, regular, new, diaspora, wholesale, corporate.
• freya_loyalty_tier — bronze, silver, gold, platinum, diamond.
• freya_currency — GHS, NGN, USD, GBP, EUR, CAD, ZAR, KES.
• freya_market — ghana, nigeria, kenya, south_africa, uk_diaspora, us_diaspora, canada_diaspora, eu_diaspora.
• freya_store_type — flagship, pop_up, duty_free, mall_kiosk, market_stall, studio, warehouse, outlet.
• freya_inspection_type — fabric, garment, cosmetics, jewelry, packaging, finished, raw_materials, in_process.
• freya_certification_status — pending, approved, rejected, expired, under_review.
• freya_asset_type — logo, sketch, tech_pack, pattern, cad, mood_board, product_photo, lifestyle_photo, video, ar_model.
• freya_trend_source — instagram, tiktok, pinterest, runway, street_style, celebrity, editorial, trade_show, sales_data, search.
• freya_academic_status — enrolled, active, on_leave, graduated, withdrawn, suspended.

Schema Tables#

Twenty-four tables form the persistent core of the domain, exported as the schema object. Every table uses UUID primary keys and targeted B-tree indexes; unique indexes enforce the business keys listed at the end of this section.

• freya_products — catalog row. Key columns: sku (unique index), ean13, upc_a, name, business_unit, category, status (default concept), brand_id → freya_brands, collection_id → freya_collections, base_price_amount/base_price_currency, market_prices (jsonb), weight_kg, dimensions_cm, materials (jsonb array of { materialId, pct }), country_of_origin, sustainability_rating, certifications, embedding (vector(1536)), ai_tags, is_limited_edition, edition_size, edition_number, launch_date, discontinue_date, metadata. Indexed on sku, business_unit, status, brand_id, collection_id.
• freya_product_variants — product_id → freya_products (cascade delete), sku_suffix, full_sku (unique), size, color_name, color_pantone, color_hex, material_variant, weight_kg, price_adjustment, inventory_quantity, reserved_quantity, reorder_point, reorder_quantity, warehouse_location, barcode, is_active, image_urls.
• freya_collections — name, slug (unique), type, season, year, brand_id, theme, mood_board_urls, color_palette, style_count_target, launch_date, markets, price_range_min/price_range_max/currency, is_numbered, total_pieces, collaborator_name, collaborator_type, embedding (vector(1536)). Indexed on slug, (season, year), type, brand_id.
• freya_materials — code (unique), name, type, textile columns (fiber_composition, weave_type, weight_gsm, width_cm, thread_count, finish), leather columns (leather_type, tannage, thickness_mm), metal/gemstone columns (purity, carat, cut, clarity, color_grade), beauty-ingredient columns (inci_name, cas_number, ph_range_min/ph_range_max, max_use_pct, eu_restricted), quality and sustainability (grade, sustainability_score, certifications, origin_country, origin_region), supplier linkage (supplier_id → freya_suppliers, unit_of_measure, unit_cost, cost_currency, lead_time_days, minimum_order_quantity), storage (storage_conditions, shelf_life_months), and African-textile cultural metadata (cultural_origin, cultural_significance, pattern_name, is_heritage).
• freya_suppliers — code (unique), name, type, location columns, contact columns, capability columns (business_units, product_categories, capabilities, MOQ fields), performance ratings (quality_rating/delivery_rating/communication_rating/overall_rating, on_time_delivery_pct, defect_rate_pct, average_lead_time_days), certifications (jsonb array of { name, body, expiry, verified }), is_verified, is_active, payment_terms_days, preferred_currency.
• freya_artisans — code (unique), name, craft_type, location columns, years_experience, specializations, certifications, portfolio_urls, capacity columns (monthly_capacity_units, typical_lead_time_days, day_rate_amount/day_rate_currency), cooperative columns, is_certified_fair_trade, ratings, bio, heritage_story.
• freya_manufacturing_orders — order_number (unique), type, business_unit, status (default planned), priority, product linkage (product_id, variant_id, collection_id), production columns (facility_id, supplier_id, artisan_id, quantity, batch_size, quantity_completed, quantity_rejected, yield_pct), bom (jsonb), scheduling timestamps (planned_start_date, actual_start_date, target_completion_date, actual_completion_date), cost columns, labor_hours, quality_standard, quality_result, and routing (jsonb array of { step, operation, workstation, durationMin, completedAt? }).
• freya_customers — email (unique), name/phone columns, date_of_birth, gender, market, segment (default new), loyalty_tier (default bronze), loyalty_points, lifetime_points, diaspora columns (is_diaspora, origin_country, diaspora_country), financial columns (total_spend_ghs, order_count, average_order_value_ghs, last_purchase_at), preference columns (preferred_language, preferred_currency, preferred_categories, preferred_sizes, preferred_colors, preferred_brands, preferred_price_range, preferred_communication), VIP columns, body-measurement columns (measurements, hair_type, skin_type, fitzpatrick_scale), preference_embedding (vector(1536)), and consent columns (marketing_consent, data_processing_consent, consents_updated_at).
• freya_retail_locations — code (unique), name, type, brand_id, location/geo columns, lease columns, operations columns (opening_hours, staff_count, pos_terminal_count, manager contact), KPI columns (monthly_revenue_target_ghs, avg_daily_footfall, conversion_rate_pct, nps_score), business_units, and facility flags (has_fitting_room, has_vip_lounge, has_alteration_service, has_fragrance_bar).
• freya_orders — order_number (unique), customer_id → freya_customers, channel, market, status (default pending), lines (jsonb array of order-line objects), shipping_address/ billing_address (jsonb), pricing columns (subtotal, shipping_cost, discount_amount, tax_amount, total, currency), payment columns (payment_method, payment_reference, payment_status, paid_at), shipping columns (shipping_method_id, carrier, tracking_number, estimated_delivery, delivered_at), promotion columns (promo_code, loyalty_points_earned, loyalty_points_redeemed, gift_message, gift_wrap), and retail_location_id → freya_retail_locations for click-and-collect.
• freya_carts — session_id (unique), customer_id, market, currency, lines (jsonb), promo_code, discount_amount, total_items, subtotal, expires_at.
• freya_wishlists — customer_id → freya_customers (cascade), name, is_public, share_token, items (jsonb).
• freya_virtual_tryon_sessions — customer_id, session_token (unique), product_id, variant_id, input columns (body_photo_url ephemeral — deleted after the session to satisfy privacy requirements, measurements_used), output columns (result_image_url, result_video_url, fit_assessment, recommended_size), feedback columns (customer_rating, added_to_cart, purchased), technical columns (ar_engine, processing_time_ms), expires_at.
• freya_brands — code (unique), name, parent_brand_id (self-referential), positioning columns (tier, tagline, heritage_story, founding_year, founded_in), identity columns (colors, fonts, logo_url, brand_book_url), target-market columns, social-media handles, and metrics (brand_equity_score, nps_score, social_followers).
• freya_brand_campaigns — brand_id → freya_brands, name, type, channels, markets, date columns, budget columns, KPI columns (target/actual impressions, conversions, revenue, roas), content columns (creative_assets, hashtags, influencer_ids), status.
• freya_influencer_partnerships — brand_id → freya_brands, influencer columns, platform, handle, followers, engagement_rate_pct, niche, tier, market, contract columns, fee_per_post/fee_currency, deliverables (jsonb), performance (jsonb), status.
• freya_quality_inspections — inspection_number (unique), type, manufacturing_order_id → freya_manufacturing_orders, batch_id, product_id, supplier_id, inspector columns, AQL sampling columns (lot_size, sample_size, aql_level, aql_critical default 0, aql_major default 2.5, aql_minor default 4.0), result columns (samples_inspected, defects_found, critical_defects, major_defects, minor_defects, defect_rate_pct, defect_details, result), test_results (jsonb), gmp_checks (jsonb — cosmetics GMP), corrective_actions (jsonb), retest_required, retest_date, certificate_url.
• freya_academy_students — student_number (unique), email (unique), name/contact columns, status (default enrolled), enrollment/graduation dates, programme, specialization, cohort, scholarship_type, tuition_paid, gpa, portfolio_url, certifications_earned (jsonb), employment columns.
• freya_academy_courses — code (unique), title, programme, level (100–400), credits, duration_weeks, description, learning_outcomes, prerequisites, instructor_id, materials_required, max_enrollment.
• freya_academy_enrollments — student_id → freya_academy_students (cascade), course_id → freya_academy_courses, academic_year, semester, grade, grade_letter, attendance_pct, status, completed_at.
• freya_formulations — code+version (unique pair), name, business_unit, category, subcategory, product_type, ingredients (jsonb array of INCI ingredient objects), total_batch_size_kg, physical-chemical specs (ph_min/ph_max, viscosity, density_g_ml, color/odor/appearance specs), safety columns (preservative_system, spf_value, is_allergen_free, allergens_present, eu_compliant, ghana_fda_approved, nafdac_approved), stability columns (shelf_life_months, storage_conditions, stability_results), fragrance-note columns (fragrance_family, top_notes, middle_notes, base_notes), efficacy_claims (jsonb), cost_per_kg/cost_currency, status, is_approved, approved_by, approved_at.
• freya_trend_signals — source, source_id, source_url, classification columns (business_unit, category, trend_name, tags), cultural columns (cultural_context, markets), metric columns (engagement_count, view_count, share_count, sentiment_score, virality_score, trend_velocity), AI-analysis columns (summary, design_recommendations, color_palette, material_suggestions), content_embedding (vector(1536)), lifecycle flags (is_emerging, is_mainstream, is_declining), peak_prediction_date, captured_at.
• freya_financial_records — period_year+period_month+business_unit +market (unique tuple), retail_location_id, revenue columns (gross_revenue_ghs, net_revenue_ghs, returns_amount_ghs, discount_amount_ghs), COGS columns (cogs_ghs, material_cost_ghs, labor_cost_ghs, overhead_cost_ghs), margin columns (gross_margin_ghs, gross_margin_pct), opex columns, EBITDA columns, volume columns (units_sold, transactions, average_transaction_value_ghs), inventory columns (inventory_value_ghs, inventory_turnover, days_inventory_outstanding), and accounts columns.
• freya_inventory_valuations — valuation_date, business_unit, product_id → freya_products, variant_id, quantity_on_hand, unit_cost_ghs, total_value_ghs, valuation_method (default FIFO), location_id.

Schema Indexes and Partitioning Notes#

Every table declares targeted B-tree indexes. Unique indexes enforce business keys: freya_products.sku, freya_product_variants.full_sku, freya_collections.slug, freya_materials.code, freya_suppliers.code, freya_artisans.code, freya_manufacturing_orders.order_number, freya_customers.email, freya_retail_locations.code, freya_orders.order_number, freya_carts.session_id, freya_virtual_tryon_sessions.session_token, freya_brands.code, freya_quality_inspections.inspection_number, freya_academy_students.student_number and email, freya_academy_courses.code, the (code, version) pair on freya_formulations, and the (period_year, period_month, business_unit, market) tuple on freya_financial_records. Query-pattern indexes cover status, business-unit, foreign-key, and time-range filters (for example freya_orders is indexed on customer_id, status, market, and created_at; freya_trend_signals on source, business_unit, virality_score, captured_at, and is_emerging). The five vector(1536) columns (freya_products.embedding, freya_collections.embedding, freya_customers.preference_embedding, freya_trend_signals.content_embedding) support pgvector similarity search for catalog, collection, recommendation, and trend-clustering queries.

Connection Pooling (connection.ts)#

buildFreyaDbPoolConfig(serviceRole, overrides) sizes the connection pool differently per service role, reflecting the read/write intensity of each service. It produces a FreyaDbPoolConfig as follows: ecommerce (max 10 with PgBouncer / 20 direct, min 2), manufacturing (5/10, min 1), analytics (3/5, min 1), admin (3/5, min 1), background (2/3, min 0). It reads FREYA_DATABASE_URL (falling back to DATABASE_URL, then postgresql://oshun:oshun_dev@localhost:5432/freya), sets a 30-second statement_timeout, and toggles PgBouncer transaction mode when FREYA_USE_PGBOUNCER is true. buildReadReplicaConfig routes analytics/reporting reads to weighted replicas listed in FREYA_DATABASE_REPLICA_URLS. buildPgBouncerUrl rewrites the port to PGBOUNCER_PORT (default 6432) and disables prepared statements. The Drizzle migration config (FREYA_DRIZZLE_CONFIG) points at schema.ts, outputs to libs/freya/db/drizzle, dialect postgresql, with tablesFilter: ['freya_*'].

Redis Caching (redis-config.ts)#

Redis is central to Freya's real-time commerce behavior: inventory availability, cart state, and pricing are all read from Redis rather than Postgres on the hot path.

FREYA_REDIS_PREFIX is freya. FreyaRedisKeys builds namespaced keys for inventory (freya:inv:{variantId}), product catalog, collection, customer session/profile/loyalty, cart, exchange rates, per-market product price, store KPIs and footfall, trend scores, API and checkout rate-limit counters, virtual-try-on session, and distributed locks (freya:lock:inv:{variantId}, freya:lock:checkout:{orderId}).

FreyaRedisTTL defines TTLs in seconds: inventory 30, product 600, product search 120, collection 3600, session 86400 (sliding), customer profile 900, cart 604800, exchange rates 900, product price 900, store KPI 300, trend score 3600, trending-now 1800, rate limit 60, lock 10, try-on session 1800. FreyaInvalidationPatterns defines SCAN-based bulk invalidation groups.

FreyaPubSubChannels defines the six Redis pub/sub channels used for low-latency fan-out to connected clients: freya:pubsub:inventory, freya:pubsub:order_status, freya:pubsub:price, freya:pubsub:store_kpi, freya:pubsub:trend, freya:pubsub:cart. buildInventoryCacheEntry computes a write-through InventoryCacheEntry whose available is max(0, inventoryQty - reservedQty). buildFreyaRedisConfig reads FREYA_REDIS_URL/REDIS_URL (default redis://localhost:6379).

Object Storage (s3-config.ts)#

Three MinIO/S3 buckets serve different asset types with different access and retention policies:

• freya-design-assets — private, signed URLs only, versioned, with a 730-day Glacier transition for archived designs. Used for sketches, tech packs, patterns, mood boards, and CAD files.
• freya-product-imagery — public CDN-served, not versioned, 365-day expiration. Used for studio shots, lifestyle images, 360-degree frames, and AR .glb models.
• freya-manufacturing-docs — strictly private, versioned, retained for regulatory compliance. Used for GMP batch records, QC reports, QC photos, certificates, and formulation documents.

FreyaS3Keys defines object-key conventions per asset class. FREYA_S3_SIGNED_URL_TTL sets signed-URL lifetimes per class. buildFreyaS3Config reads FREYA_S3_ENDPOINT, FREYA_S3_REGION, FREYA_S3_ACCESS_KEY, FREYA_S3_SECRET_KEY, and FREYA_CDN_BASE_URL, and forces path-style addressing for MinIO.

Observability (observability.ts)#

FREYA_OTEL_CONFIG configures OpenTelemetry tracing. FREYA_PROMETHEUS_METRICS defines the Prometheus metric catalog and FREYA_METRICS_CONFIG its scrape settings. Structured logging uses FreyaLogEntry with LogLevel of debug, info, warn, error, fatal. FREYA_CIRCUIT_BREAKERS defines per-service circuit-breaker configs with a CircuitBreakerState of closed, open, or half_open; shouldOpenCircuit and shouldCloseCircuit implement the transition logic.

Reference Seed Data (seed.ts)#

seed.ts ships reference datasets used during development and testing rather than transactional rows. It includes: FABRIC_REFERENCE (African textile types with GSM ranges, fiber composition, cultural origin and significance, and isHeritage flags — e.g. Ankara wax print, Kente cloth), ingredient INCI references, GIA-standard gemstone grades, the African Pantone palette, and per-market standard size charts.

API Surface: apps/freya/api#

@freya/api (apps/freya/api/src) exposes the Freya domain through REST, GraphQL, gRPC, and WebSocket interfaces. Source modules: schemas.ts, middleware.ts, product-routes.ts, order-routes.ts, customer-routes.ts, other-routes.ts, graphql-schema.ts, websocket.ts, grpc-services.ts, event-bus.ts, openapi-spec.ts.

REST Endpoints and Route Map#

The OpenAPI 3.1 spec (openapi-spec.ts) is the published REST contract, served at /openapi.json. Base path /v1. FREYA_API_ROUTES enumerates the route map. OpenAPI servers are https://api.freya.oshun.ai/v1 (production), https://api.staging.freya.oshun.ai/v1 (staging), and http://localhost:3500/v1 (local).

REST Authentication and Authorization (middleware.ts)#

Two security schemes are enforced. bearerAuth uses JWT for user-facing calls; apiKey (the X-API-Key header) is used for service-to-service calls and webhook validation.

UserRole is one of customer, associate, manager, admin. authMiddleware validates a three-part bearer token, checks required claims (userId, email, role), enforces expiresAt, and rejects unknown roles.

ROLE_PERMISSIONS defines what each role can do:

• customer — products:read, orders:create, orders:read:own, customer:read:own, customer:update:own, loyalty:read:own, loyalty:redeem:own, cart:manage:own, wishlist:manage:own, reviews:create.
• associate — products:read, orders:read, inventory:read, customer:read, clienteling:manage, transactions:create, store:read.
• manager — adds products:write, orders:update, inventory:manage, reports:read, staff:read, store:manage, manufacturing:read, manufacturing:write, analytics:read.
• admin — wildcard * (full access).

rbacMiddleware enforces :own permissions with an ownership check: the requesting user must match the resource owner. Rate limiting (RATE_LIMITS) uses three buckets: api allows 100 requests/60 s, auth 10/60 s, webhooks 1000/60 s; rateLimitMiddleware returns retryAfterMs when a window is exhausted.

REST Request/Response Schemas#

Two Zod schema sets exist. The API app's own schemas.ts backs the handler logic directly. @freya/contracts holds the cross-service contract schemas consumed by any other domain calling Freya.

apps/freya/api/src/schemas.ts defines, among others: CreateProductSchema/UpdateProductSchema/SearchProductsSchema, CreateOrderSchema (with paymentMethod of card/mobile_money/ bank_transfer and market of ghana/nigeria/uk/eu/us), UpdateOrderStatusSchema, ProcessReturnSchema, ProcessRefundSchema, RegisterCustomerSchema, UpdateProfileSchema, UpdatePreferencesSchema, RedeemPointsSchema (points must be a positive multiple of 100), CreateManufacturingOrderSchema (priority RUSH/STANDARD/DEFERRED), ScheduleOrderSchema, UpdateBatchSchema, RecordQualityCheckSchema (defect class CRITICAL/MAJOR/MINOR), ScheduleMaintenanceSchema, RecordTransactionSchema, LookupInventorySchema, RequestTransferSchema, CreateCampaignSchema, AddInfluencerSchema, TrackCampaignMetricsSchema, CreateFormulationSchema, AddIngredientSchema, ScheduleStabilityTestSchema, GetTrendReportSchema, GetFinancialReportSchema, and webhook schemas (PaystackWebhookSchema, StripeWebhookSchema, ShippingUpdateSchema, SocialCommerceWebhookSchema).

@freya/contracts (libs/contracts/freya/src) defines four schema modules:

• product-schemas.ts — ProductStatusSchema (draft, active, archived, out_of_stock, discontinued), ProductCategorySchema (fashion, textiles, beauty, skincare, haircare, fragrance, jewelry, footwear, eyewear, accessories, home_decor, luggage, personal_care, detergent), MarketSchema (GH, NG, KE, ZA, UK, US, EU, CA, AU, GLOBAL), PriceSchema, ProductVariantSchema, CreateProductRequestSchema, UpdateProductRequestSchema, ProductSearchRequestSchema, ProductResponseSchema.
• order-schemas.ts — OrderStatusSchema (pending, confirmed, processing, shipped, delivered, cancelled, refunded, return_requested, returned), ShippingAddressSchema, OrderLineSchema, CreateOrderRequestSchema, UpdateOrderStatusRequestSchema, OrderResponseSchema.
• customer-schemas.ts — CustomerSegmentSchema (vip, premium, regular, new, diaspora, wholesale, corporate), LoyaltyTierSchema (bronze, silver, gold, platinum, diamond), RegisterCustomerRequestSchema, UpdateCustomerRequestSchema, CustomerPreferencesSchema, CustomerResponseSchema.
• manufacturing-schemas.ts — ManufacturingOrderStatusSchema (planned, in_progress, quality_check, completed, on_hold, cancelled), BusinessUnitSchema (eighteen values matching freya_business_unit), CreateManufacturingOrderRequestSchema, QualityInspectionRequestSchema, ManufacturingOrderResponseSchema.

REST Order State Machine (order-routes.ts)#

The customer-order handler enforces a strict status state machine for orders flowing through the REST API. This is the public-API order lifecycle, separate from the ecommerce DTC fulfillment machine and the factory-floor machine.

OrderStatus is PLACED, CONFIRMED, SHIPPED, DELIVERED, RETURNED, CANCELLED. Legal transitions:

handleProcessReturn rejects returns on any order not in DELIVERED. handleProcessRefund rejects a refund amount exceeding the order total. computeOrderTotals applies 15% tax and free domestic shipping for Ghana/Nigeria orders ≥ GHS 500 (otherwise GHS 30 domestic, GHS 150 international).

GraphQL API (graphql-schema.ts)#

FREYA_GRAPHQL_TYPEDEFS is a schema-first SDL definition. It mirrors the REST surface but adds real-time subscription and connection-based pagination.

Enums: BusinessUnit (eighteen values), ProductStatus (eight values matching freya_product_status), Season, Market, OrderStatus, LoyaltyTier. Object types include Product, ProductVariant, Collection, Brand, InventoryLevel, Customer, Order, OrderLine, TrendSignal, Relay-style connection/edge types, and PageInfo. Queries cover product/collection/brand lookup and listing, inventory levels, customer lookup, order lookup, and trending signals. Mutations cover createProduct, updateProductStatus, createOrder, updateOrderStatus, cancelOrder, registerCustomer, updateCustomerProfile, addLoyaltyPoints, cart operations (addToCart, removeFromCart, updateCartQuantity), and inventory operations (reserveInventory, releaseInventory). Subscriptions are inventoryUpdated, orderStatusChanged, trendSignalReceived, and storeKpiUpdated. encodeCursor/decodeCursor implement base64 offset cursors.

gRPC Services (grpc-services.ts)#

gRPC is used for the five internal high-throughput service calls that need lower overhead than HTTP/REST. FREYA_GRPC_PACKAGE is freya.internal, version v1. The five services are defined as GrpcServiceDefinition records:

• InventoryService — CheckInventory, BatchCheckInventory, ReserveInventory (TTL-based, idempotent), ReleaseReservation, StreamInventoryUpdates (server streaming).
• ManufacturingService — GetManufacturingOrder, ListManufacturingOrders, UpdateManufacturingStatus, StreamProductionEvents (server streaming).
• QualityService — EvaluateQualityGate (AQL-based gate evaluation).
• PricingService — GetPricing (final price with promotions, loyalty, market pricing).
• CustomerService — GetCustomerProfile, AdjustLoyaltyPoints (transactional earn/redeem).

generateProtoStub scaffolds a proto3 service definition from each GrpcServiceDefinition. ReleaseReservationRequest.reason is one of order_confirmed, order_cancelled, expired. QualityGateResponse.nextAction is one of release, rework, scrap, retest.

WebSocket API (websocket.ts)#

The WebSocket server at /ws carries three categories of real-time message: inventory updates for live stock counts, auction bidding for limited-edition drops, and collaborative design sessions in the studio app.

WsMessageType enumerates subscribe, unsubscribe, inventory_update, order_status, bid_placed, auction_ended, price_alert, collaboration_join, collaboration_cursor, collaboration_change, store_kpi, trend_signal, error, ping, pong. WsChannel is one of inventory, orders, auctions, collaboration, store_kpis, trends. Typed payloads exist for each message type: InventoryUpdatePayload, OrderStatusPayload, BidPayload, AuctionEndedPayload, CollaborationCursorPayload, CollaborationChangePayload, StoreKpiPayload, TrendSignalPayload. WS_CONFIG sets a 30-second ping interval, 10-second pong timeout, 20 subscriptions per connection, 64 KB max message size, and a 100-message backpressure queue. buildReservationResult produces an InventoryReservationResult whose failureReason is one of insufficient_stock, already_reserved, product_discontinued.

Domain Events (event-bus.ts)#

Freya domain events follow the CloudEvents 1.0 envelope. The DomainEvent<T> type carries: specversion, id, source, type, datacontenttype, optional dataschema, subject, time, data, optional correlationId, businessUnit, market. Events are published to Kafka topics and consumed by subscribing services inside and outside the Freya domain.

FreyaEventType enumerates the full event vocabulary, organized by family:

• Product — freya.product.created, freya.product.updated, freya.product.status_changed, freya.product.discontinued.
• Inventory — freya.inventory.stocked, freya.inventory.reserved, freya.inventory.released, freya.inventory.depleted, freya.inventory.reorder_triggered.
• Orders — freya.order.placed, freya.order.confirmed, freya.order.processing, freya.order.shipped, freya.order.delivered, freya.order.cancelled, freya.order.refunded, freya.order.return_requested.
• Manufacturing — freya.manufacturing.order_created, freya.manufacturing.started, freya.manufacturing.batch_completed, freya.manufacturing.quality_passed, freya.manufacturing.quality_failed, freya.manufacturing.completed, freya.manufacturing.cancelled.
• Quality — freya.quality.inspection_scheduled, freya.quality.inspection_completed, freya.quality.corrective_action_required.
• Customers — freya.customer.registered, freya.customer.segment_changed, freya.customer.loyalty_tier_changed, freya.customer.vip_granted, freya.customer.points_earned, freya.customer.points_redeemed.
• Trends — freya.trend.signal_detected, freya.trend.reached_mainstream, freya.trend.declining.
• Collections — freya.collection.created, freya.collection.launched, freya.collection.sold_out.
• Academy — freya.academy.student_enrolled, freya.academy.student_graduated, freya.academy.certification_issued.
• Formulations — freya.formulation.approved, freya.formulation.rejected, freya.formulation.batch_released.
• Retail — freya.retail.store_opened, freya.retail.daily_close, freya.retail.kpi_updated.
• Payments — freya.payment.succeeded, freya.payment.failed, freya.payment.refunded.

FREYA_EVENT_TOPICS maps event types to six Kafka topics: freya.orders, freya.inventory, freya.production, freya.quality, freya.customers, freya.trends; resolveEventTopic falls back to freya.misc for unmapped types. FREYA_DLQ_TOPIC is freya.dlq.

Defined payload interfaces capture the data that crosses service boundaries: ProductCreatedEventData, OrderPlacedEventData (includes orderId, orderNumber, customerId, market, channel, currency, totalAmount, lineCount, lines, paymentReference), OrderShippedEventData, InventoryReservedEventData (includes reservationToken, expiresAt), InventoryDepletedEventData, ManufacturingBatchCompletedEventData, QualityInspectionCompletedEventData (result of passed/failed/conditional_pass/pending_retest, nextAction of release/rework/scrap/retest), CustomerLoyaltyTierChangedEventData, TrendSignalDetectedEventData, FormulationApprovedEventData.

buildFreyaEventBusConfig reads FREYA_KAFKA_BROKERS/KAFKA_BROKERS (default localhost:9092), defaults producer acks to -1 (all replicas — important for orders and payments), and uses snappy compression. FREYA_CONSUMER_CONFIGS defines consumer groups per service role: freya-ecommerce consumes freya.orders/freya.inventory/freya.customers; freya-manufacturing consumes freya.orders/freya.production/freya.quality; freya-retail consumes freya.inventory/freya.customers/freya.trends; freya-trend-worker consumes freya.trends.

Capability Libraries#

Each capability library is deterministic, domain-specific business logic — not generic CRUD. Libraries depend on @freya/core for shared types and never on each other. State machines in every library are enforced with explicit transition tables that throw on illegal transitions.

@freya/fashion — Apparel Design Pipeline#

Source modules: design-pipeline.ts, collection-planner.ts, size-grading.ts, trend-forecasting.ts, production-scheduler.ts, african-print-library.ts.

Design pipeline state machine (DesignPipeline). Every style moves through a controlled set of stages, each of which has defined entry requirements. DesignStage is concept, mood_board, sketch, pattern, prototype, sample, production, discontinued. transitionTo throws on any unlisted transition and appends a timestamped entry to history.

ApprovalStatus (used by sketches and design approvals) is pending, approved, rejected, revision_required.

Other classes in this library: ConceptBoardManager, SketchManager (versioned sketches), PatternMaker (default 1.5 cm seam allowance, marker utilization estimation), PrototypingTracker (capped at MAX_REVISION_CYCLES = 5), TechPackGenerator (emits a TechPack with a six-row XS–XXL measurements table, BOM, construction details, and labeling specs; validate checks required fields), DesignApprovalWorkflow (multi-stakeholder sign-off — required roles designer, merchandiser, qa, director; overall status derived from all sign-offs), DesignAssetManager (AssetType of sketch/photo/3d/flat), and DesignCostEstimator (30% overhead rate, SMV-based labor costing).

Collection planning. CollectionStatus is concept, design, production, launched, archived. SEASON_CALENDAR defines per-season show months, delivery months, and milestone offsets for SS, FW, Resort, PreFall, and Capsule. CapsuleCollectionBuilder enforces MAX_STYLES = 12. CollectionBudgetPlanner applies a 2.2× wholesale markup and 2.4× retail-on-wholesale markup, and enforces a minimum 60% gross margin (marginCompliant). CollectionPresentationBuilder requires 6–12 looks.

@freya/textiles — Dyeing, Printing, Finishing#

Source modules: dye-management.ts, print-operations.ts, finishing-operations.ts, vertical-integration.ts.

dye-management.ts models dye recipes (DyeClass of reactive, acid, disperse, vat, direct), a dye-process state machine (DyePhase of loading, heating, dyeing, rinsing, unloading), color matching against Lab color values, dye-consistency SPC control limits, water-usage optimization, chemical inventory with HazardClass 1–9, African natural-dye formulation (NaturalDyeFormulator), and effluent compliance monitoring (EffluentParameter of COD, BOD, pH, color_ADMI, TDS).

print-operations.ts models a wax print state machine, digital/screen/block printing, print design preparation, and print costing. finishing-operations.ts models finishing processes (sanforizing, calendering, mercerizing, softening, anti-shrink), DWR water repellency (DWRChemistry from C8_PFAS through C0_bio), wrinkle resistance, a fabric-testing lab, and a finishing quality gate.

vertical-integration.ts models make-vs-buy analysis, spinning/weaving/knitting operations, capacity planning, textile cost modeling, waste reduction, Kente weave preservation (KENTE_COLOR_MEANINGS), and a sustainability scorecard.

@freya/beauty — Skincare, Cosmetics, Fragrance, Haircare#

Source modules: skincare-formulation.ts, cosmetics-development.ts, fragrance-development.ts, haircare-development.ts, personal-care-detergent.ts, stability-regulatory.ts.

skincare-formulation.ts models a formulation lifecycle, shea-butter and cocoa-butter grade management (SheaButterGrade, CocoaButterType), an African botanical library, a formulation incompatibility checker (IncompatibilitySeverity of mild/moderate/severe), emulsion HLB calculation (EmulsionType W/O/O/W), preservative-system design, an SPF calculator over a UV-filter library, and batch costing.

cosmetics-development.ts models a cosmetics development pipeline with STAGE_DELIVERABLES, shade-range design (Undertone of cool/neutral/warm/olive), lip and eye product formulation, packaging design, product naming, and launch planning.

fragrance-development.ts models the fragrance pyramid (FragranceNoteClass top/heart/base with evaporation profiles), an African scents library, perfume concentration specs (PerfumeConcentration), and fragrance blending. haircare-development.ts and personal-care-detergent.ts cover Afro-textured haircare and personal-care/detergent formulation respectively. stability-regulatory.ts covers stability testing protocols and regulatory submission logic across Ghana FDA, NAFDAC, EU SCCS, and US FDA.

@freya/ecommerce — Catalog, Cart, Checkout, Diaspora DTC#

Source modules: catalog-inventory.ts, social-personalization.ts, diaspora-commerce.ts.

Ecommerce order state machine (catalog-inventory.ts). This is the DTC fulfillment lifecycle, separate from the REST API's customer-order machine. OrderStatus has fourteen values: placed, payment_confirmed, processing, picked, packed, shipped, out_for_delivery, delivered, return_requested, return_approved, returned, refund_processing, refunded, cancelled.

Other enums and classes in this module: PaymentGateway (paystack, flutterwave, stripe), PaymentMethod (includes mtn_momo, vodafone_cash, bank_card, bank_transfer, ussd, card, apple_pay, google_pay), ShippingCarrier (DHL, FedEx, UPS), CheckoutStep (cart_review, address, shipping, payment, confirmation). Classes include ProductCatalogService, CartManager, CheckoutOrchestrator, PaymentProcessor, OrderManagementService, InventoryService (over a fixed WAREHOUSES set), WishlistService, ReviewService, and SearchEngine.

diaspora-commerce.ts models diaspora markets (DiasporaCountry), multi-currency management, international shipping calculation, customs document generation, diaspora pricing strategy, localized content (Language en/fr), and international returns. social-personalization.ts models social commerce, a product recommendation engine, customer segmentation (BehavioralSegment of vip, loyal, at_risk, new, dormant, one_time), email-marketing automation (EmailFlowType), a subscription-box manager (SubscriptionTier of essentials/luxe/heritage), abandoned-cart recovery, a customer lifetime-value model, a loyalty-program engine (LoyaltyTierName from bronze to obsidian), and virtual try-on integration (TryOnProductType).

@freya/manufacturing — Production Execution#

Source modules: cosmetics-manufacturing.ts, textile-manufacturing.ts, assembly-manufacturing.ts, cross-manufacturing.ts.

cosmetics-manufacturing.ts models a cosmetics manufacturing stage machine, clean-room management (CleanRoomISO ISO7/ISO8), BatchScale of lab, pilot, commercial, mixing-process control, filling lines (FillingLineType of tube/jar/pump_bottle), batch records, in-process quality testing, and a detergent manufacturing line (DetergentProductionMethod of spray_drying, agglomeration, liquid_mixing).

cross-manufacturing.ts models machine utilization (OEE — OEELossCategory), production cost analysis, lean manufacturing (MudaType waste categories), capacity planning, equipment maintenance (MaintenanceType of preventive/predictive/corrective), manufacturing compliance (ComplianceStandard of ISO9001, ISO22716, ISO14001, ISO45001, OHSAS18001), waste management, and energy management (EnergySource of grid/solar/generator).

textile-manufacturing.ts models textile production lines (ProductionLineStatus of idle, setup, running, maintenance, breakdown), loom scheduling (LoomType of shuttle/rapier/air_jet), dye-house planning, textile waste tracking, and maintenance scheduling. assembly-manufacturing.ts models per-product-type assembly stage machines for watches, jewelry, eyewear, footwear, and leather goods, plus a component inventory manager.

@freya/retail — Store Operations and Clienteling#

Source modules: store-operations.ts, customer-experience.ts, portfolio-management.ts.

store-operations.ts models a fixed StoreId set (accra_osu, accra_mall, kumasi_garden_city, lagos_victoria_island), opening/closing checklists (ChecklistStage, ChecklistItemStatus of pending/in_progress/ completed/issue), visual merchandising by StoreZone, store inventory management (StockCategory of fashion/beauty/jewelry), sales analytics, staff scheduling and performance tracking, POS integration (PaymentMethod of cash/card/MoMo), customer-traffic analysis, and store maintenance (MaintenanceUrgency of routine/urgent/emergency).

customer-experience.ts models in-store personalization, a clienteling tool, VIP experience management (VIPService), in-store try-on tracking (TryOnOutcome of purchased/not_purchased/size_exchange), and customer feedback (NPSClassification of promoter/passive/detractor).

@freya/brand — Brand Architecture and Storytelling#

Source modules: brand-architecture.ts, heritage-storytelling.ts, digital-presence.ts.

brand-architecture.ts models brand relationship structures (BrandRelationshipType of master/endorsed/sub), a brand positioning map, brand-guideline management, brand-equity measurement, sub-brand creation, brand-consistency auditing, brand-extension evaluation, and co-branding opportunity identification.

heritage-storytelling.ts models a heritage story engine, artisan story capture, a cultural calendar manager, a provenance story builder (NarrativeComponent, LuxuryPillar), and luxury positioning strategy. digital-presence.ts models social-media monitoring (SocialChannel), brand-sentiment analysis, influencer management (InfluencerTier of nano/micro/macro/mega), PR coverage tracking, diaspora brand perception (DiasporaMarketKey), content-calendar planning, UGC curation, and competitor brand tracking.

@freya/academy — Curriculum and Certification#

Source modules: curriculum.ts, curriculum-internals.ts, course-management (academy-operations.ts), student-management.ts.

CourseLevel is certificate, diploma, degree. BloomsTaxonomyLevel models the cognitive taxonomy used for learning outcome design. Classes include CurriculumDesigner, CourseManager, ModuleBuilder, and three specialized curriculum builders: AfricanFashionCurriculum, SustainableFashionCurriculum, BusinessFashionCurriculum. student-management.ts manages student records and progression.

@freya/jewelry — Ethical Gold Jewelry#

Source modules: jewelry-production.ts, gold-management.ts, craft-preservation.ts. This library focuses heavily on provenance: it covers gold sourcing and management with full chain-of-custody tracking, jewelry production processes, hallmarking, and craft preservation with artisan heritage records.

@freya/market-intel — Trend and Competitive Intelligence#

Source modules: trend-monitoring.ts, competitive-intelligence.ts, market-research.ts. Models trend monitoring (ingesting runway, social, and sales-data signals), competitive intelligence (CompetitorMove), and market research. Outputs feed into @freya/financials and @freya/brand.

@freya/financials — Unit Economics and Investment#

Source modules: unit-economics.ts, financial-planning.ts, startup-investment.ts. FreyaBusinessUnit enumerates the financed business units. InvestmentScale is pilot, standard, flagship. Classes include StartupCostModeler, PhaseInvestmentPlanner, FundingStructureOptimizer, EquipmentCapexPlanner, FacilityInvestmentModeler (FacilityType, Location), and ROIProjector. DepreciationMethod is straight_line or declining_balance.

@freya/connectors — Cross-Domain Integration#

Source modules: asase-connectors.ts, brigid-connectors.ts, cybele-connectors.ts, saraswati-connectors.ts, maat-connectors.ts. This library is the sole point where Freya's shapes are translated to other domains' contracts, keeping all cross-domain coupling in one place.

• Asase (agriculture, task 57.14.1) — SheaButterSupplyChain, CocoaButterProcurement, NaturalIngredientTraceability, CottonSupplyChain, IngredientQualitySync, FairTradeCertification.
• Brigid (manufacturing automation, 57.14.2) — TextileAutomation, CosmeticsPackagingAutomation, QualityVisionSystem, SmartPackaging, PredictiveMaintenanceSync.
• Cybele (construction, 57.14.3) — FlagshipStoreDesign, RetailSpacePlanning, FactoryConstruction, InteriorTextileSupply.
• Saraswati (logistics, 57.14.4) — EcommerceLogistics, IoTRetailSensors, SmartWarehouse, EVDeliveryFleet.
• Maat (strategic intelligence, 57.14.5) — FreyaDashboardSync, BrandAnalyticsFeed, FinancialConsolidation, MarketIntelligenceFeed.

@freya/sota — State-of-the-Art Enhancements#

Source modules: ai-design.ts, ai-analytics.ts, computer-vision.ts, nlp.ts, blockchain-auth.ts, virtual-tryon.ts. This library houses the Phase 57 state-of-the-art layer: AI-assisted design and generative collection ideation, AI analytics, computer-vision quality control, NLP, blockchain-based authenticity verification, and virtual try-on. Each is delivered as an opt-in enrichment over the deterministic capability libraries — the business logic does not depend on them and remains testable in isolation.

Single-Module Business-Unit Libraries#

Eleven libraries each ship a single src/index.ts module, owning their business-unit logic: @freya/watches, @freya/perfumes, @freya/bridal-events, @freya/hair-care, @freya/home-decor, @freya/footwear, @freya/eyewear, @freya/luggage-leather, @freya/personal-care, @freya/cleaning-products, @freya/textile-finishing. (@freya/textile-finishing's index.ts models textile production lines, loom scheduling, dye-house planning, waste tracking, energy monitoring, and maintenance scheduling.)

Applications#

Five applications under apps/freya/* compose user workflows over the capability libraries. Each ships a thin set of view/orchestration modules. Applications depend on capability libraries but not on each other; cross-app coordination goes through the API service and the event bus.

• apps/freya/api — documented in full in the API Surface section above.
• apps/freya/studio — design and brand studio. Source modules: trend-board.ts, collection-dashboard.ts, design-workspace.ts, design-approval-board.ts, tech-pack-editor.ts, textile-library.ts, color-palette-studio.ts.
• apps/freya/shop — DTC storefront. Source modules: product-listing.ts, product-detail.ts, shopping-cart.ts, checkout-flow.ts, customer-account.ts, subscription-box.ts, virtual-tryon.ts.
• apps/freya/retail — retail-operations app. Source modules: store-dashboard.ts, clienteling-app.ts, inventory-lookup.ts, staff-performance.ts, visual-merchandising.ts.
• apps/freya/manufacturing — factory-floor app. Source modules: order-management.ts, production-dashboard.ts, batch-record-manager.ts, quality-inspection.ts, equipment-dashboard.ts, waste-reporting.ts.

Manufacturing-App Order State Machine (order-management.ts)#

The factory-floor app enforces its own strict linear state machine over manufacturing orders. This is separate from the supply-chain OrderStatus in @freya/core and the ecommerce DTC machine in @freya/ecommerce.

OrderStatus is DRAFT, SCHEDULED, IN_PROGRESS, QC, COMPLETE, SHIPPED. OrderPriority is RUSH, STANDARD, DEFERRED.

assertStatus throws if an order is not in the expected status, preventing out-of-sequence transitions. A RUSH priority applies the RUSH_PREMIUM_MULTIPLIER of 2.0 to the order's total cost.

Configuration and Environment Inputs#

The following environment variables control all infrastructure connections. Every variable has a fallback so the system runs locally without extra configuration.

Requirements and Invariants#

These six requirements are enforced by code or mandated by features.md for any change touching the relevant data. They are not optional — violating any of them can result in regulatory exposure, data loss, or financial errors.

1. Provenance and certification evidence. Material, Supplier, Artisan, and freya_materials records retain source country/region and certifications. Jewelry and gold provenance records retain full source and certification evidence permanently. freya_quality_inspections retains certificate_url, defect detail, and corrective actions.

2. Idempotent commerce. Inventory reservation is TTL-based and idempotent (gRPC ReserveInventory accepts a reservationToken for idempotent checks; InventoryReservedEventData carries a reservationToken). Order and inventory updates must not double-create or double-decrement on a retried webhook or sync event. Cart and inventory state is held in Redis with distributed locks (freya:lock:inv:{variantId}, freya:lock:checkout:{orderId}).

3. Beauty audit trails and formulation versioning. Formulation carries a version; freya_formulations uses a (code, version) unique pair so a formulation change creates a new version rather than mutating the prior one. Stability and regulatory records are append-only evidence. Beauty product efficacy_claims are stored with their evidence type and study reference.

4. Privacy and role-based access. freya_customers carries marketing_consent, data_processing_consent, and consents_updated_at. freya_virtual_tryon_sessions.body_photo_url is ephemeral and deleted after the session. The API enforces UserRole-based RBAC with :own ownership checks (middleware.ts).

5. State-machine integrity. Order and design state machines reject illegal transitions: the REST customer-order machine, the ecommerce DTC fulfillment machine, the manufacturing-app OrderManagement machine, the fashion DesignPipeline, and the various per-product-type assembly machines all use explicit transition tables and throw on violation.

6. Quality gating. A failed AQL inspection (evaluateQualityResult returning fail) blocks order release; QualityGateResponse.nextAction drives the release/rework/scrap/retest decision.

Domain Boundaries#

Freya owns luxury-goods business operations and product supply. It does not own personal consumer styling, virtual try-on as a consumer feature, or individual recommendation decisions — those belong to Aglaea. Freya publishes products, textiles, sizing, retail inventory, brand campaigns, and provenance records; Aglaea consumes them for consumer recommendation and shopping experiences. Stores, factories, and real-estate facilities belong to Cybele; factory-automation machinery belongs to Brigid; advanced technology-product manufacturing belongs to Saraswati. The @freya/connectors library is the sole integration boundary to Asase, Brigid, Cybele, Saraswati, and Maat — no capability library imports from those domains directly.

Verification Expectations#

Changes run package tests for affected libraries and apps (Vitest — every library has a vitest.config.ts and a *.spec.ts suite). Commerce, payment, inventory, manufacturing, and customer-data changes additionally require contract and persistence regression coverage. Tests must assert specific computed values against known-correct answers; asserting only shape or truthiness is not sufficient for the domain's financial, quality, and formulation logic.