High-Level System Context Diagram

Executive Summary

The Ergodic Insurance Limits framework analyzes insurance decisions using time-average (ergodic) theory rather than traditional ensemble averages. This approach reveals that insurance can enhance business growth even when premiums exceed expected losses by 200-500%, transforming insurance from a cost center to a growth enabler.

Simplified System Architecture

        flowchart LR
       %% Simplified Executive View
       INPUT[("📊 Market Data<br/>& Configuration")]
       BUSINESS[("🏭 Business<br/>Simulation")]
       ERGODIC[("📈 Ergodic<br/>Analysis")]
       OPTIMIZE[("🎯 Strategy<br/>Optimization")]
       OUTPUT[("📑 Reports &<br/>Insights")]

       INPUT --> BUSINESS
       BUSINESS --> ERGODIC
       ERGODIC --> OPTIMIZE
       OPTIMIZE --> OUTPUT

       %% Styling
       classDef inputStyle fill:#e3f2fd,stroke:#0d47a1,stroke-width:3px,font-size:14px
       classDef processStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,font-size:14px
       classDef outputStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:3px,font-size:14px

       class INPUT inputStyle
       class BUSINESS,ERGODIC,OPTIMIZE processStyle
       class OUTPUT outputStyle
    

Key Innovation: By comparing time-average growth (what one business experiences over time) with ensemble-average growth (statistical average across many businesses), the framework demonstrates that insurance fundamentally transforms the growth dynamics of volatile businesses.

System Architecture Overview (Detailed)

The actual implementation follows a sophisticated multi-layer architecture:

        graph TB
       %% Input Layer
       subgraph Inputs["📥 Input Layer"]
           CONF["Configuration<br/>(YAML/JSON)"]
           HIST["Historical Loss Data"]
           PARAMS["Business Parameters"]
       end

       %% Core Simulation
       subgraph Core["⚙️ Core Simulation Engine"]
           MANU["WidgetManufacturer<br/>(Business Model)"]
           LOSSG["ManufacturingLossGenerator<br/>(Loss Events)"]
           INS["InsuranceProgram<br/>(Coverage Tower)"]
           SIM["Simulation Engine<br/>(Time Evolution)"]
       end

       %% Financial Core
       subgraph Financial["💰 Financial Core"]
           LEDGER["Ledger<br/>(Double-Entry Accounting)"]
           ACCRUAL["AccrualManager<br/>(Accrual Timing)"]
           INSACCT["InsuranceAccounting<br/>(Premium Amortization)"]
           TAXH["TaxHandler<br/>(Tax Calculations)"]
           DECUTIL["decimal_utils<br/>(Decimal Precision)"]
       end

       %% Analysis Layer
       subgraph Analysis["📊 Analysis & Optimization"]
           MONTE["Monte Carlo Engine<br/>(10,000+ paths)"]
           ERGODIC["Ergodic Analyzer<br/>(Time vs Ensemble)"]
           OPT["Business Optimizer<br/>(Strategy Selection)"]
           SENS["Sensitivity Analysis<br/>(Parameter Impact)"]
       end

       %% Output Layer
       subgraph Outputs["📤 Output & Insights"]
           EXCEL["Excel Reports<br/>(Detailed Results)"]
           VIZ["Visualizations<br/>(Executive & Technical)"]
           METRICS["Risk Metrics<br/>(VaR, CVaR, Ruin Prob)"]
           STRATEGY["Optimal Strategy<br/>(Limits & Retentions)"]
       end

       %% Data Flow
       Inputs --> Core
       Core --> MONTE
       MONTE --> Analysis
       Analysis --> Outputs

       %% Key Connections
       MANU -.-> INS
       LOSSG -.-> INS
       INS -.-> SIM
       SIM -.-> MONTE
       ERGODIC -.-> OPT
       OPT -.-> SENS

       %% Financial Core Connections
       MANU --> LEDGER
       MANU --> ACCRUAL
       MANU --> INSACCT
       TAXH --> ACCRUAL
       LEDGER --> DECUTIL
       ACCRUAL --> DECUTIL
       INSACCT --> DECUTIL

       classDef inputClass fill:#e3f2fd,stroke:#1565c0
       classDef coreClass fill:#fff3e0,stroke:#ef6c00
       classDef financialClass fill:#fff9c4,stroke:#f9a825
       classDef analysisClass fill:#f3e5f5,stroke:#7b1fa2
       classDef outputClass fill:#e8f5e9,stroke:#2e7d32

       class CONF,HIST,PARAMS inputClass
       class MANU,LOSSG,INS,SIM coreClass
       class LEDGER,ACCRUAL,INSACCT,TAXH,DECUTIL financialClass
       class MONTE,ERGODIC,OPT,SENS analysisClass
       class EXCEL,VIZ,METRICS,STRATEGY outputClass
    

