Skip to content

components.md

Latest commit

 

History

History
289 lines (213 loc) · 15.5 KB

components.md

File metadata and controls

289 lines (213 loc) · 15.5 KB

Components Documentation

This document indexes all component documentation for Holiday Peak Hub, organized by libs (framework) and apps (domain services).

Libs (Framework Components)

Core micro-framework providing reusable patterns for retail AI agents.

Component Path Description Pattern
Adapters lib/src/holiday_peak_lib/adapters/ Pluggable retail system integrations Adapter Pattern
Agents lib/src/holiday_peak_lib/agents/ Agent orchestration, MCP wrappers, guardrails Builder Pattern (memory)
Memory lib/src/holiday_peak_lib/agents/memory/ Three-tier memory with parallel I/O Tiered Caching
Orchestration lib/src/holiday_peak_lib/orchestration/ SAGA choreography helpers Event-driven
Schemas lib/src/holiday_peak_lib/schemas/ Pydantic models for data contracts Domain Models
Utils lib/src/holiday_peak_lib/utils/ Logging, config, retry logic Utilities
Integrations lib/src/holiday_peak_lib/integrations/ Connector contracts, registry, writeback Integration Pattern
Connectors lib/src/holiday_peak_lib/connectors/ Enterprise system connectors Adapter Pattern

Agent Runtime (v2.1.0)

Component Path Purpose
DirectModelInvoker agents/direct.py Canonical MAF direct-model runtime over a pluggable ChatClient with native function-calling
Enrichment Guardrail agents/guardrails/enrichment_guardrail.py Validation layer for enrichment outputs
Memory Tools agents/memory/builder.py get_memory, set_memory, search_memory tools for agent use
Parallel Memory I/O agents/memory/ asyncio.gather-based concurrent hot/warm/cold tier operations
gather_adapters agents/base_agent.py Helper for concurrent adapter initialization

Enterprise Connectors (v1.1.0)

Production-ready connectors for enterprise retail systems.

Inventory & SCM Connectors

Connector Path Capabilities
Oracle Fusion Cloud SCM connectors/inventory_scm/oracle_scm/ Inventory, Purchase Orders, Shipments
SAP S/4HANA (integrated) Material Master, Inventory Positions, POs

CRM & Loyalty Connectors

Connector Path Capabilities
Salesforce CRM connectors/crm_loyalty/salesforce/ Contacts, Accounts, Leads, Campaigns
Dynamics 365 (integrated) Contact, Account, Opportunity, Case

DAM & PIM Connectors

Connector Path Capabilities
Generic REST DAM integrations/dam_generic.py Configurable asset management
Generic REST PIM integrations/pim_generic_rest.py Configurable product ingestion and enrichment write-back
PIM Writeback integrations/pim_writeback.py Bi-directional sync with conflict detection

Enterprise Hardening (v1.1.0)

Resilience patterns for production workloads.

Component Path Purpose
Circuit Breaker utils/circuit_breaker.py Failure isolation with half-open recovery
Bulkhead utils/bulkhead.py Semaphore-based resource isolation
Rate Limiter utils/rate_limiter.py Token bucket with async support
Telemetry utils/telemetry.py OpenTelemetry spans and metrics

Product Truth Layer

Foundation for unified product data management.

Component Path Purpose
Truth Schemas schemas/truth.py TruthAttribute, ProposedAttribute, GapReport, AuditEvent
Truth Ingestion apps/truth-ingestion/ Event-driven product record processing
Truth Enrichment Service apps/truth-enrichment/ Candidate attribute enrichment and confidence scoring
HITL Review UI apps/ui/app/staff/review/ Human-in-the-loop attribute validation
Admin UI apps/ui/app/admin/ Schema management, tenant config, analytics
Truth HITL Service apps/truth-hitl/ Human approval workflow and review queue orchestration
Truth Export Service apps/truth-export/ Approved data export and writeback pipeline
Search Enrichment Agent apps/search-enrichment-agent/ Search-side enrichment and retrieval augmentation

Apps (Domain Services)

Runnable services built on the framework, one per retail process.

App Index: components/apps/README.md

E-commerce Domain

Service Path Purpose
CRUD Service apps/crud-service/ Transactional APIs + ACP checkout sessions
Catalog Search apps/ecommerce-catalog-search/ Product discovery with AI Search
Product Detail Enrichment apps/ecommerce-product-detail-enrichment/ ACP metadata augmentation
Cart Intelligence apps/ecommerce-cart-intelligence/ Personalized cart recommendations
Checkout Support apps/ecommerce-checkout-support/ Allocation validation, dynamic pricing
Order Status apps/ecommerce-order-status/ Proactive order tracking

Product Management Domain

Service Path Purpose
Normalization/Classification apps/product-management-normalization-classification/ Automated taxonomy alignment
ACP Transformation apps/product-management-acp-transformation/ Standards-compliant catalog export
Consistency Validation apps/product-management-consistency-validation/ Real-time data quality checks
Assortment Optimization apps/product-management-assortment-optimization/ ML-driven SKU mix recommendations

CRM Domain

Service Path Purpose
Profile Aggregation apps/crm-profile-aggregation/ Unified customer view
Segmentation/Personalization apps/crm-segmentation-personalization/ Dynamic cohort building
Campaign Intelligence apps/crm-campaign-intelligence/ ROI-optimized marketing automation
Support Assistance apps/crm-support-assistance/ Agent-augmented customer service

Inventory Domain

Service Path Purpose
Health Check apps/inventory-health-check/ Predictive stock-out alerts
JIT Replenishment apps/inventory-jit-replenishment/ Demand-sensing reorder triggers
Reservation Validation apps/inventory-reservation-validation/ Real-time allocation locking
Alerts/Triggers apps/inventory-alerts-triggers/ Exception-based notifications

