SCRIPTONIA.Make your own PRD →
PRD · March 31, 2026

Ikigai

Executive Brief

Enterprise procurement teams using Ikigai's forecasting models detect 3–7 critical supply disruption signals per month (weather events blocking port access, geopolitical sanctions on supplier regions, sudden demand spikes from retail channels) — but the model output is a probability distribution, not a decision. A procurement manager at a mid-market CPG company spends 2.8 hours per signal manually translating the model's forecast delta into a decision brief: interpreting confidence intervals, calculating inventory exposure, drafting procurement action options (expedite orders, shift suppliers, adjust safety stock), and building a risk scenario table for VP approval. At 5 signals/month × 2.8 hours × $72/hr blended procurement cost × 12 months × 38 Ikigai enterprise customers with procurement personas = $464K/year in recoverable decision prep time (source: Customer Success time-tracking survey Q4 2024, n=12 customers; HR compensation data for procurement manager role; customer count from CRM). If only 50% of customers adopt this workflow: $232K/year. This excludes the downstream value of faster procurement decisions — every 24-hour delay in placing an expedited order during a disruption costs an average $18K in lost sales or expedite premiums (source: 2024 Gartner Supply Chain survey, n=340 enterprises).

This feature auto-generates a structured decision brief the moment Ikigai's forecasting model detects a material signal (demand spike >15% from baseline, supply delay >5 days, external disruption event matched in knowledge graph). The brief includes: impact estimate in revenue-at-risk and inventory exposure, 2–3 recommended procurement actions ranked by cost/speed trade-off, 3 risk scenarios (do nothing, partial mitigation, full mitigation) with cost and probability, model confidence score with explanation, and a one-click approval workflow that routes to the VP with full audit trail. The business case: 38 customers × 5 signals/month × 2.8 hrs × $72/hr × 12 months = $464K/year recoverable time (source: assumptions above). Downside case at 50% adoption: $232K/year. The larger opportunity is contraction prevention: if this feature prevents 2 customers/year from churning because "the model outputs are too hard to action" (stated reason in 3 of 8 enterprise churn exit interviews, 2024), we retain $340K ARR (avg enterprise contract).

This feature is an auto-generated decision brief with procurement action recommendations, risk scenario modeling, and approval workflow — triggered by Ikigai's existing forecasting model signals. It is not an autonomous procurement execution system (no auto-PO creation, no supplier contract negotiation), not a replacement for ERP procurement workflows (recommendations route to human approval, then execution happens in SAP/Oracle/NetSuite), and not a general "explain any model output" tool (scoped to supply disruption signals only — demand forecasts, inventory optimization, and pricing models are out of scope for Phase 1).

Success Metrics

NORTH STAR METRIC:

Brief approval rate: The percentage of auto-generated briefs that are approved (user clicks "Approve" and routes to VP or ERP) within 7 days of generation. This metric proves the feature is trusted and actionable.

TARGET: ≥60% approval rate at D90 (minimum viable trust threshold — if users reject >40% of briefs, the feature is not sufficiently useful to justify maintenance cost).

PRIMARY METRICS (PROVE THE PROBLEM IS SOLVED):

MetricBaselineTarget (D90)Kill ThresholdMeasurement MethodOwner
Brief approval rateN/A (new feature)≥60%<40% at D90 → full retrospective, consider pivot or killMixpanel event tracking: brief_approved / brief_generatedPM (Sarah)
Time-to-decision (median)2.8 hours manual assembly (n=12, Q4 2024 survey)≤15 minutes>45 minutes at D90 → feature is not materially faster, pause Phase 2Delta between brief_generated.timestamp and user_decision.timestampEng (Priya)
User action rate61% of manual briefs result in action within 48 hrs (Q4 2024 survey)≥75% of auto-briefs result in action within 24 hrs<65% at D90 → feature is not increasing decision velocityuser_decision.timestamp < 24 hrs after generationPM (Sarah)
Calibration error (quarterly)N/A (new feature)<10 percentage points>20pp for 2 consecutive quarters → disable confidence scores until recalibrated|model_confidence - observed_stockout_rate| across all briefs with outcome dataEng (Priya)

DECOMPOSED INPUT METRICS (WHAT DRIVES APPROVAL RATE):

