Building Matrix Destiny Calculator with React, Vite, and SVG

A calculator can fit its arithmetic into a few dozen lines and still need serious engineering around it.

Matrix Destiny Calculator turns a birth date into a numbered, interactive chart. Its domain is a symbolic numerology convention, but the engineering problems are familiar: preserve business rules, validate dates, explain results, support keyboard users, and avoid shipping unnecessary JavaScript.

This is a technical walkthrough of those decisions. The readings are reflection prompts; numerology is not scientifically validated. Testing the arithmetic establishes conformance to a documented convention, not predictive accuracy.

1. Put the calculation contract before the components

The stack is React 19 and Vite 7, with plain JavaScript modules for the calculation engine. The engine does not import React, access the DOM, or make network requests.

The core rule sounds simple:

• Preserve positive integers from 1 through 22.
• When a completed value exceeds 22, repeatedly add its digits until it fits.
• Reject inputs outside the positive safe-integer domain.

Here is the implementation:

export function digitSum(value) {
  return [...String(value)].reduce(
    (sum, digit) => sum + Number(digit),
    0
  );
}

export function reduce22(value) {
  if (!Number.isSafeInteger(value) || value < 1) {
    throw new RangeError(
      'Arcana input must be a positive safe integer.'
    );
  }

  while (value > 22) value = digitSum(value);
  return value;
}

This is neither a modulo operation nor repeated subtraction of 22. For example, 28 becomes 10, while 22 stays 22.

Five anchors establish the personal chart:

A = reduce(day)
B = month
C = reduce(sum of year digits)
D = reduce(A + B + C)
E = reduce(A + B + C + D)

For 15 May 1990, those anchors are 15, 5, 19, 12, 6. The other positions are derived from completed nodes. The public methodology documents the convention and worked examples.

The useful pattern is the separation: a calculation module returns structured data; presentation components decide how to display it.

2. Reduction timing is part of the algorithm

The easiest mistake is to assume that moving a reduction cannot change the answer.

It can:

reduce22(reduce22(15 + 10) + 5); // 12
reduce22(15 + reduce22(10 + 5)); // 3

Preserving values through 22 makes the grouping meaningful. A refactor that looks algebraically harmless can change the chart.

Compatibility mode makes this especially important. It completes both personal charts first, then combines corresponding completed positions:

const pairedNodes = Object.fromEntries(
  Object.keys(first.nodes).map(key => [
    key,
    reduce22(first.nodes[key] + second.nodes[key])
  ])
);

Rebuilding every inner position from the combined outer anchors produces a different algorithm. Purpose totals also have their own documented recomputation order.

This generalizes to pricing, tax, and scoring systems: rounding, clamping, and reduction boundaries belong in the specification. They are observable behavior.

3. Validate calendar dates, not just numeric ranges

Checking that a day is between 1 and 31 does not establish that a date exists. JavaScript also normalizes overflowing date parts, so constructing a Date without checking the result can accept invalid input.

The validator accepts a strict YYYY-MM-DD string, checks the supported year range, constructs a UTC date, and compares its components with the input:

const date = new Date(Date.UTC(year, month - 1, day));

if (
  date.getUTCFullYear() !== year ||
  date.getUTCMonth() !== month - 1 ||
  date.getUTCDate() !== day
) {
  throw new Error(
    'That date does not exist. Check day, month, and leap year.'
  );
}

Future dates are rejected separately. Calendar validity uses UTC; the future-date boundary is built from the current local calendar day.

The validator also accepts an injected today argument. Tests can freeze the clock instead of depending on the day they run. That matters around birthdays, year boundaries, and future-date checks.

4. Treat an SVG chart as an interface

SVG suits this chart because positions have explicit coordinates, labels remain text, and the same geometry can be exported.

But drawing clickable circles is only part of the work. Interactive nodes need names, focus, keyboard activation, and selection state. A simplified node looks like this:

