Skip to main content

​
System Philosophy

At Village Labs, we designed the Repurchase Engine for transparency, fidelity, and scalability. Our architecture separates the core simulation logic from data intake and reporting, allowing for maximum flexibility. This modular design is a key principle of our Village Operating System, ensuring that each component is specialized and highly effective.
The architecture is grounded in the legal and financial first principles of ESOPs. This ensures that the outputs from our engine are not only predictive but also robust, auditable, and defensible.

​
Core Capability

The engine’s core capability is to process a company’s census data and financial state through a discrete, step-by-step annual simulation cycle, producing a detailed year-over-year forecast of all ESOP activities.

​
System Architecture

Simulation Core

Discrete annual processing pipeline

Data Layer

Immutable, versioned system of record

Design Principles

Foundational architectural concepts

Input Framework

PlanRules, OperatingAssumptions, and more

​
High-Level Flow

1

Input Configuration

Provide four structured inputs:
  • PlanRules: Legal framework
  • OperatingAssumptions: Annual strategy
  • InitialState: Current ESOP state
  • SystemConfiguration: Simulation settings
2

Annual Processing Cycle

For each projection year, execute ordered processing steps:
  • Turnover projection
  • Share pool calculation
  • Contribution determination
  • Diversification processing
  • Repurchase events
3

State Capture

Record complete snapshots:
  • Company financial state
  • Trust cash and shares
  • Individual participant accounts
  • All transactions and events
4

Output Generation

Generate comprehensive results:
  • Annual projections
  • Repurchase obligations
  • Cash flow analysis
  • Participant snapshots

​
Key Components

​
1. Simulation Core

The heart of the system is a discrete, step-by-step annual processing pipeline. For each year of a projection, the engine executes a sequence of modules, each responsible for a specific aspect of ESOP administration. 
# Conceptual annual processing flow
for year in range(start_year, end_year):
    # Step 0: Project employee turnover (optional)
    turnover_events = project_turnover(participants, year)
    
    # Step 1: Initialize year - calculate share price
    share_price = calculate_share_price(company_equity, outstanding_shares)
    
    # Step 2: Determine share pool for allocation
    share_pool = calculate_share_pool(esop_loans, contributions)
    
    # Step 3: Allocate shares to participants
    allocations = allocate_shares(share_pool, eligible_participants)
    
    # Step 4: Calculate company contribution
    contribution = determine_contribution(policy, financial_state)
    
    # Step 5: Update vesting status
    vesting_updates = update_vesting(participants, vesting_schedule)
    
    # Step 6: Process diversification elections
    diversifications = process_diversifications(eligible_participants)
    
    # Step 7: Process repurchase events
    repurchases = process_repurchases(terminated_participants, funding_waterfall)
    
    # Step 8: Year-end closing - roll forward and evolve
    year_end_closing(participants, company_state, trust_state)
    
    # Capture year-end state
    save_annual_snapshot(year, company_state, trust_state, participants)
Critical Design Choice: This strict order of operations ensures that legal obligations are met before discretionary actions are taken.

​
2. Data Layer

All inputs and outputs are managed in a versioned, relational database that serves as the immutable system of record for all modeling activities.
  • Scenarios: Versioned scenario configurations
  • Censuses: Versioned participant data
  • PlanRules: Legal framework definitions
  • OperatingAssumptions: Annual strategy settings

​
3. Input Framework

The engine requires structured input organized into four distinct categories:

PlanRules

The “Constitution”Stable legal framework:
  • Vesting schedule
  • Distribution policy
  • Cash usage policy
  • Diversification rules

OperatingAssumptions

The “Annual Strategy”Variable financial decisions:
  • Contribution amounts
  • Repurchase strategy
  • Share valuations
  • Growth projections

InitialState

Starting PointCurrent ESOP status:
  • Participant census
  • Trust cash balances
  • ESOP loan details
  • Share allocations

SystemConfiguration

Simulation SettingsRuntime parameters:
  • Projection years
  • Turnover models
  • Sensitivity analysis
  • Output preferences

​
Processing Pipeline

The annual simulation cycle executes a precise sequence of operations:
The order of operations is legally significant. For example, vesting must be updated before repurchases are processed to determine what employees are entitled to receive.

​
Data Flow Architecture

┌─────────────────────────────────────────────────────────┐
│ Input Layer                                             │
│ ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│ │  PlanRules   │  │ Operating    │  │ InitialState │  │
│ │              │  │ Assumptions  │  │              │  │
│ └──────────────┘  └──────────────┘  └──────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────┐
│ Simulation Engine                                       │
│ ┌──────────────────────────────────────────────────┐   │
│ │  Annual Processing Pipeline                      │   │
│ │  → Turnover → Share Pool → Contributions →       │   │
│ │  → Diversification → Repurchases                 │   │
│ └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────┐
│ Data Layer (Immutable Database)                         │
│ ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│ │ Company      │  │ Trust        │  │ Participant  │  │
│ │ Snapshots    │  │ Snapshots    │  │ Snapshots    │  │
│ └──────────────┘  └──────────────┘  └──────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────┐
│ Output Layer                                            │
│ ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│ │ Forecast     │  │ Analytics    │  │ Exports      │  │
│ │ Results      │  │ & Insights   │  │ & Reports    │  │
│ └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘

​
Key Architectural Features

Leveraged ESOPs with multiple debt tranches are modeled with precision. Each ESOPLoan object owns its specific suspense shares, and the engine iterates through each loan independently to calculate share releases.Why It Matters: Prevents cross-contamination of suspense accounts and ensures accurate modeling of complex debt structures.
The repurchase processing module implements a strict, rules-based sequence for drawing funds from the trust’s cash accounts, following the PlanRules.cash_usage_policy.Why It Matters: Ensures legal compliance and prevents improper use of restricted cash sources (e.g., forfeitures).
Every simulation run creates a complete, timestamped snapshot of all system state. Nothing is ever overwritten.Why It Matters: Perfect reproducibility and the ability to perform temporal analysis (e.g., “How did our June forecast compare to September?”).
The engine exposes high-level user intent functions designed for AI agent integration.Why It Matters: Stable API for conversational interfaces, allowing internal refactoring without breaking agent capabilities.

​
Performance Characteristics

Speed

20-year projection: < 2 seconds100-participant census

Scale

Tested up to 10,000 participants50-year projections

Accuracy

Deterministic resultsBit-for-bit reproducible

​
Next Steps

Design Principles

Understand the foundational concepts

Simulation Core

Dive into the processing pipeline

Data Layer

Explore the database structure

Data Models

Learn the core data structures