Aglaea Domain — Technical Specifications

Aglaea — AI-Powered Fashion, Beauty, and Personal Style Platform

This document specifies the implemented contracts of the Aglaea domain: the foundation type system, domain entities, enumerations, the REST API surface, the domain event system, persistence schemas, and configuration. Every type, enum value, endpoint, and event below is drawn directly from the source under libs/aglaea/.

Aglaea is a pure library domain — it has no apps/aglaea/ or services/aglaea/. It is implemented as 93 libraries under libs/aglaea/.

For a plain-English description of what each library does, see features.md. For how they are layered and wired together, see architecture.md. This document is the definitive contract reference — the source of truth for type shapes, API paths, event strings, and schema field names.

Table of Contents#

1. Foundation Type System (@aglaea/core)
2. Core Domain Constants (@aglaea/core)
3. Configuration (@aglaea/core)
4. AI Orchestration Types (@aglaea/ai-orchestrator)
5. REST API Surface (@aglaea/api-services)
6. Domain Event System (@aglaea/events)
7. API-Services Event Catalog (@aglaea/api-services)
8. Persistence Schemas (@aglaea/database)
9. SDK Surface (@aglaea/sdk)
10. Technology Stack

1. Foundation Type System (@aglaea/core)#

@aglaea/core (libs/aglaea/core/src/types.ts) is the foundation type system for the domain. Every composite type is defined as a Zod schema with an inferred TypeScript type (z.infer), which means all types are validated at runtime wherever they cross a module boundary. The package depends only on zod, so it can be safely imported by any library in the domain without introducing additional dependency weight.

The index.ts barrel re-exports types, constants, validation, errors, color-science, body-analysis, skin-analysis, hair-analysis, fashion-taxonomy, style-profiling, recommendation-engine, occasion-context, trend-analysis, fabric-intelligence, fragrance-profiling, logging, config, feature-flags, rate-limiting, and caching.

1.1 Branded ID Types#

Aglaea uses five nominal (branded) string types to prevent accidental mixing of IDs across different entity types at compile time. Each is validated against a UUID v4 pattern by its corresponding Zod schema.

Each schema enforces UUID_V4_PATTERN (^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$) and returns a typed z.ZodType for the branded type.

1.2 Color Science Types#

Colors are stored in multiple spaces simultaneously because different spaces serve different purposes. RGB and Pantone are for display and production output; HSL is for human-readable hue/saturation/lightness reasoning; LAB is the canonical internal space for color-distance calculations and harmony scoring, because LAB is perceptually uniform — equal numeric deltas correspond to equal perceived differences.

The following enums capture color-system concepts used throughout the recommendation engine:

ColorHarmonySchema (ColorHarmony) — color-wheel relationship enum, used to score and label the palette harmony of an outfit recommendation: Complementary, Analogous, Triadic, SplitComplementary, Tetradic, Monochromatic.

SeasonalSubtypeSchema (SeasonalSubtype) — the 12-season color analysis system, which refines the four parent seasons along warmth, value, and chroma axes: LightSpring, WarmSpring, ClearSpring, LightSummer, SoftSummer, CoolSummer, SoftAutumn, WarmAutumn, DeepAutumn, DeepWinter, CoolWinter, ClearWinter.

SeasonSchema (Season) — parent season grouping: Spring, Summer, Autumn, Winter.

SkinUndertoneSchema (SkinUndertone) — Cool, Warm, Neutral, Olive.

ColorTemperatureSchema (ColorTemperature) — Cool, Warm, Neutral.

SeasonalColorPaletteSchema (SeasonalColorPalette) is the primary output of color analysis and the primary input to outfit and accessory recommendations. Its fields are:

1.3 Body Measurement Types#

Body measurements are stored in centimeters. All ten fields are constrained to physiologically plausible maximums (e.g., bust ≤ 300 cm) so that measurement errors from photo analysis are caught at the schema boundary rather than producing absurd downstream recommendations.

BodyMeasurementsSchema (BodyMeasurements) — all values in centimeters, all positive:

BodyShapeSchema (BodyShape) — eight values: Hourglass, Pear, Apple, Rectangle, InvertedTriangle, Oval, Diamond, Athletic. Each enum entry carries a doc comment describing the measurement relationship that defines it.

BodyProportionsSchema (BodyProportions) holds the ratios calculated from raw measurements. These ratios — not the body shape label alone — determine which visual-balance corrections are most appropriate, so two users with the same body shape label but different ratios receive different silhouette guidance.

SizeRegionSchema (SizeRegion) — US, UK, EU, JP, AU, KR.

ClothingSizeSchema (ClothingSize): region (SizeRegion), category (string), sizeValue (string), optional alphaSize, optional numericSize, optional modifier (Petite | Regular | Tall | Plus).

1.4 Skin Analysis Types#

The skin analysis type system models both the categorical classification of skin (type, tone, concerns) and the quantitative scoring of individual biomarkers. The separation matters: categorical classifications drive routine logic (sensitive skin gets different formulations than oily skin), while biomarker scores enable longitudinal tracking (a user can see their hydration score improving over time).

