Teather Engine

Web software for timeline graphs

---

A self-hosted web app for building wikis as connected graphs. Each entry is a node with a title, description, dates and sources; nodes link to each other through typed relations (caused, evolved into, opposed, part of, …). A timeline slider filters the graph by period, so a project can be explored node by node or viewed whole. Anyone can browse a project; only its author can edit it.

Features

• Projects — each user builds their own wiki: nodes, typed edges, custom categories and sources. Projects are public (listed) or link-only (unlisted but openable by URL).
• Timeline — a dual range slider; bounds are derived from the project's data. Everything filters by "node started within the range".
• Explore view — a decade ribbon as the entry point, then a local graph that flows smoothly around the focused node (camera ease-in, history with a Back button and breadcrumbs). Groups larger than four collapse into capsules; nodes with many links in range surface as anchors.
• Map view — the whole project as a force-directed graph with timeline-aware layout, plus shortest-path routing between any two nodes (respects the slider).
• Visual editor (owner) — drag nodes and persist positions, draw edges by pulling between handles and pick the type in a popup, add nodes by double-click, one-click auto-layout. Available both on the map and around a node.
• Edge palette — each relation type has a distinct color and stroke, with a legend on the graph.
• Auth — Google OAuth, plus a password-less dev login for local development.
• Import — load a project from JSON (see backend/sample_data.json).

Demo

Stack

• Backend: FastAPI, SQLAlchemy, SQLite (Postgres-ready via DATABASE_URL).
• Frontend: React, Vite, TypeScript, React Flow, Tailwind CSS, d3-force.
• Delivery: Docker Compose — nginx serves the built SPA and proxies /api.

Quick start (Docker)

cp .env.example .env          # set SECRET_KEY (any long random string)
docker compose up --build

Open http://localhost:5173. On first run a public demo project is seeded. Reset everything with docker compose down -v.

Local development

# backend
cd backend
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # set SECRET_KEY
uvicorn main:app --reload --port 8000

# frontend (separate terminal)
cd frontend
npm install
npm run dev                     # Vite proxies /api to http://localhost:8000

Environment variables

Variable	Required	Default	Description
SECRET_KEY	yes	—	Signs session cookies. Use a long random string.
DATABASE_URL	no	sqlite:///./teather.db	SQLAlchemy connection string.
BASE_URL	no	http://localhost:5173	Public origin, used for the OAuth redirect URI.
DEV_LOGIN	no	false	Enables password-less login by name. Local development only.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	no	—	Enables Google sign-in when both are set.

Google OAuth

1. Create an OAuth client (Web application) in the Google Cloud Console.
2. Add the redirect URI {BASE_URL}/api/auth/google/callback (locally http://localhost:5173/api/auth/google/callback).
3. Put the client id/secret into .env and restart — the "Sign in with Google" button appears automatically.

Repository layout

backend/    FastAPI app, SQLite, REST API   (see backend/README.md)
frontend/   React + Vite SPA
docker-compose.yml

License

MIT