https://github.com/docxology/timeline_generator
Timeline Generator — Knowledge Graph Explorer for historical figures, networks, and OSINT research
https://github.com/docxology/timeline_generator
data-visualization history knowledge-graph open-source osint timeline typescript visualization
Last synced: about 9 hours ago
JSON representation
Timeline Generator — Knowledge Graph Explorer for historical figures, networks, and OSINT research
- Host: GitHub
- URL: https://github.com/docxology/timeline_generator
- Owner: docxology
- Created: 2026-03-03T16:01:58.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-03T23:46:31.000Z (4 months ago)
- Last Synced: 2026-06-11T02:27:51.154Z (19 days ago)
- Topics: data-visualization, history, knowledge-graph, open-source, osint, timeline, typescript, visualization
- Language: TypeScript
- Homepage:
- Size: 8.97 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Timeline Generator
**Networked Life Encoding for People, Ideas, and Civilizational Threads**
[](https://www.typescriptlang.org/)
[](https://reactjs.org/)
[](https://www.fastify.io/)
[](https://d3js.org/)
[](https://neo4j.com/)
[](https://pnpm.io/)
[](docs/testing.md)
[](LICENSE)
An open, browser-native knowledge graph that encodes human lives as first-class temporal objects and weaves them into richly typed relational networks.
---
## 📸 Screenshots
### Force-Directed Knowledge Graph with Edge Type Labels
### Person Detail Panel & Edge Inspector
Person detail with biography, events, and relationships
Edge inspector with type, confidence, and description
### AI-Powered Research with Enrich Existing Entities
Search and add new historical figures via Perplexity AI
Enrich existing persons with additional research data
## 🎬 Demo
Live walkthrough showing edge labels, hover effects, research enrich tab, and date display improvements
---
## 📖 Vision & Strategic Intent
Where 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.
Beginning 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?
## ✨ Features
- **Interactive Force-Directed Graph** — Fluid, physics-based D3 visualization of complex human networks with domain-colored nodes and confidence rings
- **Edge Type Labels** — Relationship types displayed directly on graph edges, with hover highlighting and angle-following rotation
- **Temporal Brushing** — Interactive SVG timeline to filter relationships and nodes by specific date ranges
- **Rich Biographical Entities** — Every node contains granular details — births, deaths, domains, and 12 types of temporal events
- **24 Typed, Weighted Edges** — Full relationship taxonomy (Epistemic, Collaboration, Pedagogical, Family, etc.) with epistemic confidence floors
- **Perplexity-Powered Research** — Built-in LLM integration to automatically research new figures, enrich existing profiles, and inject them into the active graph
- **Enrich Existing Entities** — Searchable dropdown of all graph persons for targeted AI-powered profile enrichment
- **Glassmorphic UI Engine** — Sleek Black, White, Gray, and Red aesthetic with accessible, responsive control panels
- **Neo4j Graph Database** — Persistent Cypher-backed storage with BFS traversal, shortest path, and APOC algorithms
- **Smart Date Display** — Intelligent year formatting that collapses same-year ranges (no more "1941–1941")
## 🏗️ Architecture
Built as a modern, ESM-native monorepo using `pnpm workspaces` with a Neo4j graph database backend.
```text
timeline_generator/
├── packages/
│ ├── shared/ # Isomorphic constraints, Zod schemas, Edge taxonomy
│ ├── seed-data/ # The Buckminster Fuller historical dataset (20 persons, 42 edges, 46 events)
│ ├── backend/ # Fastify REST API + Neo4j Graph Database (IGraphStore → Neo4jStore)
│ └── frontend/ # React + Zustand + D3 Graph and SVG Timeline
├── docs/ # Comprehensive documentation (15 files)
├── docker-compose.yml # Neo4j service definition
└── run.sh # All-in-one orchestrator script
```
See the [Architecture Guide](docs/architecture.md) for the full system design, data flow, and key design decisions.
## 🚀 Getting Started
### Prerequisites
- **Node.js** v20+
- **pnpm** v9+ (`corepack enable pnpm`)
- **Docker** — for Neo4j graph database
- **Perplexity API Key** _(optional)_ — for research features, set `PERPLEXITY_API_KEY` in `packages/backend/.env`
### Quick Start
```bash
# 1. Clone and install
git clone https://github.com/docxology/timeline_generator.git
cd timeline_generator
pnpm install
# 2. Start Neo4j
docker compose up -d
# 3. Launch everything
pnpm dev
# Or use the all-in-one orchestrator (installs, tests, launches):
./run.sh
```
The application will be available at:
- **Frontend** (UI): `http://localhost:5173`
- **Backend** (API): `http://localhost:3001`
- **Neo4j Browser**: `http://localhost:7474`
See the [Getting Started Guide](docs/getting-started.md) for detailed setup instructions.
## 📚 Documentation
All aspects of the system are documented in the [`/docs`](docs/README.md) directory:
| Document | Description |
|---|---|
| [Getting Started](docs/getting-started.md) | Installation, setup, and first run |
| [Architecture](docs/architecture.md) | System design, monorepo structure, data flow |
| [Data Model](docs/data-model.md) | 24 relationship types, 12 event types, confidence tiers |
| [API Reference](docs/api-reference.md) | 18 REST endpoints with examples |
| [Research](docs/research.md) | Perplexity AI research and entity enrichment |
| [Frontend Guide](docs/frontend-guide.md) | React components, D3 visualization, Zustand state |
| [Backend Guide](docs/backend-guide.md) | Fastify server, Neo4j store, route handlers |
| [Configuration](docs/configuration.md) | Environment variables, Docker, TypeScript, Vite |
| [Seed Data](docs/seed-data.md) | Fuller network dataset specification |
| [Testing](docs/testing.md) | 204-test suite across 4 packages |
| [Contributing](docs/contributing.md) | Code style, PR process, development workflow |
| [Roadmap](docs/roadmap.md) | Completed phases and future plans |
| [Glossary](docs/glossary.md) | Domain terminology and definitions |
## 🧪 Testing
Robust test coverage across the entire stack — **204 tests, all passing**.
```bash
# Run the entire test suite
pnpm test
# Or via the orchestrator
./run.sh --test-only
```
| Package | Tests | Coverage |
|---|---|---|
| `shared` | 72 | Zod schemas, constants, barrel exports |
| `seed-data` | 28 | Referential integrity, schema validation |
| `backend` | 104 | Store CRUD, graph algorithms, route handlers, research/enrichment |
| **Total** | **204** | |
Tests use an in-memory `MemoryStore` for speed — no Neo4j instance required.
## 🤝 Contributing
We welcome contributions! Please review our [Contribution Guidelines](docs/contributing.md) before submitting a pull request.
We maintain a strict **Zero-Mock** policy for tests and require comprehensive JSDoc annotations for all newly added methods.
## 🎨 Design Philosophy
No 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.
---
Built for the exploration of networked human intellectual history.