OpenZupu: An Open-Source Genealogy Platform That Brings Vertical Chinese Clan Books Back to Life

At the OpenAI Build Week hackathon in July 2026 (13–21 July), an open-source project called OpenZupu (Kaiyuan Zupu) caught the attention of the genealogy digitization community. Submitted by developer Joan Kuo, the project targets a deep pain point in the transmission of Chinese clan genealogies: building, with open-source code, a digital platform that can genuinely read vertical Classical-Chinese clan books, connect geographic migration and genetic genealogy. A full technical description and live demo were published on Devpost.

The inspiration came from observing the predicament of traditional genealogies: for more than two millennia, Chinese families preserved their heritage through paper-based clan pedigree books (zupu / jiapu). These physical registries are extremely vulnerable — time, war and environmental decay can reduce centuries of lineage to nothing. More importantly, they are written in highly abbreviated Classical Chinese, formatted in traditional vertical right-to-left layout columns, and use complex sibling numbering and generational characters (beizi / zhaomu) that are nearly indecipherable to younger generations.

OpenZupu’s feature set covers the full chain of genealogy digitization. First, interactive multi-style pedigree charts: it dynamically generates Su-style lineage trees (vertical-column tree layouts showing direct patrilineal lines) and Ou-style registry text (dense vertical blocks for print and record-keeping), alongside western-style descendants/ancestry graphs and radial fan charts. Second, spatiotemporal geolocation timelines and mapping: it extracts birthplace, residence and burial records to map centuries of family migrations on an interactive spatial canvas. Third, genetic genealogy mapping: it maps patrilineal Y-STR/Y-SNP and matrilineal mtDNA mutational haplogroups across branches, runs federated queries, and calculates the Most Recent Common Ancestor (MRCA). Fourth, automated pedigree sanity validation: rule-based engines identify biological anomalies such as children older than parents, generational gaps and sibling generation character mismatches. Fifth, universal portability: seamless import and export of standard GEDCOM (.ged), GraphML, CSV and JSON backups.

Technically, OpenZupu uses a robust decoupled monorepo architecture: the frontend is built with Next.js, React and TypeScript, styled with custom Tailwind CSS and integrating ancient parchment textures and the serif typeface Source Han Serif; the backend is powered by NestJS with clean RESTful endpoints, JWT authentication, custom guards and transaction-level audit logging; the database layer uses PostgreSQL indexed via Prisma ORM; and OCR relies on asynchronous workers using Tesseract.js (chi_tra) for automated text extraction from scanned archives. The whole system is easily self-hostable via Docker Compose, without expensive SaaS providers.

The team candidly described the hardest part: rendering traditional Chinese vertical writing-mode layouts (writing-mode: vertical-rl) in Next.js caused severe horizontal text clipping, overlapping columns and printing omissions on the infinite print canvas. They resolved it by engineering dynamic column sizing bounds (160px ≤ width ≤ 400px) and overriding print CSS stylesheets with native page print margins. Hydration mismatches and pre-rendering failures from dynamic search parameters were resolved by wrapping navigation hooks in client-side boundaries.

The project also produced several proud accomplishments: pristine SVG vectors for traditional Su-style and Ou-style vertical charts that look gorgeous when printed; robust UTF-8 BOM encoding for Microsoft Excel-compatible CSV exports, permanently resolving traditional Chinese character scrambling (luànma); and a fully production-ready Next.js + NestJS codebase that any local clan council can self-host without relying on commercial platforms.

OpenZupu’s roadmap is equally forward-looking: the team plans to deeply integrate OpenAI’s GPT-4o with Vision and Structured Outputs. Users will upload raw photos of vertical hand-written, weathered clan books, and the AI will transcribe, segment names and output a structured JSON/GEDCOM tree directly; translate highly abbreviated Classical Chinese biography logs into modern readable narrative summaries; and provide a semantic RAG search copilot allowing questions such as “Which branch of our family migrated south to Fujian during the late Ming dynasty?”

For genetic genealogy researchers, OpenZupu’s distinctive value lies in putting traditional genealogical records and molecular evidence into the same platform: genealogy texts provide the lineage framework, geographic timelines restore migration, and Y-DNA and mtDNA haplogroups supply kinship verification — together significantly enhancing the credibility and interpretability of family records. This aligns with the current academic direction of multimodal genealogical archives: text, space and genes are converging onto a single family network.

As an open-source project, OpenZupu’s choice is methodologically significant: when genealogy data concerns family privacy and autonomy, a “self-hosted, privacy-first” route lets clan organizations avoid entrusting core family records to commercial platforms. The source code is available on GitHub (github.com/yuancafe/openZupu) with a live demo. From paper clan books to open digital lineage, the way Chinese family memory is preserved is opening to new possibilities.