# TrahKeluarga.com — Blueprint v1.0 (PRD)

> Status: DRAFT — awaiting user approval (Gate 1)
> Scope: this document defines WHAT the product must do and WHY. It intentionally
> avoids naming any technology, framework, or storage engine — those decisions belong
> to the Tier B technical spec, written only after this blueprint is approved.

## 1. Problem & Purpose

Large extended families (Indonesian families in particular, often spanning many cities
and countries) have no shared, trustworthy place to record who is related to whom, how
to reach each other, and the history/evidence behind family facts. Existing tools are
either static family-tree images (no collaboration, no privacy control) or generic
genealogy software (not built for living contact directories or evidence-based disputed
data).

TrahKeluarga.com exists to let a family (a "Trah") collaboratively build and maintain:
1. An accurate, evidence-based genealogical record (who is related to whom).
2. A private, consent-based family contact directory.
3. A long-term archive of family memory (deferred to a later phase — see §8).

## 2. Product shape decided for V1

- **Multi-tenant from day one.** Any family can register and create their own isolated
  Trah; the product is not scoped to a single family's private deployment.
- **MVP scope = 20 features** (identity, relationship engine, tree, search, permissions,
  invitations, audit — see §5). Archive (photos/stories/documents), Family Map/Calendar,
  Discovery Engine across Trah, and AI features are explicitly deferred (§8).
- **Validation dataset = dummy data, not a real family**, modeled on the documented
  lineage (nasab) of Prophet Muhammad ﷺ (see §6). Real family data comes after MVP is
  functionally stable.

## 3. Core objects (conceptual, not a schema)

- **USER** — a login account. A User is not automatically a Person.
- **PERSON** — a human recorded in a Trah's genealogy. May or may not have a linked User.
- **TRAH (FAMILY)** — an isolated space owning its own Persons, Relationships, and
  membership. One User can belong to multiple Trah.
- **RELATIONSHIP** — a first-class record connecting two Persons (not a foreign key on
  Person). This is what makes divorce, polygamy, step/adoptive relationships, and
  multiple marriages representable without special-casing.
- **MEMBERSHIP** — links a User to a Trah with a role and, optionally, a claimed Person.

## 4. Requirements

Each requirement has a stable ID. "Acceptance" states how it is verified — every
requirement here must be testable.

### 4.1 Account & Access (ACC)

- **REQ-ACC-001**: A visitor can register a new User account with email or phone, and
  password. Acceptance: a new User row exists after registration; duplicate
  email/phone is rejected with a clear error.
- **REQ-ACC-002**: A User can log in and log out. Acceptance: valid credentials start a
  session; invalid credentials are rejected; logout ends the session.
- **REQ-ACC-003**: A User account is distinct from a Person record — creating a User
  never implicitly creates or links a Person. Acceptance: registering a User with no
  Trah membership results in zero Person records.
- **REQ-ACC-004**: A User who forgets their password can regain access via a
  one-time reset code sent to their registered email or phone, without contacting an
  admin. Acceptance: requesting a reset for a known email/phone issues a single-use,
  time-limited code; submitting a valid code lets the User set a new password and
  invalidates the code; an invalid or expired code is rejected. Added post-Gate-2 as a
  necessary correction — REQ-ACC-001/002 are not usable in practice without it.

### 4.2 Trah (Family) Management (FAM)

- **REQ-FAM-001**: A logged-in User can create a new Trah, becoming its OWNER.
  Acceptance: the creating User gets an OWNER membership on the new Trah.
- **REQ-FAM-002**: A Trah member with sufficient role can invite someone to join, via
  a shareable invitation (email, phone, or link). Acceptance: an invitation record is
  created; the invited person can join the Trah by accepting it.
- **REQ-FAM-003**: An invited/joining User can "claim" an existing Person record in the
  Trah (e.g., "Are you Eko Prasetyo?") instead of creating a duplicate Person.
  Acceptance: after claim + confirmation, the User's Membership links to the existing
  Person; no duplicate Person is created.
- **REQ-FAM-004**: A User can be a member of more than one Trah simultaneously.
  Acceptance: a User can hold two or more active Memberships in different Trah at once.
- **REQ-FAM-005**: Each Trah's data (Persons, Relationships, Memberships) is isolated
  from every other Trah by default. Acceptance: a member of Trah A cannot list, search,
  or view Persons belonging to Trah B without an explicit, separate mechanism (out of
  scope for V1 — see §8, Discovery Engine).

### 4.3 Permissions (PERM)

- **REQ-PERM-001**: Every Membership has exactly one role: OWNER, ADMIN, EDITOR,
  CONTRIBUTOR, MEMBER, or VIEWER. Acceptance: role is set on join/invite and is always
  one of these six values.
- **REQ-PERM-002**: Only OWNER/ADMIN/EDITOR roles can create or modify Person and
  Relationship records; VIEWER can only read. Acceptance: an attempted write by a
  VIEWER-role Membership is rejected.
- **REQ-PERM-003**: Only OWNER can change another member's role or remove a member.
  Acceptance: a non-OWNER attempting a role change or removal is rejected.

