Market Intelligence Integration

This document explains how Zeron's feedback service integrates with the market intelligence hub to update business intelligence reports with real customer data.

Vision

Business intelligence reports typically start with assumptions about markets, customers, and competitors. As you bring your product to market and gather customer feedback, these assumptions should be validated or refuted with real-world evidence.

The integration creates an intelligence feedback loop:

Generate initial report with market research and assumptions
Take product to market and gather customer conversations
Update report with real customer objections, traction data, and competitive intelligence
Feed into strategic planning through knowledge graph integration

Architecture

┌─────────────────────┐         REST API          ┌──────────────────────┐
│                     │   ────────────────────>    │                      │
│  Feedback Service   │                            │  Market Intelligence │
│                     │   <────────────────────    │         Hub          │
│  (Customer Data)    │    Updated Reports         │   (AI Analysis)      │
└─────────────────────┘                            └──────────────────────┘
         │                                                    │
         │                                                    │
         v                                                    v
    ┌──────────┐                                        ┌──────────┐
    │   Neo4j  │<───────────────────────────────────────│ Reports  │
    │   Graph  │   Ingest updated intelligence          │ Database │
    └──────────┘                                        └──────────┘

Design Decision: REST APIs over Redis Pub/Sub

We chose REST APIs for portability:

✅ Works locally and in production (just change URL)
✅ Functions in serverless environments
✅ Standard patterns for testing and debugging
✅ No shared infrastructure requirements

Integration Patterns

Pattern 1: Threshold-Based Updates

Update reports when you have sufficient data:

javascript

const FEEDBACK_THRESHOLD = 20; // Update after 20 new conversations

async function checkAndUpdateIntelligence(projectId) {
  const conversationCount = await getNewConversationCount(projectId);

  if (conversationCount >= FEEDBACK_THRESHOLD) {
    const aggregatedFeedback = await aggregateFeedback(projectId);
    const reportId = await getReportIdForProject(projectId);

    await intelligenceClient.updateReport(reportId, {
      additionalContext: aggregatedFeedback,
      metadata: { conversationCount }
    });

    // Reset counter
    await resetConversationCount(projectId);
  }
}

Pattern 2: Scheduled Updates

Update reports on a regular schedule (weekly, monthly):

javascript

// In a scheduled job (cron, etc.)
async function weeklyIntelligenceUpdate() {
  const projects = await getActiveProjects();

  for (const project of projects) {
    const reportId = project.intelligenceReportId;
    if (!reportId) continue;

    const weeklyFeedback = await aggregateFeedbackForWeek(project.id);

    await intelligenceClient.updateReport(reportId, {
      additionalContext: weeklyFeedback,
      updateInstructions: 'Weekly feedback synthesis',
      metadata: {
        dateRange: {
          start: getLastWeekStart(),
          end: new Date()
        }
      }
    });
  }
}

Pattern 3: Event-Driven Updates

Update immediately on significant events:

javascript

// After a critical customer conversation
async function handleCriticalFeedback(conversationId) {
  const conversation = await getConversation(conversationId);

  if (conversation.tags.includes('competitor_intel') ||
      conversation.tags.includes('pricing_objection')) {

    const reportId = await getReportIdForProject(conversation.projectId);

    await intelligenceClient.updateReport(reportId, {
      additionalContext: `
        URGENT FEEDBACK:
        ${conversation.summary}

        Source: ${conversation.customerRole} at ${conversation.companySize}-person company
        Date: ${conversation.createdAt}
      `,
      updateInstructions: 'Incorporate this urgent competitive intelligence'
    });
  }
}

Data Quality Improvements

Conservative Assumptions

When generating reports WITHOUT customer data, the AI uses conservative assumptions:

Competitor Pricing: "Based on publicly available information"
Persona Demographics: "Typical decision-makers in this role..." (not specific ages)
Market Sizing: "Industry analysts estimate..." with source caveats
Financial Projections: "Preliminary estimates requiring validation"

High Confidence Data

When you provide customer feedback, the AI treats it as validated facts:

Optional Input Fields:

Competitor Intelligence: Known pricing, features, positioning
Current Traction: Real customer numbers, revenue, pipeline data
Known Challenges: Actual customer objections and market feedback

Example Update:

javascript

await intelligenceClient.updateReport('report-id', {
  additionalContext: `
    Customer Feedback Summary (23 conversations, Nov 1-11):

    **Common Objections**:
    - "Why not just hire a dev team?" (mentioned 12 times)
      → Response pattern: Cost comparison analysis
    - "What if you go out of business?" (mentioned 8 times)
      → Customers want code ownership guarantee

    **Validated Traction**:
    - 3 paying customers at target pricing tier
    - 12 qualified leads in pipeline (avg company size: 150 employees)
    - $18,750 total MRR

    **Competitor Intelligence** (from customer conversations):
    - Competitor A pricing confirmed: $6,500-50k/year (4 customers mentioned)
    - Competitor B: $11-15/user/month (2 customers confirmed)
    - Implementation time: 3 months vs our 2-4 weeks
  `,
  metadata: {
    conversationCount: 23,
    dataSourceTypes: ['customer_conversations', 'sales_calls'],
    dateRange: {
      start: new Date('2025-11-01'),
      end: new Date('2025-11-11')
    }
  }
});