Logistics Domain

Service Path Purpose
ETA Computation apps/logistics-eta-computation/ Real-time delivery predictions
Carrier Selection apps/logistics-carrier-selection/ Cost/speed trade-off optimization
Returns Support apps/logistics-returns-support/ Reverse logistics automation
Route Issue Detection apps/logistics-route-issue-detection/ Proactive delay mitigation

Frontend Components

Next.js 15 application with atomic design component library connecting to all backend services.

Frontend Stack: Next.js App Router, React, TypeScript, Tailwind CSS

Component Library

52 production-ready components organized by atomic design principles:

Category Count Location Description
Atoms 20 ui/components/atoms/ Basic building blocks (Button, Input, Icon, etc.)
Molecules 20 ui/components/molecules/ Simple composed components (Card, FormField, etc.)
Organisms 15 ui/components/organisms/ Complex composed components (Navigation, ProductGrid, etc.)
Templates 4 ui/components/templates/ Page-level layouts (MainLayout, ShopLayout, etc.)

See Component Library Documentation for details.

Page Structure

15 pages total: Organized by user role (anonymous, customer, staff, admin)

Anonymous Pages (5 pages - Public Access)

Page Route Services Used Purpose
Homepage / catalog-search, segmentation-personalization, assortment-optimization Landing with featured products
Category /category/[slug] catalog-search, inventory-health-check, assortment-optimization Product browsing by category
Product /product/[id] product-detail-enrichment, inventory-health-check, eta-computation, cart-intelligence Detailed product view
Reviews /product/[id]/reviews product-detail-enrichment, profile-aggregation Product reviews and ratings
Order /order/[id] order-status, eta-computation, route-issue-detection Order status lookup

Customer Pages (4 pages - Role: customer)

Page Route Services Used Purpose
Checkout /checkout cart-intelligence, checkout-support, inventory-reservation-validation, carrier-selection Complete purchase
Order Tracking /my-orders order-status, eta-computation, returns-support View customer orders
Dashboard /dashboard profile-aggregation, segmentation-personalization, order-status, inventory-health-check Customer overview
Profile /profile profile-aggregation, segmentation-personalization User profile and preferences

Issue #28 alignment (dashboard/profile):

  • Supported dashboard/profile data paths are consumed through UI API hooks over /api/* contracts.
  • Previously hardcoded dashboard/profile values without backend contracts were removed.
  • Unsupported profile/dashboard fields now render explicit unavailable/unsupported states rather than fabricated values.

Staff Pages (5 pages - Role: staff)

Page Route Services Used Purpose
Sales Analytics /staff/sales campaign-intelligence, catalog-search, inventory-health-check Sales metrics (page views, per product, per category)
Requests /staff/requests support-assistance, profile-aggregation, returns-support Customer support requests
Shippings /staff/shippings eta-computation, carrier-selection, route-issue-detection Shipping management
Logistic Tracking /staff/logistics eta-computation, route-issue-detection, carrier-selection Real-time logistics tracking
Customer Profiles /staff/customers profile-aggregation, segmentation-personalization, order-status Customer information and history

Admin Pages (1 page - Role: admin)

Page Route Services Used Purpose
Admin Portal /admin All backend services Gateway to all sensitive backend capabilities

Protocol Compliance

AG-UI Protocol: All interactive elements annotated with data-ag-* attributes for agent interoperability

Agentic Commerce Protocol (ACP): Product data standardized for agent consumption

Authentication & Security

  • JWT tokens in httpOnly cookies
  • Role-Based Access Control (RBAC) with 4 roles: anonymous, customer, staff, admin
  • Next.js middleware for route protection
  • Session management with automatic refresh
  • Dual auth mode:
    • Primary: Entra ID sign-in and role claims
    • Dev fail-safe: signed mock auth cookie with role selection (customer, staff, admin) for local/non-prod demos
  • Production safeguards:
    • Dev mock auth is disabled in production runtime
    • Mock auth routes reject requests with 403 when disabled
    • Route authorization remains enforced in middleware for staff and admin paths

Design System

  • Atomic design methodology with shared atoms, molecules, organisms, and templates
  • Role-based pages with common navigation and layout primitives
  • Dark mode support implemented in UI layer

Related ADRs

Operational Playbooks

Operational response guides for common incidents and runtime issues.

Architecture Compliance

Component Interaction Matrix

Component Depends On Consumed By
Adapters - All apps (via DI)
Memory Builder Redis, Cosmos, Blob SDKs Agents
Agents Memory, Adapters All apps
Orchestration Event Hubs SDK Apps (SAGA participants)
Schemas Pydantic Adapters, Agents, Apps
Utils Azure Monitor SDK All apps

Extension Points

For Retailers

  1. Custom Adapters: Implement RetailAdapter interface for your APIs
  2. Memory Policies: Override tier promotion rules in MemoryBuilder
  3. Agent Tools: Register custom MCP tools in app main.py
  4. Event Handlers: Subscribe to Event Hubs topics for SAGA participation

For Microsoft Partners

  1. ISV Adapters: Package adapters for common retail platforms (Shopify, SAP, Oracle)
  2. Model Tuning: Fine-tune Foundry models on retailer catalogs
  3. Evaluation Harnesses: Build scenario-based quality tests
  4. UI Components: Foundry-based React components for common flows

Documentation Standards

Each component README includes:

  • Purpose: What problem does it solve?
  • Patterns: Which design patterns are used?
  • ADRs: Links to relevant architectural decisions
  • API Reference: Key classes and methods
  • Usage Examples: Code snippets for common scenarios
  • Testing: How to run unit/integration tests
  • Extension: How retailers customize this component

Next Steps

  • Explore lib components: libs/
  • Review app components: apps/
  • Understand patterns: ADRs