Skip to content

Commit efb7ca3

Browse files
CataldirCataldir
committed
Add documentation for app components in various domains
- Created an index for app-level components in the E-commerce, CRM, Inventory, Product Management, and Logistics domains. - Added detailed documentation for the following services: - CRM Campaign Intelligence Service - CRM Profile Aggregation Service - CRM Segmentation & Personalization Service - CRM Support Assistance Service - Inventory Alerts & Triggers Service - Inventory Health Check Service - Inventory JIT Replenishment Service - Inventory Reservation Validation Service - Logistics Carrier Selection Service - Logistics ETA Computation Service - Logistics Returns Support Service - Logistics Route Issue Detection Service - Product Management ACP Transformation Service - Product Management Assortment Optimization Service - Product Management Consistency Validation Service - Product Management Normalization & Classification Service
1 parent 853ee1e commit efb7ca3

24 files changed

+1655
-0
lines changed

‎docs/architecture/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This folder contains comprehensive architectural documentation for the Holiday P
88
- [Architecture Overview](architecture.md) — System context, use case diagrams, component interaction, deployment views
99
- [Architecture Decision Records](ADRs.md) — Index of all ADRs
1010
- [Components](components.md) — Detailed component documentation for libs and apps
11+
- [Operational Playbooks](playbooks/README.md) — Incident response guides and runbooks
1112

1213
## Quick Links
1314

‎docs/architecture/components.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ Core micro-framework providing reusable patterns for retail AI agents.
1919

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

22+
**App Index**: [components/apps/README.md](components/apps/README.md)
23+
2224
### E-commerce Domain
2325

2426
| Service | Path | Purpose |
@@ -65,6 +67,12 @@ Runnable services built on the framework, one per retail process.
6567
| [Returns Support](components/apps/logistics-returns-support.md) | `apps/logistics-returns-support/` | Reverse logistics automation |
6668
| [Route Issue Detection](components/apps/logistics-route-issue-detection.md) | `apps/logistics-route-issue-detection/` | Proactive delay mitigation |
6769

70+
## Operational Playbooks
71+
72+
Operational response guides for common incidents and runtime issues.
73+
74+
- [Playbooks Index](playbooks/README.md)
75+
6876
## Component Interaction Matrix
6977

7078
| Component | Depends On | Consumed By |

‎docs/architecture/components/apps/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# App Components Index
2+
3+
Links to all app-level component docs.
4+
5+
## E-commerce Domain
6+
7+
- [Catalog Search](ecommerce-catalog-search.md)
8+
- [Product Detail Enrichment](ecommerce-product-detail-enrichment.md)
9+
- [Cart Intelligence](ecommerce-cart-intelligence.md)
10+
- [Checkout Support](ecommerce-checkout-support.md)
11+
- [Order Status](ecommerce-order-status.md)
12+
13+
## CRM Domain
14+
15+
- [Campaign Intelligence](crm-campaign-intelligence.md)
16+
- [Profile Aggregation](crm-profile-aggregation.md)
17+
- [Segmentation & Personalization](crm-segmentation-personalization.md)
18+
- [Support Assistance](crm-support-assistance.md)
19+
20+
## Inventory Domain
21+
22+
- [Alerts & Triggers](inventory-alerts-triggers.md)
23+
- [Health Check](inventory-health-check.md)
24+
- [JIT Replenishment](inventory-jit-replenishment.md)
25+
- [Reservation Validation](inventory-reservation-validation.md)
26+
27+
## Product Management Domain
28+
29+
- [ACP Transformation](product-management-acp-transformation.md)
30+
- [Assortment Optimization](product-management-assortment-optimization.md)
31+
- [Consistency Validation](product-management-consistency-validation.md)
32+
- [Normalization & Classification](product-management-normalization-classification.md)
33+
34+
## Logistics Domain
35+
36+
- [Carrier Selection](logistics-carrier-selection.md)
37+
- [ETA Computation](logistics-eta-computation.md)
38+
- [Returns Support](logistics-returns-support.md)
39+
- [Route Issue Detection](logistics-route-issue-detection.md)

