Use Cases & User Stories¶
Comprehensive use case catalog for CostEngine (MfgIQ).
Summary Table¶
| ID | Use Case Name | Category | Priority | Complexity | User Role |
|---|---|---|---|---|---|
| UC-001 | Complete RFQ-to-Quote Flow | Core Workflow | P0 - Critical | High | Estimator |
| UC-002 | Rush Quote (High Priority) | Core Workflow | P0 - Critical | Medium | Estimator |
| UC-003 | From First Guess to Final Sample | Core Workflow | P0 - Critical | High | Estimator |
| UC-101 | Import Standard Costing Template | Excel Import | P0 - Critical | Medium | Estimator |
| UC-102 | Import with Errors | Excel Import | P1 - Important | Medium | Estimator |
| UC-103 | Import Legacy Excel (Non-Standard) | Excel Import | P1 - Important | High | Estimator |
| UC-104 | Similar Part Geometry Search | Excel Import | P1 - Important | High | Estimator |
| UC-105 | Intelligent Logic Extraction | Excel Import | P0 - Critical | High | System |
| UC-201 | Calculate Material Cost | Cost Calculation | P0 - Critical | Low | System |
| UC-202 | Calculate Multi-Operation Cost | Cost Calculation | P0 - Critical | Medium | System |
| UC-203 | Apply Cascading Scrap | Cost Calculation | P0 - Critical | Medium | System |
| UC-301 | Drill Down on Cost Line | Explainability | P0 - Critical | Medium | Estimator |
| UC-302 | Compare Two Versions | Explainability | P1 - Important | Medium | Estimator |
| UC-303 | Benchmark against History | Explainability | P1 - Important | Medium | Estimator |
| UC-304 | Low-Margin Approval Workflow | Explainability | P0 - Critical | Medium | Manager |
| UC-305 | What-If / Scenario Simulation | Explainability | P1 - Important | High | Estimator |
| UC-306 | Risk & Confidence Scoring | Explainability | P1 - Important | Medium | System |
| UC-307 | Post-Order Feedback Loop | Explainability | P2 - Future | High | Admin |
| UC-308 | Tracking Manual Checks | Analytics | P1 - Important | Medium | Admin |
| UC-401 | Customer Requests Quantity Change | Versioning | P1 - Important | Low | Estimator |
| UC-402 | Material Price Increase | Versioning | P1 - Important | Medium | Admin |
| UC-403 | Dynamic Material Pricing | Versioning | P1 - Important | Medium | System |
| UC-501 | Generate Standard Quote | Output | P0 - Critical | Medium | Estimator |
| UC-502 | Quote for Tender Submission | Output | P1 - Important | Low | Estimator |
| UC-601 | Missing Critical Data | UI & Data Integrity | P1 - Important | Low | System |
| UC-602 | Unrealistic Values | UI & Data Integrity | P1 - Important | Medium | System |
| UC-603 | UI Validation Patterns | UX/UI Hygiene | P1 - Important | Low | UI Layer |
| UC-604 | Role-Based Access Control (RBAC) | Governance | P0 - Critical | Medium | Admin |
| UC-701 | Sync with Tally ERP | Integration | P2 - Future | High | Admin |
| UC-702 | Email Integration | Integration | P2 - Future | Low | Estimator |
| UC-801 | Incremental Excel Sync | Data Pipeline | P0 - Critical | High | System |
| UC-802 | Automated Rate Lock | Data Pipeline | P1 - Important | Medium | System |
| UC-901 | Database Failover Recovery | System Ops | P1 - Important | High | DevOps |
| UC-902 | Audit Trail Forensic Search | System Ops | P1 - Important | Medium | Admin |
| UC-903 | Containerized Deployment (Docker) | Technical Ops | P1 - Important | Medium | DevOps |
| UC-904 | Centralized Observability & Logging | Technical Ops | P1 - Important | Low | Admin |
| UC-905 | MLOps Pipeline (Phase 3) | Intelligence | P2 - Future | High | System |
| UC-910 | Decision Analytics & Cost Intelligence | Intelligence | P2 - Future | High | Admin |
Total Use Cases: 34 covering all MVP, Intelligence, & Governance functionality
Core Workflow Use Cases¶
UC-001: Complete RFQ-to-Quote Flow¶
Priority: P0 - Critical
Complexity: High
Actor: Estimator
Precondition: Customer sent RFQ via email with part drawings and quantity
Main Success Scenario:
| Step | Action | Expected Result |
|---|---|---|
| 1 | Estimator uploads RFQ or selects "New Product" + Category | Category logic (defaults) auto-populated |
| 2 | System extracts material specs (or pulls from Category) | Data parsed and displayed |
| 3 | System calculates costs automatically | All cost components calculated |
| 4 | Estimator reviews cost breakdown | Cost details visible with explainability |
| 5 | Estimator overrides cycle time based on shop floor expertise | Override accepted, impact shown |
| 6 | System recalculates and shows impact | Updated costs displayed |
| 7 | Estimator generates quote with 3 margin scenarios | Quote previewed |
| 8 | System creates PDF and Excel quote pack | Files generated |
| 9 | Estimator sends quote to customer | Quote sent |
| 10 | System saves version 1.0 | Version saved with timestamp |
Alternative Flows:
| Flow ID | Condition | Action |
|---|---|---|
| 3a | Missing material rate | System prompts for manual entry |
| 4a | Cost seems too high | Estimator investigates assumptions |
| 6a | Override rejected | Estimator must provide reason |
Postcondition: Quote sent to customer, version saved in system
Performance Target: 15-20 minutes (vs 2-4 hours manually)
Acceptance Criteria: - Complete flow in < 20 minutes - All 6 cost components calculated - At least 1 override applied successfully - PDF + Excel quote generated
UC-002: Rush Quote (High Priority)¶
Priority: P0 - Critical
Complexity: Medium
Actor: Estimator
Business Context: Customer needs quote in 1 hour for urgent project
Flow:
| Step | Action | Time Target |
|---|---|---|
| 1 | Estimator uses existing similar part as template | 5 min |
| 2 | Adjusts quantity and critical dimensions | 10 min |
| 3 | Accepts default assumptions (no deep validation) | 5 min |
| 4 | Generates Base margin scenario only | 5 min |
| 5 | Sends quote within 30 minutes | 5 min |
Key Requirements:
| Requirement | Supported | Notes |
|---|---|---|
| Fast template duplication | Yes | Copy from existing quote |
| Quick overrides without full validation | Yes | Skip validation checks |
| Single margin scenario option | Yes | Base margin only |
UC-003: From First Guess to Final Sample¶
Priority: P0 - Critical
Complexity: High
Actor: Estimator
Scenario: Taking a quote from an initial rough estimate all the way to a sample-validated final cost.
Steps:
| Step | What happens | Status | Result |
|---|---|---|---|
| 1 | Create initial quote based on similar part | Draft | Budgetary pricing sent |
| 2 | Client wants samples; Estimator flags the shop floor | Prototype | Production starts planning |
| 3 | Sample run finishes; We record the actual times | Validating | We see where we were off |
| 4 | Estimator pulls sample data into the quote | Validated | Prices fixed based on reality |
| 5 | Save it as the "Final" version with notes | Final | Ready for the PO |
Success Criteria: - We can see the whole journey from the first "Draft" to the "Final" version. - Any changes during sample validation are explained.
Excel Import Use Cases¶
UC-101: Import Standard Costing Template¶
Priority: P0 - Critical
Complexity: Medium
Actor: Estimator
Precondition: Estimator has filled Excel template with part data
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | Click "Upload Costing Sheet" | File dialog opens |
| 2 | Select Excel file from computer | File uploading... |
| 3 | System validates file structure | Validation in progress |
| 4 | System extracts and displays data | Shows Part number, drawing number, Material grade and specs, Operations list with times, Tooling requirements |
| 5 | System highlights any missing fields | Warning indicators shown |
| 6 | Estimator confirms import | Processing... |
| 7 | System creates quote draft | Quote draft created |
Success Criteria:
| Criterion | Target | Measurement |
|---|---|---|
| Data field mapping | 100% | All fields mapped correctly |
| Missing field warnings | All | Warnings shown for empty fields |
| Import time | < 10 sec | From upload to draft creation |
UC-102: Import with Errors¶
Priority: P1 - Important
Complexity: Medium
Actor: Estimator
Flow:
| Step | Action | Error Detected |
|---|---|---|
| 1 | Upload Excel file | Processing... |
| 2 | System detects errors | Unknown material grade "XYZ123" |
| 2a | Missing cycle time for Operation 3 | |
| 2b | Negative scrap percentage | |
| 3 | System shows error report with line numbers | Error details with cell references |
| 4 | Estimator fixes issues in Excel | File updated |
| 5 | Re-uploads corrected file | Validation passed |
| 6 | Import succeeds | Quote draft created |
Error Handling:
| Feature | Supported | Details |
|---|---|---|
| Clear error messages with cell references | Yes | Shows exact Excel cell |
| Partial import option (skip errored rows) | Yes | Import valid data only |
| Downloadable error log | Yes | CSV export of errors |
UC-103: Import Legacy Excel (Non-Standard Format)¶
Priority: P1 - Important
Complexity: High
Actor: Estimator
Scenario: Factory has been using Excel for 10 years, custom format
Flow:
| Step | Action | Result |
|---|---|---|
| 1 | Upload custom Excel | Attempt auto-detection |
| 2 | System attempts auto-detection | Fails - format unknown |
| 3 | Estimator selects "Manual Field Mapping" mode | Mapping UI opens |
| 4 | System shows Excel preview | First 10 rows displayed |
| 5 | Estimator maps fields | "Item Code" → Part Number "Material Type" → Material Grade "Time per Piece (min)" → Cycle Time |
| 6 | System saves mapping template | Template saved |
| 7 | Future uploads use saved mapping | Auto-applied |
Key Feature: Excel-first onboarding (differentiation!)
UC-104: Similar Part Geometry Search¶
Priority: P1 - Important
Complexity: High
Actor: Estimator
Scenario: User uploads a part with a new Part Number (e.g., "AX-505"), but the factory has made a similar "Shaft" before.
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | Estimator uploads part details | System begins geometric analysis |
| 2 | Geometric Hashing | System analyzes critical dimensions (Diameter, Length, Material) |
| 3 | Similarity Detect | System identifies Part #AX-102 as a 90% geometric match |
| 4 | Context Suggestion | Sidebar shows: "Found similar part AX-102. Usual quote: ₹1,100. Should I import its Routing logic?" |
| 5 | Selection | Estimator accepts suggestion to save 15 minutes of data entry |
UC-105: Intelligent Logic Extraction (Ingest & Learn)¶
Priority: P0 - Critical
Complexity: High
Actor: System / Estimator
Scenario: User uploads a legacy Excel sheet to "teach" the system their logic.
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | Upload Excel | System parses formulas, dependencies, and references. |
| 2 | Pattern Detection | Identifies Logic: "If Dia > 50 -> Machine B". Identifies Data: MHR = 450, Material = mild steel. |
| 3 | Summary Presentation | "Detected Logic: - Category: Shafts - MHR: 450/hr - Margin: Tiered (10% < 1000 qty)" |
| 4 | Verification | Estimator reviews and corrects assumptions. |
| 5 | Memory Update | System saves these rules as "Category Defaults" for future use. |
Key Feature: "Learn from Excel" (differentiation!)
Cost Calculation Use Cases¶
UC-201: Calculate Material Cost¶
Priority: P0 - Critical
Complexity: Low
Actor: System (automated)
Trigger: Material data imported
Calculation Steps:
| Step | Action | Value | Source |
|---|---|---|---|
| 1 | Get material grade | SAE4140 | Excel import |
| 2 | Look up current RM rate | ₹99.5/kg | Material Master (updated 2026-01-20) |
| 3 | Get gross weight | 2.304 kg | Excel (per drawing) |
| 4 | Get net weight | 2.0 kg | Excel (finished part) |
| 5 | Calculate yield | 86.8% | 2.0 / 2.304 |
| 6 | Apply formula | ₹263.95 | (2.304 × 99.5) / 0.868 |
| 7 | Save to cost breakdown with assumption tags | Saved | With full traceability |
Explainability Output:
Material Cost: ₹263.95
├─ Material: SAE4140 (from Excel)
├─ RM Rate: ₹99.5/kg (current market rate, last updated 2026-01-20)
├─ Gross Weight: 2.304 kg (per drawing)
├─ Net Weight: 2.0 kg (finished part)
├─ Yield: 86.8% (calculated)
└─ Formula: (2.304 × 99.5) / 0.868
Formula: $$ \text{Material Cost} = \frac{\text{Gross Weight} \times \text{RM Rate}}{\text{Yield}} $$
UC-202: Calculate Multi-Operation Cost¶
Priority: P0 - Critical
Complexity: Medium
Actor: System
Input: Routing with 5 operations
Calculation Breakdown:
| Operation | Setup Cost | Cycle Cost | Tool Cost | Total | Calculation |
|---|---|---|---|---|---|
| Op 1: Cutting | ₹0.07 | ₹14.40 | ₹0.00 | ₹14.47 | Setup: 0.30h @ ₹120/h ÷ 500pcs Cycle: 0.12h @ ₹120/h |
| Op 2: Turning | ₹0.05 | ₹72.00 | ₹0.00 | ₹72.05 | Setup: 0.20h @ ₹120/h ÷ 500pcs Cycle: 0.60h @ ₹120/h |
| Op 3: Threading | ₹0.08 | ₹137.20 | ₹2.00 | ₹139.28 | Setup: 0.30h @ ₹140/h ÷ 500pcs Cycle: 0.98h @ ₹140/h Tool: ₹2.00/pc |
| Op 4: Heat Treat | ₹0.04 | ₹8.00 | ₹0.00 | ₹8.04 | Setup: 0.10h @ ₹100/h ÷ 500pcs Cycle: 0.08h @ ₹100/h |
| Op 5: Coating | ₹0.06 | ₹4.55 | ₹0.00 | ₹4.61 | Setup: 0.15h @ ₹80/h ÷ 500pcs Cycle: 0.06h @ ₹80/h |
| Total | ₹0.30 | ₹236.15 | ₹2.00 | ₹238.45 |
Key Feature: Operations-first model (differentiation!)
UC-203: Apply Cascading Scrap¶
Priority: P0 - Critical
Complexity: Medium
Actor: System
Scenario: Need 1000 finished pieces, scrap at each stage
Cascading Calculation:
| Stage | Scrap % | Required Qty | Calculation |
|---|---|---|---|
| Final Output | - | 1000 pcs | Target quantity |
| Material Stage | 5% | 1053 pcs | 1000 / 0.95 |
| Operation 1 | 3% | 1085 pcs | 1053 / 0.97 |
| Operation 2 | 2% | 1107 pcs | 1085 / 0.98 |
| Raw Material Start | - | 1107 pcs | +10.7% total |
Cost Impact:
| Component | Impact | Notes |
|---|---|---|
| Material cost | +10.7% | Purchase 1107 instead of 1000 |
| Tracked in explainability | Yes | Full scrap traceability |
Explainability Use Cases¶
UC-301: Drill Down on Cost Line¶
Priority: P0 - Critical
Complexity: Medium
Actor: Estimator
Scenario: Customer questions why material cost is ₹264
Flow:
| Step | Action | Display |
|---|---|---|
| 1 | Estimator clicks on "Material Cost: ₹263.95" | Cost line highlighted |
| 2 | System shows popup | Material Cost Breakdown Source Data: ✓ Material Grade: SAE4140 (from Excel cell B7) ✓ Gross Weight: 2.304 kg (from Excel cell D13) ✓ RM Rate: ₹99.5/kg (from Material Master) Calculation: (Gross Weight × RM Rate) / Yield % = (2.304 × 99.5) / 0.868 = ₹263.95 Assumptions: • Yield: 86.8% (calculated from gross/net) • RM Rate: Current market rate (updated 2026-01-20) • No scrap surcharge applied [Override RM Rate] [Override Yield %] |
| 3 | Estimator screenshots this for customer | Screenshot taken |
| 4 | Customer satisfied with transparency | Accepted |
Key Feature: Explainable + defensible (differentiation!)
UC-302: Compare Two Versions¶
Priority: P1 - Important
Complexity: Medium
Actor: Estimator
Scenario: Customer asks "Why did quote go up from v1.0 to v1.1?"
Flow:
| Step | Action | Result |
|---|---|---|
| 1 | Open quote, select "Compare Versions" | Version selector shown |
| 2 | Choose v1.0 vs v1.1 | Loading comparison... |
| 3 | System shows diff | Detailed changes displayed |
| 4 | Estimator forwards comparison to customer with context | Email sent |
Diff Display:
| Cost Component | v1.0 | v1.1 | Change | Reason |
|---|---|---|---|---|
| Material Cost | ₹229.22 | ₹263.95 | +₹34.73 (+15.1%) | RM Rate: ₹89.5/kg → ₹99.5/kg "RM price increase from supplier" |
| Op 3: Threading | ₹125.00 | ₹139.28 | +₹14.28 (+11.4%) | Cycle: 0.85h → 0.98h "Revised time after trial run" |
| Total Impact | +₹49.01 (+9.3%) |
UC-303: Benchmark against History¶
Priority: P1 - Important
Complexity: Medium
Actor: Estimator
Scenario: Estimator identifies a new "Cost to Quote" of ₹950, but remembers charging ₹1,100 previously.
Main Success Scenario:
| Step | Action | System Response |
|---|---|---|
| 1 | Estimator begins costing for Part #AX-102 | System identifies historical quotes for the same or similar part number. |
| 2 | System displays "History Sidebar" | Shows: "Last Quoted: ₹1,100 (v2.0, 2025-11-15)". |
| 3 | Estimator completes the 950 estimate | System calculates variance: -₹150 (-13.6%). |
| 4 | System highlights "Significant Variance Detected" | UI shows a comparison bar: [Historical: 1,100] vs [Current: 950]. |
| 5 | Estimator clicks "Analyze Variance" | System pulls price-buildup from both versions to highlight delta (e.g., "Steel Rate was ₹110, now ₹98"). |
| 6 | Estimator confirms the new price as defensible | Variance note saved to audit log. |
Key Feature: Prevents "Price Drift" by surfacing historical context during active estimation.
UC-304: Low-Margin Approval Workflow¶
Priority: P0 - Critical
Complexity: Medium
Actor: Manager
Scenario: Estimator sets price to ₹950 (8% margin), which is below the "Aggressive" floor of 15%.
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | Floor Check | System flags the 8% margin as "High Risk" |
| 2 | Restriction | "Publish Quote" button is disabled |
| 3 | Request Approval | Estimator adds note: "Matching competitor price for strategic entry" |
| 4 | Notification | Sales Manager receives an app/email alert |
| 5 | Action | Manager reviews cost buildup (UC-301) and benchmark (UC-303) |
| 6 | Decision | Manager clicks "Approve" |
| 7 | Resolution | Quote button enabled; timestamped approval added to audit log |
UC-305: What-If / Scenario Simulation¶
Priority: P1 - Important
Complexity: High
Actor: Estimator
Scenario: Estimator wants to see the cost impact of changing key variables without creating a permanent new version. Includes quantity/volume discount modeling for sales negotiations.
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | Enter "Simulation Mode" | System snapshots current quote state into volatile memory |
| 2 | Adjust "Machine Load" to 120% | System recalculates all MHR-dependent operations in real-time |
| 3 | Toggle "Premium Material Source" | System applies alternate RM rate from master |
| 4 | Adjust "Batch Size" exponentially | System shows a curve of cost-per-piece optimization |
| 5 | Compare Simulation vs. Baseline | UI shows a "Ghost Version" overlay for side-by-side analysis |
| 6 | Apply to Quote | System converts simulation into a permanent version (v-new) |
Quantity Discount Scenarios:
Enable sales teams to quickly model pricing for different quantities to support negotiations.
| Quantity | Setup Amortization | Material Discount | NRE Impact | Price/Unit |
|---|---|---|---|---|
| 500 pcs | ₹2.40/pc | 0% | ₹133.80/pc | ₹586.20 |
| 1,000 pcs | ₹1.20/pc | 0% | ₹66.90/pc | ₹518.10 |
| 2,500 pcs | ₹0.48/pc | 2% | ₹26.76/pc | ₹474.24 |
| 5,000 pcs | ₹0.24/pc | 5% | ₹13.38/pc | ₹456.62 |
| 10,000 pcs | ₹0.12/pc | 8% | ₹6.69/pc | ₹441.81 |
Quantity Discount Rules:
| Rule | Threshold | Discount Type |
|---|---|---|
| Setup Amortization | All quantities | Inverse linear (setup ÷ qty) |
| Material Volume Discount | 2,000+ pcs | Tiered (2%, 5%, 8%) |
| NRE Proration | First order only | Spread over MOQ |
| Tooling Recovery | Configurable | Per customer agreement |
What-If Parameters:
| Parameter | Range | Impact |
|---|---|---|
| Quantity | 100 - 100,000 | Setup, NRE, material discounts |
| Material Source | Standard/Premium | +10-20% on RM |
| Machine Load | 80-120% | MHR adjustment |
| Lead Time | Rush/Normal | Premium multiplier |
| Payment Terms | Net 30/60/90 | Cash discount |
UI Display:
Quantity Analysis for Part #AX-505
────────────────────────────────────
500 pcs 1,000 pcs 5,000 pcs
───────── ────────── ──────────
Material ₹190.00 ₹190.00 ₹180.50 (-5%)
Process ₹182.40 ₹181.20 ₹180.24
NRE ₹133.80 ₹66.90 ₹13.38
Overhead ₹30.00 ₹30.00 ₹30.00
───────── ────────── ──────────
TOTAL ₹586.20 ₹518.10 ₹456.62
Savings Baseline -11.6% -22.1%
[Generate Multi-Qty Quote PDF] [Apply 5,000 to Quote]
UC-306: Risk & Confidence Scoring¶
Priority: P1 - Important
Complexity: Medium
Actor: System (Automated)
Scenario: The system assigns a 0-100 "Confidence Score" to a quote based on data maturity.
Scoring Pillars:
| Pillar | Logic | Weight | Impact |
|---|---|---|---|
| Material Freshness | 100% if rate < 7 days; 40% if > 30 days | 40% | Penalizes quotes with stale prices |
| Operational History | 100% if based on historical winner (UC-104); 50% if manual | 40% | Incentivizes reuse of proven routing |
| Margin Safety | 100% if above floor; High risk if below (UC-304) | 20% | Flags financial risk in low-margin deals |
System Action: - High Confidence (90+): Quote is ready for direct PDF export. - Low Confidence (< 60): System flags quote with: "Warning: This quote relies on 2-month old Steel Rates. Risk of under-quoting is High." - Audit: Score is embedded in the internal Excel export for Manager review.
UC-307: Post-Order Feedback Loop (Actual vs Quote)¶
Priority: P2 - Future
Complexity: High
Actor: Admin / Finance
Scenario: After an order is completed, the system compares the "Estimated Cost" with the "Actual Cost" from the factory floor.
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | Order Completed | System pulls actual consumption data from Tally/ERP |
| 2 | Cost Reconciliation | Compares Estimated Material (2.3kg) vs Actual (2.5kg) |
| 3 | Variance Flagging | Highlights that actual yield was 8% lower than quoted |
| 4 | Intelligence Update | System asks: "Global yield for Part AX-102 seems lower. Update future quotes?" |
| 5 | Closing the Loop | If accepted, the "Material Master" for that part is updated to prevent future losses |
Versioning Use Cases¶
UC-401: Customer Requests Quantity Change¶
Priority: P1 - Important
Complexity: Low
Actor: Estimator
Flow:
| Step | Action | Result |
|---|---|---|
| 1 | Customer emails: "Please requote for 2000 pcs instead of 500" | Request received |
| 2 | Estimator opens quote v1.0 | Quote loaded |
| 3 | Clicks "Create New Version" | Version dialog opens |
| 4 | Changes quantity: 500 → 2000 | Recalculating... |
| 5 | System recalculates | Setup costs amortized over 2000 pcs (lower per-piece) Total cost per piece drops from ₹529 to ₹487 |
| 6 | Estimator adds note: "Qty change: 500 → 2000 pcs" | Note saved |
| 7 | Saves as v2.0 | Version created |
| 8 | Generates new quote | Quote ready |
Key Insight: Batch economics automatically calculated
UC-402: Material Price Increase¶
Priority: P1 - Important
Complexity: Medium
Actor: Admin
Scenario: Steel prices increased 12% across the board
Flow:
| Step | Action | Impact |
|---|---|---|
| 1 | Admin updates Material Master: SAE4140: ₹89.5/kg → ₹99.5/kg Effective date: 2026-01-24 |
Rate updated |
| 2 | System flags 47 open quotes using SAE4140 | Affected quotes identified |
| 3 | Admin selects "Bulk Update Affected Quotes" | Batch process started |
| 4 | For each quote: Create new version (v1.1, v1.2, etc.) Recalculate with new rate Add note: "RM price update (12% increase)" |
47 versions created |
| 5 | Estimators review and approve changes | Changes reviewed |
| 6 | Updated quotes sent to customers | Quotes sent |
Governance: Price changes auditable, traceable to source
UC-403: Dynamic Material Pricing with Volatility Buffer¶
Priority: P1 - Important
Complexity: Medium
Actor: System / Admin
Scenario: Automatically build price buffers into quotes based on historical material price volatility (e.g., +5% for steel over 3-month validity).
Business Context: - Material prices fluctuate between quote and order - Long quote validity periods increase price risk - Manual buffer calculations are inconsistent
Flow:
| Step | Action | System Response |
|---|---|---|
| 1 | System analyzes material price history | Last 12 months data retrieved |
| 2 | Calculate volatility metrics | Mean: ₹95/kg, Std Dev: ₹8/kg, Max swing: +15% |
| 3 | Determine quote validity period | 90 days selected |
| 4 | Apply volatility buffer | +5% buffer recommended based on 90-day forecast |
| 5 | Show buffer in cost breakdown | "Material buffer: ₹9.50/kg (5% volatility protection)" |
| 6 | Estimator accepts or adjusts | Buffer applied to quote |
Volatility Buffer Rules:
| Material Category | 30-day Buffer | 60-day Buffer | 90-day Buffer |
|---|---|---|---|
| Structural Steel | 2% | 4% | 6% |
| Stainless Steel | 3% | 5% | 8% |
| Aluminum | 4% | 6% | 10% |
| Copper/Brass | 5% | 8% | 12% |
| Plastics | 1% | 2% | 3% |
Configuration:
volatility_buffer:
enabled: true
calculation_method: "historical_stddev" # or "manual", "forecast"
lookback_months: 12
confidence_level: 0.95 # 95th percentile
minimum_buffer: 2%
maximum_buffer: 15%
warning_threshold: 10% # Alert if buffer exceeds this
Quote Display:
Material Cost: ₹263.95
├─ Base Material: ₹251.38 (SAE4140 @ ₹99.5/kg)
├─ Volatility Buffer: ₹12.57 (+5%)
│ └─ Reason: 90-day quote validity, steel volatility
└─ Total Material: ₹263.95
Audit Trail: - Buffer percentage and reasoning logged - Historical prices at quote time recorded - Actual vs. quoted comparison for future learning
Output Use Cases¶
UC-501: Generate Standard Quote¶
Priority: P0 - Critical
Complexity: Medium
Actor: Estimator
Output Requirements: - Professional PDF for customer - Detailed Excel for internal review
PDF Quote Structure:
| Section | Content |
|---|---|
| Header | Company Logo, Quote #Q-2026-0042, Date: 2026-01-24, Valid Until: 2026-02-24 |
| Customer Info | Customer: ABC Manufacturing Part: Receiver Housing (Drawing #RH-2024-05) |
| Pricing Scenarios | Base (25%): 1000 pcs @ ₹661.50 = ₹661,500 Aggressive (15%): 1000 pcs @ ₹608.00 = ₹608,000 Safe (35%): 1000 pcs @ ₹714.50 = ₹714,500 |
| Terms | Payment Terms: Net 30 Delivery: 6-8 weeks ARO Tooling: Included in piece price |
| Technical Specs | Material: SAE4140 Steel, 21mm diameter Processes: Cut, Turn, Thread, Heat Treat, Coat Quality: As per drawing specifications |
Excel Breakdown Structure:
| Sheet | Content |
|---|---|
| Sheet 1: Summary | Same as PDF |
| Sheet 2: Detailed Cost Breakdown | Material costs Each operation with time/rate Tooling costs Overheads Scrap factors |
| Sheet 3: Assumptions & Notes | Manual overrides with justifications Critical assumptions Customer-specific notes |
UC-502: Quote for Tender Submission¶
Priority: P1 - Important
Complexity: Low
Actor: Estimator
Scenario: Government tender requires specific format
Flow:
| Step | Action | Output |
|---|---|---|
| 1 | Generate standard quote | PDF + Excel created |
| 2 | Export cost data to tender template (Excel) | Data exported |
| 3 | Fill required fields | GST breakdown Make in India certification Delivery schedule |
| 4 | Upload to tender portal | Submitted |
| 5 | Keep CostEngine version for future reference | Version saved |
Feature: Export to custom templates
Edge Cases & Error Handling¶
UC-601: Missing Critical Data¶
Priority: P1 - Important
Complexity: Low
Actor: System
Scenario: Excel uploaded without material grade
Flow:
| Step | System Action | User Action | UI/UX Feedback |
|---|---|---|---|
| 1 | System detects missing material grade | - | Red Highlight on field B7 in the Excel preview table. |
| 2 | Halts import, shows error | - | Toast Notification: "Incomplete Data". A modal slides in showing the missing field. |
| 3 | - | Estimator enters "SAE4140" | Field turns from Red to White with a checkmark [OK]. |
| 4 | Import resumes | Click "Continue" | Background processing indicator shown. |
UC-602: Unrealistic Values¶
Priority: P1 - Important
Complexity: Medium
Actor: System
Scenario: Typo in Excel: Cycle time = 100 hours (should be 1.0)
Flow:
| Step | System Action | Detection | UI/UX Feedback |
|---|---|---|---|
| 1 | System calculates operation cost = ₹12,000 | Calculation complete | Total cost bar turns Orange (Suspicious value). |
| 2 | Validation rule triggers | Cycle > 24 hrs | Inline Warning Icon [!] next to the Turning Cycle row. |
| 3 | Warning shown | Popup triggered | Tooltip: "Value is 10x higher than peer parts." |
| 4 | Estimator clicks "Fix" | Value updated | Value turns Green briefly to confirm change. |
| 5 | System recalculates | Cost: ₹120/piece | Dashboard totals update in real-time with smooth animation. |
Safety: Catch data entry errors before bad quotes
UC-603: System-Wide UI Validation Patterns¶
Priority: P1 - Important
Category: UX/UI Hygiene
Standard system behaviors for input and feedback:
| Scenario | UI Pattern | Behavior |
|---|---|---|
| Mandatory Field | Asterisk (*) | Field label includes a red asterisk. Submit is disabled until filled. |
| Logic Conflict | Error Bar | If Net Weight > Gross Weight, show a persistent red header: "Physical Inconsistency Detected." |
| Manual Override | Yellow Highlight | Any cell carrying a manual override must have a yellow background to distinguish from calculated values. |
| Unsaved Changes | Form Guard | Prompt "Unsaved Changes" if the user attempts to navigate away during an edit. |
| Calculation Delay | Skeleton Load | Show shimmering placeholder states if background calculations take > 200ms. |
UC-604: Role-Based Access Control (RBAC)¶
Priority: P0 - Critical
Complexity: Medium
Actor: Admin
Scenario: Ensuring different personas have appropriate levels of control over costing and pricing.
Permissions Table:
| Feature | Estimator | Manager | Admin |
|---|---|---|---|
| Import Excel | Yes | Yes | Yes |
| Apply Overrides | Yes | Yes | Yes |
| Approve Low Margin | No | Yes | Yes |
| Update Master Rates | No | No | Yes |
| Configure Governance Floors | No | No | Yes |
Integration Use Cases¶
UC-701: Sync with Tally ERP¶
Priority: P2 - Future
Complexity: High
Actor: Admin (scheduled job)
Flow:
| Time | Action | Result |
|---|---|---|
| 2:00 AM | Nightly job runs | Job started |
| 2:01 AM | System queries CostEngine for won quotes | 12 won quotes found |
| 2:02 AM | For each won quote: Create customer order in Tally Transfer BOM and quantities Set pricing from quote |
Orders created |
| 2:05 AM | System logs sync status | Log updated |
| 8:00 AM | Morning report shows 12 quotes synced | Report available |
Integration Point: REST API to Tally
Decision Intelligence / Analytics Use Cases¶
UC-910: Decision Analytics & Cost Intelligence¶
Priority: P2 - Future
Complexity: High
Actor: Admin / Finance
Objective: Transform costing data into strategic insights.
Capabilities:
- Historical Cost Comparison: Compare similar parts across Time, Customers, and Plants.
- Operation-Level Analysis: Identify cost-heavy operations and inefficient machines.
- Raw Material Intelligence: Track supplier-wise cost trends and impact of rate fluctuations.
- Margin Sensitivity Analysis: Simulate margin changes, MOQ variations, and see impact on profitability.
- Customer Profitability Analysis: Identify margin-dilutive customers and renegotiation opportunities.
UC-308: Tracking Manual Checks¶
Priority: P1 - Important
Complexity: Medium
Actor: Admin / Manager
Scenario: Find out which parts or machines need the most manual "nudges" from the team.
Steps:
| Step | Action | Visualization |
|---|---|---|
| 1 | Admin opens the "Manual Check Dashboard" | Heatmap showing most-overridden fields |
| 2 | Filter for a specific machine (e.g., "CNC-01") | List of every time someone changed a cycle |
| 3 | See the trend: Cycle times are 15% lower than the default | Comparison chart |
| 4 | Click "Update Defaults": System fixes the master data | Defaults are now accurate |
Key Metric: Reduction in the "Manual Check Rate" over time.
UC-702: Email Integration¶
Priority: P2 - Future
Complexity: Low
Actor: Estimator
Flow:
| Step | Action | Pre-filled Data |
|---|---|---|
| 1 | Generate quote PDF | PDF created |
| 2 | Click "Email Quote" | Email compose opens |
| 3 | System pre-fills | To: {{ customer_email }} (from RFQ) Subject: "Quote #{{ quote_number }} for {{ part_number }}" Body: Professional Jinja2 template Attachment: PDF + Excel |
| 4 | Estimator reviews and sends | Email sent |
| 5 | System tracks | "Quote sent on 2026-01-24 10:30 AM" |
Technical Use Cases (Pipeline & Ops)¶
UC-801: Incremental Excel Sync¶
Actor: Background Job (Temporal/Node.js)
Ensures that large Excel files don't bog down the UI and that only changed data creates new database versions.
- Checksum Generation: System hashes the incoming Excel file/sheet.
- Comparison: Compares with the hash of the last
v-current. - Diff Engine: If hashes differ, identifies which specific rows (Operations) or clusters (Material) have changed.
- Async Load: UI shows "Importing in progress (75%)" while the background worker processes the diff.
- Completion: User receives a toast: "Sync complete. 2 Operations updated, Material cost unchanged."
UC-802: Automated Rate Lock¶
Actor: System
Ensures that once a quote is "Published", changing a global Raw Material rate doesn't break historical data.
- Publish Trigger: Estimator marks quote as "Final".
- Snapshot: System copies the current global Material Rate and MHR into the
quote_itemrecord. - Decoupling: The quote now references its internal snapshot, not the global Master.
- Verification: Admin updates Steel Rate. Quote remains at the old rate unless the estimator explicitly chooses to "Upgrade Version".
UC-901: Database Failover Recovery¶
Actor: DevOps / Infrastructure
Standard Operating Procedure (SOP) for when the primary database becomes unresponsive.
- Detection: Monitoring system triggers an alert (Avg Latency > 2s).
- Traffic Halt: Load balancer returns 503 "Maintenance Underway".
- Failover: Promote Read Replica to Primary status.
- Verification: Run
SELECT count(*) FROM quotesto ensure zero data loss from the last 1-hour window (matching RPO). - Recovery: Restore traffic and notify Admin of the failover event.
UC-902: Audit Trail Forensic Search¶
Actor: Admin
Tracking down "who changed what" when a customer disputes a quote from 6 months ago.
- Search Params: Admin enters
part_number = "Y"and date range. - Log Retrieval: System pulls all
audit_logswheretarget_idmatches the part. - Timeline View: Displays a chronological list of:
- [Jan 10]: User A changed MHR from 200 to 220.
- [Jan 12]: User B overrode Steel Rate to 65.00 with reason "Special Supplier offer".
- Export: Admin exports this as a PDF "Traceability Report" to show the customer why the price changed mid-project.
UC-903: Containerized Deployment (Docker)¶
Actor: DevOps
Ensures the application runs identically in local dev, staging, and production environments.
- Containerization: Packaging of the FastAPI backend, Next.js frontend, and Celery workers into industry-standard Docker images.
- Orchestration: Use of
docker-composefor local testing and Cloudflare/Cloud Run for production. - Reproducibility: Ability to spin up a fresh testing environment in < 5 minutes for trial-run simulations.
UC-904: Centralized Observability & Logging¶
Actor: Admin / Developer
Consolidating logs from the API, Database, and Background workers into a single pane of glass.
- Unified Logging: Implementation of structured (JSON) logging across all microservices.
- Alerting: Integration with Sentry/ELK for high-severity error alerting.
- Telemetry: Tracking system health metrics (API latency, worker queue depth) to prevent downtime.
UC-905: MLOps Pipeline (Phase 3)¶
Actor: System / Data Science
Lifecycle management for the AI agents and Price Prediction models.
- Model Training: Automated retraining of RM rate forecasting models as new market data arrives.
- Version Control: Tracking which version of an LLM or Embedding model produced a specific agentic suggestion.
- Evaluation: Continuous monitoring of Agentic "Helpfulness" vs. Human overrides.
Use Case Testing Matrix¶
| Use Case | Manual Test | Automated Test | User Acceptance | Priority |
|---|---|---|---|---|
| UC-001 | Required | E2E test | 5 real RFQs | P0 |
| UC-002 | Required | Integration | 3 rush scenarios | P0 |
| UC-101 | Required | Unit test | 3 templates | P0 |
| UC-102 | Required | Unit test | Error scenarios | P1 |
| UC-103 | Required | Manual | Legacy formats | P1 |
| UC-201 | Spot check | Unit test | N/A | P0 |
| UC-202 | Spot check | Unit test | Multi-op routing | P0 |
| UC-203 | Spot check | Unit test | Scrap scenarios | P0 |
| UC-301 | Required | Manual | Customer demo | P0 |
| UC-302 | Required | Integration | Version test | P1 |
| UC-401 | Required | Integration | Qty changes | P1 |
| UC-402 | Required | Integration | Bulk updates | P1 |
| UC-501 | Required | Output test | Quote review | P0 |
| UC-502 | Required | Manual | Tender format | P1 |
| UC-601 | Required | Unit test | Missing data | P1 |
| UC-602 | Required | Unit test | Validation | P1 |
| UC-701 | Manual | Integration | ERP sync | P2 |
| UC-702 | Required | Integration | Email send | P2 |
| UC-801 | Required | Pipeline test | Sync logic | P0 |
| UC-802 | Required | Unit test | Snapshot lock | P1 |
| UC-901 | Manual | Chaos Test | Failover SOP | P1 |
| UC-902 | Required | Manual | Forensic search | P1 |
| UC-903 | Required | Unit Test | Docker Build | P1 |
| UC-904 | Required | Integration | Sentry Logs | P1 |
| UC-905 | Manual | Sandbox | Model Version | P2 |
Related Documentation¶
- Detailed Use Case Estimates → - Granular effort estimates for implementation
- Modular Blocks → - Architecture building blocks
- Core Workflows → - Detailed process flows
- MVP Scope → - Feature specifications