SkinTypeSchema (SkinType) — Normal, Dry, Oily, Combination, Sensitive.

SkinConcernSchema (SkinConcern) — twelve concerns, each of which maps to specific recommended active ingredients in SKIN_CONCERN_INGREDIENTS: Acne, Wrinkles, DarkSpots, LargePores, Dullness, Redness, Dehydration, Hyperpigmentation, SunDamage, Texture, UndereyeCircles, Sagging.

FitzpatrickScaleSchema (FitzpatrickScale) — TypeI through TypeVI, the Fitzpatrick UV-response phototype scale. Used to determine recommended SPF and burn-time guidance from FITZPATRICK_UV_DATA.

SensitivityLevelSchema (SensitivityLevel) — Mild, Moderate, Severe. Used by IngredientSensitivity to record the severity of a known reaction to a specific ingredient.

SkinAnalysisResultSchema (SkinAnalysisResult) is the output type of a skin analysis run. It carries both the categorical classifications and eleven quantitative biomarker scores, each on a 0–100 scale. Note the direction of scoring: positive-attribute scores (hydration, firmness, clarity) read 100 = best; negative-attribute scores (oiliness, redness) read 0 = none, 100 = severe.

Fields: id (AnalysisId), analyzedAt (datetime), skinType (SkinType), concerns (SkinConcern[]), plus twelve quantitative scores each constrained 0–100: hydration, oiliness, elasticity, pigmentation, texture, wrinkleDepth, poreSize, redness, firmness, clarity, radiance.

SkinToneSchema (SkinTone) — fitzpatrickType (FitzpatrickScale), undertone (SkinUndertone), labColor (LAB), optional hexApproximation.

IngredientSensitivitySchema (IngredientSensitivity) — ingredientName (string), sensitivityLevel (SensitivityLevel), optional notes.

1.5 Hair Analysis Types#

Hair analysis types model the physical properties of hair that determine product and routine compatibility. The Andre Walker curl-pattern system (1A–4C) is the industry standard for curl classification, and porosity is the single most important determinant of whether a product will moisturize or weigh down the hair.

HairTypeSchema (HairType) — the Andre Walker curl-pattern system: Straight1A, Straight1B, Straight1C, Wavy2A, Wavy2B, Wavy2C, Curly3A, Curly3B, Curly3C, Coily4A, Coily4B, Coily4C.

HairDensitySchema (HairDensity) — Fine, Medium, Thick (strand diameter classification).

HairPorositySchema (HairPorosity) — Low, Medium, High. Porosity determines the balance between moisture-rich and protein-rich formulations a hair type needs.

HairConditionSchema (HairCondition) — Healthy, SlightlyDamaged, Damaged, SeverelyDamaged.

HairColorSchema (HairColor) — naturalColor (LAB), currentColor (LAB), isColorTreated (boolean), grayPercentage (0–100), optional naturalLevel (1–10), optional currentLevel (1–10).

HairAnalysisResultSchema (HairAnalysisResult) is the output type of a hair analysis run: id (AnalysisId), analyzedAt, hairType, density, porosity, condition, color (HairColor), plus four 0–100 scores: scalpHealth, moisture, elasticity, shine.

1.6 Fashion Taxonomy Types#

Fashion taxonomy provides the controlled vocabulary that every garment classification and recommendation module uses to describe clothes. Without a shared taxonomy, garment categories and style terms would be ad-hoc strings with no consistent meaning across libraries.

GarmentCategorySchema (GarmentCategory) — twelve top-level categories: Tops, Bottoms, Dresses, Outerwear, Swimwear, Activewear, Sleepwear, Underwear, Accessories, Shoes, Bags, Jewelry.

GarmentSubcategorySchema (GarmentSubcategory) — a flat enum of sub-categories grouped by parent category, including (among others) TShirt/ButtonDown/Blouse/Sweater (Tops), Jeans/Trousers/Skirt (Bottoms), MiniDress/Gown/Jumpsuit (Dresses), Blazer/Coat/Trench (Outerwear), Bikini/OnePiece (Swimwear), Sneakers/Heels/Boots (Shoes), Tote/Crossbody/Clutch (Bags), and Necklace/Ring/Earrings (Jewelry).

FabricTypeSchema (FabricType) — twenty fabric types: Cotton, Silk, Wool, Linen, Polyester, Nylon, Rayon, Cashmere, Denim, Leather, Suede, Satin, Chiffon, Velvet, Tweed, Jersey, Lycra, Organza, Tulle, Lace.

FabricWeightSchema (FabricWeight) — Sheer, Lightweight, Midweight, Heavyweight.

PatternSchema (Pattern) — fourteen patterns: Solid, Stripes, Plaid, Floral, PolkaDots, Geometric, Abstract, Paisley, Houndstooth, Camo, AnimalPrint, Chevron, Gingham, TieDye.

