@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/architecture/architecture-01-overview.md

@@ -1,427 +1,427 @@
-## SDK Philosophy
-
-**Core Principle:** The SDK provides **building-block services**. YOU compose them into workflows.
-
-### Primary Approach: Building Blocks (Recommended)
-
-```typescript
-// ✅ RECOMMENDED - Compose services yourself (maximum flexibility)
-import { createClient, S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config }, { logger });
-const s3 = new S3DataSource(s3Config, logger);
-const parser = new CSVParserService(logger);
-
-// Build your workflow
-const file = await s3.downloadFile('inventory.csv');
-const records = await parser.parse(file.toString());
-const mapped = records.map(record => ({ /* your mapping */ }));
-await client.sendBatch(jobId, { items: mapped });
-```
-
-### Optional Convenience: Orchestrators (When Appropriate)
-
-```typescript
-// ✅ ALSO VALID - Use orchestrators for common patterns
-import { ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
-
-const orchestrator = new ExtractionOrchestrator(client, logger);
-await orchestrator.extractToCSV({
-  query: '...',
-  outputPath: 'inventory.csv'
-});
-```
-
-### When to Use What
-
-| Approach | Use When | Pros | Cons |
-|----------|----------|------|------|
-| **Building Blocks** | Custom workflows, unique requirements | Maximum flexibility, full control | More code to write |
-| **Orchestrators** | Standard patterns, rapid prototyping | Less code, batteries included | Less flexibility |
-
-**Recommendation:** Start with building blocks. Use orchestrators when you need a common pattern implemented quickly.
-
-**Key Features:**
-
-- **ExtractionOrchestrator**: Optional high-level service for GraphQL extraction (auto-pagination, path-based extraction, validation)
-- **Versori client parity**: Strips internal fields, auto-paginates, aligned endpoints, retry/backoff, and `validateWebhook()`
-- **Logging architecture**: Function-based utilities (`createConsoleLogger()`, `toStructuredLogger()`) for standalone environments
-- **Core services**: JobTracker, PartialBatchRecovery, PreflightValidator, WebhookValidationService
-- **SFTP enhancements**: Connection pooling, wait queues, improved retry logic, Deno compatibility
-
-**See:** [SDK Philosophy](../../00-START-HERE/SDK-PHILOSOPHY.md) for design principles.
-
-# FC Connect SDK - Architecture Overview
-
-This document provides a high-level overview of the FC Connect SDK architecture, designed to help you understand how the SDK works and how to use it effectively.
-
-## What is the FC Connect SDK?
-
-The FC Connect SDK is a TypeScript library that helps you build integrations with Fluent Commerce. It handles the complexity of:
-
-- Authentication and API communication
-- Data transformation and mapping
-- File processing (CSV, XML, JSON, Parquet)
-- Batch operations and state management
-- Multi-runtime support (Node.js, Deno, Versori)
-- High-level extraction orchestration with auto-pagination
-- Webhook signature validation
-- Job tracking and partial batch recovery
-- Pre-flight validation to save API quota
-- SFTP connection pooling for better performance
-
-## High-Level Architecture
-
-```mermaid
-graph TB
-    subgraph "Your Application"
-        APP[Your Integration Code]
-    end
-
-    subgraph "FC Connect SDK"
-        FACTORY[Client Factory<br/>Auto-detects runtime]
-
-        subgraph "Client Layer"
-            FC[FluentClient<br/>OAuth2]
-            FVC[FluentVersoriClient<br/>Platform Auth]
-        end
-
-        subgraph "Service Layer"
-            BATCH[Batch API Client]
-            MAPPER[Universal Mapper]
-            EXTRACT[Extraction Orchestrator]
-            STATE[State Service]
-            WEBHOOK[Webhook Validation]
-            JOBTRACK[Job Tracker]
-            PREFLIGHT[Preflight Validator]
-        end
-
-        subgraph "Data Layer"
-            DS[Data Sources<br/>S3, SFTP]
-            PARSERS[Parsers<br/>CSV, XML, JSON, Parquet]
-        end
-
-        subgraph "Orchestration"
-            INGEST[Ingestion Service<br/>Optional Helper]
-        end
-    end
-
-    subgraph "External Systems"
-        FLUENT[Fluent Commerce API]
-        S3[Amazon S3]
-        SFTP[SFTP Servers]
-    end
-
-    APP --> FACTORY
-    FACTORY --> FC
-    FACTORY --> FVC
-    FC --> BATCH
-    FVC --> BATCH
-    FC --> MAPPER
-    FVC --> MAPPER
-    FC --> EXTRACT
-    FVC --> EXTRACT
-    BATCH --> STATE
-    MAPPER --> PARSERS
-    EXTRACT --> DS
-    INGEST --> DS
-    INGEST --> PARSERS
-    INGEST --> MAPPER
-    INGEST --> BATCH
-    DS --> S3
-    DS --> SFTP
-    BATCH --> FLUENT
-    FC --> FLUENT
-    FVC --> FLUENT
-
-    style APP fill:#e1f5ff
-    style FACTORY fill:#fff4e6
-    style FC fill:#f3e5f5
-    style FVC fill:#f3e5f5
-    style FLUENT fill:#ffebee
-    style S3 fill:#ffebee
-    style SFTP fill:#ffebee
-```
-
-## Core Concepts
-
-### 1. Universal Client Factory
-
-The SDK automatically detects your runtime environment and creates the appropriate client:
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Works in Node.js, Deno, or Versori - automatically detects context
-const client = await createClient(ctx); // Pass context directly
-```
-
-**Supported Environments:**
-
-- **Node.js/Deno**: Uses OAuth2 authentication
-- **Versori Platform**: Uses platform-managed connections
-
-### 2. Layered Architecture
-
-The SDK is organized into clear layers:
-
-```mermaid
-graph LR
-    subgraph "Layer 1: Client"
-        CLIENT[Client Factory & Implementations]
-    end
-
-    subgraph "Layer 2: Services"
-        SERVICES[Batch, Mapping, Extraction,<br/>Transformation, State]
-    end
-
-    subgraph "Layer 3: Data"
-        DATA[Data Sources & Parsers]
-    end
-
-    subgraph "Layer 4: Optional Orchestration"
-        ORCHESTRATION[Optional High-level Services<br/>IngestionService, ExtractionOrchestrator]
-    end
-
-    CLIENT --> SERVICES
-    SERVICES --> DATA
-    ORCHESTRATION --> SERVICES
-    ORCHESTRATION --> DATA
-
-    style CLIENT fill:#e3f2fd
-    style SERVICES fill:#f3e5f5
-    style DATA fill:#fff3e0
-    style ORCHESTRATION fill:#e8f5e9
-```
-
-**Why Layers Matter:**
-
-- **Flexibility**: Use low-level services for custom logic or optional high-level services (like IngestionService) for common patterns
-- **Testability**: Each layer can be tested independently
-- **Maintainability**: Clear separation of concerns
-
-### 3. Universal Mapping Pattern
-
-One mapping configuration works for ALL data transformations:
-
-```mermaid
-graph LR
-    CSV[CSV Ingestion] --> MAPPER[Universal Mapper]
-    XML[XML Transformation] --> MAPPER
-    JSON[JSON Extraction] --> MAPPER
-    PARQUET[Parquet Processing] --> MAPPER
-
-    MAPPER --> CONFIG{Mapping Config}
-    CONFIG --> FLUENT[Fluent Commerce]
-
-    style MAPPER fill:#fff4e6
-    style CONFIG fill:#e8f5e9
-```
-
-**Example Mapping:**
-
-```typescript
-const mappingConfig = {
-  fields: {
-    skuRef: { source: 'sku_id', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-    expectedOn: { source: 'date', resolver: 'sdk.formatDate' },
-  },
-};
-```
-
-This same configuration works whether you're:
-
-- Processing CSV files from S3
-- Transforming XML orders from SFCC
-- Extracting data to Parquet
-- Converting JSON to GraphQL mutations
-
-## Design Principles
-
-### 1. Stateless & Parallel-Safe
-
-All SDK methods are stateless and can be called in parallel:
-
-```typescript
-// Safe to run in parallel - multiple GraphQL queries
-await Promise.all([
-  client.graphql({
-    query: `query GetInventory($id: ID!) { inventoryPosition(id: $id) { id ref qty } }`,
-    variables: { id: 'inv-1' },
-  }),
-  client.graphql({
-    query: `query GetInventory($id: ID!) { inventoryPosition(id: $id) { id ref qty } }`,
-    variables: { id: 'inv-2' },
-  }),
-  client.graphql({
-    query: `query GetInventory($id: ID!) { inventoryPosition(id: $id) { id ref qty } }`,
-    variables: { id: 'inv-3' },
-  }),
-]);
-```
-
-### 2. Streaming for Large Data
-
-The SDK uses streaming to handle large files without memory issues:
-
-```mermaid
-graph LR
-    FILE[Large CSV File<br/>1GB] --> STREAM[Stream Parser]
-    STREAM --> CHUNK1[Chunk 1<br/>1000 rows]
-    STREAM --> CHUNK2[Chunk 2<br/>1000 rows]
-    STREAM --> CHUNK3[Chunk N<br/>1000 rows]
-
-    CHUNK1 --> BATCH1[Batch 1]
-    CHUNK2 --> BATCH2[Batch 2]
-    CHUNK3 --> BATCHN[Batch N]
-
-    BATCH1 --> API[Fluent API]
-    BATCH2 --> API
-    BATCHN --> API
-
-    style FILE fill:#ffebee
-    style STREAM fill:#e3f2fd
-    style API fill:#e8f5e9
-```
-
-### 3. Smart Error Handling
-
-The SDK handles errors intelligently:
-
-```mermaid
-graph TD
-    ERROR{Error Type?}
-    ERROR -->|4xx Client Error| FAIL[Fail Fast<br/>No Retry]
-    ERROR -->|5xx Server Error| RETRY[Exponential Backoff<br/>Max 3 Retries]
-    ERROR -->|Network Error| RETRY
-    ERROR -->|Job Expired| RECREATE[Create New Job<br/>Auto-retry]
-
-    RETRY --> SUCCESS{Successful?}
-    SUCCESS -->|Yes| CONTINUE[Continue]
-    SUCCESS -->|No| FAIL
-
-    RECREATE --> CONTINUE
-
-    style FAIL fill:#ffebee
-    style RETRY fill:#fff3e0
-    style RECREATE fill:#e8f5e9
-    style CONTINUE fill:#e3f2fd
-```
-
-## Common Use Cases
-
-### 1. Inventory Ingestion
-
-Process CSV files from S3 and send to Fluent Commerce:
-
-```mermaid
-sequenceDiagram
-    participant S3
-    participant SDK
-    participant Fluent
-
-    SDK->>S3: List files
-    S3-->>SDK: file1.csv, file2.csv
-    SDK->>S3: Download file1.csv
-    S3-->>SDK: CSV data
-    SDK->>SDK: Parse & Map fields
-    SDK->>Fluent: Create batch job
-    Fluent-->>SDK: Job ID
-    SDK->>Fluent: Send batch 1
-    SDK->>Fluent: Send batch 2
-    SDK->>Fluent: Send batch N
-    SDK->>S3: Archive file1.csv
-```
-
-### 2. Data Extraction
-
-Query Fluent Commerce and save results to S3:
-
-```mermaid
-sequenceDiagram
-    participant SDK
-    participant Fluent
-    participant S3
-
-    SDK->>Fluent: Execute GraphQL query
-    Fluent-->>SDK: Page 1 (100 items)
-    SDK->>Fluent: Fetch page 2
-    Fluent-->>SDK: Page 2 (100 items)
-    SDK->>SDK: Transform & Map data
-    SDK->>S3: Upload results.json
-    S3-->>SDK: Success
-```
-
-### 3. Order Transformation
-
-Convert SFCC XML orders to Fluent GraphQL mutations:
-
-```mermaid
-sequenceDiagram
-    participant SFCC
-    participant SDK
-    participant Fluent
-
-    SFCC->>SDK: POST /webhook (XML order)
-    SDK->>SDK: Parse XML
-    SDK->>SDK: Apply mutation mapping
-    SDK->>Fluent: Execute createOrder mutation
-    Fluent-->>SDK: Order created
-    SDK-->>SFCC: 200 OK
-```
-
-## Multi-Runtime Support
-
-The SDK works seamlessly across different runtimes:
-
-```mermaid
-graph TB
-    SDK[FC Connect SDK]
-
-    subgraph "Node.js"
-        NODE[OAuth2 Authentication]
-        NODE_ENV[Environment Variables]
-    end
-
-    subgraph "Deno"
-        DENO[OAuth2 Authentication]
-        DENO_ENV[Deno.env]
-    end
-
-    subgraph "Versori Platform"
-        VERSORI[Connection-based Auth]
-        VERSORI_KV[KV Storage]
-        VERSORI_LOG[Platform Logging]
-    end
-
-    SDK --> NODE
-    SDK --> DENO
-    SDK --> VERSORI
-
-    NODE --> FLUENT[Fluent Commerce API]
-    DENO --> FLUENT
-    VERSORI --> FLUENT
-
-    style SDK fill:#e3f2fd
-    style NODE fill:#f3e5f5
-    style DENO fill:#fff3e0
-    style VERSORI fill:#e8f5e9
-    style FLUENT fill:#ffebee
-```
-
-## Next Steps
-
-Explore detailed architecture diagrams:
-
-- [Client Architecture](./architecture-02-client-architecture.md) - Client creation and context detection
-- [Data Flow](./architecture-03-data-flow.md) - Ingestion, extraction, and transformation flows
-- [Service Layer](./architecture-04-service-layer.md) - Service organization and responsibilities
-- [Integration Architecture](./architecture-05-integration-architecture.md) - External system integrations
-- [State Management](./architecture-06-state-management.md) - Distributed state and deduplication
-
-Or jump to practical guides:
-
-- [Getting Started](../../00-START-HERE/getting-started.md)
-- [Universal Mapping Guide](../../02-CORE-GUIDES/mapping/mapping-readme.md)
-- [Use Cases](../../01-TEMPLATES/readme.md)
+## SDK Philosophy
+
+**Core Principle:** The SDK provides **building-block services**. YOU compose them into workflows.
+
+### Primary Approach: Building Blocks (Recommended)
+
+```typescript
+// ✅ RECOMMENDED - Compose services yourself (maximum flexibility)
+import { createClient, S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config }, { logger });
+const s3 = new S3DataSource(s3Config, logger);
+const parser = new CSVParserService(logger);
+
+// Build your workflow
+const file = await s3.downloadFile('inventory.csv');
+const records = await parser.parse(file.toString());
+const mapped = records.map(record => ({ /* your mapping */ }));
+await client.sendBatch(jobId, { items: mapped });
+```
+
+### Optional Convenience: Orchestrators (When Appropriate)
+
+```typescript
+// ✅ ALSO VALID - Use orchestrators for common patterns
+import { ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
+
+const orchestrator = new ExtractionOrchestrator(client, logger);
+await orchestrator.extractToCSV({
+  query: '...',
+  outputPath: 'inventory.csv'
+});
+```
+
+### When to Use What
+
+| Approach | Use When | Pros | Cons |
+|----------|----------|------|------|
+| **Building Blocks** | Custom workflows, unique requirements | Maximum flexibility, full control | More code to write |
+| **Orchestrators** | Standard patterns, rapid prototyping | Less code, batteries included | Less flexibility |
+
+**Recommendation:** Start with building blocks. Use orchestrators when you need a common pattern implemented quickly.
+
+**Key Features:**
+
+- **ExtractionOrchestrator**: Optional high-level service for GraphQL extraction (auto-pagination, path-based extraction, validation)
+- **Versori client parity**: Strips internal fields, auto-paginates, aligned endpoints, retry/backoff, and `validateWebhook()`
+- **Logging architecture**: Function-based utilities (`createConsoleLogger()`, `toStructuredLogger()`) for standalone environments
+- **Core services**: JobTracker, PartialBatchRecovery, PreflightValidator, WebhookValidationService
+- **SFTP enhancements**: Connection pooling, wait queues, improved retry logic, Deno compatibility
+
+**See:** [SDK Philosophy](../../00-START-HERE/SDK-PHILOSOPHY.md) for design principles.
+
+# FC Connect SDK - Architecture Overview
+
+This document provides a high-level overview of the FC Connect SDK architecture, designed to help you understand how the SDK works and how to use it effectively.
+
+## What is the FC Connect SDK?
+
+The FC Connect SDK is a TypeScript library that helps you build integrations with Fluent Commerce. It handles the complexity of:
+
+- Authentication and API communication
+- Data transformation and mapping
+- File processing (CSV, XML, JSON, Parquet)
+- Batch operations and state management
+- Multi-runtime support (Node.js, Deno, Versori)
+- High-level extraction orchestration with auto-pagination
+- Webhook signature validation
+- Job tracking and partial batch recovery
+- Pre-flight validation to save API quota
+- SFTP connection pooling for better performance
+
+## High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Your Application"
+        APP[Your Integration Code]
+    end
+
+    subgraph "FC Connect SDK"
+        FACTORY[Client Factory<br/>Auto-detects runtime]
+
+        subgraph "Client Layer"
+            FC[FluentClient<br/>OAuth2]
+            FVC[FluentVersoriClient<br/>Platform Auth]
+        end
+
+        subgraph "Service Layer"
+            BATCH[Batch API Client]
+            MAPPER[Universal Mapper]
+            EXTRACT[Extraction Orchestrator]
+            STATE[State Service]
+            WEBHOOK[Webhook Validation]
+            JOBTRACK[Job Tracker]
+            PREFLIGHT[Preflight Validator]
+        end
+
+        subgraph "Data Layer"
+            DS[Data Sources<br/>S3, SFTP]
+            PARSERS[Parsers<br/>CSV, XML, JSON, Parquet]
+        end
+
+        subgraph "Orchestration"
+            INGEST[Ingestion Service<br/>Optional Helper]
+        end
+    end
+
+    subgraph "External Systems"
+        FLUENT[Fluent Commerce API]
+        S3[Amazon S3]
+        SFTP[SFTP Servers]
+    end
+
+    APP --> FACTORY
+    FACTORY --> FC
+    FACTORY --> FVC
+    FC --> BATCH
+    FVC --> BATCH
+    FC --> MAPPER
+    FVC --> MAPPER
+    FC --> EXTRACT
+    FVC --> EXTRACT
+    BATCH --> STATE
+    MAPPER --> PARSERS
+    EXTRACT --> DS
+    INGEST --> DS
+    INGEST --> PARSERS
+    INGEST --> MAPPER
+    INGEST --> BATCH
+    DS --> S3
+    DS --> SFTP
+    BATCH --> FLUENT
+    FC --> FLUENT
+    FVC --> FLUENT
+
+    style APP fill:#e1f5ff
+    style FACTORY fill:#fff4e6
+    style FC fill:#f3e5f5
+    style FVC fill:#f3e5f5
+    style FLUENT fill:#ffebee
+    style S3 fill:#ffebee
+    style SFTP fill:#ffebee
+```
+
+## Core Concepts
+
+### 1. Universal Client Factory
+
+The SDK automatically detects your runtime environment and creates the appropriate client:
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Works in Node.js, Deno, or Versori - automatically detects context
+const client = await createClient(ctx); // Pass context directly
+```
+
+**Supported Environments:**
+
+- **Node.js/Deno**: Uses OAuth2 authentication
+- **Versori Platform**: Uses platform-managed connections
+
+### 2. Layered Architecture
+
+The SDK is organized into clear layers:
+
+```mermaid
+graph LR
+    subgraph "Layer 1: Client"
+        CLIENT[Client Factory & Implementations]
+    end
+
+    subgraph "Layer 2: Services"
+        SERVICES[Batch, Mapping, Extraction,<br/>Transformation, State]
+    end
+
+    subgraph "Layer 3: Data"
+        DATA[Data Sources & Parsers]
+    end
+
+    subgraph "Layer 4: Optional Orchestration"
+        ORCHESTRATION[Optional High-level Services<br/>IngestionService, ExtractionOrchestrator]
+    end
+
+    CLIENT --> SERVICES
+    SERVICES --> DATA
+    ORCHESTRATION --> SERVICES
+    ORCHESTRATION --> DATA
+
+    style CLIENT fill:#e3f2fd
+    style SERVICES fill:#f3e5f5
+    style DATA fill:#fff3e0
+    style ORCHESTRATION fill:#e8f5e9
+```
+
+**Why Layers Matter:**
+
+- **Flexibility**: Use low-level services for custom logic or optional high-level services (like IngestionService) for common patterns
+- **Testability**: Each layer can be tested independently
+- **Maintainability**: Clear separation of concerns
+
+### 3. Universal Mapping Pattern
+
+One mapping configuration works for ALL data transformations:
+
+```mermaid
+graph LR
+    CSV[CSV Ingestion] --> MAPPER[Universal Mapper]
+    XML[XML Transformation] --> MAPPER
+    JSON[JSON Extraction] --> MAPPER
+    PARQUET[Parquet Processing] --> MAPPER
+
+    MAPPER --> CONFIG{Mapping Config}
+    CONFIG --> FLUENT[Fluent Commerce]
+
+    style MAPPER fill:#fff4e6
+    style CONFIG fill:#e8f5e9
+```
+
+**Example Mapping:**
+
+```typescript
+const mappingConfig = {
+  fields: {
+    skuRef: { source: 'sku_id', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+    expectedOn: { source: 'date', resolver: 'sdk.formatDate' },
+  },
+};
+```
+
+This same configuration works whether you're:
+
+- Processing CSV files from S3
+- Transforming XML orders from SFCC
+- Extracting data to Parquet
+- Converting JSON to GraphQL mutations
+
+## Design Principles
+
+### 1. Stateless & Parallel-Safe
+
+All SDK methods are stateless and can be called in parallel:
+
+```typescript
+// Safe to run in parallel - multiple GraphQL queries
+await Promise.all([
+  client.graphql({
+    query: `query GetInventory($id: ID!) { inventoryPosition(id: $id) { id ref qty } }`,
+    variables: { id: 'inv-1' },
+  }),
+  client.graphql({
+    query: `query GetInventory($id: ID!) { inventoryPosition(id: $id) { id ref qty } }`,
+    variables: { id: 'inv-2' },
+  }),
+  client.graphql({
+    query: `query GetInventory($id: ID!) { inventoryPosition(id: $id) { id ref qty } }`,
+    variables: { id: 'inv-3' },
+  }),
+]);
+```
+
+### 2. Streaming for Large Data
+
+The SDK uses streaming to handle large files without memory issues:
+
+```mermaid
+graph LR
+    FILE[Large CSV File<br/>1GB] --> STREAM[Stream Parser]
+    STREAM --> CHUNK1[Chunk 1<br/>1000 rows]
+    STREAM --> CHUNK2[Chunk 2<br/>1000 rows]
+    STREAM --> CHUNK3[Chunk N<br/>1000 rows]
+
+    CHUNK1 --> BATCH1[Batch 1]
+    CHUNK2 --> BATCH2[Batch 2]
+    CHUNK3 --> BATCHN[Batch N]
+
+    BATCH1 --> API[Fluent API]
+    BATCH2 --> API
+    BATCHN --> API
+
+    style FILE fill:#ffebee
+    style STREAM fill:#e3f2fd
+    style API fill:#e8f5e9
+```
+
+### 3. Smart Error Handling
+
+The SDK handles errors intelligently:
+
+```mermaid
+graph TD
+    ERROR{Error Type?}
+    ERROR -->|4xx Client Error| FAIL[Fail Fast<br/>No Retry]
+    ERROR -->|5xx Server Error| RETRY[Exponential Backoff<br/>Max 3 Retries]
+    ERROR -->|Network Error| RETRY
+    ERROR -->|Job Expired| RECREATE[Create New Job<br/>Auto-retry]
+
+    RETRY --> SUCCESS{Successful?}
+    SUCCESS -->|Yes| CONTINUE[Continue]
+    SUCCESS -->|No| FAIL
+
+    RECREATE --> CONTINUE
+
+    style FAIL fill:#ffebee
+    style RETRY fill:#fff3e0
+    style RECREATE fill:#e8f5e9
+    style CONTINUE fill:#e3f2fd
+```
+
+## Common Use Cases
+
+### 1. Inventory Ingestion
+
+Process CSV files from S3 and send to Fluent Commerce:
+
+```mermaid
+sequenceDiagram
+    participant S3
+    participant SDK
+    participant Fluent
+
+    SDK->>S3: List files
+    S3-->>SDK: file1.csv, file2.csv
+    SDK->>S3: Download file1.csv
+    S3-->>SDK: CSV data
+    SDK->>SDK: Parse & Map fields
+    SDK->>Fluent: Create batch job
+    Fluent-->>SDK: Job ID
+    SDK->>Fluent: Send batch 1
+    SDK->>Fluent: Send batch 2
+    SDK->>Fluent: Send batch N
+    SDK->>S3: Archive file1.csv
+```
+
+### 2. Data Extraction
+
+Query Fluent Commerce and save results to S3:
+
+```mermaid
+sequenceDiagram
+    participant SDK
+    participant Fluent
+    participant S3
+
+    SDK->>Fluent: Execute GraphQL query
+    Fluent-->>SDK: Page 1 (100 items)
+    SDK->>Fluent: Fetch page 2
+    Fluent-->>SDK: Page 2 (100 items)
+    SDK->>SDK: Transform & Map data
+    SDK->>S3: Upload results.json
+    S3-->>SDK: Success
+```
+
+### 3. Order Transformation
+
+Convert SFCC XML orders to Fluent GraphQL mutations:
+
+```mermaid
+sequenceDiagram
+    participant SFCC
+    participant SDK
+    participant Fluent
+
+    SFCC->>SDK: POST /webhook (XML order)
+    SDK->>SDK: Parse XML
+    SDK->>SDK: Apply mutation mapping
+    SDK->>Fluent: Execute createOrder mutation
+    Fluent-->>SDK: Order created
+    SDK-->>SFCC: 200 OK
+```
+
+## Multi-Runtime Support
+
+The SDK works seamlessly across different runtimes:
+
+```mermaid
+graph TB
+    SDK[FC Connect SDK]
+
+    subgraph "Node.js"
+        NODE[OAuth2 Authentication]
+        NODE_ENV[Environment Variables]
+    end
+
+    subgraph "Deno"
+        DENO[OAuth2 Authentication]
+        DENO_ENV[Deno.env]
+    end
+
+    subgraph "Versori Platform"
+        VERSORI[Connection-based Auth]
+        VERSORI_KV[KV Storage]
+        VERSORI_LOG[Platform Logging]
+    end
+
+    SDK --> NODE
+    SDK --> DENO
+    SDK --> VERSORI
+
+    NODE --> FLUENT[Fluent Commerce API]
+    DENO --> FLUENT
+    VERSORI --> FLUENT
+
+    style SDK fill:#e3f2fd
+    style NODE fill:#f3e5f5
+    style DENO fill:#fff3e0
+    style VERSORI fill:#e8f5e9
+    style FLUENT fill:#ffebee
+```
+
+## Next Steps
+
+Explore detailed architecture diagrams:
+
+- [Client Architecture](./architecture-02-client-architecture.md) - Client creation and context detection
+- [Data Flow](./architecture-03-data-flow.md) - Ingestion, extraction, and transformation flows
+- [Service Layer](./architecture-04-service-layer.md) - Service organization and responsibilities
+- [Integration Architecture](./architecture-05-integration-architecture.md) - External system integrations
+- [State Management](./architecture-06-state-management.md) - Distributed state and deduplication
+
+Or jump to practical guides:
+
+- [Getting Started](../../00-START-HERE/getting-started.md)
+- [Universal Mapping Guide](../../02-CORE-GUIDES/mapping/mapping-readme.md)
+- [Use Cases](../../01-TEMPLATES/readme.md)