System Architecture¶

Technical architecture for CostEngine (MfgIQ).

High-Level Architecture¶

graph TB
    Estimator[Estimator User]
    Admin[Admin User]
    Customer[Customer]

    CostEngine[CostEngine System]

    Email[Email System]
    ERP[ERP/Tally]
    Excel[Excel Import/Export]

    Estimator --> CostEngine
    Admin --> CostEngine
    CostEngine --> Email
    CostEngine --> ERP
    CostEngine --> Excel
    CostEngine --> Customer

    style CostEngine fill:#fce4ec,stroke:#e91e63,stroke-width:3px
    style Estimator fill:#e3f2fd
    style Admin fill:#e3f2fd
    style Email fill:#fff3e0
    style ERP fill:#fff3e0

Application Architecture¶

Three-Tier Architecture¶

graph TB
    subgraph "Presentation Layer"
        UI[Web UI - React]
        PDF[PDF Generator]
        Excel[Excel Generator]
    end

    subgraph "Application Layer"
        API[REST API - FastAPI/Node.js]
        Auth[Authentication]
        BL[Business Logic]
        CE[Cost Engine]
        VE[Validation Engine]
        QE[Quote Generator]
    end

    subgraph "Data Layer"
        DB[(PostgreSQL)]
        Cache[(Redis)]
        Files[File Storage]
    end

    UI --> API
    PDF --> API
    Excel --> API

    API --> Auth
    API --> BL
    BL --> CE
    BL --> VE
    BL --> QE

    CE --> DB
    VE --> DB
    QE --> DB
    API --> Cache
    QE --> Files

    style UI fill:#e3f2fd
    style API fill:#fff3e0
    style CE fill:#fce4ec
    style DB fill:#f3e5f5

Component Architecture¶

Frontend Components¶

graph TD
    A[App Shell] --> B[Authentication]
    A --> C[Navigation]
    A --> D[Main Content Area]

    D --> E[Quote List View]
    D --> F[Quote Detail View]
    D --> G[Part Setup View]
    D --> H[Cost Builder View]
    D --> I[Review View]
    D --> J[Masters Management]

    F --> F1[Part Info Panel]
    F --> F2[Material Cost Card]
    F --> F3[Operations List]
    F --> F4[Cost Summary]

    H --> H1[Material Input Form]
    H --> H2[Routing Builder]
    H --> H3[Outside Process Form]
    H --> H4[Live Cost Preview]

    style A fill:#e3f2fd
    style D fill:#fff3e0
    style H fill:#fce4ec

Backend Modules¶

graph LR
    subgraph "Core Modules"
        CM[Cost Module]
        QM[Quote Module]
        MM[Master Data Module]
        UM[User Module]
    end

    subgraph "Calculation Engines"
        MCE[Material Cost Engine]
        OCE[Operations Cost Engine]
        OPE[Outside Process Engine]
        SCE[Scrap Calculator]
        OHE[Overhead Engine]
    end

    subgraph "Output Engines"
        PDFE[PDF Generator]
        XLSE[Excel Generator]
        EML[Email Service]
    end

    CM --> MCE
    CM --> OCE
    CM --> OPE
    CM --> SCE
    CM --> OHE

    QM --> CM
    QM --> PDFE
    QM --> XLSE
    QM --> EML

    MM --> CM
    UM --> QM

    style CM fill:#fce4ec,stroke:#e91e63,stroke-width:3px
    style QM fill:#e3f2fd
    style MM fill:#fff3e0

Data Model¶

Core Entities¶