Reference to System Architecture Diagram

For a visual representation, see: assets/system_architecture.png

The PNG diagram shows the simplified flow, while the detailed architecture above reflects the actual implementation with all major components.

Detailed System Architecture

This diagram shows the overall architecture of the Ergodic Insurance Limits framework, including the main components, external dependencies, and data flow between major modules.

        flowchart TB
       %% External Inputs and Configurations
       subgraph External["External Inputs"]
           CONFIG[("Configuration Files<br/>YAML/JSON")]
           MARKET[("Market Data<br/>Loss Distributions")]
           PARAMS[("Business Parameters<br/>Financial Metrics")]
       end

       %% Core System Components
       subgraph Core["Core Simulation Engine"]
           SIM["Simulation<br/>Engine"]
           MANU["Widget<br/>Manufacturer<br/>Model"]
           LOSSG["Manufacturing<br/>Loss Generator"]
           INS["Insurance<br/>Program"]
       end

       %% Financial Accounting Subsystem
       subgraph FinAcct["Financial Accounting Subsystem"]
           LEDGER["Ledger<br/>(Double-Entry)"]
           ACCRUAL["AccrualManager<br/>(GAAP Timing)"]
           INSACCT["InsuranceAccounting<br/>(Premium & Recovery)"]
           TAXH["TaxHandler<br/>(Tax Accruals)"]
           DECUTIL["decimal_utils<br/>(Precision)"]
       end

       %% Insurance Subsystem
       subgraph InsuranceSub["Insurance Subsystem"]
           INSPOL["InsurancePolicy<br/>(Basic Path)"]
           INSLAY["InsuranceLayer<br/>(Basic Layers)"]
           INSPROG["InsuranceProgram<br/>(Enhanced Path)"]
           ENHLAY["EnhancedInsuranceLayer<br/>(Enhanced Layers)"]
           PRICER["InsurancePricer<br/>(Market Cycles)"]
       end

       %% Exposure & Trend System
       subgraph ExposureSub["Exposure & Trend System"]
           EXPBASE["ExposureBase<br/>(Dynamic Frequency)"]
           FSPROV["FinancialStateProvider<br/>(Protocol)"]
           TRENDS["trends.py<br/>(Trend Analysis)"]
       end

       %% Analysis and Optimization
       subgraph Analysis["Analysis & Optimization"]
           ERGODIC["Ergodic<br/>Analyzer"]
           OPT["Business<br/>Optimizer"]
           MONTE["Monte Carlo<br/>Engine"]
           SENS["Sensitivity<br/>Analyzer"]
       end

       %% Validation and Testing
       subgraph Validation["Validation & Testing"]
           ACC["Accuracy<br/>Validator"]
           BACK["Strategy<br/>Backtester"]
           WALK["Walk-Forward<br/>Validator"]
           CONV["Convergence<br/>Monitor"]
       end

       %% Processing Infrastructure
       subgraph Infrastructure["Processing Infrastructure"]
           BATCH["Batch<br/>Processor"]
           PARALLEL["Parallel<br/>Executor"]
           CACHE["Smart<br/>Cache"]
           STORAGE["Trajectory<br/>Storage"]
       end

       %% Reporting and Visualization
       subgraph Output["Reporting & Visualization"]
           VIZ["Visualization<br/>Engine"]
           EXCEL["Excel<br/>Reporter"]
           STATS["Summary<br/>Statistics"]
           METRICS["Risk<br/>Metrics"]
       end

       %% Data Flow - Input to Core
       CONFIG --> SIM
       MARKET --> LOSSG
       PARAMS --> MANU

       %% Core orchestration
       SIM --> MANU
       SIM --> LOSSG
       SIM --> INS

       MANU <--> INS
       LOSSG --> INS

       %% Manufacturer to Financial Accounting
       MANU --> LEDGER
       MANU --> ACCRUAL
       MANU --> INSACCT
       TAXH --> ACCRUAL
       LEDGER --> DECUTIL
       ACCRUAL --> DECUTIL
       INSACCT --> DECUTIL

       %% Insurance subsystem relationships
       INSPOL --> INSLAY
       INSPROG --> ENHLAY
       PRICER --> INSPROG
       PRICER --> INSPOL
       INS -.-> INSPROG
       INS -.-> INSPOL

       %% Exposure system
       EXPBASE --> FSPROV
       MANU -.-> FSPROV
       TRENDS --> LOSSG

       %% Core to Analysis
       SIM --> MONTE
       MONTE --> ERGODIC
       MONTE --> OPT

       ERGODIC --> SENS
       OPT --> SENS

       %% Validation
       MONTE --> ACC
       MONTE --> BACK
       BACK --> WALK

       MONTE --> CONV
       CONV --> BATCH

       %% Infrastructure
       BATCH --> PARALLEL
       PARALLEL --> CACHE
       CACHE --> STORAGE

       %% Output
       ERGODIC --> VIZ
       OPT --> VIZ
       SENS --> VIZ

       STORAGE --> STATS
       STATS --> EXCEL
       STATS --> METRICS

       VIZ --> EXCEL

       %% Styling
       classDef external fill:#e1f5fe,stroke:#01579b,stroke-width:2px
       classDef core fill:#fff3e0,stroke:#e65100,stroke-width:2px
       classDef financial fill:#fff9c4,stroke:#f9a825,stroke-width:2px
       classDef insurance fill:#ffe0b2,stroke:#e65100,stroke-width:2px
       classDef exposure fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
       classDef analysis fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
       classDef validation fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
       classDef infra fill:#fce4ec,stroke:#880e4f,stroke-width:2px
       classDef output fill:#e0f2f1,stroke:#004d40,stroke-width:2px

       class CONFIG,MARKET,PARAMS external
       class SIM,MANU,LOSSG,INS core
       class LEDGER,ACCRUAL,INSACCT,TAXH,DECUTIL financial
       class INSPOL,INSLAY,INSPROG,ENHLAY,PRICER insurance
       class EXPBASE,FSPROV,TRENDS exposure
       class ERGODIC,OPT,MONTE,SENS analysis
       class ACC,BACK,WALK,CONV validation
       class BATCH,PARALLEL,CACHE,STORAGE infra
       class VIZ,EXCEL,STATS,METRICS output
    