### 4.4 Person / Identity (ID)

- **REQ-ID-001**: A Person record captures: full name, nickname (optional), gender
  (MALE/FEMALE/UNKNOWN), birth date, birth place, death date (optional), death place
  (optional), life status (ALIVE/DECEASED/UNKNOWN). Acceptance: all fields are
  independently settable and readable; omitted optional fields do not block saving.
- **REQ-ID-002**: A birth or death date can be stored with a precision qualifier —
  exact, year-only, month-year, approximate ("circa"), before, or after a given date —
  rather than forcing a single exact date. Acceptance: a Person can be saved with
  birth date recorded as e.g. "circa 570" and this is retrievable and displayed
  distinctly from an exact date.
- **REQ-ID-003**: A Person can have zero or more Residence entries, each with a place,
  a start date, an optional end date, and an is-current flag. Acceptance: a Person with
  three sequential residences shows the correct one as current.
- **REQ-ID-004**: A Person can have zero or more Contact entries (WhatsApp, phone,
  email, other), each independently markable as visible to: only me, family members,
  or public. Acceptance: a Contact set to "family members" is visible to a logged-in
  Trah member but not to an unauthenticated visitor.
- **REQ-ID-005**: Every field on a Person can carry a verification status: VERIFIED,
  PROBABLE, UNCERTAIN, or DISPUTED. Acceptance: two conflicting values for the same
  fact (e.g., two different birth years) can both be stored and shown side by side,
  each with its own status, rather than one overwriting the other.

### 4.5 Relationship Engine (REL)

- **REQ-REL-001**: A Relationship record connects exactly two Persons and has a type.
  Minimum supported types: BIOLOGICAL_PARENT/CHILD, ADOPTIVE_PARENT/CHILD,
  STEP_PARENT/CHILD, PARTNER/SPOUSE, SIBLING. Acceptance: each type can be created
  between two existing Persons and retrieved.
- **REQ-REL-002**: A Person can have more than one PARTNER/SPOUSE relationship over
  time, including concurrent ones (polygamy) and sequential ones (remarriage after
  widowhood or divorce). Acceptance: a Person can have two simultaneously-active
  PARTNER relationships, and separately, two PARTNER relationships where the first
  has an end date before the second's start date.
- **REQ-REL-003**: A PARTNER/SPOUSE relationship carries a start date, an optional end
  date, and a status (MARRIED, DIVORCED, WIDOWED, ENDED). Acceptance: ending a
  relationship (divorce or death) does not delete or alter the PARENT_CHILD
  relationships of either partner with their shared children.
- **REQ-REL-004**: A Person can be linked as ADOPTED_CHILD to one set of parents while
  retaining a separate BIOLOGICAL_PARENT relationship to their birth parent(s), both
  visible at once. Acceptance: a Person can show both an adoptive parent and a
  biological parent simultaneously, distinguishable by relationship type.
- **REQ-REL-005**: The system computes indirect kinship labels (grandparent, sibling,
  aunt/uncle, cousin, etc.) from the stored PARENT_CHILD and PARTNER relationships; it
  does not require these to be stored directly. Acceptance: given a stored
  grandparent → parent → child chain, the system can answer "what is the relationship
  between grandparent and child?" as "grandparent" without a directly-stored record of
  that fact.

### 4.6 Tree Visualization (TREE)

- **REQ-TREE-001**: A member can view an interactive family tree centered on any
  Person in the Trah, showing ancestors, descendants, and partners. Acceptance: from
  a selected Person, ancestors and descendants are reachable through the interface.
- **REQ-TREE-002**: The tree view supports expand/collapse of branches and a
  generation-depth filter. Acceptance: limiting to "2 generations" shows fewer nodes
  than "all generations" for the same starting Person.
- **REQ-TREE-003**: A Person with multiple partners and children by different
  partners renders each partner's children as distinguishable branches. Acceptance: a
  Person with two spouses and children by each shows children grouped correctly under
  the correct parent pairing.

### 4.7 Profile (PROF)

- **REQ-PROF-001**: Each Person has a profile page showing their identity summary,
  parents, partners, children, siblings, and visible contact info, respecting each
  field's privacy setting for the viewing member. Acceptance: two members with
  different roles viewing the same profile see different contact fields if privacy
  settings differ.
- **REQ-PROF-002**: A profile displays a verification badge when the underlying Person
  has been claimed and confirmed by a matching User (REQ-FAM-003). Acceptance: an
  unclaimed Person shows no verification badge; after a successful claim, it does.

### 4.8 Search & Relationship Finder (SRCH)

- **REQ-SRCH-001**: A member can search for a Person within their Trah by name.
  Acceptance: a search for a partial name returns matching Persons in that Trah only.
- **REQ-SRCH-002**: A member can ask "what is my relationship to [Person]?" and receive
  a computed kinship label with the connecting path. Acceptance: given two Persons
  connected through a known chain, the finder returns a correct label (e.g., "cousin")
  and a path of intermediate Persons.

### 4.9 Audit (AUD)

