# denissergeevitch/ex-ussr-kinship-research architecture

> Architecture diagram of the GitHub repository denissergeevitch/ex-ussr-kinship-research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/denissergeevitch/ex-ussr-kinship-research
- Repository: https://github.com/denissergeevitch/ex-ussr-kinship-research

## Overview

This repository is an AI-agent genealogy research skill for former Soviet and Russian Empire records, with scripts and templates for managing and checking case evidence. The principal workflow moves from scoped case intake through historical jurisdiction and source research, then records artifacts and evaluates claims and relationships before producing a traceable report. The README documents additional capabilities such as institutional correspondence, photo research, privacy safeguards and PDF output. Some domain workflow details are documented but their implementation was not sampled; those links are cited to the README.

Main entry points: [`SKILL.md`](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/SKILL.md) (Research skill), [`assets`](https://github.com/denissergeevitch/ex-ussr-kinship-research/tree/main/assets) (Research registers), [`references/correspondence.md`](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/correspondence.md) (Archive correspondence), [`assets/final-report.template.md`](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/assets/final-report.template.md) (Final report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research guidance"]
  node_skill["Research skill<br/>[SKILL.md]"]
  node_jurisdiction["Jurisdiction research"]
  node_source_strategy["Source strategy<br/>[source-strategy.md]"]
  node_browser["Browser guidance"]
  node_correspondence["Archive correspondence<br/>[correspondence.md]"]
  node_photo_search["Photo research<br/>[photo-search.md]"]
  node_privacy["Privacy safeguards"]
end

subgraph group_case["Case management"]
  node_case_setup["Case setup<br/>[init_case.py]"]
  node_case_templates["Case templates"]
  node_registers[("Research registers")]
  node_artifact_hash["Artifact hashing<br/>[hash_artifact.py]"]
end

subgraph group_validation["Evidence validation"]
  node_evidence_protocol["Evidence protocol"]
  node_evidence_audit["Evidence audit<br/>[audit_evidence.py]"]
end

subgraph group_reporting["Reporting"]
  node_final_report["Final report"]
  node_pdf_builder["PDF builder<br/>[build_pdf.py]"]
  node_html_template["PDF HTML template"]
end

node_researcher(("Researcher"))
node_browser_service{{"Browser tools"}}
node_mail_service{{"Mail or web tools"}}

node_researcher -->|"asks question"| node_skill
node_skill -->|"sets up case"| node_case_setup
node_case_setup -->|"copies templates"| node_case_templates
node_case_templates -->|"provides registers"| node_registers
node_skill -->|"resolves jurisdiction"| node_jurisdiction
node_skill -->|"plans searches"| node_source_strategy
node_skill -->|"follows access rules"| node_browser
node_browser -.->|"uses when available"| node_browser_service
node_skill -->|"guides requests"| node_correspondence
node_skill -->|"guides photo research"| node_photo_search
node_skill -->|"applies safeguards"| node_privacy
node_researcher -->|"hashes artifacts"| node_artifact_hash
node_skill -->|"records findings"| node_registers
node_skill -->|"assesses evidence"| node_evidence_protocol
node_evidence_protocol -->|"defines statuses"| node_registers
node_evidence_audit -->|"checks references"| node_registers
node_evidence_audit -->|"checks citations"| node_final_report
node_skill -->|"prepares conclusions"| node_final_report
node_skill -->|"drafts requests"| node_correspondence
node_correspondence -.->|"may send via"| node_mail_service
node_final_report -->|"provides HTML report"| node_pdf_builder
node_html_template -->|"constrains HTML"| node_pdf_builder

click node_skill "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/SKILL.md"
click node_jurisdiction "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/ex-ussr-locale-guide.md"
click node_source_strategy "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/source-strategy.md"
click node_browser "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/browser-and-captcha.md"
click node_correspondence "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/correspondence.md"
click node_photo_search "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/photo-search.md"
click node_privacy "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/privacy-and-safety.md"
click node_case_setup "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/init_case.py"
click node_case_templates "https://github.com/denissergeevitch/ex-ussr-kinship-research/tree/main/assets"
click node_registers "https://github.com/denissergeevitch/ex-ussr-kinship-research/tree/main/assets"
click node_artifact_hash "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/hash_artifact.py"
click node_evidence_protocol "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/evidence-protocol.md"
click node_evidence_audit "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/audit_evidence.py"
click node_final_report "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/assets/final-report.template.md"
click node_pdf_builder "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/build_pdf.py"
click node_html_template "https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/assets/report-pdf.template.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_jurisdiction,node_source_strategy,node_browser,node_correspondence,node_photo_search,node_privacy,node_browser_service toneBlue
class node_case_setup,node_case_templates,node_registers,node_artifact_hash toneAmber
class node_evidence_protocol,node_evidence_audit toneMint
class node_final_report,node_pdf_builder,node_html_template toneRose
class node_researcher,node_mail_service toneIndigo
```

## Components

### Research guidance

- [Research skill](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/SKILL.md): `SKILL.md`
- [Jurisdiction research](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/ex-ussr-locale-guide.md): `references/ex-ussr-locale-guide.md`
- [Source strategy](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/source-strategy.md): `references/source-strategy.md`
- [Browser guidance](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/browser-and-captcha.md): `references/browser-and-captcha.md`
- [Archive correspondence](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/correspondence.md): `references/correspondence.md`
- [Photo research](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/photo-search.md): `references/photo-search.md`
- [Privacy safeguards](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/privacy-and-safety.md): `references/privacy-and-safety.md`

### Case management

- [Case setup](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/init_case.py): `scripts/init_case.py`
- [Case templates](https://github.com/denissergeevitch/ex-ussr-kinship-research/tree/main/assets): `assets`
- [Research registers](https://github.com/denissergeevitch/ex-ussr-kinship-research/tree/main/assets): `assets`
- [Artifact hashing](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/hash_artifact.py): `scripts/hash_artifact.py`

### Evidence validation

- [Evidence protocol](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/references/evidence-protocol.md): `references/evidence-protocol.md`
- [Evidence audit](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/audit_evidence.py): `scripts/audit_evidence.py`

### Reporting

- [Final report](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/assets/final-report.template.md): `assets/final-report.template.md`
- [PDF builder](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/scripts/build_pdf.py): `scripts/build_pdf.py`
- [PDF HTML template](https://github.com/denissergeevitch/ex-ussr-kinship-research/blob/main/assets/report-pdf.template.html): `assets/report-pdf.template.html`

### Other components

- **Researcher**
- **Browser tools**
- **Mail or web tools**

## Connections

- Researcher → Research skill: asks question (evidence: `README.md`)
- Research skill → Case setup: sets up case (evidence: `README.md`)
- Case setup → Case templates: copies templates (evidence: `scripts/init_case.py`)
- Case templates → Research registers: provides registers (evidence: `README.md`)
- Research skill → Jurisdiction research: resolves jurisdiction (evidence: `README.md`)
- Research skill → Source strategy: plans searches (evidence: `README.md`)
- Research skill → Browser guidance: follows access rules (evidence: `README.md`)
- Browser guidance → Browser tools: uses when available (evidence: `README.md`)
- Research skill → Archive correspondence: guides requests (evidence: `README.md`)
- Research skill → Photo research: guides photo research (evidence: `README.md`)
- Research skill → Privacy safeguards: applies safeguards (evidence: `README.md`)
- Researcher → Artifact hashing: hashes artifacts (evidence: `README.md`)
- Research skill → Research registers: records findings (evidence: `README.md`)
- Research skill → Evidence protocol: assesses evidence (evidence: `README.md`)
- Evidence protocol → Research registers: defines statuses (evidence: `README.md`)
- Evidence audit → Research registers: checks references (evidence: `scripts/audit_evidence.py`)
- Evidence audit → Final report: checks citations (evidence: `scripts/audit_evidence.py`)
- Research skill → Final report: prepares conclusions (evidence: `README.md`)
- Research skill → Archive correspondence: drafts requests (evidence: `README.md`)
- Archive correspondence → Mail or web tools: may send via (evidence: `README.md`)
- Final report → PDF builder: provides HTML report (evidence: `README.md`)
- PDF HTML template → PDF builder: constrains HTML (evidence: `README.md`)