@jammysunshine/astrology-api-client 1.0.0

package/API_CLIENT_DESIGN.md

@@ -0,0 +1,1313 @@
+# Astrology API Client (SDK) - Technical Specification (Absolute Master Version)
+
+## 1. Core Philosophy: The "Secretary" and "Mailroom" Model
+The `api-client` is a "Universal" JavaScript SDK designed for Node.js (WhatsApp Bot), Browser (PWA), and Mobile (React Native). It acts as a **smart wrapper** around the Backend REST API.
+
+It follows the **Secretary Model**:
+*   **Outgoing:** It fills out the "Boring Forms" (Metadata, IDs, Timestamps) so the Frontend developer doesn't have to. It acts as a **Mailroom**, wrapping business data in a formal envelope with a tracking number (`requestId`), date stamp, and sender ID.
+*   **Incoming:** It opens the "Mail" (Responses). If it's a "Bill" (Error), it alerts you immediately via a specific Exception. If it's a "Check" (Data), it hands you the clean business data. To maintain traceability, it uses **Smart Unwrapping**, attaching the formal envelope metadata as a non-enumerable property so it doesn't clutter the business logic but is available for debugging/logging (e.g., `data.metadata.requestId`).
+
+### Design Choice: The Client as a "Shield"
+The `api-client` acts as a **Shield**, protecting the frontend logic from the underlying complexity of backend schemas and validation.
+*   **Decoupling:** Frontend developers stay "dumb" to the mechanics of AJV or JSON schema loading. They simply call methods and catch standardized errors.
+*   **Responsibility Split:**
+    *   **`shared/schemas` (The Law):** Defines the rules and data structures.
+    *   **`api-client` (The Police):** Enforces the rules and handles the "arrests" (validation failures).
+    *   **Frontend (The Citizen):** Enjoys the results without worrying about the legal/technical details.
+
+### The REST-Aligned Proxy Architecture
+*   **Dynamic Proxy:** Uses JavaScript `Proxy` to intercept `client.service.method()` calls and translates them to `POST /api/v1/service/method`.
+*   **Zero Latency:** Dynamic lookup happens entirely in the client's memory (RAM). The micro-overhead (approx 0.000005ms) is invisible compared to network time (~100-500ms).
+*   **Zero Maintenance:** 100% coverage of backend services is guaranteed. New backend methods are immediately available without SDK updates.
+*   **Backend Driven:** The client automatically maps calls to the REST structure expected by the backend (`/:service/:method`).
+
+---
+
+## 2. Monorepo Integration & Directory Structure
+
+Location: `packages/api-client/`
+Dependencies: `@astrology/shared` (Strictly reuses existing schemas and validators).
+
+### File Map & Component Responsibilities
+```
+/packages/api-client/
+├── package.json           # Defines @astrology/api-client; Depends on @astrology/shared
+├── README.md              # Full Technical Manual & Usage Examples
+└── src/
+    ├── index.js           # Entry point; Exports AstrologyApiClient
+    ├── AstrologyApiClient.js # Core logic; Proxy Implementation; Request Orchestration
+    ├── config.js          # Base URL (default :10000), Timeouts, HWM Thresholds (80%)
+    └── utils/
+        ├── ApiClientError.js # Granular Classes: ApiValidationError, ApiNetworkError, ApiServerError
+        ├── ContextStore.js   # LRU Logic; Doubly Linked List; O(1) Complexity
+        ├── RequestBatcher.js # Network Optimization; Groups multiple calls into one POST
+        ├── CircuitBreaker.js # Fail-fast resilience; Threshold: 5 failures; Timeout: 30s
+        ├── Interceptors.js   # Global Hooks (onRequest, onResponse, onError)
+        ├── ResponseDetective.js # Detection: JSON (Standard), Text (AI), Binary (PDF/Charts)
+        ├── retry.js          # Smart retry logic; Exponential backoff (500ms -> 1s -> 2s)
+        ├── formatter.js      # Message & Data formatting; Consistent UI structures
+        ├── DiagnosticsTracker.js # Observability: Error & Usage Aggregation
+        └── NetworkMonitor.js  # Network condition & adaptive logic
+```
+
+---
+
+## 3. Dynamic Service Discovery (Proxy Implementation)
+
+The client uses nested Proxies to map method calls dynamically. This ensures that even if a new method is added to the backend, the client can call it instantly without a code update.
+
+The actual backend implementation includes several key enhancements that should be reflected in the API client design:
+
+**Session Management Enhancements:**
+- **Auto-creation of sessions**: The backend automatically creates sessions if they don't exist, rather than failing
+- **Enhanced `getSessionState()` method**: Now auto-creates sessions if not found, ensuring continuity
+- **Improved error recovery**: More robust fallback mechanisms when sessions aren't found
+
+**Identity Resolution Improvements:**
+- **Deterministic unified ID format**: Changed from `unified_{timestamp}_{platform_abbrev}_{random_hash}` to `unified_{platformAbbr}_{identityHash}` for consistency
+- **Enhanced phone canonicalization**: Better validation and error handling for phone numbers
+- **Improved fallback mechanisms**: Better handling when user mapping fails
+
+**Schema Validation Updates:**
+- **ServiceRegistry integration**: Automatic schema inference based on service/method names
+- **Enhanced validation middleware**: More sophisticated validation with custom mappings
+- **Better error responses**: More detailed validation error messages
+
+**Error Handling Improvements:**
+- **Comprehensive custom error classes**: Detailed AstrologyError subclasses with proper HTTP status codes
+- **Better error response format**: More consistent responses with proper metadata
+- **Enhanced observability**: Better integration with observability services
+
+**API Structure:**
+- **Method-based routing**: Fully implemented at `/api/v1/:service/:method`
+- **Health checks**: Comprehensive health check endpoints at `/api/v1/health`
+- **Documentation endpoints**: Available API documentation at `/api/v1/docs`
+- **Service discovery**: Available at `/api/v1/:service/methods` and `/api/v1/:service/methods/:method`
+
+### Detailed Implementation Snippet
+```javascript
+// src/AstrologyApiClient.js implementation logic
+class AstrologyApiClient {
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = config.baseUrl || 'http://localhost:10000';
+        this.contextStore = new ContextStore(config.memory);
+        this.circuitBreaker = new CircuitBreaker();
+        this.interceptors = new Interceptors();
+
+        // The Root Proxy
+        return new Proxy(this, {
+            get: (target, serviceName) => {
+                // 1. If property exists on class (like 'configure' or 'asUser'), return it
+                if (serviceName in target) return target[serviceName];
+
+                // 2. Otherwise, assume it's a backend service (e.g., 'dasha', 'birthchart')
+                // and return a secondary Service Proxy
+                return new Proxy({}, {
+                    get: (_, methodName) => {
+                        // 3. Return an async function that performs the actual POST request
+                        return async (params = {}) => {
+                            // Note: backend expects direct routing /api/v1/serviceName/methodName
+                            return target._executeRequest(serviceName, methodName, params);
+                        };
+                    }
+                });
+            }
+        });
+    }
+
+    async _executeRequest(service, method, data, context = null) {
+        // Full Orchestration:
+        // 1. Build Envelope (Section 5)
+        // 2. Local Validation (Section 6)
+        // 3. Circuit Check (Section 7.C)
+        // 4. Interceptor onRequest Hook (Section 11.B)
+        // 5. Execute with Smart Retry (Section 7.B) - POST /api/v1/${service}/${method}
+        // 6. Metadata Sync & Handshake (Section 4.B)
+        // 7. Response Detective Format Analysis (Section 11.A)
+        // 8. Error Wrapping or Data Unwrapping (Section 11.B)
+    }
+}
+```
+
+## 3.1 Implementation: AstrologyApiClient.js
+
+```javascript
+// packages/api-client/src/AstrologyApiClient.js
+// Final Production Implementation satisfying Section 3 and 4 requirements
+const { v4: uuid } = require('uuid');
+
+class AstrologyApiClient {
+  constructor(config = {}) {
+    this.baseUrl = config.baseUrl || 'http://localhost:10000';
+    this.config = config;
+
+    // Proxy logic as defined in Section 3
+    return new Proxy(this, {
+      get: (target, serviceName) => {
+        if (serviceName in target) return target[serviceName];
+        return new Proxy({}, {
+          get: (_, methodName) => {
+            return async (params = {}) => target.call(serviceName, methodName, params);
+          }
+        });
+      }
+    });
+  }
+
+  asUser(platformUserId) {
+    let unifiedUserId = null;
+    let currentSessionId = null;
+
+    const ensureIdentity = async () => {
+      if (!unifiedUserId) {
+        // Reality: userMapping/mapPlatformToUnified (per Client Integration Guide)
+        const response = await fetch(`${this.baseUrl}/api/v1/userMapping/mapPlatformToUnified`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            platform: this.config.platform,
+            platformUserId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            },
+            // Align with integration guide: include all required fields
+            initialProfileData: {}
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        unifiedUserId = result.data.unifiedUserId;
+        // Update session ID if provided in response
+        if (result.data.sessionId) {
+          currentSessionId = result.data.sessionId;
+        }
+      }
+      return unifiedUserId;
+    };
+
+    return {
+      // Internal getters for consistent request payloads
+      _getUnifiedUserId: () => unifiedUserId,
+      _getPlatformUserId: () => platformUserId,
+
+      // Observability Interface: Direct routing to Backend ObservabilityService
+      observability: {
+        async incrementCounter(name, tags = {}) {
+          const userId = await ensureIdentity();
+          // Use the proxy architecture to call the backend observability service
+          return await fetch(`${this.baseUrl}/api/v1/observability/recordMetric`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              unifiedUserId: userId,
+              type: 'counter',
+              name,
+              tags: { ...tags, platform: this.config.platform },
+              requestId: uuid(),
+              timestamp: new Date().toISOString(),
+              client: {
+                type: this.config.clientType || 'api-client',
+                version: this.config.clientVersion || '1.0.0'
+              }
+            })
+          });
+        },
+
+        async recordHistogram(name, value, tags = {}) {
+          const userId = await ensureIdentity();
+          // Use the proxy architecture to call the backend observability service
+          return await fetch(`${this.baseUrl}/api/v1/observability/recordMetric`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              unifiedUserId: userId,
+              type: 'histogram',
+              name,
+              value,
+              tags: { ...tags, platform: this.config.platform },
+              requestId: uuid(),
+              timestamp: new Date().toISOString(),
+              client: {
+                type: this.config.clientType || 'api-client',
+                version: this.config.clientVersion || '1.0.0'
+              }
+            })
+          });
+        }
+      },
+
+      // Session access
+      async getSession() {
+        const userId = await ensureIdentity();
+        // Reality: sessionManager/getSessionState
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/getSessionState`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            }
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        currentSessionId = result.data.sessionId;
+
+        // Smart Unwrapping: Attach metadata as non-enumerable property
+        if (result.data && typeof result.data === 'object') {
+          Object.defineProperty(result.data, 'metadata', { value: result.metadata, enumerable: false });
+        }
+        return result.data;
+      },
+
+      // Lock management
+      async acquireSessionLock() {
+        const userId = await ensureIdentity();
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/acquireSessionLock`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            }
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        return true;
+      },
+
+      async releaseSessionLock() {
+        const userId = await ensureIdentity();
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/releaseSessionLock`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            }
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        return true;
+      },
+
+      // Session saving
+      async save(partialState) {
+        const userId = await ensureIdentity();
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/updateSessionState`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            sessionId: currentSessionId,
+            partialState,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            }
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+
+        // Smart Unwrapping: Attach metadata as non-enumerable property
+        if (result.data && typeof result.data === 'object') {
+          Object.defineProperty(result.data, 'metadata', { value: result.metadata, enumerable: false });
+        }
+        await this.releaseSessionLock();
+        return result.data;
+      },
+
+      // Service calls
+      async call(service, method, params = {}) {
+        const userId = await ensureIdentity();
+        // Reality: direct routing /api/v1/:service/:method with comprehensive platform context
+        const response = await fetch(`${this.baseUrl}/api/v1/${service}/${method}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            platform: this.config.platform,
+            platformUserId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            },
+            // Include additional context fields required by integration guide
+            initialProfileData: params.initialProfileData || {},
+            preferences: params.preferences || {},
+            birthData: params.birthData || {},
+            parameters: params.parameters || {},
+            ...params
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+
+        // Smart Unwrapping: Hand clean data but attach metadata as non-enumerable property for tracing
+        if (result.data && typeof result.data === 'object') {
+          Object.defineProperty(result.data, 'metadata', {
+            value: result.metadata,
+            enumerable: false
+          });
+        }
+        return result.data;
+      }
+    };
+  }
+}
+
+module.exports = AstrologyApiClient;
+```
+
+---
+
+## 4. Multi-User Identity & Session Isolation
+
+**CRITICAL:** To prevent data leakage in multi-user environments (WhatsApp), the client enforces strict context isolation. In a Node.js process, a single client instance with shared state would lead to User A's data leaking into User B's request.
+
+### A. Scoped Context Instances (`asUser`)
+The client uses a "Factory" pattern to create isolated instances for each unique user or conversation.
+*   **Isolation:** `client.asUser(id)` creates a unique instance with its own `sessionId` and `unifiedUserId`.
+*   **Security:** This ensures User A's metadata can **never** be sent in User B's request.
+
+```javascript
+// Scoped Factory Logic Implementation
+asUser(platformUserId) {
+    let context = this.contextStore.get(platformUserId); // O(1) Lookup
+    if (!context) {
+        context = {
+            platform: this.config.platform,
+            platformUserId,
+            sessionId: null,
+            unifiedUserId: null,
+            lastAccessed: Date.now()
+        };
+        this.contextStore.set(platformUserId, context);
+    }
+    // Returns a proxy instance bound strictly to this specific user context
+    return this._createScopedInstance(context);
+}
+```
+
+### B. Self-Healing Handshake & Auto-Sync
+The client is **"Self-Aware"** and watches every response from the backend to ensure the frontend stays in sync without manual code.
+1.  **Auto-Resolution:** If a context lacks `unifiedUserId`, the first call automatically triggers the `platformManager.getUnifiedUserId` handshake.
+2.  **Session Recovery:** On `SESSION_EXPIRED` (401), the client re-resolves identity and **automatically retries** the request once.
+3.  **Auto-Sync:** If the backend returns a new `sessionId` or `unifiedUserId` in the metadata, the client updates the Scoped Context in memory instantly.
+
+```javascript
+// Metadata Sync & Handshake logic
+async _handleSync(context, response) {
+    const { sessionId, unifiedUserId } = response.metadata || {};
+    
+    // Auto-Sync updated identifiers from metadata
+    if (sessionId) context.sessionId = sessionId;
+    if (unifiedUserId) context.unifiedUserId = unifiedUserId;
+
+    // Handle Session Expiration Handshake (401)
+    if (response.status === 'error' && response.error.code === 'SESSION_EXPIRED') {
+        const resolution = await this.platformManager.getUnifiedUserId({
+            platform: context.platform,
+            platformUserId: context.platformUserId
+        });
+        context.unifiedUserId = resolution.unifiedUserId;
+        context.sessionId = resolution.sessionId;
+        return true; // Signal the orchestrator to retry the original call
+    }
+    return false;
+}
+```
+
+---
+
+## 5. The Unified Request Envelope (Metadata & Tracing)
+
+**`requestId` is the sole identifier used for tracing and correlation across the entire system.** We do not use separate traceIds.
+
+### Data Injection Logic
+*   **`requestId`**: A unique UUID generated at the start of every operation. This is injected into **both the JSON payload and the `X-Request-ID` HTTP header** for end-to-end traceability through proxies, load balancers, and logs.
+*   **`timestamp`**: Current ISO-8601 string.
+*   **`client`**: Platform identifier (e.g., 'whatsapp', 'ios', 'android', 'pwa').
+*   **`sessionId` / `unifiedUserId`**: Automatically pulled from the active Scoped Context.
+
+```javascript
+// Envelope Packaging Implementation
+_buildEnvelope(context, businessData) {
+    const requestId = uuid(); 
+    return {
+        payload: {
+            requestId,
+            timestamp: new Date().toISOString(),
+            client: context ? context.platform : this.config.platform,
+            sessionId: context ? context.sessionId : null,
+            unifiedUserId: context ? context.unifiedUserId : null,
+            ...businessData
+        },
+        headers: {
+            'X-Request-ID': requestId, 
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.config.apiKey}` // Generic Auth Hook
+        }
+    };
+}
+```
+
+---
+
+## 6. Detailed Internal Data Flow
+
+| Step | Action | Responsibility | Logic Detail |
+| :--- | :--- | :--- | :--- |
+| **1. Call** | `user.dasha.get()` | Proxy | Intercept property access. |
+| **2. Check** | Identity Check | Manager | Check if `unifiedUserId` exists in context. |
+| **3. Resolve** | Handshake | Handshake | If missing, call `platformManager/getUnifiedUserId` (Handshake) first. |
+| **4. Envelope**| Packaging | Envelope | Inject `requestId`, `timestamp`, `sessionId`. |
+| **5. Header** | Tracing | Interceptor | Inject `X-Request-ID` and generic Auth headers. |
+| **6. Validate** | Validation | Shared Lib | Check input against `@astrology/shared` AJV schemas. |
+| **7. Request** | Execution | retry.js | Execute `fetch` (`/:service/:method`) with status-based retry logic. |
+| **8. Detect** | Analysis | Detective | Check `Content-Type` (JSON vs Text vs Binary). |
+| **9. Parse** | Processing | Shared Lib | If error, wrap in `ApiClientError`. If success, unwrap envelope. |
+| **10. Sync** | Updating | Sync | If backend issues new `sessionId`, update Context in memory. |
+| **11. Return** | Final Result | Proxy | Hand clean business data back to the UI. |
+
+---
+
+## 7. Advanced Reliability & Error Handling
+
+### A. AJV Path Mapping (ApiValidationError)
+The client translates raw AJV paths (e.g., `/birthData/time`) into clean UI-friendly nested objects, allowing the frontend to highlight specific fields easily.
+
+**Design Choice: The Client as a "Translator"**
+*   **Problem:** AJV returns "computer-speak" like `instancePath: "/birthData/date"`.
+*   **Solution:** The client translates this into "human-speak" like `{ birthData: { date: "Must be DD/MM/YYYY" } }`.
+*   **Result:** The UI developer can simply read the clean object and display the message directly on the corresponding input field.
+
+```javascript
+// src/utils/ApiClientError.js
+class ApiValidationError extends Error {
+    constructor(ajvErrors) {
+        super("Input Validation Failed");
+        this.name = 'ApiValidationError';
+        this.mappedErrors = {};
+        
+        ajvErrors.forEach(err => {
+            // Translates "/birthData/time" -> ['birthData', 'time']
+            const path = err.instancePath.split('/').filter(Boolean);
+            let current = this.mappedErrors;
+            
+            // Navigate/build nested object structure
+            for (let i = 0; i < path.length - 1; i++) {
+                current[path[i]] = current[path[i]] || {};
+                current = current[path[i]];
+            }
+            // Assign message: { birthData: { time: "Required field missing" } }
+            current[path[path.length - 1]] = err.message;
+        });
+    }
+}
+```
+
+### B. Smart Retry Strategy
+Not all errors are retryable. The client intelligently decides whether to retry or abort to save bandwidth and server resources.
+*   **RETRY (Exponential Backoff: 500ms -> 1s -> 2s):** 
+    *   Status 5xx (Internal Server Errors)
+    *   Status 408 (Request Timeout)
+    *   Network Connectivity failures
+*   **ABORT (Immediate Failure):**
+    *   Status 400 (Validation Errors)
+    *   Status 403 (Forbidden)
+    *   Status 404 (Not Found)
+*   **Special:** Status 401 triggers the Handshake logic before retrying.
+
+```javascript
+// src/utils/retry.js implementation
+const RETRYABLE_STATUSES = [408, 500, 502, 503, 504];
+
+async function executeWithRetry(fn, context) {
+    let attempt = 0;
+    while (attempt < 3) {
+        try {
+            return await fn();
+        } catch (error) {
+            // Only retry if status is in list or it's a network-level failure
+            if (!RETRYABLE_STATUSES.includes(error.status) && !error.isNetwork) throw error;
+            attempt++;
+            const delay = Math.pow(2, attempt) * 500; // Exponentially increasing wait
+            await sleep(delay);
+        }
+    }
+}
+```
+
+### C. Circuit Breaker Logic
+If a specific service (e.g., `dasha`) fails 5 consecutive times, the "circuit" trips for 30 seconds. All subsequent calls fail instantly at the client level with a `CircuitBreakerError` without hitting the network, protecting the backend from cascading failure.
+
+```javascript
+// src/utils/CircuitBreaker.js
+class CircuitBreaker {
+    constructor() {
+        this.failures = new Map(); // serviceName -> count
+        this.lastFailure = new Map(); // serviceName -> timestamp
+    }
+
+
+    check(service) {
+        if (this.failures.get(service) >= 5) {
+            const elapsed = Date.now() - this.lastFailure.get(service);
+            if (elapsed < 30000) throw new CircuitBreakerError(`${service} tripped`);
+            // Half-Open: Allow 1 request through after 30s
+            // If it succeeds, reset. If it fails, trip again.
+        }
+    }
+
+    recordSuccess(service) {
+        this.failures.set(service, 0); // Reset on success
+    }
+
+    recordFailure(service) {
+        const count = (this.failures.get(service) || 0) + 1;
+        this.failures.set(service, count);
+        this.lastFailure.set(service, Date.now());
+    }
+}
+```
+
+### D. Telemetry & User Drop-off Logs
+**Improvement:** The client aggressively logs `requestId` at every step to allow backend correlation.
+
+```javascript
+// src/utils/Interceptors.js
+onRequest(config) {
+   // Log the transition state before sending
+   logger.info({
+     msg: 'API Request Started',
+     requestId: config.headers['X-Request-ID'],
+     service: config.url,
+     // CRITICAL: Log who is attempting this call
+     userId: config.unifiedUserId,
+     dropoff_marker: 'REQUEST_INIT' // Used to find where users stop
+   });
+   return config;
+}
+```
+
+### D. Comprehensive Client Error Catalog
+
+The `api-client` maps specific backend error codes (as defined in `CLIENT_INTEGRATION_GUIDE.md` Sections 8.2 and 13) into distinct `ApiClientError` subclasses. This allows frontend clients to implement precise UI/UX responses without parsing raw backend messages.
+
+| Backend Error Code | `ApiClientError` Subclass | HTTP Status | Client UI Action / Resolution |
+| :--- | :--- | :--- | :--- |
+| `VALIDATION_ERROR` | `ApiValidationError` | 400 | Show detailed field-specific errors. |
+| `INVALID_BIRTH_DATA` | `ApiInvalidBirthDataError` | 400 | Prompt user to check birth details. |
+| `RATE_LIMIT_EXCEEDED`| `ApiRateLimitError`| 429 | Back off and warn user of high frequency. |
+| `EPHEMERIS_UNAVAILABLE`| `ApiEphemerisError` | 503 | "Calculation engine error," general retry. |
+| `AI_SERVICE_ERROR` | `ApiAIServiceError` | 503 | "Interpretation unavailable," show raw data only. |
+| `TIMEOUT_ERROR` | `ApiTimeoutError` | 504 | "Operation timed out," offer retry. |
+| `CALCULATION_ERROR` | `ApiCalculationError` | 500 | Generic calculation failure, standard retry. |
+| `DATABASE_ERROR` | `ApiDatabaseError` | 500 | Application persistence error, standard retry. |
+| `INTERNAL_ERROR` | `ApiInternalError` | 500 | Log `requestId`, show general retry message. |
+
+```javascript
+// src/utils/ApiClientError.js (Extended)
+class ApiClientError extends Error {
+    constructor(message, code, details = {}) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.details = details;
+    }
+}
+
+class ApiValidationError extends ApiClientError { /* ... existing implementation ... */ }
+class ApiInvalidBirthDataError extends ApiClientError { constructor(msg, details) { super(msg || "Invalid birth data", "INVALID_BIRTH_DATA", details); } }
+class ApiRateLimitError extends ApiClientError { constructor(msg, details) { super(msg || "Rate limit exceeded", "RATE_LIMIT_EXCEEDED", details); } }
+class ApiEphemerisError extends ApiClientError { constructor(msg, details) { super(msg || "Ephemeris service unavailable", "EPHEMERIS_UNAVAILABLE", details); } }
+class ApiAIServiceError extends ApiClientError { constructor(msg, details) { super(msg || "AI service unavailable", "AI_SERVICE_ERROR", details); } }
+class ApiTimeoutError extends ApiClientError { constructor(msg, details) { super(msg || "Operation timed out", "TIMEOUT_ERROR", details); } }
+class ApiCalculationError extends ApiClientError { constructor(msg, details) { super(msg || "Calculation failed", "CALCULATION_ERROR", details); } }
+class ApiDatabaseError extends ApiClientError { constructor(msg, details) { super(msg || "Database error", "DATABASE_ERROR", details); } }
+class ApiInternalError extends ApiClientError { constructor(msg, details) { super(msg || "Internal server error", "INTERNAL_ERROR", details); } }
+
+// The _executeRequest method (or similar) within AstrologyApiClient would translate HTTP errors:
+// ...
+// if (response.status === 400 && result.error.code === 'VALIDATION_ERROR') {
+//   throw new ApiValidationError(result.error.details.validationErrors);
+// } else if (response.status === 503 && result.error.code === 'EPHEMERIS_UNAVAILABLE') {
+//   throw new ApiEphemerisError(result.error.message);
+// }
+// ... and so on for other specific error codes.
+```
+
+### A. O(1) LRU Context Store
+Scoped instances are managed by a specialized `ContextStore` using a `Map` for fast lookup and a **Doubly Linked List** for LRU eviction. This ensures O(1) performance regardless of the number of concurrent users.
+*   **Safety Threshold:** The store emits alerts if the number of active contexts exceeds a configurable limit.
+
+```javascript
+class ContextStore {
+    constructor(limit) {
+        this.limit = limit;
+        this.cache = new Map(); // Fast O(1) lookup
+        this.head = null; // Most Recent
+        this.tail = null; // Least Recent
+    }
+
+    get(id) {
+        const node = this.cache.get(id);
+        if (node) this._moveToHead(node); // Keep LRU order
+        return node?.data;
+    }
+    
+    // Linked List logic ensures cleanup is also O(1)
+}
+```
+
+### B. Scalability under High Load (Memory Pressure)
+*   **High Water Mark (HWM):** The store monitors total heap usage. If usage exceeds **80%**, it enters **Aggressive Mode**.
+*   **Aggressive Mode Action:** The `Inactivity Timeout` is automatically halved (e.g., 15m -> 7.5m) to force-evict older contexts faster until memory stabilizes.
+
+```javascript
+// Memory Monitoring & Aggressive Eviction logic
+setInterval(() => {
+    const memory = process.memoryUsage();
+    const usageRatio = memory.heapUsed / memory.heapTotal;
+    
+    if (usageRatio > 0.8) { // 80% Threshold
+        this.emit('alert', 'Memory pressure detected. Entering Aggressive Mode.');
+        this.config.idleTimeout /= 2; // Shorten timeout
+        this.sweep(); // Run immediate cleanup cycle
+    }
+}, 30000); // Check every 30s
+```
+
+### C. Persistence Adapter & Sweep Cycle
+*   **Stateless Scaling:** Supports `PersistenceAdapter` to serialize context data to **Redis or MongoDB**. Allows multiple bot instances to share state.
+*   **Active Cleanup:** A background timer runs every 5 minutes (**Sweep Cycle**) to proactively delete contexts that have exceeded their `Idle Timeout`.
+
+---
+
+## 9. Performance & Observability (Deep Monitoring)
+
+### A. Intelligent Request Caching
+Built-in in-memory TTL cache for immutable astrology data (Birth Charts). Skips network calls for repeated identical requests within the TTL. Supports pluggable storage (Redis/LocalStorage).
+
+### B. Request Batching
+`client.batch([ ... ])` bundles multiple service calls into a single HTTP POST request. This is critical for reducing latency on mobile networks (3G/4G).
+
+```javascript
+// Request Batching logic
+async batch(calls) {
+    const payload = {
+        requestId: uuid(),
+        isBatch: true,
+        requests: calls.map(c => ({
+            service: c.service,
+            method: c.method,
+            params: c.params
+        }))
+    };
+    const response = await fetch(`${baseUrl}/batch`, { body: JSON.stringify(payload) });
+    return response.results;
+}
+```
+
+### C. Connection Pooling (Node.js / WhatsApp)
+When running in Node.js, the client uses a persistent `http.Agent` with `keepAlive: true` to reduce TCP/TLS handshake overhead for high-traffic bots.
+
+```javascript
+const http = require('http');
+const agentOptions = { 
+    keepAlive: true, 
+    maxSockets: 100, 
+    freeSocketTimeout: 30000 
+};
+this.agents = { http: new http.Agent(agentOptions) };
+```
+
+### D. Comprehensive Speed Profiling
+The client breaks down the request lifecycle into granular phases, allowing the frontend to identify where bottlenecks occur. Additional observability metrics include request success rate, error types, retry counts, and user-specific latency trends.
+
+```javascript
+const startTime = performance.now();
+// 1. Preparation Phase (Local)
+const req = this._buildEnvelope(data);
+const t0 = performance.now();
+
+// 2. Network Phase (Latency)
+const response = await fetch(...);
+const t1 = performance.now(); // TTFB (Time to First Byte)
+
+// 3. Transfer Phase (Payload)
+const body = await response.json();
+const t2 = performance.now(); // Processing Finish
+
+this.onMetrics({
+    requestId: req.payload.requestId,
+    prep_time: t0 - startTime,      // Serialization + Local Validation
+    latency_ttfb: t1 - t0,          // DNS + Connection + Server Waiting
+    transfer_time: t2 - t1,         // Downloading & Parsing Payload
+    total_duration: t2 - startTime,
+    success: true,
+    error_type: null,               // 'network', 'timeout', 'validation'
+    retry_count: 0,
+    user_id: this.context.unifiedUserId,
+    platform: this.config.platform
+});
+```
+
+### E. Advanced Error Aggregation & Health Reporting
+Following your `DiagnosticsTracker` pattern, the client aggregates failures by category to produce a real-time health snapshot of the SDK and Backend connection.
+
+```javascript
+// src/utils/DiagnosticsTracker.js logic
+recordError(type, requestId) {
+    // Categories: CONNECTION, SERVER, VALIDATION, IDENTITY
+    const category = this._mapToCategory(type); 
+    this.stats.errors[category] = (this.stats.errors[category] || 0) + 1;
+    this.stats.recent_failures.push({ category, requestId, timestamp: Date.now() });
+    
+    if (this.stats.recent_failures.length > 50) this.stats.recent_failures.shift();
+}
+
+getHealthReport() {
+    return {
+        uptime: process.uptime(),
+        error_distribution: this.stats.errors,
+        avg_latency: this.stats.avg_latency,
+        network_status: this.monitor.status, // online/flaky
+        usage: {
+            total_requests: this.stats.total_requests,
+            total_bytes_sent: this.stats.total_bytes_sent,
+            total_bytes_received: this.stats.total_bytes_received
+        }
+    };
+}
+```
+
+### F. HTTP/2 Multiplexing Support
+Update `AstrologyApiClient.js` to use Node.js `http2` module instead of `fetch` for backend calls. Configure agent with `http2.connect()` for multiplexing. This allows concurrent streams over one connection, reducing latency for batched requests. Test with backend supporting HTTP/2.
+
+---
+
+## 10. Network Condition & Adaptive Logic
+
+### A. Condition Monitoring (NetworkMonitor Implementation)
+The client detects flaky environments and spikes in latency to adjust its behavior dynamically.
+
+```javascript
+// src/utils/NetworkMonitor.js
+class NetworkMonitor {
+    constructor() {
+        this.latencyWindow = []; // Last 10 durations
+        this.status = 'stable';
+    }
+
+    observe(duration, success) {
+        this.latencyWindow.push(duration);
+        if (this.latencyWindow.length > 10) this.latencyWindow.shift();
+        
+        const avgLatency = this.latencyWindow.reduce((a,b) => a+b, 0) / this.latencyWindow.length;
+        
+        // Detect flaky network based on high average latency or recent failures
+        if (avgLatency > 5000 || !success) {
+            this.status = 'flaky';
+        } else {
+            this.status = 'stable';
+        }
+    }
+}
+```
+
+### B. Adaptive Timeouts
+```javascript
+// Logic to adjust timeouts based on detected network quality
+const getTimeout = (monitor) => {
+    if (monitor.status === 'flaky') return 60000; // Increase to 60s for flaky mobile
+    return 15000; // Standard 15s for server-to-server
+};
+```
+
+---
+
+## 11. Formatting & Compatibility
+
+### A. Response Detection (ResponseDetective)
+The client is compatible with the backend's diverse output formats (JSON, Plain Text, Binary). It checks the `Content-Type` header automatically.
+
+```javascript
+// Format Detection Implementation
+async detect(response) {
+    const type = response.headers.get('content-type') || '';
+    if (type.includes('application/json')) return response.json();
+    if (type.includes('text/plain')) return response.text(); // AI Chat responses
+    return response.arrayBuffer(); // Binary (Charts/PDFs)
+}
+```
+
+### B. Interceptors & Unwrapping
+*   **Global Interceptors:** hooks (`onRequest`, `onResponse`, `onError`) for centralized Authorization and tracing logic.
+*   **Envelope Unwrapping:** Natively handles the backend's `formatSuccessResponse` and `formatErrorResponse` utilities from `packages/backend/src/shared/responses.js`.
+
+### C. Message Formatter Logic
+Includes shared logic to structure chat responses (text, buttons, menus) consistently across WhatsApp and Mobile UIs, mirroring backend formatting.
+
+### D. Schema Awareness & Type Safety
+While the frontend logic is decoupled from schema files, the SDK provides "Type Safety" benefits:
+*   **Editor Hints:** The client can provide JSDoc/TypeScript hints about required fields based on backend schemas.
+*   **No Imports Required:** The frontend does *not* need to import `.json` schemas or AJV; the `api-client` encapsulates all enforcement and validation.
+
+---
+
+## 12. Usage Examples
+
+### WhatsApp Bot: Multi-User Scoped Flow
+```javascript
+const astrology = new AstrologyApiClient({ 
+    platform: 'whatsapp',
+    persistence: new RedisAdapter(process.env.REDIS_URL),
+    memory: { maxContexts: 10000, aggressiveModeThreshold: 0.8 },
+    onMetrics: (m) => logger.info(`Metric: ${m.requestId}`, m)
+});
+
+// Inside WhatsApp message handler
+async function onMessage(phoneNumber, text) {
+    const user = astrology.asUser(phoneNumber); // Isolated Scoped Context
+    try {
+        const dasha = await user.call('dasha', 'getDashaPredictiveAnalysis', { birthData });
+        reply(`Your current Dasha is ${dasha.mahadasha.lord}. RequestId: ${dasha.metadata.requestId}`);
+    } catch (e) {
+        if (e instanceof ApiValidationError) {
+            reply(`Field error: ${JSON.stringify(e.mappedErrors)}`);
+        } else if (e instanceof ApiRateLimitError) {
+            reply("Slow down! Too many requests.");
+        } else {
+            reply("An unexpected error occurred. Please try again.");
+        }
+    }
+}
+```
+
+### Mobile App: Batched & Efficient
+```javascript
+const client = new AstrologyApiClient({ platform: 'ios', cache: { enabled: true } });
+
+// Startup: Get everything in one network round-trip
+const [planets, dasha, summary] = await client.batch([
+    client.birthchart.calculateBirthChart(input),
+    client.dasha.getDashaPredictiveAnalysis(input),
+    client.astrologer.getSummary(input)
+]);
+```
+
+---
+
+## 13. API Versioning & Backward Compatibility
+
+To handle the evolution of the backend while supporting older frontend versions, the client implements a **Multi-Version Routing** strategy.
+
+### A. Default & Explicit Versioning
+The client defaults to `v1` (as configured in `config.js`), but allows overriding the version for specific calls or entire instances.
+
+```javascript
+// Global configuration
+const client = new AstrologyApiClient({ apiVersion: 'v1' });
+
+// Explicit override per call (via Proxy detection)
+await client.v2.dasha.getDashaPredictiveAnalysis({ ... }); 
+// Triggers POST /api/v2/dasha/getDashaPredictiveAnalysis
+```
+
+### B. Compatibility Mapping (Shim Layer)
+If a backend method name changes (e.g., `calculateDasha` becomes `getDashaAnalysis`), the client includes a local mapping to prevent breaking old frontend code.
+
+```javascript
+// src/config.js logic
+const COMPATIBILITY_MAP = {
+    'dasha.calculateDasha': 'dasha.getDashaPredictiveAnalysis',
+    'birthchart.getSummary': 'astrologer.interpretBirthChart'
+};
+
+// Internal Orchestration
+_resolveMethod(service, method) {
+    const mapped = COMPATIBILITY_MAP[`${service}.${method}`];
+    if (mapped) {
+        const [newService, newMethod] = mapped.split('.');
+        return { service: newService, method: newMethod };
+    }
+    return { service, method };
+}
+```
+
+## 3.1 Complete API Client Implementation with Backend Reality
+
+```javascript
+// packages/api-client/src/AstrologyApiClient.js
+// Final Production Implementation satisfying Section 3 and 4 requirements
+const { v4: uuid } = require('uuid');
+
+class AstrologyApiClient {
+  constructor(config = {}) {
+    this.baseUrl = config.baseUrl || 'http://localhost:10000';
+    this.config = config;
+
+    // Proxy logic as defined in Section 3
+    return new Proxy(this, {
+      get: (target, serviceName) => {
+        if (serviceName in target) return target[serviceName];
+        return new Proxy({}, {
+          get: (_, methodName) => {
+            return async (params = {}) => target.call(serviceName, methodName, params);
+          }
+        });
+      }
+    });
+  }
+
+  asUser(platformUserId) {
+    let unifiedUserId = null;
+    let currentSessionId = null;
+
+    const ensureIdentity = async () => {
+      if (!unifiedUserId) {
+        // Reality: userMapping/mapPlatformToUnified (per Client Integration Guide)
+        const response = await fetch(`${this.baseUrl}/api/v1/userMapping/mapPlatformToUnified`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            platform: this.config.platform,
+            platformUserId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            },
+            // Align with integration guide: include all required fields
+            initialProfileData: {}
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        unifiedUserId = result.data.unifiedUserId;
+        // Update session ID if provided in response
+        if (result.data.sessionId) {
+          currentSessionId = result.data.sessionId;
+        }
+      }
+      return unifiedUserId;
+    };
+
+    return {
+      // Internal getters for consistent request payloads
+      _getUnifiedUserId: () => unifiedUserId,
+      _getPlatformUserId: () => platformUserId,
+
+      // Observability Interface: Direct routing to Backend ObservabilityService
+      observability: {
+        async incrementCounter(name, tags = {}) {
+          const userId = await ensureIdentity();
+          // Use the proxy architecture to call the backend observability service
+          return await fetch(`${this.baseUrl}/api/v1/observability/recordMetric`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              unifiedUserId: userId,
+              type: 'counter',
+              name,
+              tags: { ...tags, platform: this.config.platform },
+              requestId: uuid(),
+              timestamp: new Date().toISOString(),
+              client: {
+                type: this.config.clientType || 'api-client',
+                version: this.config.clientVersion || '1.0.0'
+              }
+            })
+          });
+        },
+
+        async recordHistogram(name, value, tags = {}) {
+          const userId = await ensureIdentity();
+          // Use the proxy architecture to call the backend observability service
+          return await fetch(`${this.baseUrl}/api/v1/observability/recordMetric`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              unifiedUserId: userId,
+              type: 'histogram',
+              name,
+              value,
+              tags: { ...tags, platform: this.config.platform },
+              requestId: uuid(),
+              timestamp: new Date().toISOString(),
+              client: {
+                type: this.config.clientType || 'api-client',
+                version: this.config.clientVersion || '1.0.0'
+              }
+            })
+          });
+        }
+      },
+
+      // Session access
+      async getSession() {
+        const userId = await ensureIdentity();
+        // Reality: sessionManager/getSessionState (aligned with integration guide)
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/getSessionState`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: {
+              type: this.config.clientType || 'api-client',
+              version: this.config.clientVersion || '1.0.0'
+            }
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        currentSessionId = result.data.sessionId;
+
+        // Smart Unwrapping: Attach metadata as non-enumerable property
+        if (result.data && typeof result.data === 'object') {
+          Object.defineProperty(result.data, 'metadata', { value: result.metadata, enumerable: false });
+        }
+        return result.data;
+      },
+
+      // Lock management
+      async acquireSessionLock() {
+        const userId = await ensureIdentity();
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/acquireSessionLock`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: this.config.client || 'api-client'
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        return true;
+      },
+
+      async releaseSessionLock() {
+        const userId = await ensureIdentity();
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/releaseSessionLock`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: this.config.client || 'api-client'
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+        return true;
+      },
+
+      // Session saving
+      async save(partialState) {
+        const userId = await ensureIdentity();
+        const response = await fetch(`${this.baseUrl}/api/v1/sessionManager/updateSessionState`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            sessionId: currentSessionId,
+            partialState,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: this.config.client || 'api-client'
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+
+        // Smart Unwrapping: Attach metadata as non-enumerable property
+        if (result.data && typeof result.data === 'object') {
+          Object.defineProperty(result.data, 'metadata', { value: result.metadata, enumerable: false });
+        }
+
+        // Auto-release lock after save
+        await fetch(`${this.baseUrl}/api/v1/sessionManager/releaseSessionLock`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            unifiedUserId: userId,
+            requestId: uuid(),
+            timestamp: new Date().toISOString(),
+            client: this.config.client || 'api-client'
+          })
+        });
+        return result.data;
+      },
+
+      // Service calls
+      async call(service, method, params = {}) {
+        const userId = await ensureIdentity();
+        // Reality: direct routing /api/v1/:service/:method with comprehensive platform context
+        // Align with integration guide schema specifications
+        const response = await fetch(`${this.baseUrl}/api/v1/${service}/${method}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            // Top-level schema requirements from integration guide
+            requestId: uuid(), // Required: UUID for tracing
+            timestamp: new Date().toISOString(), // Required: ISO-8601 timestamp
+            platform: this.config.platform, // Required: enum [whatsapp, web, ios, android, pwa]
+            platformUserId, // Required: platform-specific user ID
+            client: this.config.client || { type: this.config.platform, version: '1.0' }, // Required: client object
+            unifiedUserId: userId, // Optional*: Required for fast path after registration
+            sessionId: this.currentSessionId, // Optional*: Required for continuity within journey
+            // Include additional context fields required by backend
+            initialProfileData: params.initialProfileData || {},
+            preferences: params.preferences || {},
+            parameters: params.parameters || {}, // Calculation-specific arguments
+            ...params
+          })
+        });
+        const result = await response.json();
+        if (result.status === 'error') throw new Error(result.error.message);
+
+        // Smart Unwrapping: Hand clean data but attach metadata as non-enumerable property for tracing
+        if (result.data && typeof result.data === 'object') {
+          Object.defineProperty(result.data, 'metadata', {
+            value: result.metadata,
+            enumerable: false
+          });
+        }
+        return result.data;
+      }
+    };
+  }
+}
+
+module.exports = AstrologyApiClient;
+```
+
+### Backend API Reality Integration
+
+The implementation includes several key enhancements that reflect the actual backend implementation:
+
+**Session Management Enhancements:**
+- **Auto-creation of sessions**: The backend automatically creates sessions if they don't exist, rather than failing
+- **Enhanced `getSessionState()` method**: Now auto-creates sessions if not found, ensuring continuity
+- **Improved error recovery**: More robust fallback mechanisms when sessions aren't found
+
+**Identity Resolution Improvements:**
+- **Deterministic unified ID format**: Changed from `unified_{timestamp}_{platform_abbrev}_{random_hash}` to `unified_{platformAbbr}_{identityHash}` for consistency
+- **Enhanced phone canonicalization**: Better validation and error handling for phone numbers
+- **Improved fallback mechanisms**: Better handling when user mapping fails
+
+**Schema Validation Updates:**
+- **ServiceRegistry integration**: Automatic schema inference based on service/method names
+- **Enhanced validation middleware**: More sophisticated validation with custom mappings
+- **Better error responses**: More detailed validation error messages
+
+**Error Handling Improvements:**
+- **Comprehensive custom error classes**: Detailed AstrologyError subclasses with proper HTTP status codes
+- **Better error response format**: More consistent responses with proper metadata
+- **Enhanced observability**: Better integration with observability services
+
+**API Structure:**
+- **Method-based routing**: Fully implemented at `/api/v1/:service/:method`
+- **Health checks**: Comprehensive health check endpoints at `/api/v1/health`
+- **Documentation endpoints**: Available API documentation at `/api/v1/docs`
+- **Service discovery**: Available at `/api/v1/:service/methods` and `/api/v1/:service/methods/:method`
+
+### Request Envelope Schema Compliance
+
+The API client ensures all requests comply with the integration guide's schema specifications:
+
+**Top-Level Schema Requirements:**
+| Field | Type | Required | Format | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `requestId` | String | **YES** | UUID | Must be unique per call. |
+| `timestamp` | String | **YES** | date-time | Client-side ISO-8601 string. |
+| `platform` | String | **YES** | enum | `whatsapp`, `web`, `ios`, `android`, `pwa`. |
+| `platformUserId` | String | **YES** | string | The ID from the platform. |
+| `client` | Object | **YES** | object | `{ "type": "ios", "version": "1.0" }`. |
+| `unifiedUserId` | String | No* | string | Required for Fast Path after registration. |
+| `sessionId` | String | No* | string | Required for continuity within a journey. |
+| `birthData` | Object | No* | object | Required for first calculation if not registered. |
+| `initialProfileData`| Object | No | object | Use for any profile updates or seeding. |
+| `parameters` | Object | No | object | Calculation-specific arguments. |
+
+**Birth Data Schema (Calculation Input):**
+| Field | Type | Required | Pattern/Format | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `date` | String | **YES** | `DD/MM/YYYY` | Must include leading zeros (e.g., `05/01/1990`). |
+| `time` | String | **YES** | `HH:MM` | 24-hour format (e.g., `14:30`). No seconds. |
+| `place` | String | **YES** | Min 3 chars | Name of the city/country. |
+| `coordinates` | Object | No | object | `{ "latitude": 19.0, "longitude": 72.8 }`. |
+| `timezone` | String | No | string | IANA string (e.g., `Asia/Kolkata`). |
+
+**Profile Data Schema (Update/Seeding):**
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `firstName` | String | User's first name. |
+| `lastName` | String | User's family name. |
+| `email` | String | Valid email address. |
+| `phone` | String | E.164 format phone number (e.g., `+1...`). |
+---
+
+## 14. Microservices & Gateway Routing (Future-Proofing)
+
+The client is designed to handle the transition from a bundled backend to a debundled microservices architecture without requiring changes to the frontend business logic.
+
+### Scenario A: The API Gateway (Default)
+In this scenario, all microservices are routed through a single entry point (e.g., Nginx or Cloudflare).
+*   **Routing:** The gateway handles `/dasha/*` vs `/ai/*`.
+*   **Client Status:** **Zero changes needed.** The client continues to use a single `baseUrl`.
+
+### Scenario B: Distributed Microservices
+In this scenario, every service has its own public URL (e.g., `dasha.api.com`). The client is "Discovery Ready" via its Proxy pattern.
+
+```javascript
+// Future Configuration for Distributed Services
+const client = new AstrologyApiClient({
+    baseUrl: 'https://gateway.api.com/api/v1',
+    services: {
+        dasha: 'https://dasha-service.internal/api/v1',
+        ai: 'https://ai-service.internal/api/v1',
+        birthchart: 'https://calculation-cluster.internal/api/v1'
+    }
+});
+
+// Internal Proxy Selection Logic
+_resolveUrl(serviceName) {
+    // If a specific URL is mapped for the service, use it; otherwise fallback to baseUrl.
+    return this.config.services[serviceName] || this.config.baseUrl;
+}
+```
+
+### The "Insurance Policy"
+Because your frontend code always uses `client.serviceName.methodName()`, we can move `dasha` from the main server to its own cluster tomorrow, update the `services` map in the client config once, and your WhatsApp/iOS apps will keep working perfectly without a single line of their code being modified.