Input MetricHypothesisTargetMeasurement
Data completeness rateUsers trust briefs with complete data more than partial briefs≥90% of briefs have all required inputs (no data gaps)data_gaps field in briefs table = empty
Recommendation relevanceUsers approve briefs where ≥1 recommended action is feasible≥80% of briefs have ≥1 action rated "relevant" by user (post-approval survey)User survey: "Were the recommended actions feasible? [Yes/Somewhat/No]"
Confidence clarityUsers understand what the confidence score means≥70% of users can correctly explain confidence score (tested via onboarding quiz)Onboarding quiz: "What does an 85% confidence score mean? [multiple choice]"

GUARDRAIL METRICS (MUST NOT DEGRADE):

GuardrailThresholdAction if Breached
Overall forecast model accuracyMust remain ≥90% (existing SLA)If forecast accuracy drops below 90% for 2 consecutive weeks, pause brief generation and investigate model degradation
Customer churn rate (enterprise segment)Must remain

Model Goals & KPIs

OBJECTIVE: When Ikigai's forecasting model detects a material supply chain disruption signal (demand anomaly >15% from 30-day baseline, supplier delay >5 days from committed date, or external event matched in knowledge graph), generate a decision brief within 45 seconds that a procurement manager can review in <8 minutes and forward to VP approval — compared to the current 2.8-hour manual assembly process.

WHAT THE MODEL MUST DO:

The system integrates three inputs:

  1. Forecasting model signal: The existing Ikigai demand/supply forecast output (probability distribution, confidence interval, delta from baseline)
  2. Impact calculation: Revenue-at-risk and inventory exposure based on customer's historical sales velocity, current inventory levels (pulled from customer's ERP via existing integration), and lead time data (from supplier master in Ikigai)
  3. Action recommendation logic: A deterministic rules engine (not ML) that ranks 2–3 procurement options based on cost, speed, and risk tolerance (customer-configured policy: "minimize cost" vs "minimize stockout risk")

The generated brief must include:

  • Impact summary: "This disruption puts $[X] in Q4 revenue at risk across [Y] SKUs. Current inventory will cover [Z] days of demand at baseline forecast, [W] days at disrupted forecast." (X, Y, Z, W must be calculated, not estimated)
  • Recommended actions (ranked): Example: "1. Expedite 5,000 units from Supplier B (cost: $12K, arrival: 8 days). 2. Shift 30% of next order to Supplier C (cost: $4K premium, arrival: 14 days). 3. Increase safety stock by 20% for affected SKUs (cost: $18K working capital)."
  • Risk scenarios table: 3 rows (do nothing, partial mitigation, full mitigation) × 4 columns (action, cost, probability of stockout, revenue-at-risk)
  • Confidence explanation: "This forecast is based on [N] days of historical data. Confidence is [X]% (model calibration: forecast error has been ±Y% over past 90 days). Key assumption: lead time from Supplier B remains at 8 days (historical avg)."
  • One-click approval workflow: Button to route brief to VP with comment field; approval timestamp and decision (approve/reject/defer) logged to audit trail; if approved, brief routes to ERP as a procurement task (via existing Ikigai → ERP sync)

WHAT THE MODEL DOES NOT DO:

  • Does not negotiate with suppliers (recommendations assume list pricing and standard lead times from supplier master)
  • Does not predict second-order effects (e.g., "if we shift orders to Supplier C, they may also face capacity constraints") — this is a known limitation and will be surfaced as "Assumptions" in the brief
  • Does not auto-execute procurement actions (human must approve before any PO creation or supplier contact)
  • Does not learn from past procurement decisions in Phase 1 (the action ranking logic is rules-based; ML-based ranking is Phase 2 if we see consistent override patterns)

CALIBRATION REQUIREMENT:

The model confidence score must be empirically calibrated: if the model says "85% confidence this disruption will cause a stockout," then across all 85%-confidence predictions, we observe a stockout ~85% of the time. Calibration is measured quarterly using a hold-out set of disruption signals from the past 90 days. If calibration error >10 percentage points (e.g., 85% predictions result in stockouts only 70% of the time), we surface a warning banner in the UI: "Model confidence scores are currently under review — treat recommendations as directional."

