Case study · Genealogy · Live product
Family Tree: a multi-tenant genealogy platform
Designing, building and running a family-tree product in Persian and English — Postgres as the source of truth, Neo4j for kinship paths, REST and GraphQL over one use-case layer.
Family Tree is a product I designed, built and run on my own: an online family tree where a family records its people, marriages and dates, and asks the one question every family eventually asks — how exactly are these two people related?
It is live, in Persian and English, with the Jalali calendar where Persian readers expect it. Both halves are open source: the backend and the frontend. You can try the read-only demo without signing up.
The problem
A family tree looks like a small CRUD app until you list what it has to get right:
- Every family is a tenant. A person can appear in two families' trees, and the system must never let one tree's data — or one tree's people — leak into another.
- The interesting questions are graph questions. "First cousin once removed" is a path through parents and spouses, several hops long, in a graph that grows a generation at a time.
- The data has rules a form cannot enforce. No one is their own ancestor; no one has three biological parents; a parent and child belong to the same tree.
- The answer has to be in the reader's language. "Father's brother's son" is correct and useless; a Persian reader wants «پسرعمو», an English reader "first cousin".
What it does
- People, parent links (biological, adoptive, step), marriages and divorces, with photos
- The closest relationship between any two people, a male-line variant, and a few genuinely different alternative paths — each named in Persian and English
- A canvas that lays out large pedigrees, a timeline to see the tree at any year, branch views and a per-person lineage poster
- Excel import and export (an imported row that matches an existing person is applied as an edit), plus image and PDF export of the tree
- Per-tree members and permissions, users and roles, and support tickets
Architecture
The backend is FastAPI with a Clean Architecture split — domain, application, infrastructure and presentation — and two thin presentation layers, REST and GraphQL (Strawberry), over the same use cases, so authorization and errors cannot drift between them.
PostgreSQL is the source of truth. Every write commits there first. A Celery task then mirrors the change into Neo4j, which exists only to answer path questions fast; it can be rebuilt from Postgres at any time, and an hourly reconciliation task repairs any drift. Redis carries the queues and the auth rate limits; MinIO holds photos behind signed URLs.
The frontend is Next.js with React Flow for the canvas, in two languages with right-to-left layout.
Decisions that shaped it
- Tenancy is enforced inside Cypher, not just in Python: every hop of a path query is filtered by tree, so a person in two trees cannot become a bridge between them.
- Path depth scales with the tree (
6 + 4·log10(n)hops, capped), so small trees stay cheap and large pedigrees still find distant relatives. - Integrity lives in the database. A Postgres trigger rejects cycles, a third biological parent and cross-tree links, whatever path the write came from.
- The public demo is not a second code path. An anonymous visitor gets a synthetic membership with four read permissions, so every write route refuses it through the same check as anyone else.
By the numbers
| Automated tests | 803, at 88% statement coverage |
| Test layers | unit, integration (live Postgres + Neo4j), end-to-end through both APIs |
| Database migrations | 27 (Alembic) |
| APIs | REST and GraphQL, generated typed clients for both |
| Languages | English and Persian, Gregorian and Jalali calendars |
Links
- Live: family.arash-alfooneh.ir · demo
- Code: backend · frontend