Inside the MyPayCheckCal calculator architecture

MyPayCheckCal began as a collection of spreadsheet experiments. Today it runs on a production-ready stack that balances static delivery with highly interactive calculators. This post breaks down the architecture behind the scenes so you can extend or audit the project with confidence.

Astro for the shell, React for the brains

Astro renders the marketing pages, guide content, and navigation as static HTML. This keeps first paint fast and SEO-friendly. When a calculator route loads, Astro hydrates a React island that manages state-heavy inputs, tax calculations, and chart rendering.

Each calculator island shares a consistent set of hooks for:

• Mapping pay frequency conversions (hourly to annual, annual to per-paycheck).
• Handling tax tables and deduction rules stored in JSON modules.
• Broadcasting calculation results to summary cards and charts.

Because the islands are isolated, we only ship the JavaScript required for the current calculator—no unused framework code.

Shared utilities and configuration

The mypaycheckcal:config virtual module centralizes metadata, i18n settings, and blog preferences. Pulling configuration from YAML keeps deployment environments consistent and makes it easy to adjust meta tags without touching component code.

Utility helpers in src/utils handle permalink generation, RSS feeds, and sitemap output. These functions respect the configuration layer so updating the site URL or blog settings automatically flows to every integration.

Data integrity and testing

Accurate numbers are non-negotiable. Each calculator imports tax tables, deduction limits, and validation rules from versioned data files. We maintain unit tests for conversion helpers and edge cases (like partial weeks or bonus payouts) to ensure results stay correct as regulations change.

Before every release we run:

1. Type checking and linting to catch regressions early.
2. Playwright smoke tests that load each calculator, submit sample inputs, and verify the resulting net pay.
3. Sitemap and RSS validation to confirm static assets reflect the current route map.

Extending the platform

New calculators follow a repeatable pattern:

1. Create a page in src/pages that imports the shared layout and calculator island.
2. Implement the React island using existing hooks for conversions and taxes.
3. Add navigation links in src/navigation.ts and update documentation in the docs/ folder.

This architecture keeps MyPayCheckCal flexible enough to support everything from basic paychecks to complex multi-state withholding scenarios.