Lantern

Appearance

Interactive Financial Calculators — Complete ​

Date: 2026-01-11
Status: ✅ Complete
Related Feature(s): Economics Documentation, VitePress Documentation System

Problem Statement / Goal ​

The economics documentation contained static tables and Python scripts for financial modeling. Users needed to:

  1. Manually edit Python files and re-run scripts to see different scenarios
  2. Copy/paste values into spreadsheets for what-if analysis
  3. Couldn't easily explore fund allocation across different revenue scales

Goal: Create interactive, real-time financial calculators embedded directly in the documentation for immediate scenario modeling.

Solution Overview ​

Built two Vue 3 components integrated with VitePress that provide interactive financial modeling:

1. Fund Allocation Calculator (FundAllocationCalculator.vue) ​

Purpose: Model how revenue is allocated across Four Pillars, safe spaces, profit sharing, and operations at any scale.

Features:

  • Preset scenarios: Pilot (7.5K/mo), Growth (75K/mo), Enterprise (8.3M/mo), Sustainable Growth
  • Adjustable inputs:
    • Monthly revenue (5K - 10M range)
    • Number of employees (1-200)
    • Average salary multiplier (1.0× - 3.0×)
    • Profit sharing percentage (10%-100%)
  • Real-time calculations:
    • Per-category budget allocation with percentages
    • Per-employee annual compensation breakdown
    • Total monthly expenses and profit before sharing
    • Distributed vs. retained profit
  • Contextual insights:
    • Warnings for operating losses
    • Success indicators for healthy margins and compensation
    • Safe space funding scale analysis
    • Sustainable growth mode detection

2. Pilot Calculator (PilotCalculator.vue) ​

Purpose: Project 12-month revenue, costs, and profitability based on merchant acquisition assumptions.

Features:

  • Preset scenarios: Conservative, Baseline, Optimistic, Aggressive
  • Adjustable inputs:
    • ARPU (average revenue per merchant)
    • Monthly infrastructure and contractor costs
    • Merchant churn rate
    • New merchants acquired each month (per-month granular control)
  • Real-time 12-month projections:
    • Month-by-month active merchants, revenue, costs, profit
    • Cumulative profitability tracking
    • Break-even month detection
  • Year 1 summary cards:
    • Total revenue, costs, net profit
    • Profit margin, average merchants
    • Break-even timing
  • Contextual insights:
    • Profitability warnings and success indicators
    • Margin health analysis
    • Churn rate feedback (strong/moderate/high risk)
    • Break-even timing validation

Files Changed/Created ​

Created ​

Modified ​

Technical Implementation ​

VitePress Component Integration ​

VitePress automatically discovers Vue components in docs/.vitepress/components/ and makes them globally available in markdown files. No registration needed.

Usage in markdown:

markdown
<FundAllocationCalculator />
<PilotCalculator />

Component Architecture ​

Both components use Vue 3 Composition API with:

  • Reactive state: ref() for input values
  • Computed properties: Real-time derived calculations
  • Preset scenarios: One-click load of common configurations
  • Responsive design: Mobile-friendly with grid layouts and overflow handling

Styling Strategy ​

Uses VitePress CSS custom properties for theme integration:

  • --vp-c-brand / --vp-c-brand-dark — Primary colors
  • --vp-c-bg / --vp-c-bg-soft — Background layers
  • --vp-c-divider — Border colors
  • --vp-c-text-1 / --vp-c-text-2 — Text hierarchy

Ensures calculators adapt to light/dark theme automatically.

Calculation Logic ​

Fund Allocation:

javascript
// Example: Safe space percentage scales with revenue
const safeSpacePercent = computed(() => {
  if (monthlyRevenue.value < 50000) return 0.02
  if (monthlyRevenue.value < 200000) return 0.03
  if (monthlyRevenue.value < 500000) return 0.04
  return 0.05
})

Pilot Projections:

javascript
// Example: Month-over-month merchant churn and revenue
for (let month = 0; month <= 12; month++) {
  const churnedMerchants = Math.floor(activeMerchants * (merchantChurn.value / 100))
  activeMerchants = activeMerchants - churnedMerchants + newMerchants
  const revenue = activeMerchants * arpu.value
  // ...accumulate cumulative metrics
}

Testing Results ​

Manual Testing ​