StyleAestheticSchema (StyleAesthetic) — fifteen aesthetics that classify the dominant style identity of a garment or a user's preferences: Classic, Minimalist, Bohemian, Streetwear, Preppy, Romantic, Edgy, Sporty, Glamorous, Vintage, AvantGarde, Scandinavian, Coastal, Western, Gothic.

GarmentConditionSchema (GarmentCondition) — New, Excellent, Good, Fair, Poor.

SeasonSuitabilitySchema (SeasonSuitability) — four boolean flags: spring, summer, autumn, winter.

WardrobeItemSchema (WardrobeItem) is the full wardrobe item entity. It carries all attributes needed to generate outfit recommendations (category, colors, fabric, formality, occasions, seasons) alongside administrative fields for wardrobe management (purchase price, wear count, condition, storage).

1.7 Occasion and Context Types#

Occasion and context types capture the circumstances for which an outfit is being recommended. The outfit engine uses all of these fields together: occasion determines formality bounds, dress code refines them, weather context gates fabric and layering choices, and time of day affects color and formality appropriateness.

OccasionTypeSchema (OccasionType) — fifteen occasions: Casual, Business, BusinessCasual, Formal, BlackTie, Cocktail, DateNight, Wedding, Interview, Outdoor, Beach, Festival, Travel, Gym, Lounge.

WeatherContextSchema (WeatherContext) — temperatureMin / temperatureMax (Celsius, −60 to 60), humidity (0–100), precipitation (None | Light Rain | Heavy Rain | Snow | Sleet | Drizzle), uvIndex (0–15), optional windSpeed (km/h, nonnegative), optional description.

DressCodeSchema (DressCode) — refines the formality band within an occasion: WhiteTie, BlackTie, Cocktail, BusinessFormal, BusinessCasual, SmartCasual, Casual, Athleisure, Resort.

TimeOfDaySchema (TimeOfDay) — EarlyMorning, Morning, Afternoon, Evening, Night.

OutfitContextSchema (OutfitContext) — occasion (OccasionType), optional dressCode (DressCode), weather (WeatherContext), optional location, optional setting (Indoor | Outdoor | Both), timeOfDay (TimeOfDay), optional durationHours (positive), optional culturalContext, specialRequirements (string[], default []).

1.8 Recommendation Types#

The recommendation types capture both the output of the outfit engine and the multi-dimensional confidence scores that explain why an outfit was chosen. Exposing confidence as seven distinct scores rather than one overall number lets the user understand the tradeoffs — an outfit may score high on color harmony but low on occasion fit.

RecommendationConfidenceSchema (RecommendationConfidence) — seven scores each constrained 0–1: overall, styleMatch, colorHarmony, occasionFit, trendAlignment, bodyFlattery, weatherAppropriateness.

StylingNoteSchema (StylingNote) — category (Fit | Layering | Accessories | Color | Proportions | Shoes | Hair | Makeup | General), note (string), importance (Essential | Recommended | Optional).

OutfitRecommendationSchema (OutfitRecommendation) is the primary output type of the outfit engine. It includes the wardrobe item IDs that compose the outfit, the full multi-dimensional confidence score, optional swap suggestions for any item in the outfit, and a human-readable rationale explaining the recommendation.

ShoppingRecommendationSchema (ShoppingRecommendation) — id, profileId, productName, optional brand, category (GarmentCategory), subcategory (GarmentSubcategory), matchReasons (string[], min 1), priceMin / priceMax (nonnegative), currency (length 3), priorityScore (0–1), confidence (RecommendationConfidence), pairsWith (WardrobeItemId[], default []), styleAesthetic, optional suggestedColor (LAB), optional suggestedFabric (FabricType), optional productUrl, optional imageUrl, generatedAt.

1.9 Trend Analysis Types#

Trend types model the lifecycle and origin of fashion trends, enabling the forecasting engine to distinguish between a micro-trend at emergence, a macro-trend at peak, and a classic that has outlasted its original cycle.

TrendStatusSchema (TrendStatus) — Emerging, Growing, Peak, Declining, Classic, Revival.

TrendCategorySchema (TrendCategory) — Color, Silhouette, Pattern, Fabric, Styling, Accessory.

TrendOriginSchema (TrendOrigin) — Runway, Street, Social, Celebrity, Editorial, Subculture.

FashionTrendSchema (FashionTrend) — name, category (TrendCategory), status (TrendStatus), relevanceScore (0–1), seasons (Season[], min 1), emergenceYear (int 1900–2100), origin (TrendOrigin), description, alignedAesthetics (StyleAesthetic[], default []), keyPieces (string[], default []), keyColors (LAB[], default []), predictedLongevity (OneSeasonFad | MultiSeason | YearPlus | EnduringSeveral | PermanentClassic), momentum (Accelerating | Stable | Decelerating), lastUpdated.

1.10 Fragrance Types#

Fragrance types model the olfactory preference profile — preferred families, individual notes, known avoidances, and occasion/season preferences — that the fragrance matching engine uses to recommend perfumes without the user being able to smell them first.