Version History & Evolution

Every update creates a new version with changes summary:

javascript

// View how report evolved over time
const versions = await intelligenceClient.getVersions('report-id');

versions.data.versions.forEach(v => {
  console.log(`
    Version ${v.versionNumber} (${v.versionType})
    Created: ${new Date(v.createdAt).toLocaleDateString()}
    Changes: ${v.changesSummary || 'Original report'}
    Recommendation: ${v.recommendation}
  `);
});

Version Types:

original - Initial AI-generated report
supplemented - Updated with customer feedback
corrected - Manual corrections or refinements

Knowledge Graph Integration

Updated reports can be ingested into Neo4j for strategic planning:

javascript

// Fetch updated report
const report = await intelligenceClient.getReport('report-id');

// Ingest into knowledge graph
await graphService.ingestIntelligenceReport(report.data.report);

This allows you to:

Connect customer feedback to market assumptions
Track validation/refutation of initial hypotheses
Build strategic context from real-world data
Inform product and go-to-market decisions

API Endpoints

Update Report

POST /api/intelligence/reports/:id/update

Body:
{
  "additionalContext": "Customer feedback summary...",
  "updateInstructions": "Focus areas...",
  "metadata": {
    "conversationCount": 23,
    "dataSourceTypes": ["customer_conversations"],
    "dateRange": { "start": "...", "end": "..." }
  }
}

Returns: Updated report + changes summary + new version number

Get Report

GET /api/intelligence/reports/:id

Returns: Complete business intelligence report

Get Versions

GET /api/intelligence/reports/:id/versions

Returns: Array of versions with changes over time

List Reports

GET /api/intelligence/reports?projectId=<id>&limit=20

Returns: List of reports with pagination

Error Handling

The integration is designed to fail gracefully:

javascript

try {
  await intelligenceClient.updateReport(reportId, data);
} catch (error) {
  if (error.message.includes('404')) {
    console.error('Report not found - create a new one first');
  } else if (error.message.includes('400')) {
    console.error('Invalid data format - check additionalContext');
  } else {
    console.error('Intelligence API unavailable - queue for retry');
  }
}

Future Enhancements

Planned Features:

Automatic report creation when feedback service starts collecting data for a new project
Confidence score tracking to see how reports improve with more data
Diff visualization showing what changed between versions
Feedback loop metrics tracking report accuracy improvements

Example: Full Workflow

javascript

// 1. Start with initial market research report
const initialReport = await intelligenceClient.generateReport({
  businessIdea: "...",
  targetMarket: "...",
  competitorIntel: "Preliminary research from public sources"
});

// 2. Take product to market, collect feedback
// ... months of customer conversations ...

// 3. Update report with real customer data
const updatedReport = await intelligenceClient.updateReport(initialReport.id, {
  additionalContext: `
    30 customer conversations revealed:
    - Pricing sweet spot: $X-Y/month (not our assumed $Z)
    - #1 objection: Integration complexity (not pricing as assumed)
    - Competitor X actually charges 2x market rate (we assumed market rate)
  `,
  updateInstructions: 'Validate pricing assumptions and competitive positioning'
});

// 4. Ingest into Neo4j for strategic planning
await graphService.ingestIntelligenceReport(updatedReport.report);

// 5. Track evolution over time
const versions = await intelligenceClient.getVersions(initialReport.id);
console.log(`Report evolved through ${versions.data.versions.length} versions`);

Design Principles

Evidence-Based: Real customer data trumps assumptions
Transparent: Clear distinction between inferred and validated data
Portable: REST APIs work locally and in production
Versioned: Track how understanding evolves over time
Integrated: Feeds into strategic planning via knowledge graph

Market Intelligence Integration ​

Vision ​

Architecture ​

Integration Patterns ​

Pattern 1: Threshold-Based Updates ​

Pattern 2: Scheduled Updates ​

Pattern 3: Event-Driven Updates ​

Data Quality Improvements ​

Conservative Assumptions ​

High Confidence Data ​

Version History & Evolution ​

Knowledge Graph Integration ​

API Endpoints ​

Update Report ​

Get Report ​

Get Versions ​

List Reports ​

Error Handling ​

Future Enhancements ​

Planned Features: ​

Example: Full Workflow ​

Design Principles ​

Related Documentation ​

Market Intelligence Integration

Vision

Architecture

Integration Patterns

Pattern 1: Threshold-Based Updates

Pattern 2: Scheduled Updates

Pattern 3: Event-Driven Updates

Data Quality Improvements

Conservative Assumptions

High Confidence Data

Version History & Evolution

Knowledge Graph Integration

API Endpoints

Update Report

Get Report

Get Versions

List Reports

Error Handling

Future Enhancements

Planned Features:

Example: Full Workflow

Design Principles

Related Documentation