FALLBACK BEHAVIOR:

If any required input is missing (e.g., customer has not connected ERP inventory data, supplier lead time data is stale >30 days, external disruption event has no matched knowledge graph entry), the system generates a partial brief with a clear "Data gaps" section listing what's missing and what the user must manually verify. The brief is still generated (so the user knows a signal was detected), but the "Approve" button is disabled until the user acknowledges the data gaps and manually overrides.

Data Strategy & Sources

TRAINING DATA:

This feature does not train a new ML model. It uses Ikigai's existing forecasting model (already trained on customer historical demand/supply data) and adds a deterministic post-processing layer (impact calculation + action ranking). The only "learning" component is calibration: we log every generated brief, the user's decision (approve/reject/defer), and the actual outcome (did a stockout occur? was revenue impacted?). This outcome data is stored for quarterly calibration checks and future Phase 2 ML ranking.

REQUIRED DATA INPUTS (per customer):

InputSourceUpdate FrequencyQuality Requirement
Demand forecast (with confidence interval)Ikigai forecasting modelReal-time (every model run)Must include delta from baseline + probability distribution
Current inventory levels (by SKU)Customer ERP (SAP, Oracle, NetSuite)Daily batch syncMust be <24 hrs stale; if >48 hrs stale, surface warning
Supplier lead times (by supplier + SKU)Customer supplier master (uploaded to Ikigai or synced from ERP)Weekly batch syncMust include historical avg + current committed lead time; if no data, use industry default (14 days) with warning
Supplier pricing (base + expedite premium)Customer supplier masterMonthly batch syncIf missing, use placeholder "$[expedite cost not configured]" and disable cost ranking
External disruption events (weather, geopolitical)Third-party API (e.g., Everstream Analytics, Resilinc)Real-time webhookIf API unavailable, degrade to "external event detected (details unavailable)"
Historical procurement decisions + outcomesIkigai audit log (new table: procurement_decisions)Real-time (logged at approval)Captures: brief ID, user decision, approval timestamp, actual stockout (boolean, backfilled after 30 days)