<g
  role="button"
  tabIndex={0}
  aria-label={`${label}: ${value}`}
  aria-pressed={selected}
  onClick={onSelect}
  onKeyDown={event => {
    if (event.key === 'Enter' || event.key === ' ') {
      event.preventDefault();
      onSelect();
    }
  }}
>
  <circle cx={x} cy={y} r={radius} />
  <text x={x} y={y}>{value}</text>
</g>

The reading panel exposes the selected position's formula alongside its explanation. An ordinary HTML position selector offers another way to navigate, and a polite live region announces reading updates.

The broader lesson: a visualization needs a usable interaction model as well as a visual design. Keyboard support and alternative controls should influence the component API from the beginning.

5. Keep the input local by removing the API call

The calculation is deterministic and inexpensive. It does not need a server round trip.

Birth-date fields and chart results stay in React state. They are not placed in query strings or persisted in browser storage. Readings come from editorial content keyed to calculated values; generating a chart does not call an AI service.

Downloads follow the same boundary. Text reports and SVG charts are built with Blob and URL.createObjectURL(), downloaded in the browser, and followed by object-URL cleanup.

This does not mean the whole website makes no external requests. The site uses Google Analytics for traffic measurement; birth dates and chart values are not supplied as Analytics fields. Theme preference is stored locally. The privacy policy describes those distinctions.

A useful review question for any calculator is: which feature actually requires this input to leave the browser? If none does, a backend may add complexity without improving the result.

6. Render content once; hydrate the interactive sections

The site contains calculators and educational articles. Their JavaScript needs differ.

Production builds use React's server renderer to generate HTML ahead of time. Vite produces the client and server bundles; a build script renders each route. This is build-time prerendering, rather than rendering the full React page on every request.

Interactive sections are marked with data-island. A small entry script discovers those sections, imports their components, and calls hydrateRoot() on their existing HTML.

React templates + route data
          ↓ build
Prerendered HTML
          ↓ browser
Small theme/menu script
          ↓ where required
Hydrated calculator or other interactive section

Static articles remain readable without JavaScript. Calculator interactions require it. The results component and its stylesheet are split out with React.lazy() and loaded on demand; focusing the calculator form starts preloading that component.

The build also generates responsive WebP images, includes page-specific CSS, and prepares Brotli/gzip responses. Performance checks enforce byte budgets and verify that result chunks stay out of the initial preload set.

Those are implementation checks, not a claim about a live Lighthouse score. A real deployment still needs measurement on representative devices and networks.

React's hydration documentation and Vite's SSR guide explain the underlying primitives. One constraint deserves attention: hydrated markup must match the HTML generated at build time.

7. Test examples, boundaries, and the entire supported date range

The engine uses Node's built-in test runner and strict assertions. Its tests cover:

• Worked personal-chart and compatibility fixtures.
• Preservation of 22 and reduction of larger values.
• Invalid dates, leap-century rules, future dates, and birthdays.
• Deterministic output and valid node ranges across every date in a fixed interval.

That last test visits all 46,304 valid dates from 1 January 1900 through 10 October 2026. Each date is calculated twice, and every node must be an integer from 1 through 22.

The endpoint is deliberately frozen for reproducibility. This sweep tests invariants, while the worked fixtures test specific expected answers. Neither replaces the other: an engine that always returned 1 would satisfy a range check.

During preparation of this post, the current local suite passed all 15 tests, including calculation, localization, and HTTP transport checks. That result describes the checked source, not a production load test.

What this project taught about small tools

The arithmetic is small. The contract around it is the product.

An explicit convention prevents accidental algorithm changes. Pure functions make exhaustive checks affordable. Browser-local state limits data movement. Accessible SVG makes the chart usable in more ways. Prerendered content keeps the delivery model proportional to what each page needs.

You can explore the result at matrixdestinycalculator.org, then inspect a chart position to see how its value was calculated.

If you have built a calculator or scoring tool, where did your hardest bug live: the formula, the input boundary, or the UI?