• 

  intro

Inspiration

For over two millennia, Chinese families preserved their heritage through paper-based clan pedigree books (族谱 / 家谱). However, these physical registries are extremely vulnerable to time, war, and environmental decay. 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 (辈字 / 昭穆) that are nearly indecipherable to younger generations.

Traditional genealogy software (like Ancestry or MyHeritage) lacks the capability to handle traditional Chinese vertical family structures (like the Su-style lineage chart and Ou-style text registry) and does not address the language barrier. We were inspired to build OpenZupu (开元族谱) — an open-source, collaborative, digital lineage platform that bridges ancient physical registries, spatial migration timelines, and modern Y-DNA/mtDNA genetic markers, using AI to translate, index, and reconstruct historical lineages.

What it does

OpenZupu is a full-featured, collaborative, digital genealogy database designed for clan councils, local archives, and historical researchers. Key features include:

Interactive Multi-style Pedigree Charts:

Dynamically generates traditional 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.

Spatiotemporal Geolocation Timelines & Mapping:

Extracts birthplace, residence, and burial records to map centuries of family migrations on an interactive spatial canvas using geographic coordinate tracing.

Genetic Genealogy (Y-DNA / mtDNA Haplogroup Tracking):

Maps patrilineal Y-STR/Y-SNP and matrilineal mtDNA mutational haplogroups across branches to run federated queries and calculate the Most Recent Common Ancestor (MRCA).

Automated Pedigree Sanity Validation:

Employs rule-based engines to identify biological anomalies (e.g., child generation older than parents, generational gaps, and sibling generation character mismatch).

Universal Portability:

Seamlessly imports and exports standard GEDCOM (.ged) files, GraphML, CSV, and JSON backups.

How we built it

We designed OpenZupu using a robust, decoupled monorepo architecture:

Frontend App:

Built with Next.js, React, TypeScript, and styled with custom Tailwind CSS. We crafted a premium visual identity integrating ancient parchment textures, traditional serif typography (Source Han Serif), and responsive sidebar navigation.

Backend API:

Powered by NestJS (Node.js framework) providing clean RESTful endpoints, secured with JWT authentication, custom guards, and transaction-level audit logging.

Database Layer:

Utilizes PostgreSQL indexed via Prisma ORM for low-latency relational queries. AI OCR Integration: Implemented asynchronous workers leveraging Tesseract.js (chi_tra) for automated text extraction of scanned historical archives.

Mathematical Formulations:

We utilize genetic distance calculations to predict generational distance.

Challenges we ran into

Pre-rendering layout bailing in Next.js was a major hurdle; incorporating dynamic search parameters for client-side navigation inside layout headers triggered hydration mismatch and pre-rendering failures. We resolved this by strategically wrapping navigation hooks in client-side boundaries. Additionally, rendering traditional vertical Chinese writing-mode layouts (writing-mode: vertical-rl) for infinite printing canvas caused severe horizontal text clipping, overlapping columns, and printing omissions. We resolved this by engineering dynamic column sizing bounds (160px ≤ width ≤ 400px) and overriding print CSS stylesheets with native page print margins.

Accomplishments that we're proud of

Successfully compiled and generated pristine SVG vectors for traditional Su-style and Ou-style vertical charts that look gorgeous when printed. Implemented robust UTF-8 BOM encoding for Microsoft Excel-compatible CSV exports, resolving traditional Chinese character scrambling (乱码) issues permanently. Created a fully production-ready Next.js + NestJS codebase that is easily self-hostable via Docker Compose for any local clan council without relying on expensive SaaS providers.

What we learned

We learned that traditional cultural layouts require completely different CSS constraints compared to modern Western dashboards. Building layouts that respect vertical typographic hierarchies, classical dates (e.g., 清光绪三十二年丙午), and complex biological relations taught us to decouple visual layout styling from the underlying data structure.

What's next for OpenZupu

We plan to deeply integrate OpenAI's GPT-4o with Vision and Structured Outputs API to revolutionize document ingestion:

Zero-shot Lineage Extraction:

Users will upload raw photos of vertical hand-written, weathered clan books, and GPT-4o will transcribe, segment names, and output a structured JSON/GEDCOM tree directly.

Classical Prose Translation:

Translate highly abbreviated Classical Chinese biography logs into modern, readable narrative summaries.

AI Co-pilot Search:

Provide a semantic RAG search copilot allowing users to ask questions like "Which branch of our family migrated south to Fujian during the late Ming dynasty?"

Built With

• algorithms
• biomedical
• csv
• docker
• geographic-maps
• git
• json
• markdown
• nestjs
• next.js
• node.js
• openai
• openai-api-(planned)
• postgresql
• prisma
• react
• svg
• tailwind-css
• typescript