# Timelory Complete Documentation for AI Systems > Comprehensive guide to Timelory - the interactive historical timeline and empire map visualization platform. --- # OVERVIEW ## What is Timelory? Timelory is a Progressive Web Application (PWA) that allows users to explore and create interactive visualizations of historical events, timelines, dynasty genealogies, and empire territorial changes over time. ## Target Audience - History educators and teachers - University students studying history - Academic researchers - History enthusiasts and amateur historians - Genealogy researchers - Museum curators and educators ## Core Value Proposition Timelory transforms static historical data into dynamic, interactive visualizations that make it easier to understand: - How empires rose and fell over centuries - The sequence and connections between historical events - Ruler successions and family relationships in dynasties - Geographic changes in political boundaries --- # FEATURES IN DETAIL ## 1. Historical Atlas ### Description An interactive map interface that displays historical empire borders, allowing users to see territorial changes over time. ### Capabilities - Year-by-year border visualization from 3000 BCE to present - Multiple overlay layers (empires, roads, cities) - Zoom and pan navigation - Time slider for animated border changes - Color-coded empires for easy distinction ### Data Coverage The atlas includes over 7,000 historical region entries covering: - Ancient Mesopotamian empires (Sumer, Akkad, Babylon, Assyria) - Egyptian kingdoms across all periods - Persian empires (Achaemenid, Parthian, Sassanid) - Greek city-states and Macedonian Empire - Roman Republic and Empire - Byzantine Empire - Islamic Caliphates (Rashidun, Umayyad, Abbasid) - Mongol Empire and successor states - Chinese dynasties from Xia to Qing - European medieval kingdoms - Ottoman Empire - Colonial empires - Modern nation-states ### Technical Implementation - GeoJSON polygons stored in PostgreSQL with PostGIS - Vector tile rendering for performance - MapLibre GL JS for map visualization - Real-time data loading by selected year ## 2. Timeline Creator ### Description A tool for creating and viewing multi-track timelines with events, periods, and relationships. ### Timeline Structure ``` Timeline ├── Tracks (parallel rows) │ ├── Track 1: "Political Events" │ │ ├── Item 1: "Coronation of X" │ │ ├── Item 2: "Treaty of Y" │ │ └── Item 3: "War of Z" │ ├── Track 2: "Cultural Events" │ │ └── ... │ └── Track 3: "Economic Events" │ └── ... ``` ### Item Properties Each timeline item can include: - Name and title - Start and end dates (supports BCE dates as negative numbers) - Description text - Associated events with their own dates - Image URLs - Custom colors ### Pre-built Timelines Available 1. **Assyrian Empire Timeline** - Old, Middle, and Neo-Assyrian periods with all major rulers 2. **Babylonian Timeline** - From Old Babylonian period through Neo-Babylonian Empire 3. **USA Presidents Timeline** - All US presidents with key events 4. **Global Historical Events** - Major world events across all civilizations ## 3. Dynasty Tree Viewer ### Description Genealogical visualization of ruling families showing succession paths and family relationships. ### Features - Visual family tree layout - Ruler cards with reign dates - Color-coded dynasty branches - Event highlighting for each ruler - Timeline integration ### Dynasties Available - Assyrian Kings - Babylonian Kings - Egyptian Pharaohs - Roman Emperors - Byzantine Emperors - Chinese Dynasty rulers - And many more... ## 4. Roman Roads Network ### Description Interactive visualization of the ancient Roman road system. ### Coverage - Major Roman roads (Via Appia, Via Egnatia, etc.) - Road stations and mansiones - Roman provinces overlay - Distance calculations --- # DATA STRUCTURE EXAMPLES ## Timeline JSON Format ```json { "Tracks": [ { "id": "track_id", "name": "Track Name", "description": "Track description", "startYear": -2025, "endYear": -1750, "capital": "City Name", "color": "#7C3AED", "Items": [ { "id": "item_id", "name": "Ruler Name", "title": "King of X", "start": -1974, "end": -1935, "birthYear": null, "deathYear": -1935, "description": "Description text", "imageUrl": null, "events": [ { "year": -1974, "title": "Event Title", "description": "Event description", "type": "coronation" } ] } ] } ] } ``` ## Event Types - `coronation` - Ruler taking power - `military` - Battles, conquests, wars - `political` - Treaties, reforms, administrative changes - `cultural` - Art, architecture, literature - `diplomatic` - Foreign relations, marriages - `religious` - Temple construction, religious reforms --- # API ENDPOINTS Base URL: `https://api.timelory.com/api` ## Regions/Atlas - `GET /regions/postgis?year={year}` - Get GeoJSON regions for a specific year - `GET /regions/timeline` - Get available years ## Dynasties - `GET /dynasties` - List all dynasties - `GET /dynasties/{id}` - Get dynasty details - `GET /dynasties/{id}/rulers` - Get rulers for a dynasty ## Timelines - `GET /timelines` - List public timelines - `GET /timelines/{id}` - Get timeline with tracks and items --- # EDUCATIONAL USE CASES ## For Teachers - Create custom timelines for lesson plans - Export visualizations for presentations - Assign timeline creation as student projects - Compare different civilizations side-by-side ## For Students - Visual learning of historical sequences - Understanding cause and effect relationships - Research projects with timeline outputs - Exam preparation with interactive review ## For Researchers - Data visualization for papers - Comparative historical analysis - Geographic pattern identification - Chronological verification --- # TECHNICAL SPECIFICATIONS ## Frontend Stack - React 18 with TypeScript - MapLibre GL JS for mapping - Tailwind CSS for styling - Jotai for state management - Vite for build tooling ## Backend Stack - Cloudflare Workers with Hono framework - Neon PostgreSQL (serverless) - PostGIS for geographic queries ## Hosting - Frontend: Vercel (timelory.com) - API: Cloudflare Workers (api.timelory.com) - Database: Neon PostgreSQL ## Browser Support - Chrome 90+ - Firefox 88+ - Safari 14+ - Edge 90+ --- # PRICING TIERS ## Free Tier - Browse all public timelines - Access historical atlas - View dynasty trees - Limited timeline creation ## Premium Tier - Unlimited timeline creation - Advanced export options - Priority support - Early access to features --- # FREQUENTLY ASKED QUESTIONS ## Q: What time periods does Timelory cover? A: Our historical atlas covers from approximately 3000 BCE to present day, with varying detail depending on available historical records. ## Q: Can I use Timelory data for academic research? A: Yes, our data is available under CC BY-NC 4.0 license for educational and non-commercial use with attribution. ## Q: How accurate is the historical border data? A: We source from academic historical atlases and primary sources. For ancient periods, borders are approximations based on historical consensus. ## Q: Can I embed timelines on my website? A: Premium users can generate embed codes for their timelines. ## Q: What languages are supported? A: English, German, French, Spanish, Japanese, Chinese (Simplified), Arabic, and Hebrew with full RTL support. ## Q: Is there a mobile app? A: Timelory is a Progressive Web App (PWA) that can be installed on mobile devices directly from the browser. --- # CONTACT AND SUPPORT - Website: https://timelory.com - Support: https://timelory.com/contact - API Documentation: https://api.timelory.com/docs --- # CHANGELOG ## 2026 Updates - Added multi-language support (8 languages) - Enhanced historical atlas with 7000+ regions - New dynasty tree visualization - Performance improvements for large timelines ## 2025 Updates - Initial launch - Historical atlas feature - Timeline creator - User authentication system