FragranceFamilySchema (FragranceFamily) — twelve families: Floral, Oriental, Woody, Fresh, Citrus, Aromatic, Chypre, Fougere, Gourmand, Aquatic, Green, Musk.

NotePositionSchema (NotePosition) — Top, Middle, Base (fragrance pyramid position; top notes are detected first and fade fastest, base notes linger longest).

FragranceNoteSchema (FragranceNote) — ingredient (string), intensity (NotePosition), description (string).

FragranceProfileSchema (FragranceProfile) — families (FragranceFamily[], min 1), preferredNotes (FragranceNote[], default []), avoidances (array of { ingredient, reason, details? } where reason is Dislike | Allergy | Sensitivity | Migraine | Other), occasionPreferences (array of { occasion, preferredFamilies, preferredIntensity } where preferredIntensity is Light | Moderate | Strong | Statement), optional preferredConcentration (EauFraiche | EauDeCologne | EauDeToilette | EauDeParfum | Parfum), seasonalPreferences (array of { season, preferredFamilies }).

1.11 Composite Profile Type#

PersonalStyleProfileSchema (PersonalStyleProfile) is the root entity of the domain — the aggregate that recommendation modules read from. It brings together the outputs of every analysis engine into a single object. All analysis fields are optional because the profile can be partially complete; the profileCompleteness score (computed by @aglaea/unified-profile) tracks which analyses are present.

2. Core Domain Constants (@aglaea/core)#

constants.ts provides reference data tables consumed by analysis and recommendation modules. These are read-only lookup tables — they encode domain knowledge (what SPF does Fitzpatrick Type III require? what ratio thresholds classify a body as pear-shaped?) that would otherwise be hardcoded in individual libraries. Centralizing them here ensures consistency and allows them to be updated in one place.