erDiagram
    CUSTOMER ||--o{ RFQ : "submits"
    RFQ ||--|{ QUOTE : "generates"
    QUOTE ||--|{ QUOTE_VERSION : "has"
    QUOTE_VERSION ||--|{ PART : "contains"
    PART ||--|| MATERIAL : "uses"
    PART ||--|{ ROUTING : "has"
    ROUTING ||--|{ OPERATION : "contains"
    OPERATION ||--|| MACHINE : "uses"
    PART ||--o{ OUTSIDE_PROCESS : "requires"
    PART ||--|| COST_SUMMARY : "has"

    CUSTOMER {
        uuid id PK
        string name
        string contact_email
        json default_margins
        json payment_terms
    }

    RFQ {
        uuid id PK
        uuid customer_id FK
        string rfq_number
        date received_date
        json parts_list
        string status
    }

    QUOTE {
        uuid id PK
        uuid rfq_id FK
        string quote_number
        date created_date
        int current_version
    }

    QUOTE_VERSION {
        uuid id PK
        uuid quote_id FK
        int version_number
        decimal total_cost
        json margin_scenarios
        string status
        timestamp created_at
    }

    PART {
        uuid id PK
        uuid quote_version_id FK
        string part_number
        uuid material_id FK
        decimal gross_weight
        decimal net_weight
        int quantity
    }

    MATERIAL {
        uuid id PK
        string grade
        string specification
        decimal current_rate
        string unit
    }

    ROUTING {
        uuid id PK
        uuid part_id FK
        int sequence
        uuid operation_id FK
    }

    OPERATION {
        uuid id PK
        string operation_type
        uuid machine_id FK
        decimal setup_time
        decimal cycle_time
        decimal scrap_percent
    }

    MACHINE {
        uuid id PK
        string machine_name
        decimal mhr
        string machine_type
    }

    OUTSIDE_PROCESS {
        uuid id PK
        uuid part_id FK
        string process_name
        string pricing_model
        decimal rate
        decimal minimum_charge
    }

    COST_SUMMARY {
        uuid id PK
        uuid part_id FK
        decimal material_cost
        decimal operations_cost
        decimal outside_cost
        decimal overhead_cost
        decimal total_cost
        json breakdown
    }

Calculation Flow Architecture¶

flowchart TD
    Start[User Initiates Calculation] --> Fetch[Fetch Part Data]
    Fetch --> M[Material Cost Module]
    Fetch --> O[Operations Module]
    Fetch --> OP[Outside Process Module]

    M --> MA[Get Material Master]
    MA --> MC[Calculate Material Cost]
    MC --> MS[Apply Scrap]

    O --> OL[Load Routing]
    OL --> OR{For Each Operation}
    OR --> OS[Calculate Setup Cost]
    OR --> OC[Calculate Cycle Cost]
    OR --> OT[Calculate Tooling]
    OS --> OSum[Sum Operation Costs]
    OC --> OSum
    OT --> OSum
    OSum --> OSc[Apply Operation Scrap]

    OP --> OPR{For Each Process}
    OPR --> OPC[Calculate Process Cost]
    OPC --> OPSum[Sum Outside Costs]

    MS --> Agg[Aggregate All Costs]
    OSc --> Agg
    OPSum --> Agg

    Agg --> OH[Apply Overheads]
    OH --> Val[Validate Results]
    Val --> Over{Overrides?}
    Over -->|Yes| ApplyO[Apply Overrides]
    Over -->|No| Final
    ApplyO --> Final[Final Cost]

    Final --> Cache[Cache Result]
    Cache --> Return[Return to UI]

    style Start fill:#e3f2fd
    style M fill:#fff3e0
    style O fill:#fce4ec
    style Final fill:#c8e6c9,stroke:#4caf50,stroke-width:3px

Quote Generation Pipeline¶

sequenceDiagram
    participant U as User
    participant API as API Server
    participant CE as Cost Engine
    participant QG as Quote Generator
    participant PDF as PDF Service
    participant XLS as Excel Service
    participant Email as Email Service
    participant DB as Database

    U->>API: Request quote generation
    API->>DB: Fetch quote version data
    DB-->>API: Return complete data
    API->>CE: Validate cost calculations
    CE-->>API: Validation OK
    API->>QG: Initiate quote generation

    par PDF Generation
        QG->>PDF: Generate PDF quote
        PDF-->>QG: PDF bytes
    and Excel Generation
        QG->>XLS: Generate Excel breakdown
        XLS-->>QG: Excel bytes
    end

    QG->>DB: Save generated files
    QG-->>API: Files ready

    API->>Email: Send quote email
    Email-->>U: Email sent confirmation

    Note over U,Email: Total time: 2-5 seconds

Deployment Architecture¶

Cloud Infrastructure¶

graph TB
    subgraph "User Layer"
        Browser[Web Browser]
        Mobile[Mobile Browser]
    end

    subgraph "CDN / Load Balancer"
        CDN[Cloudflare]
        LB[Load Balancer]
    end

    subgraph "Application Tier"
        Web1[Web Server 1]
        Web2[Web Server 2]
        API1[API Server 1]
        API2[API Server 2]
    end

    subgraph "Data Tier"
        PG[(PostgreSQL Primary)]
        PG_R[(PostgreSQL Replica)]
        Redis[(Redis Cache)]
    end

    subgraph "Storage"
        S3[Object Storage S3]
    end

    Browser --> CDN
    Mobile --> CDN
    CDN --> LB
    LB --> Web1
    LB --> Web2
    Web1 --> API1
    Web2 --> API2

    API1 --> PG
    API2 --> PG
    API1 --> Redis
    API2 --> Redis
    PG --> PG_R

    API1 --> S3
    API2 --> S3

    style Browser fill:#e3f2fd
    style CDN fill:#fff3e0
    style API1 fill:#fce4ec
    style PG fill:#f3e5f5

Containerization Strategy¶

graph LR
    subgraph "Docker Compose / Kubernetes"
        subgraph "Frontend"
            React[React App Container]
        end

        subgraph "Backend"
            API[FastAPI Container]
            Worker[Background Worker]
        end

        subgraph "Services"
            DB[(PostgreSQL)]
            Cache[(Redis)]
            Queue[Task Queue]
        end
    end

    React --> API
    API --> DB
    API --> Cache
    API --> Queue
    Worker --> Queue
    Worker --> DB

    style React fill:#e3f2fd
    style API fill:#fff3e0
    style DB fill:#f3e5f5

Security Architecture¶

graph TD
    A[User Request] --> B{Authenticated?}
    B -->|No| C[Redirect to Login]
    B -->|Yes| D{Valid JWT?}
    D -->|No| C
    D -->|Yes| E{Authorized?}
    E -->|No| F[403 Forbidden]
    E -->|Yes| G[Process Request]

    G --> H{Data Access?}
    H -->|Read| I{Own Data?}
    H -->|Write| J{Own Data?}

    I -->|Yes| K[Allow Read]
    I -->|No| L[Check Admin Role]
    J -->|Yes| M[Allow Write]
    J -->|No| L

    L -->|Admin| K
    L -->|Not Admin| F

    K --> N[Return Data]
    M --> O[Update & Log]

    style A fill:#e3f2fd
    style G fill:#fff3e0
    style N fill:#c8e6c9

Authentication Flow¶

sequenceDiagram
    participant U as User
    participant UI as Frontend
    participant Auth as Auth Service
    participant API as API Server
    participant DB as Database

    U->>UI: Enter credentials
    UI->>Auth: POST /login
    Auth->>DB: Verify credentials
    DB-->>Auth: User found
    Auth->>Auth: Generate JWT
    Auth-->>UI: Return JWT + Refresh Token
    UI->>UI: Store tokens (localStorage)

    Note over U,UI: User authenticated

    U->>UI: Request protected resource
    UI->>API: GET /quotes (+ JWT header)
    API->>API: Verify JWT signature
    API->>API: Check expiration
    API->>API: Extract user ID from token
    API->>DB: Fetch data for user
    DB-->>API: Return data
    API-->>UI: Return response

Integration Architecture¶

graph TB
    CE[CostEngine Core]

    CE <-->|REST API| Tally[Tally ERP]
    CE <-->|SMTP| Email[Email Service]
    CE <-->|File Upload| Excel[Excel Import]
    CE <-->|Webhook| Zapier[Zapier/Integration]
    CE <-->|REST API| CustomERP[Custom ERP]

    style CE fill:#fce4ec,stroke:#e91e63,stroke-width:3px

API Design¶

RESTful Endpoints:

Performance Optimization¶

Caching Strategy¶

flowchart LR
    A[User Request] --> B{In Cache?}
    B -->|Yes| C[Return from Redis]
    B -->|No| D[Query Database]
    D --> E[Compute Result]
    E --> F[Store in Cache]
    F --> G[Return to User]

    style C fill:#c8e6c9
    style E fill:#fff3e0

Cache Layers: 1. Client-side: Recent quotes, master data 2. Application-level: Redis for cost calculations 3. Database-level: Query result caching

Scalability Considerations¶

Related Documentation¶

• Semantic Layer & Metrics - Metrics catalog, dimensional model, and business intelligence layer
• Data Pipeline - Excel import, ETL process, and data quality
• Costing Process - Business logic and workflows
• Domain Logic - Detailed specifications