- **REQ-AUD-001**: Every create/update to a Person or Relationship record is logged
  with who made the change, what changed (old value → new value), and when.
  Acceptance: editing a Person's birth place produces a retrievable audit entry
  showing the previous and new value, the editor, and the timestamp.
- **REQ-AUD-002**: A member with sufficient role can view the audit history of a given
  Person or Relationship. Acceptance: the audit trail for a Person lists all prior
  changes in chronological order.

## 5. MVP feature list (confirmed scope)

1. Register / Login, incl. password reset (REQ-ACC-001, 002, 004)
2. Create Trah (REQ-FAM-001)
3. Invite members (REQ-FAM-002)
4. Person record (REQ-ID-001)
5. Gender (REQ-ID-001)
6. Birth/death date & place, with precision (REQ-ID-001, 002)
7. Residence history (REQ-ID-003)
8. Contact with privacy (REQ-ID-004)
9. Parent relationship (REQ-REL-001)
10. Partner relationship (REQ-REL-001, 003)
11. Child relationship (REQ-REL-001)
12. Divorce (REQ-REL-003)
13. Multiple spouses / polygamy (REQ-REL-002)
14. Interactive tree (REQ-TREE-001..003)
15. Person profile page (REQ-PROF-001, 002)
16. Search (REQ-SRCH-001)
17. Relationship Finder (REQ-SRCH-002)
18. Permissions/roles (REQ-PERM-001..003)
19. Claim Profile (REQ-FAM-003)
20. Audit history (REQ-AUD-001, 002)

## 6. Validation scenario (dummy dataset)

To prove the Relationship Engine handles real genealogical complexity — not just a
simple tree — V1 will be validated against a dummy dataset modeled on the well
documented lineage (nasab) of Prophet Muhammad ﷺ, per user's explicit choice. This
dataset is chosen for technical reasons: it is unusually well recorded in historical
scholarship (sirah literature) and naturally exercises every hard case in §4.5:

- **Early loss of parents**: father Abdullah bin Abdul Muttalib passed away before his
  son's birth; mother Aminah binti Wahb passed away in his early childhood — exercises
  DECEASED life status and death-before/after-birth date ordering.
- **Long monogamous marriage, then widowhood**: married to Khadijah binti Khuwailid for
  roughly 25 years as his only wife, until her death — exercises PARTNER with an
  end date caused by WIDOWED status, and single-partner-at-a-time over a long span.
- **Polygamy after widowhood**: multiple concurrent marriages following Khadijah's
  passing — exercises REQ-REL-002's concurrent-partner case.
- **Children across multiple relationships**: several children with Khadijah (including
  some who died in infancy) and a son with Maria al-Qibtiyyah — exercises multiple
  PARENT_CHILD records grouped under different partner pairings (REQ-TREE-003).
  Historical sources vary somewhat on the exact number and order of children who died
  young — this is intentionally used to exercise REQ-ID-005 (VERIFIED vs DISPUTED
  fields side by side), not to assert a single disputed claim as fact.
  All such entries must carry a Source citation per historical convention.
- **Adoption with a lineage nuance**: Zaid bin Haritsah was raised as an adopted son;
  a later well-known ruling clarified that an adopted child keeps their biological
  father's name/lineage rather than the adoptive parent's — exercises REQ-REL-004's
  simultaneous adoptive/biological relationship distinction.
- **Grandchildren through a specific line**: daughter Fatimah az-Zahra married her
  cousin Ali bin Abi Thalib; their children Hasan and Husein are grandchildren reachable
  only by computed kinship (REQ-REL-005), not a directly stored "grandparent" record.

Dates in this dataset should be entered with precision qualifiers (REQ-ID-002) rather
than exact Gregorian dates, reflecting genuine historical uncertainty around Hijri-to-
Gregorian conversion — which is itself a useful stress test of that requirement.

This dataset is for internal engineering validation only; it is not the product's
default or seed content for real users, and is expected to be replaced by test
fixtures with clear source citations before being used in any demo shown externally.

## 7. Privacy defaults

- **REQ-PRIV-001**: For a living Person (life status = ALIVE), Contact fields
  (WhatsApp, phone, email) default to visibility "only me" until the Person explicitly
  changes them. Acceptance: a newly created living Person's contact fields are not
  visible to other Trah members without an explicit visibility change.
- **REQ-PRIV-002**: For a deceased Person, name, dates, and place fields default to
  "family members" visible; Contact fields are not applicable. Acceptance: a Person
  marked DECEASED shows core identity fields to other Trah members by default.

## 8. Explicitly out of scope for V1 (deferred)

- Family Archive: photos, albums, stories, documents, audio/video.
- Family Life: calendar, events, activity feed.
- Family Map (geographic aggregation).
- Discovery Engine / cross-Trah relative finding and Family Connections.
- AI family search, OCR of old documents, GEDCOM import/export.
- Family Book generator, printable tree posters.
- Billing / paid tiers.

These remain on the long-term roadmap but must not be designed into V1's data model
in a way that blocks §4. If a V1 requirement conflicts with a deferred feature, V1
wins.

## 9. Open questions for Gate 1 review

- None blocking — ready for user approval. Flag here if anything above needs revision
  before Tier A/B spec work begins.