System Overview

The Ergodic Insurance Limits framework is designed as a modular, high-performance system for analyzing insurance purchasing decisions through the lens of ergodic theory. The architecture follows these key principles:

1. Separation of Concerns

• Core Simulation: Handles the fundamental business and insurance mechanics

• Financial Accounting: Provides double-entry ledger, accrual accounting, insurance accounting, and tax handling – all using Python’s Decimal type for precision

• Insurance Subsystem: Offers both a basic path (InsurancePolicy with InsuranceLayer) and an enhanced path (InsuranceProgram with EnhancedInsuranceLayer), with market-cycle-aware pricing via InsurancePricer

• Exposure & Trends: Dynamically adjusts claim frequencies using actual financial state (via the FinancialStateProvider protocol) and applies trend multipliers over time

• Analysis Layer: Provides ergodic and optimization capabilities

• Infrastructure: Manages computational efficiency and data handling

• Validation: Ensures accuracy and robustness of results

• Output: Delivers insights through visualizations and reports

2. Data Flow Architecture

• Configuration and market data flow into the simulation engine

• The WidgetManufacturer internally uses Ledger, AccrualManager, InsuranceAccounting, and TaxHandler for precise financial tracking

• All financial amounts use Python’s Decimal type (via decimal_utils) to prevent floating-point drift across long simulations

• The Ledger maintains an O(1) current balance cache with pruning support for performance

• Simulations generate trajectories processed by analysis modules

• Infrastructure layers provide caching and parallelization

• Results flow to visualization and reporting components

3. Key Interactions

• The Simulation Engine orchestrates the time evolution of the business model

• The Manufacturer Model interacts with the Insurance Program for claim processing and uses the Ledger for all balance sheet operations

• AccrualManager tracks timing differences between cash movements and accounting recognition (wages, interest, taxes, insurance claims)

• InsuranceAccounting handles premium amortization as a prepaid asset and tracks insurance claim recoveries

• TaxHandler consolidates tax calculation, accrual, and payment logic, delegating accrual tracking to the AccrualManager

• InsurancePricer supports market cycles (Soft / Normal / Hard) to generate realistic premiums for both basic and enhanced insurance paths

• The Exposure System uses a FinancialStateProvider protocol so that ExposureBase subclasses query live financial state from the manufacturer for state-driven claim generation

• Trend classes (in trends.py) provide multiplicative adjustments to claim frequencies and severities over time, supporting linear, scenario-based, and stochastic trends

• Monte Carlo Engine generates multiple scenarios for statistical analysis

• Ergodic Analyzer compares time-average vs ensemble-average growth

• Batch Processor and Parallel Executor enable high-performance computing

4. Financial Accounting Subsystem

