ADR-005: Modular Costing Blocks (Lego Architecture)¶

Status: Proposed
Date: 2026-01-24

Context¶

Costing logic is often monolithic, making it hard to reuse components (e.g., using "Heat Treat" logic for two different parts).

Decision¶

Implement a Micro-Service logic pattern (Modular Blocks) where each cost component is an independent, versioned entity.

🧱 The Lego Concept¶

Alignment

Core Promise: "Explainable costing from your existing Excel logic — quote-ready in minutes."

Target: Small/mid manufacturers with messy Excel costing doing frequent RFQs

Lego Block Architecture¶

MVP Building Blocks¶

graph TB
    subgraph "Input Layer"
        Excel[ Excel Import<br/>RFQ + BOM + Routing]
    end

    subgraph "Core Engine (v1)"
        Material[ Material Cost<br/>RM Rate × Weight ÷ Yield]
        Operations[ Operations Cost<br/>Setup + Cycle + MHR]
        Scrap[ Scrap & Yield<br/>Cascading %]
        Overhead[ Overheads<br/>Factory + Admin %]
    end

    subgraph "Intelligence Layer"
        Explain[ Explainability<br/>Why this number?]
        Version[📝 Versioning<br/>v1/v2 tracking]
    end

    subgraph "Output Layer"
        Margins[ Margin Scenarios<br/>Base/Aggressive/Safe]
        Quote[ Quote Pack<br/>PDF + Excel]
    end

    Excel --> Material
    Excel --> Operations

    Material --> Scrap
    Operations --> Scrap
    Scrap --> Overhead

    Overhead --> Explain
    Overhead --> Version

    Explain --> Margins
    Version --> Margins
    Margins --> Quote

    style Excel fill:#e3f2fd
    style Material fill:#fff3e0
    style Operations fill:#fff3e0
    style Explain fill:#fce4ec,stroke:#e91e63,stroke-width:2px
    style Quote fill:#c8e6c9

Core Blocks Breakdown¶

1. Excel Import Block¶

What it does: - Accepts Excel template upload - Extracts RFQ details, BOM, routing/operations - Maps fields to internal schema

MVP Scope: - Yes Excel template import - Yes BOM parsing - Yes Routing extraction - No CAD geometry parsing (out of scope) - No ERP integration (out of scope)

Tech: - Python: pandas, openpyxl - Field mapping configuration - Basic validation

2. Material Cost Block¶

Function: Calculates the raw material cost based on weights and market rates.

Material Costing Specification →
View formulas, rate lookup hierarchy, and scrap credit logic.

Current Capabilities: - [x] Gross/Net weight handling - [x] RM rate master data - [x] Yield percentage - [x] Scrap recovery (credit)

3. Operations Cost Block¶

Function: Translates routing steps and machine times into conversion costs.

Operations & Routing Specification →
View MHR logic, batch amortization, and efficiency formulas.

Current Capabilities: - [x] Setup vs Cycle time - [x] Batch amortization - [x] Machine Master integration - [ ] Tool life optimization (Future) - [ ] Multi-plant routing (Future)

4. Scrap & Yield Block¶

Function: Adjusts quantities across the production flow to account for losses.

Scrap & Yield Specification →
View cascading calculation models and explainability trees.

Current Capabilities: - [x] Material-level scrap - [x] Operation-level scrap - [x] Compounding logic (Backward-chain)

5. Overhead Block¶

Function: Allocates plant/admin costs to individuals parts.

Overheads Specification →
View allocation methods and Indian MSME patterns.

Current Capabilities: - [x] Embedded MHR models - [x] Percentage-based allocation - [x] Fixed piece-rate overheads

6. Explainability Block¶

Function: Provides the evidence for every calculated number.

Explainability Framework →
View UI patterns, source tagging, and lineage tracking.

Current Capabilities: - [x] Every line traceable to cell/master - [x] Data lineage metadata - [x] Math breakdown display - [ ] AI-assisted explanations (Future)

7. Versioning Block 📝¶

Function: Manages revision history and side-by-side comparisons.

Versioning Specification →
View immutable snapshots and diff logic.

Current Capabilities: - [x] Snapshot upon save - [x] Change logs - [x] Side-by-side comparison (diff) - [ ] Approval workflows (Future)

8. Margin Scenarios Block¶

Function: Calculates strategic pricing.

Pricing & Margins Workflow →
View scenario modeling and payment terms adjustments.

Current Capabilities: - [x] Base/Aggressive/Safe scenarios - [x] Customer-specific margin rules - [x] Payment term surcharges - [ ] Tiered volume pricing (Future)

9. Quote Pack Output Block¶

Generates: - Yes PDF quote (professional format) - Yes Excel breakdown (detailed costs) - Yes Email-ready format