• Size conversion charts — WOMENS_SIZE_CHART, MENS_SIZE_CHART, WOMENS_SHOE_CHART, MENS_SHOE_CHART (US/UK/EU mappings), ALPHA_TO_US_WOMENS, ALPHA_TO_US_MENS (alpha-to-numeric maps).
• Measurement-to-size ranges — BUST_TO_US_SIZE, WAIST_TO_US_SIZE, HIP_TO_US_SIZE (cm ranges mapped to US women's sizes).
• Color theory constants — COLOR_HARMONY_ANGLES (HSL wheel offsets per harmony type), CIE_D65 / CIE_D50 / CIE_A (illuminant white points), SRGB_TO_XYZ_MATRIX, XYZ_TO_SRGB_MATRIX, LAB_EPSILON (0.008856), LAB_KAPPA (903.3).
• FITZPATRICK_UV_DATA — per-phototype UV reaction data: minimum erythema dose range, burn-time range, recommended SPF, UV response description, melanin index range.
• FABRIC_CARE_INSTRUCTIONS — per-fabric care set: wash, dry, iron, notes, maxWashTemp, dryerSafe, bleachSafe.
• BODY_SHAPE_THRESHOLDS — ratio thresholds for body-shape classification (hourglass, pear, apple, rectangle, invertedTriangle, athletic, diamond, oval).
• IDEAL_PROPORTIONS — reference proportion ratios (golden waist-to-hip, balanced shoulder-to-hip, fashion-figure head ratio, torso-to-leg ratio).
• SEASONAL_PALETTE_ANCHORS — per-SeasonalSubtype anchor data: parent season, dominant characteristic, anchor bestColors/neutrals/avoidColors in LAB, and metalTones.
• SUBCATEGORY_FORMALITY — default formality score (1–10) per garment subcategory.
• SUBCATEGORY_TO_CATEGORY — maps each subcategory to its parent category.
• LAYERING_ORDER — stacking order (0 = innermost) per garment category.
• FRAGRANCE_NOTE_TIMING — top/middle/base note onset, peak, fade, and duration (minutes); FRAGRANCE_CONCENTRATION_LONGEVITY — longevity hours and oil-percentage ranges per concentration tier.
• PATTERN_COMPATIBILITY — per-pattern set of mix-compatible patterns.
• FABRIC_SEASONAL_SCORES — fabric suitability score (0–1) per season.
• SKIN_CONCERN_INGREDIENTS — per-SkinConcern recommended ingredient list with a description.

3. Configuration (@aglaea/core)#

config.ts defines AglaeaConfigSchema (AglaeaConfig), a section-oriented, Zod-validated configuration object. Every section has defaults, so {} parses to a valid config — libraries never have to handle a missing config section. Config values can be overridden at startup via direct object overrides or via environment variables, following the AGLAEA_<SECTION>_<KEY> naming convention (e.g., AGLAEA_COLOR_ANALYSIS_ENABLED=false).

The configuration sections and their key fields are:

Loading and accessors. loadAglaeaConfig(overrides?) merges, in priority order: schema defaults, caller-supplied overrides, and environment-variable overrides. Environment variables use a flat AGLAEA_<SECTION>_<KEY> format (example: AGLAEA_COLOR_ANALYSIS_ENABLED=false → { colorAnalysis: { enabled: false } }). validateAglaeaConfig(config) returns a safeParse-style result. getConfigSection(config, section) is a type-safe section accessor. mergeConfigs(base, override) deep-merges two partials (arrays replace, not concatenate). ConfigManager is a stateful container with getAll/get/set/reset and change-subscription support.

4. AI Orchestration Types (@aglaea/ai-orchestrator)#

libs/aglaea/ai-orchestrator/src/types.ts defines the contracts that every library uses when requesting ML inference. The library ships orchestrator, model-registry, ab-testing, fallback, inference-queue, batch-inference, monitoring, cost-tracker, warmup, and edge-deployment modules — the types below are shared across all of them.

Branded type. ModelId (Brand<string, 'ModelId'>), constructed via modelId(raw).

ModelProvider (enum) — the set of supported ML inference providers: OpenAI, Anthropic, HuggingFace, Custom, RunPod, Replicate, Local.

ModelCapability (enum) — the ten capabilities a model can be registered for: SkinAnalysis, HairAnalysis, BodyAnalysis, ColorAnalysis, OutfitRecommendation, TrendForecasting, FragranceMatching, VirtualTryOn, FabricDetection, StyleClassification.

ModelConfig — the full descriptor of a registered model: id (ModelId), name, provider (ModelProvider), endpoint, optional apiKey (in-memory only, never persisted), capabilities (ModelCapability[]), version, maxBatchSize, timeoutMs, costPerInference (USD), isActive, warmupRequired, optional metadata.

InferencePriority — low | normal | high | critical. The helper priorityWeight(p) maps these to numeric weights (critical 4 → low 1) for the priority queue.

InferenceRequest<T> — id, modelId, input, priority, timestamp, optional metadata. InferenceResult<T> — requestId, modelId, output, latencyMs, cost, cached, modelVersion, timestamp. InferenceError — requestId, modelId, error, code, retryable.

ABTestConfig — id, name, controlModelId, treatmentModelId, trafficSplitPercent (0–100), startDate, optional endDate, capability, isActive. ABTestResult — testId, controlMetrics, treatmentMetrics, optional winner (control | treatment), confidence.

ModelMetrics — per-model performance tracking: totalRequests, successRate, avgLatencyMs, p95LatencyMs, p99LatencyMs, avgCost, totalCost, errorRate.

QueuedInference — wraps a request with its resolve/reject callbacks and enqueuedAt. QueueStats — processed, failed, queued, avgWaitMs.

Edge deployment. TargetDevice (cpu | gpu | tpu | npu), Quantization (none | int8 | int4 | fp16), EdgeDeploymentConfig (modelId, targetDevice, quantization, maxMemoryMb, batchSize, warmupSamples).

Warm-up. WarmupResult (modelId, success, latencyMs, optional error), WarmupStatus (cold | warming | warm | failed).

5. REST API Surface (@aglaea/api-services)#

@aglaea/api-services defines the REST API as typed RouteDefinition objects grouped by domain module, aggregated by api-registry.ts. The registry constant API_VERSION is v1 and BASE_PATH is /api/v1. All endpoint paths use colon-prefixed path parameters (e.g. :profileId).

A RouteDefinition carries method, path, summary, tags, optional requestBody (a SchemaRef with description, contentType, schema), optional queryParams / pathParams (maps of ParamDef), a responses map (HTTP status → ResponseDef), an auth field (required | optional | none), and an optional rateLimit ({ windowMs, max }).

The registry aggregates 64 endpoints across seven modules. All endpoints require authentication (auth: 'required') except the eight Trends/Discovery endpoints noted below.

5.1 Profile Endpoints (profile-endpoints.ts)#

These ten endpoints cover the full lifecycle of a personal style profile — creation, retrieval, update, deletion, photo upload, preference management, history browsing, and external sync.

5.2 Analysis Endpoints (analysis-endpoints.ts)#

These ten endpoints submit photos or measurements for analysis and retrieve results. The six analysis-submission endpoints (POST /analysis/{type}) accept multipart/form-data and respond 202 with an AnalysisJob schema — analysis is asynchronous. They enforce per-minute rate limits (15/min for skin/color/face/hair/nails, 10/min for body).

5.3 Recommendation Endpoints (recommendation-endpoints.ts)#

These ten endpoints generate personalized recommendations across the platform's major recommendation types — outfit, shopping, style tips, color palette, skincare routine, hair care, and makeup. All are POST requests because they consume context (occasion, weather, skin analysis ID) from the request body.

5.4 Wardrobe Endpoints (wardrobe-endpoints.ts)#

These ten endpoints manage the digital wardrobe — adding, updating, and removing items, logging wear events, retrieving analytics, identifying gaps, and generating a capsule wardrobe from existing inventory.

5.5 Virtual Try-On Endpoints (tryon-endpoints.ts)#

These eight endpoints submit try-on requests for different item types and retrieve results. Try-on sessions are persistent — a session ID is returned immediately, and the rendered result is retrieved asynchronously.

5.6 Conversation Endpoints (conversation-endpoints.ts)#

These eight endpoints drive multi-turn dialogue with the AI style assistant. Sessions are stateful — each message is sent to an existing session so the assistant can maintain context across turns.

5.7 Trends and Discovery Endpoints (trends-endpoints.ts)#

These eight endpoints are the only ones in the registry that do not require authentication for all callers — trend and discovery data can be surfaced to anonymous users for browsing. Personalized endpoints (/personalized/:profileId and /forecast) require authentication because they depend on profile data.

6. Domain Event System (@aglaea/events)#

@aglaea/events provides the typed domain event system that decouples Aglaea's modules. When an analysis completes, it publishes a typed event; the skincare-routine library subscribes to that event and updates its recommendations without the analysis library needing to know it exists. This decoupling is what allows 93 libraries to coordinate without forming a tightly coupled dependency web.

The library ships publisher, consumer, dead-letter, replay, analytics, and helpers modules over the core types below.

6.1 Core Event Types#

These types form the envelope that wraps every domain event, regardless of payload type.

• DomainEvent<T> — id (UUID v4), type (dot-namespaced), timestamp (ISO-8601), version (schema version number), source (originating context), optional correlationId, optional causationId, optional metadata, payload (typed T).
• EventEnvelope<T> — wraps a DomainEvent<T> with routingKey, optional partition, optional deduplicationId.
• EventHandler<T> — (event: DomainEvent<T>) => void | Promise<void>.
• EventFilter — optional source, correlationId, metadata predicate.
• EventSubscription — id, eventType, handler, optional filter.
• EventPublisherOptions — optional retries, timeout.
• DeadLetterEntry<T> — event, error, attemptCount, lastAttempt, optional nextRetry.
• ReplayFilter — optional fromTimestamp, toTimestamp, eventTypes, source, correlationId, limit, offset.

6.2 Event Type Constants (AGLAEA_EVENT_TYPES)#

The AGLAEA_EVENT_TYPES const object defines 23 event type strings grouped by domain area. AglaeaEventType is the TypeScript union of all values, which means any switch statement on an event type will produce a compile error if a case is missed.

6.3 Event Payloads#

The following payload shapes illustrate the data carried by the most commonly consumed events. All payload types are defined in events.ts and are exported alongside their event constants.

• SkinAnalysisCompletedPayload — profileId, analysisId, skinType (oily | dry | combination | normal | sensitive), fitzpatrickType (1–6), overallScore, concerns (SkinConcern[] where each is { name, severity: 'low' | 'moderate' | 'high' }), timestamp.
• BodyAnalysisCompletedPayload — profileId, analysisId, bodyShape (hourglass | pear | apple | rectangle | inverted-triangle), measurements (MeasurementsSummary: optional bust, waist, hips, height, weight, inseam).
• HairAnalysisCompletedPayload — profileId, analysisId, hairType (1a–4c), healthScore.
• ColorAnalysisCompletedPayload — profileId, analysisId, seasonalSubtype (12-value kebab-case union), undertone (warm | cool | neutral).
• OutfitRecommendedPayload — profileId, recommendationId, itemIds, confidenceScore, occasion.
• WardrobeItemAddedPayload — profileId, itemId, category, brand.
• PurchaseCompletedPayload — profileId, productId, price, retailer, category.

7. API-Services Event Catalog (@aglaea/api-services)#

Separately from @aglaea/events, @aglaea/api-services declares 39 EventDefinition records intended for documentation and contract generation, aggregated by api-registry.ts. These records describe the same domain events from the perspective of the API contract surface — each EventDefinition carries type (dot identifier), description, payload (schema name), topic (message-bus topic), and version. They use a different naming scheme from the @aglaea/events constants and are not the runtime event type strings.

Representative event types from the catalog: skin.analysis.completed, color.analysis.completed, outfit.recommended, routine.recommended, trend.alert.generated, wardrobe.item.added, wardrobe.gap.detected, wardrobe.capsule.generated, outfit.shared, community.joined, challenge.completed, achievement.unlocked, badge.earned.

8. Persistence Schemas (@aglaea/database)#

@aglaea/database defines the persistence layer. It uses Knex for SQL migrations and Zod schemas for table row validation. There is no Prisma in this domain — the direct Knex + Zod pattern was chosen to keep the persistence layer free of ORM magic and to share the same Zod validation approach as the rest of @aglaea/core. The target store is PostgreSQL. Dependencies are minimal: knex, zod, and uuid.

8.1 Migrations#

Migrations are Knex up/down functions, re-exported from migrations/index.ts. They run in sequence; each migration builds on the previous one.

1. 20260318000001_initial_setup — creates the uuid-ossp and pg_trgm PostgreSQL extensions, the custom enum types (e.g. seasonal_subtype, skin_undertone, color_temperature, gender_type), and the shared updated_at trigger function.
2. 20260318000002_core_tables — core domain tables (profiles, analysis records, wardrobe, outfits, recommendations).
3. 20260318000003_catalog_tables — product and catalog tables (products, trends, ingredients, fabrics, brands, retailers).
4. 20260318000004_social_audit — social and audit tables (follows, shares, style boards, audit log).
5. 20260318000005_seed_data — reference data seeding.

8.2 Schema Modules#

The schema/index.ts barrel re-exports sixteen schema modules. Each module exports a full record schema plus CreateInput and (for mutable entities) UpdateInput variants derived via .omit() / .partial():

common, profiles, skin-analysis, body-measurements, wardrobe, outfits, products, recommendations, preferences, feedback, trends, ingredients, fabrics, brands, social, audit.

common.ts provides shared building blocks used by all other modules: UuidSchema, TimestampSchema, HexColorSchema, UrlSchema, CurrencyCodeSchema, PaginationSchema, SortDirectionSchema, SortSchema, DateRangeFilterSchema, NumericRangeFilterSchema, JsonValueSchema, JsonObjectSchema, StringArrayJsonSchema.

8.3 PersonalProfile (profiles.ts)#

PersonalProfileSchema is the database-layer representation of a user's profile. It carries less data than PersonalStyleProfile from @aglaea/core because analysis results are stored in their own tables and joined when needed, rather than embedded in the profile row.

PersonalProfileSchema — id (UUID), userId (UUID, FK to auth system), displayName, email, optional dateOfBirth (YYYY-MM-DD), optional gender (GenderSchema: female | male | non_binary | prefer_not_to_say | other), optional location (LocationSchema: city, country ISO 3166-1 alpha-2, timezone IANA), optional profileImageUrl, optional seasonalSubtype (SeasonalSubtypeDbSchema, 12-value), optional skinUndertone (Cool | Warm | Neutral | Olive), optional colorTemperature (Cool | Warm | Neutral), createdAt, updatedAt.

8.4 SkinAnalysisRecord (skin-analysis.ts)#

Each analysis run produces a dated history row, not an overwrite, so the full history of a user's skin condition is reconstructable over time. The eleven dimension scores here correspond exactly to those in SkinAnalysisResultSchema from @aglaea/core.

SkinAnalysisRecordSchema — id, profileId (FK), analysisDate, skinType (SkinTypeDbSchema), optional fitzpatrickType, optional undertone, eleven 0–100 dimension scores (hydrationScore, oilinessScore, elasticityScore, pigmentationScore, textureScore, wrinkleDepthScore, poreSizeScore, rednessScore, firmnessScore, clarityScore, radianceScore) plus a computed overallScore, concerns (SkinConcernDb[], default []), recommendations (string[], default []), optional imageUrl, optional metadata (JSON), createdAt. The module also exports IngredientSensitivityRecordSchema.

8.5 BodyMeasurementRecord (body-measurements.ts)#

Like skin analysis, body measurements are stored as dated history rows. All measurement fields are optional because not every photo submission produces all ten measurements.

BodyMeasurementRecordSchema — id, profileId (FK), measurementDate, ten optional cm circumference/length fields (bustCm, waistCm, hipCm, inseamCm, shoulderWidthCm, armLengthCm, torsoLengthCm, thighCircumferenceCm, neckCircumferenceCm, wristCircumferenceCm), optional heightCm and weightKg, optional bodyShape (BodyShapeDbSchema: Hourglass, Pear, Apple, Rectangle, InvertedTriangle, Oval, Diamond, Athletic), optional bodyProportions (JSON), optional clothingSizes (JSON), optional notes, optional measuredBy (MeasuredBySchema), createdAt, updatedAt.

8.6 WardrobeItemDb (wardrobe.ts)#

The wardrobe item database schema. Note that colors are stored as hex strings (for display) rather than LAB (for computation), since LAB conversion is applied in the application layer when the item is loaded for recommendation processing.

WardrobeItemDbSchema — id, profileId (FK to personal_profiles), category (GarmentCategoryDbSchema), optional subcategory (free-text), optional brand, name, optional description, optional primaryColorHex / accentColorHex (HexColorSchema), optional fabricType (FabricTypeDbSchema), optional fabricBlend (free-text), optional pattern (PatternDbSchema), optional styleAesthetic (StyleAestheticDbSchema), seasonSuitability (string-array JSON, default []), optional formalityLevel (1–10), optional condition (GarmentConditionDbSchema), optional purchaseDate / purchasePrice / purchaseCurrency / retailer, optional size / sizeRegion, wearCount (default 0), optional lastWornDate, optional careInstructions, imageUrls (JSON array, default []), tags (JSON array, default []), isFavorite (default false), isArchived (default false), createdAt, updatedAt.

8.7 Outfit (outfits.ts)#

OutfitSchema — id, profileId (FK), name, optional description, items (string-array JSON of wardrobe item UUIDs, default []), optional occasion, optional dressCode, optional weatherContext (JSON), optional dateWorn, optional rating (1–5), optional notes, optional imageUrl, isPublic (default false), createdAt, updatedAt. The module also exports OutfitItemSchema.

8.8 RecommendationRecord (recommendations.ts)#

Recommendation records persist the full multi-dimensional confidence scores and feedback, enabling the preference learning pipeline to train on both the recommendation and its outcome.

RecommendationRecordSchema — id, profileId (FK), type (RecommendationTypeDbSchema: outfit | shopping | style_tip | color_palette), optional context (JSON), items (array of JSON objects, default []), seven optional 0–1 confidence scores (confidenceScore, styleMatchScore, colorHarmonyScore, occasionFitScore, trendAlignmentScore, bodyFlatteryScore, weatherScore), stylingNotes (array of JSON objects, default []), optional wasAccepted, optional feedbackRating (1–5), optional feedbackText, createdAt.

8.9 Product (products.ts)#

Products in the Aglaea database represent catalog items from retail partners, normalized into the domain's type system for matching against profile attributes.

ProductSchema — id, optional externalId (retailer sync key), name, optional brand, optional description, optional category / subcategory, optional price / priceCurrency, optional retailerUrl, imageUrls (JSON array), colors (JSON array), optional fabricType, optional pattern, optional styleAesthetic, sizes (JSON array), seasonSuitability (JSON array), optional formalityLevel (1–10), optional rating (0–5), optional reviewCount, isAvailable (default true), optional lastSyncedAt, timestamps.

8.10 Trend (trends.ts)#

TrendSchema plus its database-layer enums. Note that the database enums for trend category, status, and origin use more granular values than the @aglaea/core types, providing richer data for the trend forecasting engine.

• TrendCategoryDbSchema — color, fabric, pattern, silhouette, style, accessory, footwear, beauty, lifestyle (nine values, vs. six in core).
• TrendStatusDbSchema — emerging, rising, peak, declining, fading, classic, revived (seven values, vs. six in core).
• TrendOriginDbSchema — runway, street, celebrity, social_media, subculture, designer, vintage_revival, technology, sustainability (nine values, vs. six in core).

8.11 Other Schema Modules#

These modules cover user preferences, feedback, reference data (ingredients, fabrics, brands), social interactions, and audit logging.

• preferences.ts — UserPreferencesSchema plus SustainabilityPreferenceSchema, SizePreferenceSchema, CoveragePreferenceSchema, FragranceConcentrationSchema.
• feedback.ts — FeedbackSchema, FeedbackTargetTypeSchema.
• ingredients.ts — IngredientSchema, IngredientCategoryDbSchema.
• fabrics.ts — FabricMaterialSchema, FabricCategoryDbSchema, PriceRangeDbSchema.
• brands.ts — BrandSchema and RetailerSchema, BrandPriceRangeDbSchema.
• social.ts — FollowSchema, ShareSchema, StyleBoardSchema, ShareTargetTypeSchema, SharePlatformSchema.
• audit.ts — AuditLogSchema, AuditActionSchema.

9. SDK Surface (@aglaea/sdk)#

@aglaea/sdk provides a high-level TypeScript client for consuming the @aglaea/api-services endpoints. It handles authentication, retry logic, and file uploads, so callers interact with typed domain methods rather than raw HTTP requests.

AglaeaClient is the primary entry point, composed of five sub-components also exported as instance fields:

• http (AglaeaHttpClient) — the underlying HTTP client
• interceptors (InterceptorManager) — request/response interceptor chain
• retry (RetryHandler) — exponential back-off with maxRetries defaulting to 3 and baseDelayMs to 1000
• batch (BatchProcessor) — batch multiple requests together
• uploader (FileUploader) — handles multipart file uploads for analysis and photo endpoints

The client is constructed from an AglaeaSDKConfig. Its domain methods wrap REST endpoints through the retry handler:

The SDK module set also includes auth, websocket, and http-client. The SDK uses its own client-facing result types (APIResponse<T>, SkinAnalysisResult, BodyAnalysisResult, ColorPalette, OutfitRecommendation, WardrobeItem, TrendsResponse, ShoppingRecommendationsResponse, UploadResult, etc.) defined in sdk/src/types.ts.

10. Technology Stack#

The technology choices below apply across all 93 Aglaea libraries. Each library declares its own package.json, exposing source directly via "main": "./src/index.ts" — there is no compiled output checked in, and libraries depend on each other via TypeScript path aliases resolved at build time.

Dependencies are kept minimal by design: @aglaea/core depends only on zod; @aglaea/database on knex, zod, uuid. This keeps the foundation layer importable without pulling in unnecessary transitive dependencies.

Grounding#

Every type, enum value, endpoint path, event constant, schema field, and configuration default in this document was read directly from source under libs/aglaea/ — primarily core/src/types.ts, core/src/constants.ts, core/src/config.ts, ai-orchestrator/src/types.ts, events/src/types.ts, events/src/events.ts, api-services/src/*.ts, database/src/schema/*.ts, database/src/migrations/*.ts, and sdk/src/client.ts. Counts (93 libraries, 64 endpoints, 23 event constants, 39 EventDefinition records, 16 schema modules) reflect the current monorepo state. Aglaea is a pure library domain; no apps/aglaea/ or services/aglaea/ exists.