Matching Engine — High-Level Design

Status: Draft for review · Part of: Astro Composer · Updated: 2026-10-24

The matching engine evaluates ashtakoota (eight-factor compatibility) for two charts: eight kootas, thirty-six points, the doshas (faults) they imply and the cancellation rules the rulebook chooses. It is pure table evaluation over two sets of Moon facts: no astronomy, no binder call, no interpretation.

1. Purpose

Ashtakoota looks like eight table lookups plus a total, but the total is the least trustworthy part. Three things complicate it:

• Several schools cancel Nadi and Bhakoot doshas under named conditions.
• Varna, Vashya and Tara are computed in a direction, so pair order changes the result.
• 18 of 36 is a traditional threshold, not a verdict on two people.

The matching engine exists so that:

1. the eight kootas run once, in fixed order, from one rulebook;
2. every koota returns points, basis and verdict, not just a total;
3. doshas and cancellations stay visible;
4. the pair direction is explicit, because order-sensitive kootas change the result;
5. two charts are matched only under the same conventions.

2. Where it sits

subject A · Moon sign/nakshatra/pada ──┐
subject B · Moon sign/nakshatra/pada ──┼──▶ matching engine ──▶ eight kootas + doshas + total
pair direction · profile · rulebook ───┘

• Upstream: the composition facade supplies two compact subject references, the pair direction, one profile and one rulebook handle. Each subject comes from a verified chart core chart or a stored composer snapshot; the engine reads neither birth data nor the binder.
• Downstream: the facade builds POST /v1/matching; the product renders points and doshas in its own words, and the chart/account domain may store the response as an immutable report snapshot.
• Never: it does not compute a natal chart, call the binder, recompute a nakshatra from a longitude, read a clock, or decide whether two people should marry.

Input contract

Output contract

3. Responsibilities

Each area owns one compatibility factor and one deterministic rule.

Koota ledger

4. Architecture

Diagram: reference design, not deployed behaviour.

The engine is a table evaluator with an admission gate. Once both subjects pass, every koota reads the same facts and rulebook, so the total can disagree with its parts only through an assembler defect.

5. Rules

1. Matching compares facts, not charts. The engine reads Moon sign, nakshatra and pada; never a longitude, house, aspect or dasha period.
2. Same conventions on both sides. Both subjects must share profile version, rulebook hash and binder engine version; a cross-convention pair gets REFERENCE_VERSION_MISMATCH.
3. The pair has a direction. Ordered kootas score A against B, and the response echoes that direction; a reverse request is a different evaluation.
4. Only Moon facts are required. Sign, nakshatra and pada cover all eight kootas; pada enters only where a cancellation rule needs it.
5. The binder owns nakshatra. The engine never recomputes a nakshatra or pada from a longitude; a fact disagreeing with its sign span fails admission.
6. Koota tables are rulebook data. Every matrix, class order and remainder band is a table row. Maxima must sum to 36 and each table must cover its domain at load.
7. Exact arithmetic. Points are exact decimals or scaled integers; a total is never a float sum of eight rounded parts.
8. Every koota is returned. All eight carry points, maximum, verdict and basis; collapsing to one score is a product choice.
9. Doshas are explicit. Nadi and Bhakoot carry present, cancelled and the deciding rule id; a cancelled dosha stays in the response.
10. Eighteen is a threshold, not a verdict. meetsTraditionalThreshold compares against the pinned threshold; the engine does not rank or recommend.
11. Graha Maitri is pinned. Natural friendship is the default; compound friendship needs temporal friendship and is a rulebook option.
12. Cancellations are named predicates. No exception is hardcoded; a rulebook without a cancellation table yields cancelled: false.
13. Mangal dosha is not in this slice. It needs Mars and a different fact set, so it belongs to a separate dosha pack.
14. Deterministic order and ids. Kootas run varna, vashya, tara, yoni, graha maitri, gana, bhakoot, nadi; identical requests give byte-identical output.
15. No clock, no binder, no storage. The engine is a pure function of two admitted subjects and one rulebook; caching and report storage belong elsewhere.
16. Privacy is part of the contract. The response carries Moon facts and scores, never birth dates or coordinates; cache keys are hashed and bodies are not logged.

6. Edge cases

Bad input fails loudly; nothing is silently corrected.

7. Out of scope

• Natal chart assembly, signs and nakshatras (chart core) and binder astronomy (Astro Binder).
• Mangal or Kuja dosha, Saptamamsha, Nadi astrology, western synastry, composite charts and dasha compatibility.
• Panchang, transits and muhurta windows (panchang engine, transit engine).
• Interpretation, recommendations, remedies, wedding advice and compatibility prose.
• Gender roles in the API. Subjects are ordered, not gendered; a rulebook may encode the traditional direction, and the response always states it.
• Storing match reports (chart/account domain).
• Binder access, caching, retries and provenance (facade and binder).
• Localisation and display formatting (client).

8. Planned code