Getting Started

Start the server

pnpm --filter @faraid/server dev
# → http://localhost:8787

A production instance is available at https://faraid-server.siddiqmutarjim.workers.dev/.

Flat inheritance

Submit a list of heirs with counts and receive each person’s share.

curl -X POST http://localhost:8787/solve \
  -H 'content-type: application/json' \
  -d '{
    "heirs": [
      { "type": "Husband",  "count": 1 },
      { "type": "Daughter", "count": 2 },
      { "type": "Mother",   "count": 1 }
    ]
  }'

Response:

{
  "base":  "12",
  "shares": [
    { "type": "Husband",  "sahm": "3",  "base": "12" },
    { "type": "Daughter", "sahm": "8",  "base": "12" },
    { "type": "Mother",   "sahm": "2",  "base": "12" }
  ],
  "excluded": [],
  "phenomena": []
}

Each sahm / base pair is an exact fraction. No rounding.

Chain of deaths (Munāsakhat)

When multiple people die in sequence, the engine re-expresses each heir’s relationship for each sub-death.

Flat chain — manually specify each death step:

curl -X POST http://localhost:8787/chain \
  -H 'content-type: application/json' \
  -d '{
    "primaryHeirs": [
      { "type": "Son",  "count": 2 },
      { "type": "Wife", "count": 1 }
    ],
    "deaths": [
      { "dying": "Son", "heirs": [
        { "type": "Son",  "count": 1 },
        { "type": "Wife", "count": 1 }
      ]}
    ]
  }'

DAG chain — define a family tree once, then specify a sequence of deceased:

curl -X POST http://localhost:8787/chain/dag \
  -H 'content-type: application/json' \
  -d '{
    "spec": {
      "dag": {
        "nodes": [
          { "id": "Ahmad", "gender": 1 },
          { "id": "Zayd",  "gender": 1 },
          { "id": "Hind",  "gender": 0 }
        ],
        "edges": [
          { "from": "Ahmad", "to": "Zayd" },
          { "from": "Ahmad", "to": "Hind" }
        ],
        "deceased": "Ahmad"
      },
      "spouses": [{ "id": "Maryam", "gender": 0 }]
    },
    "deceasedSequence": ["Ahmad", "Zayd"],
    "includeTable": true
  }'

Missing heir (Mafqūd)

Mark one or more heirs as possibly dead. The engine evaluates all combinations and assigns each known heir their guaranteed minimum. The remainder is held in suspension (mawqūf).

curl -X POST http://localhost:8787/mafqud \
  -H 'content-type: application/json' \
  -d '{
    "heirs":   [{ "type": "Mother", "count": 1 }, { "type": "Son", "count": 1 }],
    "missing": ["Son"]
  }'

Extended relatives (Dhawī al-Arḥām)

Relatives who inherit when no primary heir exists. Two methods: Tanzīl (projection) and Qarāba (priority cascade).

curl -X POST http://localhost:8787/dha \
  -H 'content-type: application/json' \
  -d '{
    "dhaHeirs": [{ "type": "Grandson", "count": 1 }],
    "spouse":   { "type": "Wife", "count": 1 },
    "config":   { "dharhamMethod": "tanzil" }
  }'

Questionnaire

An interactive yes/no flow that determines which heirs exist.

1. Start — POST /questionnaire with the deceased’s gender.
2. Answer — POST /questionnaire/advance for each yes/no.
3. Done — Use the returned finalHeirs with /solve.

# Start
curl -X POST http://localhost:8787/questionnaire \
  -H 'content-type: application/json' \
  -d '{"deceasedGender": 1}'

School presets

All four Sunni schools are supported. Pass a config object with the endpoint:

curl -X POST http://localhost:8787/solve \
  -H 'content-type: application/json' \
  -d '{
    "heirs": [{ "type": "Husband", "count": 1 }],
    "config": { "useDelta": true }
  }'

See the HTTP API reference for all config fields and the full list of heir types.