‎docs/architecture/components/apps/crm-campaign-intelligence.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# CRM Campaign Intelligence Service
2+
3+
**Path**: `apps/crm-campaign-intelligence/`
4+
**Domain**: CRM
5+
**Purpose**: Campaign insights, funnel diagnostics, and ROI guidance
6+
7+
## Overview
8+
9+
Generates campaign intelligence by combining CRM contact context with funnel metrics and producing actionable insights.
10+
11+
## Architecture
12+
13+
```mermaid
14+
graph LR
15+
Client[Campaign Request] -->|POST /invoke| API[FastAPI App]
16+
API --> Agent[Campaign Intelligence Agent]
17+
Agent --> CRM[CRM Adapter]
18+
Agent --> Funnel[Funnel Adapter]
19+
Agent --> Analytics[ROI Analytics]
20+
```
21+
22+
## Components
23+
24+
### 1. FastAPI Application (`main.py`)
25+
26+
**REST Endpoints**:
27+
- `POST /invoke`
28+
- `GET /health`
29+
30+
**MCP Tools**:
31+
- `/campaign/contact-context`
32+
- `/campaign/funnel-context`
33+
- `/campaign/roi`
34+
35+
### 2. Campaign Intelligence Agent (`agents.py`)
36+
37+
Orchestrates:
38+
- CRM contact context
39+
- Funnel metrics
40+
- ROI estimation
41+
42+
**Current Status**: ✅ **IMPLEMENTED (mock adapters)**
43+
44+
### 3. Adapters
45+
46+
**CRM Adapter**: Contact + interactions
47+
**Funnel Adapter**: Stage metrics
48+
**Analytics Adapter**: ROI estimation
49+
50+
**Current Status**: ⚠️ **PARTIAL** — Mock adapters return deterministic data
51+
52+
## What's Implemented
53+
54+
✅ MCP tool registration
55+
✅ Campaign intelligence agent orchestration
56+
✅ Dockerfile + Bicep module
57+
58+
## What's NOT Implemented
59+
60+
❌ Real CRM/funnel integrations
61+
❌ Foundry model integration for narratives
62+
❌ Observability dashboards for funnel drift
63+
64+
## Operational Playbooks
65+
66+
- [Agent latency spikes](../../playbooks/playbook-agent-latency-spikes.md)
67+
- [Tool call failures](../../playbooks/playbook-tool-call-failures.md)
68+
- [Adapter failure](../../playbooks/playbook-adapter-failure.md)
69+
- [Adapter latency spikes](../../playbooks/playbook-adapter-latency-spikes.md)
70+
71+
## Sample Implementation
72+
73+
Replace mock CRM adapter with a real CRM client:
74+
75+
```python
76+
from holiday_peak_lib.adapters.base import BaseAdapter
77+
from holiday_peak_lib.adapters.crm_adapter import CRMConnector
78+
79+
class CrmApiAdapter(BaseAdapter):
80+
async def _connect_impl(self, **kwargs):
81+
return None
82+
83+
async def _fetch_impl(self, query):
84+
# Call CRM API for contact/account/interactions
85+
...
86+
87+
async def _upsert_impl(self, payload):
88+
return payload
89+
90+
async def _delete_impl(self, identifier):
91+
return True
92+
93+
crm = CRMConnector(adapter=CrmApiAdapter())
94+
```

‎docs/architecture/components/apps/crm-profile-aggregation.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# CRM Profile Aggregation Service
2+
3+
**Path**: `apps/crm-profile-aggregation/`
4+
**Domain**: CRM
5+
**Purpose**: Aggregate customer profile context for downstream agents
6+
7+
## Overview
8+
9+
Builds a consolidated CRM profile with account and interaction history for use by other services.
10+
11+
## Architecture
12+
13+
```mermaid
14+
graph LR
15+
Client[Profile Request] -->|POST /invoke| API[FastAPI App]
16+
API --> Agent[Profile Aggregation Agent]
17+
Agent --> CRM[CRM Adapter]
18+
Agent --> Analytics[Profile Summary]
19+
```
20+
21+
## Components
22+
23+
### 1. FastAPI Application (`main.py`)
24+
25+
**REST Endpoints**:
26+
- `POST /invoke`
27+
- `GET /health`
28+
29+
**MCP Tools**:
30+
- `/crm/profile/context`
31+
- `/crm/profile/summary`
32+
- `/crm/profile/account`
33+
34+
### 2. Profile Aggregation Agent (`agents.py`)
35+
36+
Orchestrates:
37+
- CRM context assembly
38+
- Profile summarization
39+
40+
**Current Status**: ✅ **IMPLEMENTED (mock adapters)**
41+
42+
### 3. Adapters
43+
44+
**CRM Adapter**: Contact/account/interactions
45+
**Analytics Adapter**: Profile summary heuristics
46+
47+
**Current Status**: ⚠️ **PARTIAL** — Mock adapters return deterministic data
48+
49+
## What's Implemented
50+
51+
✅ MCP tool registration
52+
✅ Profile aggregation agent orchestration
53+
✅ Dockerfile + Bicep module
54+
55+
## What's NOT Implemented
56+
57+
❌ Real CRM integrations
58+
❌ Foundry model integration for narratives
59+
❌ Observability dashboards for profile quality
60+
61+
## Operational Playbooks
62+
63+
- [Agent latency spikes](../../playbooks/playbook-agent-latency-spikes.md)
64+
- [Tool call failures](../../playbooks/playbook-tool-call-failures.md)
65+
- [Adapter failure](../../playbooks/playbook-adapter-failure.md)
66+
- [Adapter schema changes](../../playbooks/playbook-adapter-schema-changes.md)
67+
68+
## Sample Implementation
69+
70+
Swap in a CRM adapter with real API calls:
71+
72+
```python
73+
from holiday_peak_lib.adapters.base import BaseAdapter
74+
from holiday_peak_lib.adapters.crm_adapter import CRMConnector
75+
76+
class CrmApiAdapter(BaseAdapter):
77+
async def _connect_impl(self, **kwargs):
78+
return None
79+
80+
async def _fetch_impl(self, query):
81+
# Call CRM API by entity type
82+
...
83+
84+
async def _upsert_impl(self, payload):
85+
return payload
86+
87+
async def _delete_impl(self, identifier):
88+
return True
89+
90+
crm = CRMConnector(adapter=CrmApiAdapter())
91+
```

