Skip to content

Architectural Patterns & Playbooks

This document outlines how Alpha Pebble engineering playbooks are applied to the Pebble Orchestrator (Pebble IQ). To understand how we separate Data, Process, and Commercials, see Section 8: Functional Boundaries.

1. Enterprise Context Layer

Problem: "The Heterogeneity Problem." Sales data lives in emails, financial data in ERP (Focus RT/BC), and relationship data in CRM (D365). No single system sees the whole picture.

Pebble Solution:

We treat the Kanban Card as the UI perspective of the Workflow Layer, acting as a Universal Context Container.

  • Signals: It stitches together the Email (unstructured signal), the ERP Order Status (transactional signal), and the CRM Master/Masters data (industrial identity).
  • Implementation: The ProcessInboxUseCase orchestrator aggregates these disparate IDs (MessageID, MasterID, OrderID) into a single KanbanCard entity.
  • Hierarchical Triage: Implements a 2-Level Queue (Global Controller -> Department HOD) to ensure no ambiguous signal lands in a staff inbox without human or high-confidence AI verification.
  • Value: When a user looks at the board, they see the whole customer context, breaking down the silos between Sales, Logistics, and Finance.

2. Precedent Engineering

Problem: "Dark Context." Why did we give a 5% discount? Why did we pick Supplier B over Supplier A? This reasoning is buried in email threads or Slack chats and lost to the ERP.

Pebble Solution:

We use AI (Ralph/Ollama) to extract "Decision Traces" from unstructured communications.

  • Tracing: When an email says "Approved discount due to bulk volume," the AI extracts this reason and appends it to the Kanban Card's metadata as a structured "Decision Note."
  • Audit Trail: This turns ephemeral approvals into permanent audit records.
  • Value: Future price searches ("Why did we quote X last time?") return not just the price, but the reasoning (Precedent) behind it.

3. Activity-Stream Engineering

Problem: Static Database Records. A CRM "Status" is a snapshot in time. It doesn't tell the story of how we got there or allow for different teams to view the same data differently.

Pebble Solution:

We treat business events as an Immutable Activity Stream.

  • Events: EmailReceived, LeadClassified, QuoteRequested, OrderDispatched.
  • Perspective Engines:
    • Sales Lens: Views the stream as a Funnel (New -> Won).
    • Logistics Lens: Views the same stream as a Dispatch Schedule (Ordered -> Shipped).
    • Compliance Lens: Views it as a Risk Alert stream (New Customer -> KYC Verified).
  • Implementation: The underlying event log (stored in Database) is the source of truth; the Kanban Board is just one perspective on that stream.

4. Lead-to-Enquiry State Machine (FSM)

Problem: "Process Leaks." Leads stall in "Pending" or move to "Qualified" without valid IDs, leading to downstream compliance failures in Tally/ERP.

Pebble Solution:

We implement a Finite State Machine (FSM) pattern for the Workflow Layer to ensure structural integrity and process isolation from the CRM Masters.

  • Deterministic Transitions: A lead cannot move to Enquiry without passing through Validation (CIN/PAN) and Contacted states.
  • Validation Gates: Integration with MCA/GST APIs acts as a "hard gate." If validation fails, the transition to Qualified is blocked.
  • Terminal Catch-Alls: All unsuccessful leads are funneled into structured terminal states (Junk, Fake, Barred) for future re-extraction training.
  • Value: Ensures 100% data hygiene before any record reaches the Tally/ERP integration layer in Phase 1.

5. Agentic Orchestration (LangGraph)

Problem: "The Decision Bottleneck." Staff wait for owner approval or lack technical knowledge to reply to complex B2B enquiries (pricing, chemicals, compliance).

Pebble Solution: We utilize an Agentic DAG (Directed Acyclic Graph) pattern to manage the "Staff Decision Support" journey.

  • Stateful Persistence: Maintaining context across multi-turn email clarifications.
  • Conditional Routing: Nodes that dynamically switch between CRM (Leads), ERP (Tally Stock), and Tenders based on LLM intent.
  • Decision-Ready Inputs: AI gathers all info (Stock in Tally + Ledger Dues + Past Quotes) and presents a Draft Reply for staff to approve.
  • Value: Reduces owner dependency by 70-80% on routine sales/ops emails.

Technical Foundational Base

We adopt patterns from frontier OSS projects: - LangGraph email automation: For grounded RAG and tool-calling flows. - Semantic mail systems: For local embedding-based context retrieval.

6. Unified Enterprise Intelligence

Problem: "The Search Paradox." A search in Outlook won't find the ERP order, and a search in the ERP won't find the email thread where the discount was discussed.

Pebble Solution:

We implement a Unified Semantic Index that bridges data silos across the organization.

  • Unified Semantic Search: A single portal to search across unstructured data (emails, PDFs) and structured data (CRM, ERP).
  • Signal-Stream Clustering: Automatically grouping related signals (e.g., all emails + quotes + orders related to "Project X") into a single, cohesive feed.
  • Retrieval-Augmented Intelligence: An AI layer that answers questions based exclusively on "grounded" organizational data, providing traceable citations to the original source.
  • Knowledge Graph: Named Entity Recognition (NER) creates relational links between customers, orders, and communications.
  • Value: Instead of asking "Where is that file?", users ask "What is the status of the tender for ABC Corp?" and get a consolidated view of all relevant emails, cards, and ERP data.

7. Semantic Continuity Architecture

Problem: "The Connectivity Illusion." We connect systems (API A talks to API B), but we don't connect meaning. The AI doesn't know that "Invoice Pending" in Tally means "Credit Blocked" in CRM.

Pebble Solution:

We implement Semantic Continuity to bridge the gap between technical connectivity and business reality, using a three-tiered ontology.

Tier 1: Structure (System of Record)

The "What" — Raw Data.

  • Source: Postgres, Tally XML, Outlook API.
  • Definition: The unopinionated brute facts. table: orders, column: status, value: 04.
  • Role: High integrity, low intelligence.

Tier 2: Meaning (Enterprise Taxonomy)

The "Why" — Business Reality.

  • Source: Pebble Logic Layer / Configuration.
  • Definition: The human-readable labels that define business health.
    • 04 = "Shipment Delayed".
    • "Credit Blocked" = "Total Outstanding > Credit Limit".
  • Role: Operational clarity.

Tier 3: Connection (Universal Ontology)

The "How" — AI-Native Intelligence.

  • Source: Vector Store (Chroma/Pinecone) + Knowledge Graph.
  • Definition: The graph that maps the Structure to the Meaning.
  • Capability: When an AI agent asks "Is this customer healthy?", it traverses the graph:
    1. Query: "Customer Health".
    2. Ontology Map: Health = (No Credit Block) AND (Recent Orders > 0).
    3. Retrieval: Fetches Tally Ledger Balance + CRM Order History.
    4. Answer: "Healthy. Last order 2 days ago, balance clear."
  • Value: AI agents reason like a Senior Manager, not just a database query tool.

8. Functional Boundaries: CRM vs Workflow vs CPQ

To maintain structural integrity during the POC and future phases, we enforce strict architectural boundaries between the Data (Masters), Process (Workflow), and Commercials (CPQ) layers.

Layer Type Responsibility Analogy
CRM & Masters DATA Identity, Compliance (GST/CIN), and Multi-location Profiles. The "ID Card"
Workflow Logic PROCESS State Machine, Qualification Gates, and Work-shifting Rules. The "Checkpost"
CPQ Engine COMMERCIAL Landed Costing, Margin Governance, and PDF PDF PDF Quoting. The "Billing Counter"
  • CRM Masters (Phase 1): The static source of truth for "Who" we are dealing with.
  • Workflow Logic (Phase 2): The dynamic "HOW" cards move from New to Qualified.
  • CPQ Execution (Phase 2): The final "WHAT" is being sold and at what margin.

9. Incremental Automation (Shadow to Autopilot)

Problem: "The Trust Gap." High-stakes B2B decisions cannot be fully automated from Day 1. One "hallucinated" price or misrouted email can lead to significant business loss.

Pebble Solution: We implement a Human-in-the-Loop (HITL) Learning Engine designed to transition from a "Shadow" tool to an "Automated Partner."

9.1 The "Trust but Verify" Layer (Pending States)

Instead of the AI moving cards secretly, we use a Pending State visual indicator: - AI Action: The AI "tags" an email and places it on the board. - Ghost State: The card appears with a grayed-out "Pending Approval" status. - Feedback Loop: - Approve (Check): Reinforces the model (Positive Reinforcement). - Reject (Cross): Triggers a "Why?" Questionnaire. The user's text answer is logged as a specific correction for future fine-tuning.

9.2 "Shadow Memory" (Dual-Database Architecture)

To ensure the system gets robust over a year, we separate deterministic rules from learned memory: - Database A (The Rules): Hard-coded "If/Then" logic (e.g., Domain-based routing). Highest priority, zero learning. - Database B (The Memory): Vector Store saving email text + "Why" rejection reasons. - Weekly Fine-Tuning: A scheduled loop that retrains the classifier based on the validated mappings in Database B.

9.3 Unified Knowledge Transfer

The implementation of the Master Sheet (Intent → Action → Steps) ensures that business logic is "Universal." - Knowledge Portability: If the HOD defines a rule for "Invoice Processing," it becomes a system-wide SOP that the AI follows deterministically, regardless of which department handles the email.

← Back to Architecture Index