Contents: 1. Cover page (quote #, validity, customer) 2. Part summary (prices for all variants) 3. Cost breakdown (per line item) 4. Assumptions list (all defaults/overrides) 5. Margin scenarios comparison 6. Terms & conditions

How Blocks Connect¶

Data Flow Through Blocks¶

sequenceDiagram
    participant User
    participant Excel as Excel Import
    participant Material as Material Block
    participant Ops as Operations Block
    participant Scrap as Scrap Block
    participant OH as Overhead Block
    participant Explain as Explainability
    participant Margin as Margins Block
    participant Output as Quote Output

    User->>Excel: Upload costing sheet
    Excel->>Material: Extract material data
    Excel->>Ops: Extract operations

    Material->>Scrap: Material cost
    Ops->>Scrap: Operations cost

    Scrap->>OH: Apply scrap adjustments
    OH->>Explain: Add overhead

    Explain->>Margin: Cost + assumptions
    Margin->>Output: Apply pricing scenarios

    Output->>User: PDF + Excel quote

    Note over User,Output: Total time: <15 minutes

MVP Scope Boundaries¶

Yes IN SCOPE (Must Build)¶

Block	Features
Excel Import	Template upload, BOM/routing extraction
Material Cost	Grade, weight, RM rate, yield
Operations	Setup/cycle, batch, MHR, tooling
Scrap	Material + operation scrap %
Overhead	Factory + admin %
Explainability	Per-line breakdown, assumptions
Versioning	v1/v2 tracking, reason for change
Margins	3 scenarios, customer rules
Output	PDF + Excel quote pack

No OUT OF SCOPE (Not Building)¶

CAD geometry parsing
Full ERP integration
Fancy dashboards/analytics
Multi-plant optimization
Advanced approval workflows
Automated pricing decisions
Tool life modeling
AI-generated cost suggestions

Technology Stack per Block¶

graph LR
    subgraph "Frontend Blocks"
        UI[React UI<br/>Upload + Review]
    end

    subgraph "Backend Blocks"
        Parser[Python<br/>Excel Parser]
        Engine[Python/Node<br/>Cost Engine]
        Calc[Python<br/>Calculations]
        Gen[Python<br/>PDF/Excel Gen]
    end

    subgraph "Data Blocks"
        PG[(PostgreSQL<br/>Versioning)]
        Cache[(Redis<br/>Fast lookups)]
    end

    UI --> Parser
    Parser --> Engine
    Engine --> Calc
    Calc --> PG
    PG --> Gen
    Engine --> Cache
    Gen --> UI

    style UI fill:#e3f2fd
    style Engine fill:#fce4ec,stroke:#e91e63,stroke-width:2px
    style PG fill:#f3e5f5

Alignment with Differentiation Moats¶

Excel-first Onboarding¶

Blocks that support this: - Yes Excel Import Block - Absorbs existing templates - Yes Material Cost Block - Uses their RM rates - Yes Operations Block - Imports their routing

How: Upload Excel → System maps fields → Refine gradually

Operations-first Model¶

Blocks that support this: - Yes Operations Block - Setup/cycle/batch at the core - Yes Scrap Block - Operation-level scrap tracking

Competitive edge: Others focus on material; we nail operations complexity

Explainable + Defensible¶

Blocks that support this: - Yes Explainability Block - Every line traceable - Yes Versioning Block - Change history

How: Click any cost → See formula → See assumptions → Override with reason

Customer-specific Pricing¶

Blocks that support this: - Yes Margins Block - Per-customer rules - Yes Quote Output - Multiple scenarios

How: Store customer margins → Apply automatically → Show 3 scenarios

Composability & Extensibility¶

Adding New Blocks (Future)¶

Easy to add: - Yes Outside Process Block (heat treatment, coating) - Yes Packing Cost Block (from your Excel!) - Yes Logistics Block (freight calculations)

How modular design helps:

graph LR
    Core[Core Cost] --> New1[+ Outside Process]
    Core --> New2[+ Packing]
    Core --> New3[+ Logistics]
    New1 --> Final[Final Cost]
    New2 --> Final
    New3 --> Final

    style Core fill:#fff3e0
    style Final fill:#c8e6c9

Each block is independent → Can be added/removed without breaking others

Summary: MVP = 9 Lego Blocks¶

#	Block	Status	Priority
1	Excel Import	Yes Defined	P0 - Critical
2	Material Cost	Yes Defined	P0 - Critical
3	Operations Cost	Yes Defined	P0 - Critical
4	Scrap & Yield	Yes Defined	P0 - Critical
5	Overheads	Yes Defined	P0 - Critical
6	Explainability	Yes Defined	P0 - Critical
7	Versioning	Yes Defined	P1 - Important
8	Margin Scenarios	Yes Defined	P0 - Critical
9	Quote Output	Yes Defined	P0 - Critical

Build sequence: 1. Core engine (blocks 2-5) 2. Excel importing (block 1) 3. Explainability (block 6) 4. Outputs (blocks 8-9) 5. Versioning (block 7)

System Architecture → - Full technical architecture
Data Pipeline → - Excel import details
Semantic Layer → - Metrics catalog
Costing Process → - Detailed workflows