‎docs/architecture/components/apps/crm-segmentation-personalization.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# CRM Segmentation & Personalization Service
2+
3+
**Path**: `apps/crm-segmentation-personalization/`
4+
**Domain**: CRM
5+
**Purpose**: Segment customers and recommend personalized outreach
6+
7+
## Overview
8+
9+
Segments contacts based on engagement and opt-in status, producing personalization guidance for campaigns.
10+
11+
## Architecture
12+
13+
```mermaid
14+
graph LR
15+
Client[Segmentation Request] -->|POST /invoke| API[FastAPI App]
16+
API --> Agent[Segmentation Agent]
17+
Agent --> CRM[CRM Adapter]
18+
Agent --> Segmenter[Segmentation Rules]
19+
```
20+
21+
## Components
22+
23+
### 1. FastAPI Application (`main.py`)
24+
25+
**REST Endpoints**:
26+
- `POST /invoke`
27+
- `GET /health`
28+
29+
**MCP Tools**:
30+
- `/crm/segment/context`
31+
- `/crm/segment`
32+
- `/crm/personalization`
33+
34+
### 2. Segmentation Agent (`agents.py`)
35+
36+
Orchestrates:
37+
- CRM context assembly
38+
- Segmentation and personalization rules
39+
40+
**Current Status**: ✅ **IMPLEMENTED (mock adapters)**
41+
42+
### 3. Adapters
43+
44+
**CRM Adapter**: Contact/account/interactions
45+
**Segmentation Adapter**: Heuristic segmenting
46+
47+
**Current Status**: ⚠️ **PARTIAL** — Mock adapters return deterministic data
48+
49+
## What's Implemented
50+
51+
✅ MCP tool registration
52+
✅ Segmentation agent orchestration
53+
✅ Dockerfile + Bicep module
54+
55+
## What's NOT Implemented
56+
57+
❌ Real CRM integrations
58+
❌ Foundry model integration for narratives
59+
❌ Observability dashboards for segment drift
60+
61+
## Operational Playbooks
62+
63+
- [Agent latency spikes](../../playbooks/playbook-agent-latency-spikes.md)
64+
- [Tool call failures](../../playbooks/playbook-tool-call-failures.md)
65+
- [Adapter failure](../../playbooks/playbook-adapter-failure.md)
66+
- [Adapter latency spikes](../../playbooks/playbook-adapter-latency-spikes.md)
67+
68+
## Sample Implementation
69+
70+
Replace the CRM adapter with a real client:
71+
72+
```python
73+
from holiday_peak_lib.adapters.base import BaseAdapter
74+
from holiday_peak_lib.adapters.crm_adapter import CRMConnector
75+
76+
class CrmApiAdapter(BaseAdapter):
77+
async def _connect_impl(self, **kwargs):
78+
return None
79+
80+
async def _fetch_impl(self, query):
81+
# Retrieve contact, account, interactions
82+
...
83+
84+
async def _upsert_impl(self, payload):
85+
return payload
86+
87+
async def _delete_impl(self, identifier):
88+
return True
89+
90+
crm = CRMConnector(adapter=CrmApiAdapter())
91+
```

0 commit comments

Comments
 (0)