The financial accounting subsystem was introduced to provide GAAP-compliant financial tracking within the simulation. This subsystem is internal to the WidgetManufacturer and consists of four tightly integrated components:

        flowchart LR
       MANU["WidgetManufacturer"] --> LEDGER["Ledger"]
       MANU --> ACCRUAL["AccrualManager"]
       MANU --> INSACCT["InsuranceAccounting"]
       MANU --> TAXH["TaxHandler"]

       TAXH --> ACCRUAL
       LEDGER --> DECUTIL["decimal_utils"]
       ACCRUAL --> DECUTIL
       INSACCT --> DECUTIL

       classDef manuClass fill:#fff3e0,stroke:#e65100,stroke-width:2px
       classDef finClass fill:#fff9c4,stroke:#f9a825,stroke-width:2px
       classDef utilClass fill:#e0f2f1,stroke:#004d40,stroke-width:2px

       class MANU manuClass
       class LEDGER,ACCRUAL,INSACCT,TAXH finClass
       class DECUTIL utilClass
    

• Ledger: Event-sourcing double-entry ledger with a typed AccountName enum (preventing typo bugs), AccountType classification, O(1) balance lookups via an internal cache, and support for pruning old transactions

• AccrualManager: Tracks accrual items (wages, interest, taxes, insurance claims, revenue) with configurable payment schedules (immediate, quarterly, annual, custom)

• InsuranceAccounting: Manages premium payments as prepaid assets with straight-line monthly amortization, and tracks insurance claim recoveries separately from claim liabilities

• TaxHandler: Centralizes tax calculation and accrual management, explicitly designed to avoid circular dependencies in the tax flow; delegates accrual tracking to AccrualManager

• decimal_utils: Foundation module providing to_decimal(), quantize_currency(), and standard constants (ZERO, ONE, PENNY) used by all financial modules

5. Insurance Subsystem

The insurance subsystem provides two complementary paths for modeling coverage:

        flowchart TB
       subgraph Basic["Basic Path"]
           INSPOL["InsurancePolicy"]
           INSLAY["InsuranceLayer"]
           INSPOL --> INSLAY
       end

       subgraph Enhanced["Enhanced Path"]
           INSPROG["InsuranceProgram"]
           ENHLAY["EnhancedInsuranceLayer"]
           INSPROG --> ENHLAY
       end

       PRICER["InsurancePricer<br/>(Soft / Normal / Hard)"]
       PRICER --> INSPOL
       PRICER --> INSPROG

       classDef basicClass fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
       classDef enhancedClass fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
       classDef pricerClass fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

       class INSPOL,INSLAY basicClass
       class INSPROG,ENHLAY enhancedClass
       class PRICER pricerClass
    

• Basic Path: InsurancePolicy (in insurance.py) composes one or more InsuranceLayer objects for straightforward coverage modeling

• Enhanced Path: InsuranceProgram (in insurance_program.py) uses EnhancedInsuranceLayer objects for richer features including market-cycle-aware pricing

• InsurancePricer (in insurance_pricing.py) supports three MarketCycle states – HARD (60% loss ratio), NORMAL (70%), and SOFT (80%) – and can price both basic and enhanced insurance structures

6. Exposure & Trend System

The exposure and trend system models how insurance risks evolve dynamically during simulation:

        flowchart LR
       MANU["WidgetManufacturer<br/>(implements protocol)"] -.-> FSPROV["FinancialStateProvider<br/>(Protocol)"]
       FSPROV --> EXPBASE["ExposureBase<br/>(Dynamic Frequency)"]
       TRENDS["trends.py<br/>(Trend Multipliers)"] --> LOSSG["ManufacturingLossGenerator"]
       EXPBASE --> LOSSG

       classDef coreClass fill:#fff3e0,stroke:#e65100,stroke-width:2px
       classDef protoClass fill:#e1f5fe,stroke:#01579b,stroke-width:2px
       classDef trendClass fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px

       class MANU coreClass
       class FSPROV,EXPBASE protoClass
       class TRENDS,LOSSG trendClass
    

• FinancialStateProvider: A Protocol (in exposure_base.py) defining properties like current_revenue, current_assets, current_equity and their base counterparts. WidgetManufacturer implements this protocol.

• ExposureBase: Abstract base for exposure classes that query live financial state to compute frequency multipliers (e.g., RevenueExposure scales claim frequency based on actual revenue vs. base revenue)

• trends.py: Provides a hierarchy of trend classes (Trend ABC, LinearTrend, ScenarioTrend, and stochastic variants) that apply multiplicative adjustments to claim frequencies and severities over time, supporting both annual and sub-annual time steps with optional seeded reproducibility

7. External Dependencies

The system integrates with:

• NumPy/SciPy for numerical computations

• Pandas for data manipulation

• Matplotlib/Plotly for visualizations

• OpenPyXL for Excel reporting

• Multiprocessing for parallel execution

• Python’s decimal module for precise financial arithmetic