{"id":51247255,"url":"https://github.com/docxology/timeline_generator","last_synced_at":"2026-06-29T05:03:35.281Z","repository":{"id":363939353,"uuid":"1171791242","full_name":"docxology/timeline_generator","owner":"docxology","description":"Timeline Generator — Knowledge Graph Explorer for historical figures, networks, and OSINT research","archived":false,"fork":false,"pushed_at":"2026-03-03T23:46:31.000Z","size":9401,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T02:27:51.154Z","etag":null,"topics":["data-visualization","history","knowledge-graph","open-source","osint","timeline","typescript","visualization"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docxology.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-03T16:01:58.000Z","updated_at":"2026-04-26T16:03:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/docxology/timeline_generator","commit_stats":null,"previous_names":["docxology/timeline_generator"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/docxology/timeline_generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Ftimeline_generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Ftimeline_generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Ftimeline_generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Ftimeline_generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docxology","download_url":"https://codeload.github.com/docxology/timeline_generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docxology%2Ftimeline_generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34913587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-visualization","history","knowledge-graph","open-source","osint","timeline","typescript","visualization"],"created_at":"2026-06-29T05:03:34.713Z","updated_at":"2026-06-29T05:03:35.271Z","avatar_url":"https://github.com/docxology.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Timeline Generator\n\n**Networked Life Encoding for People, Ideas, and Civilizational Threads**\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-18.x-61DAFB?style=flat-square\u0026logo=react\u0026logoColor=black)](https://reactjs.org/)\n[![Fastify](https://img.shields.io/badge/Fastify-4.x-black?style=flat-square\u0026logo=fastify)](https://www.fastify.io/)\n[![D3.js](https://img.shields.io/badge/D3.js-7.x-F9A03C?style=flat-square\u0026logo=d3.js\u0026logoColor=white)](https://d3js.org/)\n[![Neo4j](https://img.shields.io/badge/Neo4j-5.x-008CC1?style=flat-square\u0026logo=neo4j\u0026logoColor=white)](https://neo4j.com/)\n[![pnpm](https://img.shields.io/badge/pnpm-workspace-F69220?style=flat-square\u0026logo=pnpm\u0026logoColor=white)](https://pnpm.io/)\n[![Tests](https://img.shields.io/badge/tests-204_passing-brightgreen?style=flat-square)](docs/testing.md)\n[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)\n\nAn open, browser-native knowledge graph that encodes human lives as first-class temporal objects and weaves them into richly typed relational networks.\n\n\u003c/div\u003e\n\n---\n\n## 📸 Screenshots\n\n\u003cdiv align=\"center\"\u003e\n\n### Force-Directed Knowledge Graph with Edge Type Labels\n\n\u003cimg src=\"docs/assets/screenshot_graph.png\" alt=\"Main graph view with edge type labels, person list, and timeline\" width=\"100%\" /\u003e\n\n### Person Detail Panel \u0026 Edge Inspector\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshot_person_detail.png\" alt=\"Person detail panel showing R. Buckminster Fuller biography\" width=\"100%\" /\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshot_edge_inspector.png\" alt=\"Edge inspector showing COLLABORATED WITH relationship\" width=\"100%\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cem\u003ePerson detail with biography, events, and relationships\u003c/em\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cem\u003eEdge inspector with type, confidence, and description\u003c/em\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### AI-Powered Research with Enrich Existing Entities\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshot_research_new.png\" alt=\"Research modal - New Person search via Perplexity AI\" width=\"100%\" /\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshot_research_enrich.png\" alt=\"Research modal - Enrich existing person dropdown\" width=\"100%\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cem\u003eSearch and add new historical figures via Perplexity AI\u003c/em\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cem\u003eEnrich existing persons with additional research data\u003c/em\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/div\u003e\n\n## 🎬 Demo\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/assets/demo_ui_improvements.webp\" alt=\"UI improvements demo walkthrough\" width=\"100%\" /\u003e\n\n\u003cem\u003eLive walkthrough showing edge labels, hover effects, research enrich tab, and date display improvements\u003c/em\u003e\n\n\u003c/div\u003e\n\n---\n\n## 📖 Vision \u0026 Strategic Intent\n\nWhere conventional biography treats a person's life as a linear text, Timeline Generator treats it as a node in a multidimensional graph — alive with dated events, weighted relationships, epistemic provenance, and searchable context drawn from live information sources.\n\nBeginning with a seed network around **R. Buckminster Fuller**, the system expands outward through time and association: Who knew of whom? Who corresponded? Who built on whose ideas? Who shared an institution, however briefly, before diverging?\n\n## ✨ Features\n\n- **Interactive Force-Directed Graph** — Fluid, physics-based D3 visualization of complex human networks with domain-colored nodes and confidence rings\n- **Edge Type Labels** — Relationship types displayed directly on graph edges, with hover highlighting and angle-following rotation\n- **Temporal Brushing** — Interactive SVG timeline to filter relationships and nodes by specific date ranges\n- **Rich Biographical Entities** — Every node contains granular details — births, deaths, domains, and 12 types of temporal events\n- **24 Typed, Weighted Edges** — Full relationship taxonomy (Epistemic, Collaboration, Pedagogical, Family, etc.) with epistemic confidence floors\n- **Perplexity-Powered Research** — Built-in LLM integration to automatically research new figures, enrich existing profiles, and inject them into the active graph\n- **Enrich Existing Entities** — Searchable dropdown of all graph persons for targeted AI-powered profile enrichment\n- **Glassmorphic UI Engine** — Sleek Black, White, Gray, and Red aesthetic with accessible, responsive control panels\n- **Neo4j Graph Database** — Persistent Cypher-backed storage with BFS traversal, shortest path, and APOC algorithms\n- **Smart Date Display** — Intelligent year formatting that collapses same-year ranges (no more \"1941–1941\")\n\n## 🏗️ Architecture\n\nBuilt as a modern, ESM-native monorepo using `pnpm workspaces` with a Neo4j graph database backend.\n\n```text\ntimeline_generator/\n├── packages/\n│   ├── shared/        # Isomorphic constraints, Zod schemas, Edge taxonomy\n│   ├── seed-data/     # The Buckminster Fuller historical dataset (20 persons, 42 edges, 46 events)\n│   ├── backend/       # Fastify REST API + Neo4j Graph Database (IGraphStore → Neo4jStore)\n│   └── frontend/      # React + Zustand + D3 Graph and SVG Timeline\n├── docs/              # Comprehensive documentation (15 files)\n├── docker-compose.yml # Neo4j service definition\n└── run.sh             # All-in-one orchestrator script\n```\n\nSee the [Architecture Guide](docs/architecture.md) for the full system design, data flow, and key design decisions.\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- **Node.js** v20+\n- **pnpm** v9+ (`corepack enable pnpm`)\n- **Docker** — for Neo4j graph database\n- **Perplexity API Key** _(optional)_ — for research features, set `PERPLEXITY_API_KEY` in `packages/backend/.env`\n\n### Quick Start\n\n```bash\n# 1. Clone and install\ngit clone https://github.com/docxology/timeline_generator.git\ncd timeline_generator\npnpm install\n\n# 2. Start Neo4j\ndocker compose up -d\n\n# 3. Launch everything\npnpm dev\n\n# Or use the all-in-one orchestrator (installs, tests, launches):\n./run.sh\n```\n\nThe application will be available at:\n\n- **Frontend** (UI): `http://localhost:5173`\n- **Backend** (API): `http://localhost:3001`\n- **Neo4j Browser**: `http://localhost:7474`\n\nSee the [Getting Started Guide](docs/getting-started.md) for detailed setup instructions.\n\n## 📚 Documentation\n\nAll aspects of the system are documented in the [`/docs`](docs/README.md) directory:\n\n| Document | Description |\n|---|---|\n| [Getting Started](docs/getting-started.md) | Installation, setup, and first run |\n| [Architecture](docs/architecture.md) | System design, monorepo structure, data flow |\n| [Data Model](docs/data-model.md) | 24 relationship types, 12 event types, confidence tiers |\n| [API Reference](docs/api-reference.md) | 18 REST endpoints with examples |\n| [Research](docs/research.md) | Perplexity AI research and entity enrichment |\n| [Frontend Guide](docs/frontend-guide.md) | React components, D3 visualization, Zustand state |\n| [Backend Guide](docs/backend-guide.md) | Fastify server, Neo4j store, route handlers |\n| [Configuration](docs/configuration.md) | Environment variables, Docker, TypeScript, Vite |\n| [Seed Data](docs/seed-data.md) | Fuller network dataset specification |\n| [Testing](docs/testing.md) | 204-test suite across 4 packages |\n| [Contributing](docs/contributing.md) | Code style, PR process, development workflow |\n| [Roadmap](docs/roadmap.md) | Completed phases and future plans |\n| [Glossary](docs/glossary.md) | Domain terminology and definitions |\n\n## 🧪 Testing\n\nRobust test coverage across the entire stack — **204 tests, all passing**.\n\n```bash\n# Run the entire test suite\npnpm test\n\n# Or via the orchestrator\n./run.sh --test-only\n```\n\n| Package | Tests | Coverage |\n|---|---|---|\n| `shared` | 72 | Zod schemas, constants, barrel exports |\n| `seed-data` | 28 | Referential integrity, schema validation |\n| `backend` | 104 | Store CRUD, graph algorithms, route handlers, research/enrichment |\n| **Total** | **204** | |\n\nTests use an in-memory `MemoryStore` for speed — no Neo4j instance required.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please review our [Contribution Guidelines](docs/contributing.md) before submitting a pull request.\n\nWe maintain a strict **Zero-Mock** policy for tests and require comprehensive JSDoc annotations for all newly added methods.\n\n## 🎨 Design Philosophy\n\nNo blue. The interface strictly adheres to a monochromatic deep-space aesthetic (Slate grays from `slate-50` to `slate-950`), accented only by vital systemic highlights in structural **Red** (`#DC2626`). Interfaces are glassy, non-obtrusive, and map dynamically to the complexity of the data they project.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eBuilt for the exploration of networked human intellectual history.\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocxology%2Ftimeline_generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocxology%2Ftimeline_generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocxology%2Ftimeline_generator/lists"}