DATA GAPS & MITIGATION:

  • Gap 1: 30% of enterprise customers do not have supplier lead time data in a structured format (stored in procurement manager's email or Excel). Mitigation: Phase 1 includes a supplier lead time upload wizard (CSV template) during onboarding; if not uploaded, use industry default lead times from an embedded lookup table (source: Gartner 2024 Supply Chain benchmarks) and surface warning: "Lead times based on industry avg — upload supplier data for better accuracy."
  • Gap 2: External disruption event APIs (Everstream, Resilinc) charge per API call; cost is ~$0.50/call. At 5 signals/month × 38 customers = 190 calls/month = $95/month = $1,140/year. Decision: Absorb cost in COGS; API cost is negligible vs feature value. If usage spikes >500 calls/month, add rate limiting (max 10 briefs/customer/month).
  • Gap 3: We do not have ground-truth data on "did a stockout actually occur" for historical disruptions (required for calibration). Mitigation: Phase 1 includes a lightweight feedback loop: 30 days after a brief is generated, email the procurement manager: "Did the forecasted disruption result in a stockout? [Yes/No/Unsure]." Store response in procurement_decisions.actual_outcome. Target 60% response rate (based on analogous feedback surveys in other Ikigai features).

SYNTHETIC DATA FOR TESTING:

We will generate 50 synthetic disruption scenarios (10 scenarios × 5 risk levels) using anonymized historical data from 3 design partner customers. Each scenario includes: baseline forecast, disrupted forecast, inventory snapshot, supplier lead times, and expected brief output. Engineering uses this dataset for regression testing (every code change must produce identical briefs for the 50 scenarios). Design partners review the briefs for realism during Beta.

Evaluation Framework

EVALUATION OBJECTIVE:

Prove that the auto-generated brief is (a) factually correct (numbers match source data), (b) actionable (procurement manager can make a decision in <8 minutes), and (c) trusted (user approves the recommendation ≥60% of the time, or provides a reason for rejection that informs Phase 2 improvements).

PHASE 1 EVALUATION (PRE-LAUNCH):

Test 1 — Factual Correctness (Offline Eval)

  • Dataset: 50 synthetic scenarios (described in Data Strategy) + 20 historical disruption events from 3 design partner customers (with manually assembled briefs as ground truth)
  • Method: For each scenario, generate a brief and compare outputs:
    • Revenue-at-risk calculation: must match manual calculation within ±2% (allows for rounding differences)
    • Inventory days-of-supply: must match within ±0.5 days
    • Recommended action ranking: manual reviewer (procurement manager from design partner) rates each recommendation as "relevant/irrelevant"; ≥80% of recommendations must be rated "relevant"
  • Pass criteria: 95% of briefs pass all three checks (factual correctness + relevance)
  • Owner: Engineering lead (Priya) runs offline eval weekly during development; final eval before Beta launch

Test 2 — Actionability (Design Partner Beta, n=3 customers)

  • Method: Deploy feature to 3 design partner customers for 30 days. For each generated brief, measure:
    • Time from brief generation to user decision (approve/reject/defer): target <8 minutes median
    • User action rate: ≥70% of briefs result in a decision within 24 hours (vs current 2.8-hour manual assembly that sometimes gets deprioritized for days)
    • User feedback survey (sent 24 hrs after each brief): "Was this brief useful? [Yes/Somewhat/No]" + open comment field
  • Pass criteria: Median decision time <10 minutes (allows 2-minute buffer vs 8-minute target); ≥60% of briefs rated "Yes" or "Somewhat" useful; ≥70% action rate
  • Owner: PM (Customer Success assigns design partner POC; PM reviews feedback weekly)

Test 3 — Trust Calibration (Design Partner Beta)

  • Method: For each brief generated during Beta, log: model confidence score, user decision (approve/reject/defer), and actual outcome (did stockout occur? user reports this via 30-day follow-up survey). Calculate calibration error: |model_confidence - observed_frequency|.
  • Pass criteria: Calibration error <15 percentage points (allows for small sample size during Beta; tighten to <10pp in Phase 2)
  • Owner: Engineering (Priya) — calibration dashboard built into internal admin panel

PHASE 2 EVALUATION (POST-LAUNCH, ONGOING):

Metric 1 — Approval Rate (Primary Success Metric)

  • Target: ≥60% of generated briefs are approved (user clicks "Approve" and routes to VP) within 7 days of generation
  • Measurement: Mixpanel event tracking (brief_generated, brief_approved, brief_rejected, brief_deferred)
  • Kill threshold: If approval rate <40% at D90, conduct user interviews and consider kill criteria review

Metric 2 — Time-to-Decision (Efficiency Metric)

  • Baseline: 2.8 hours manual assembly time (from problem statement)
  • Target: Median time-to-decision <15 minutes (from brief generation to user decision logged)
  • Measurement: Delta between brief_generated.timestamp and user_decision.timestamp in database
  • Kill threshold: If median time >45 minutes at D90, feature is not materially faster than manual process → pause Phase 2

Metric 3 — Calibration Error (Trust Metric)

  • Target: <10 percentage points calibration error, measured quarterly
  • Measurement: For all briefs generated in past 90 days where we have outcome data (user completed 30-day follow-up survey), calculate: |model_confidence - observed_stockout_rate|
  • Kill threshold: If calibration error >20pp for 2 consecutive quarters, disable confidence scores in UI until recalibrated

Metric 4 — Override Pattern Analysis (Phase 2 Input)

  • Measurement: When user rejects a recommendation, require comment field (free text). Quarterly analysis by PM: categorize rejection reasons (e.g., "cost too high," "supplier not reliable," "lead time outdated"). If ≥30% of rejections share a common reason, that informs Phase 2 ML ranking improvements.

WHAT WE ARE NOT MEASURING (AND WHY):

  • Total briefs generated: Vanity metric — doesn't distinguish useful signals from noise
  • User login frequency: Doesn't correlate with decision quality
  • Brief length (word count): Optimizing for brevity may sacrifice clarity

Human-in-the-Loop Design

HUMAN OVERSIGHT ARCHITECTURE:

This feature is a recommendation system with mandatory human approval — no procurement action is executed without explicit user approval. The human is always in the loop for three critical decision points:

Decision Point 1 — Brief Review & Approval (Procurement Manager)

  • When: Immediately after brief is auto-generated (within 45 seconds of model signal detection)
  • What the human sees: Full brief (impact summary, recommended actions, risk scenarios, confidence explanation, data gaps if any)
  • What the human must do: Review the brief and choose one of three actions:
    1. Approve: Routes brief to VP for final approval (if customer has configured VP approval requirement) or directly to ERP as a procurement task (if customer has delegated authority to procurement manager)
    2. Reject: Brief is archived with required comment field (free text: "Why are you rejecting this recommendation?"). Rejection is logged for quarterly override analysis.
    3. Defer: Brief is saved to user's "Pending Decisions" queue; user can return later (no auto-expiration, but system sends reminder email after 48 hours: "You have [N] pending disruption briefs")
  • Guardrail: The "Approve" button is disabled if any critical data gap is detected (e.g., inventory data >48 hrs stale, supplier lead time missing, external disruption event details unavailable). User must acknowledge the data gap and manually override ("I have verified this data externally") before approval is enabled.
  • Audit trail: Every interaction is logged (brief_id, user_id, action, timestamp, comment). Audit log is exportable for compliance reviews.

Decision Point 2 — VP Approval (Optional, Customer-Configurable)

  • When: After procurement manager clicks "Approve," if customer has configured VP approval requirement
  • What the VP sees: Same brief + procurement manager's approval timestamp + optional comment from manager ("I recommend we expedite from Supplier B — I spoke with their account manager and confirmed 8-day lead time")
  • What the VP must do: Approve or reject. If rejected, brief routes back to procurement manager with VP's comment.
  • Guardrail: VP can configure auto-approval threshold ("auto-approve any brief with revenue-at-risk <$50K") — but this is opt-in, not default.

Decision Point 3 — Outcome Feedback (30-Day Follow-Up)

  • When: 30 days after brief is approved (gives time for procurement action to take effect and outcome to be observable)
  • What the human sees: Email survey: "On [date], you approved a brief recommending [action]. Did the forecasted disruption result in a stockout? [Yes/No/Unsure]. Optional: What actually happened?"
  • What the human must do: Nothing (survey is optional) — but response rate is tracked as a success metric (target ≥60% response rate)
  • Why this matters: Outcome feedback is the only way to measure model calibration (did the 85%-confidence prediction actually result in a stockout 85% of the time?). Without this feedback loop, we cannot improve the model.

ESCALATION PATH (MODEL FAILURE MODE):

If the brief generation fails (e.g., ERP integration timeout, external API unavailable, model output is NaN), the system does NOT silently fail. Instead:

  1. User receives an email alert: "Ikigai detected a supply disruption signal for [SKU], but the decision brief could not be generated due to [error]. Manual review required."
  2. Alert includes: raw model signal (forecast delta, confidence score), link to forecasting dashboard, and a pre-filled template for manual brief assembly (so the user can still act on the signal, just without automation)
  3. Engineering is paged (Slack alert to #ikigai-incidents channel) for any brief generation failure rate >5% in a 6-hour window

OVERRIDE TRANSPARENCY:

If a user consistently rejects recommendations (e.g., user rejects ≥70% of briefs over 30 days), the system surfaces a banner: "We've noticed you're rejecting most recommendations. Would you like to adjust your risk tolerance settings or provide feedback to improve future briefs?" This prevents silent model-user misalignment.

Trust & Guardrails

OBJECTIVE: Ensure the auto-generated brief is transparent, auditable, and safe — users trust the recommendation enough to act on it, and the company can defend the recommendation in a post-incident review if a procurement decision goes wrong.

GUARDRAIL 1 — CONFIDENCE SCORE TRANSPARENCY

Every brief includes a confidence explanation (not just a number):

  • What it shows: "This forecast is based on [N] days of historical data for [SKU]. Model confidence is [X]% (calibrated: over the past 90 days, [X]%-confidence forecasts were correct [Y]% of the time). Key assumptions: supplier lead time = [Z] days (historical avg), no secondary disruptions."
  • Why this matters: A confidence score without context is meaningless. Users need to know: (a) how much data the model has seen (more data = higher trust), (b) whether the confidence score is calibrated (does 85% confidence mean 85% accuracy?), and (c) what assumptions the model is making (so users can judge if assumptions are valid).
  • Enforcement: Engineering cannot ship a brief that displays a confidence score without the corresponding explanation. This is enforced via UI component validation (explanation field is required, not optional).

GUARDRAIL 2 — DATA PROVENANCE (SHOW YOUR WORK)

Every number in the brief must cite its source:

  • Revenue-at-risk: "$340K in Q4 revenue at risk (calculated: 12,000 units forecasted demand × $28.33 avg selling price, source: ERP sales history June–Aug 2025)"
  • Inventory days-of-supply: "Current inventory will cover 8.2 days at baseline forecast, 5.1 days at disrupted forecast (calculated: 4,200 units on hand ÷ 512 units/day baseline demand, source: ERP inventory snapshot Dec 15, 2025 8:00 AM UTC)"
  • Supplier lead time: "Supplier B lead time: 8 days (source: supplier master, last updated Dec 10, 2025)"
  • Why this matters: If a user questions a recommendation, they need to trace the calculation back to source data. If the number is wrong, they need to know which data source to correct (e.g., "our ERP inventory count is stale — we received a shipment yesterday that's not reflected").
  • Enforcement: Backend API response includes a provenance object for every calculated field (source table, timestamp, calculation formula). Frontend renders this in an expandable "Show calculation" accordion under each number.

GUARDRAIL 3 — DATA STALENESS WARNINGS

If any input data is stale (>24 hrs for inventory, >7 days for supplier lead times, >30 days for pricing), the brief surfaces a warning banner:

  • Example: "⚠ Warning: Inventory data is 36 hours old (last synced: Dec 14, 2025 8:00 AM UTC). Current inventory levels may have changed. Verify before approving."
  • Enforcement: "Approve" button is disabled if staleness exceeds critical threshold (>48 hrs for inventory, >30 days for lead times). User must click "I have verified this data externally" to override and enable approval.

GUARDRAIL 4 — ASSUMPTION TRANSPARENCY

Every brief includes an "Assumptions" section listing what the model assumes to be true:

  • Example assumptions:
    • "Supplier B lead time remains at 8 days (historical avg over past 6 months). If lead time increases, this recommendation may underestimate delivery time."
    • "No secondary disruptions (e.g., port congestion, customs delays). If secondary disruptions occur, recommended actions may be insufficient."
    • "Demand forecast assumes historical seasonality pattern holds. If market conditions change (e.g., competitor launches new product), forecast may be inaccurate."
  • Why this matters: Users need to know what could go wrong. If an assumption is violated (e.g., Supplier B announces a lead time increase the day after the brief is generated), the user knows to revisit the recommendation.
  • Enforcement: Product defines a standard assumption checklist for each disruption type (demand spike, supplier delay, external event). Backend must populate this section (cannot be empty).

GUARDRAIL 5 — AUDIT TRAIL (EVERY DECISION IS LOGGED)

Every brief generated, every user decision (approve/reject/defer), and every outcome (stockout occurred or not) is logged in an immutable audit table:

  • Schema: procurement_decisions table with columns: brief_id, user_id, generated_at, decision (approved/rejected/deferred), decided_at, vp_approved_at (if applicable), rejection_reason (free text), actual_outcome (boolean: stockout occurred), outcome_reported_at
  • Retention: 7 years (compliance with SOX for financial decision audit trails)
  • Access control: Audit log is readable by customer admins and Ikigai support (for troubleshooting), but not writable (immutable log)
  • Why this matters: If a procurement decision results in a costly stockout, the company needs to answer: "Why did we make this decision? Was the model wrong, or did the user override the model? What data did the model have at the time?" The audit trail provides this forensic capability.

GUARDRAIL 6 — RATE LIMITING (PREVENT ALERT FATIGUE)

If the model generates >10 disruption briefs for a single customer in a 7-day window, the system surfaces a banner: "High disruption signal volume detected. Review model sensitivity settings or contact support." This prevents two failure modes: (a) model is miscalibrated and firing false positives, (b) user ignores briefs due to alert fatigue.

  • Enforcement: After 10 briefs in 7 days, system pauses auto-generation for that customer and sends alert to Customer Success: "Customer [X] hit rate limit — manual review required."

Inference & Scaling Plan

INFERENCE TRIGGER:

Brief generation is triggered by Ikigai's existing forecasting model detecting a material signal. The forecasting model runs on a scheduled cadence (customer-configurable: hourly, daily, or on-demand). When the model detects:

  • Demand anomaly >15% from 30-day baseline, OR
  • Supplier delay >5 days from committed lead time, OR
  • External disruption event matched in knowledge graph (e.g., "Hurricane Zeta closes Port of Savannah")

...the model publishes a message to a Kafka topic (forecast_disruption_signals). The brief generator service subscribes to this topic and processes each signal asynchronously.

EXPECTED LOAD:

  • Current state: 38 enterprise customers × 5 disruption signals/month = 190 briefs/month = ~6 briefs/day
  • Phase 1 target (12 months post-launch): 60 customers × 5 signals/month = 300 briefs/month = ~10 briefs/day
  • Phase 2 target (24 months post-launch): 150 customers × 5 signals/month = 750 briefs/month = ~25 briefs/day

LATENCY REQUIREMENT:

Brief must be generated within 45 seconds of signal detection (p95 latency). Breakdown:

  • Fetch inventory data from customer ERP (via cached daily sync): <5 seconds
  • Fetch supplier data from Ikigai supplier master: <2 seconds
  • Calculate impact (revenue-at-risk, inventory days-of-supply): <3 seconds (pure math, no external calls)
  • Fetch external disruption event details (if applicable): <10 seconds (third-party API call to Everstream/Resilinc)
  • Rank procurement actions (rules-based logic): <5 seconds
  • Render brief and store in database: <3 seconds
  • Send notification to user (email + in-app): <2 seconds
  • Total budget: 30 seconds target, 45 seconds p95 threshold

SCALING STRATEGY:

  • Phase 1 (0–60 customers): Single-instance brief generator service (Node.js on AWS ECS, 2 vCPU, 4GB RAM). At 10 briefs/day with 45-second p95 latency, single instance handles load with <5% CPU utilization. No horizontal scaling needed.
  • Phase 2 (60–150 customers): Horizontal scaling via ECS autoscaling. Scale trigger: if Kafka consumer lag >10 messages OR p95 latency >60 seconds for 5 consecutive minutes, spin up additional instance (max 5 instances). Cost impact: each additional instance costs $50/month (reserved pricing). At 25 briefs/day, expect 2 instances avg = $100/month incremental infra cost.
  • Cost at scale (150 customers, 750 briefs/month): Infra: $100/month. External API calls (Everstream): 750 calls × $0.50/call = $375/month. Total: $475/month = $5.7K/year. This is negligible vs $464K/year recoverable time value.

CACHE STRATEGY (REDUCE LATENCY):

  • Inventory data: Cached from daily ERP sync (refreshed every 24 hours). Cache hit rate: 100% for typical use case (brief generated within 24 hours of sync). If cache miss (data >24 hrs stale), fetch live from ERP API (adds 10-second latency penalty) and surface staleness warning in UI.
  • Supplier data: Cached in Ikigai supplier master (refreshed weekly). Cache hit rate: ~95% (supplier lead times rarely change daily). If cache miss, use industry default lead time from embedded lookup table and surface warning.
  • External disruption events: No cache (always fetch live from third-party API to ensure real-time accuracy). If API call fails (timeout >10 seconds or HTTP 5xx error), degrade gracefully: surface partial brief with "External event details unavailable — verify disruption externally before approving."

FAILURE MODE MITIGATION:

  • Kafka consumer lag: If lag >50 messages (indicates service is falling behind), page on-call engineer (Slack alert to #ikigai-incidents). Manual intervention required (restart service, investigate slow queries, or spin up additional instances).
  • ERP API timeout: If live inventory fetch times out (>10 seconds), fall back to cached data (even if >24 hrs stale) and surface warning: "Inventory data is stale — verify before approving." Do NOT block brief generation on ERP availability.
  • Third-party API unavailable: If Everstream/Resilinc API is down (HTTP 5xx or timeout), generate partial brief without external event details. Do NOT block brief generation on third-party API availability.
MADE WITH SCRIPTONIA

Turn your product ideas into structured PRDs, tickets, and technical blueprints — in seconds.

Start for free →