✅ Verified scenarios:

  • Pilot (7.5K/mo) — Properly shows early-stage compensation and tight margins
  • Growth (75K/mo) — Demonstrates improving employee compensation as scale increases
  • Enterprise (8.3M/mo) — Confirms exceptional profit margins (68%) and high total comp (935K/employee)
  • Sustainable Growth — Shows balanced approach with 78% profit sharing, 22% retained for expansion

✅ Input validation:

  • Slider ranges prevent invalid values
  • Real-time recalculation on any input change
  • No UI lag or calculation errors observed

✅ Responsive design:

  • Mobile layout tested (tables horizontal scroll, cards stack vertically)
  • All insights readable on small screens
  • Preset buttons adapt to narrow viewports

✅ Theme compatibility:

  • Light mode: Proper contrast and readability
  • Dark mode: Colors integrate with VitePress dark theme

Cross-Browser Testing ​

  • ✅ Chrome/Chromium (primary development)
  • 🔄 Firefox (not yet tested — recommend manual check)
  • 🔄 Safari (not yet tested — recommend manual check)

Accessibility ​

  • ⚠️ Range sliders: Native HTML5 input type="range" (keyboard accessible)
  • ⚠️ Color contrast: Visual-only insights (success/warning/info) — Consider adding ARIA labels
  • ⚠️ Screen readers: Tables use proper semantic HTML, but insights list may need aria-live regions for dynamic updates

Recommendation: Add ARIA labels and test with screen readers in future iteration.

User Impact ​

For Strategic Planning ​

  • Founders/Leadership: Instantly model fund allocation at any revenue scale
  • Investor Conversations: Real-time scenario planning during pitch meetings
  • Budget Committees: Transparent what-if analysis for quarterly planning

For Financial Literacy ​

  • New Employees: Understand how cooperative economics work at different scales
  • Potential Hires: See total compensation modeling based on company growth
  • Community Members: Explore how safe space funding scales with revenue

Vs. Python Scripts ​

Before:

  1. Find Python script in repo
  2. Edit variables in code
  3. Run script in terminal
  4. Copy output to spreadsheet for comparison
  5. Repeat for each scenario

Now:

  1. Open docs in browser
  2. Click preset or drag sliders
  3. See results instantly
  4. Compare scenarios side-by-side by adjusting values

Time savings: ~5 minutes per scenario → ~5 seconds

Deployment ​

The calculators are live once VitePress docs are built and deployed:

bash
npm run docs:build   # Build static site
npm run docs:preview # Preview locally

Deployed docs available at:

Note: Ensure VitePress deployment (Cloudflare Pages, etc.) includes Vue runtime — VitePress bundles this automatically.

Future Enhancements ​

Calculator Features ​

  • [ ] Export to CSV: Download projections for offline analysis
  • [ ] Scenario comparison: Side-by-side comparison of 2-3 scenarios
  • [ ] Chart visualizations: Line/bar charts showing revenue/profit over time
  • [ ] Sensitivity analysis: Auto-generate best/worst case scenarios
  • [ ] URL state sharing: Share scenarios via query parameters

Additional Calculators ​

  • [ ] User Growth Calculator: Project DAU/MAU based on merchant acquisition
  • [ ] Safe Space Impact Calculator: Model community funding distribution by tier
  • [ ] Salary Calculator: Interactive salary scale explorer with role comparisons
  • [ ] Break-Even Calculator: Determine minimum merchants/ARPU to reach profitability

UX Improvements ​

  • [ ] Add tooltips explaining each input/metric
  • [ ] Keyboard shortcuts (arrow keys to adjust sliders)
  • [ ] Mobile-optimized touch interactions
  • [ ] ARIA live regions for screen reader updates
  • [ ] Dark mode toggle persistence

Financial Planning ​

Engineering ​

Next Steps ​

  1. ✅ Deploy to production — Merge to dev, then deploy docs site
  2. 🔄 User feedback — Share with finance committee and gather usability feedback
  3. 🔄 Accessibility audit — Test with screen readers and add ARIA improvements
  4. 🔄 Additional calculators — Prioritize User Growth and Salary calculators based on demand
  5. 🔄 Chart visualizations — Add Chart.js or similar for visual projections

Last Updated: 2026-01-11
Maintained By: Engineering + Finance Teams
Questions? File an issue or ask in #engineering Slack channel

Built with VitePress

Copyright © 2026 Lantern