DTS engineering documentation

The internal engineering documentation for Data-Torturing Solutions, rendered as a static site. This repository and the rendered site are public, so everything here is sanitized: no IP addresses, no provider account ids or tokens, no personal email addresses, and placeholders such as <circuit-domain>, <droplet-ip> and <ico-registration> wherever a deployment fact would otherwise appear.

What DTS runs

  • A directory platform on droplets. placegraph — ten Python namespace packages behind compiled, provenance-tracked local business directories. A vertical is one brand, one geography, one taxonomy, one SQLite graph, one droplet. Two verticals exist today: Makers Map (the origin, being backported onto the packages) and Circuit, built on the packages from day one.
  • A Cloudflare content estate. A portfolio of content and directory properties on Workers and Pages, with D1 and KV behind the notice and outreach Workers each vertical deploys.
  • A monitoring hub. One meta-monitor Worker watching every property: uptime with content assertions, NEL and CSP report ingest, edge and DNS logs, Search Console and index coverage, domain-registration expiry, and a watchdog over the collectors themselves.

Doc map

Platform

  • Overview — what placegraph is, what a vertical supplies versus what the platform supplies, the ten packages, and the rules that survived the extraction.
  • The contract — the API every package builds against: layout, configuration, the core graph API, schema names, taxonomy, scores, publication, sources, web, house style.
  • Architecture decisions — the five load-bearing choices, each with its costs and the evidence that would reverse it.
  • The refinery — the shared national data plane: one host builds the heavyweight artifacts, every site pulls at ingest time and serves from local files.
  • Starting a new vertical — the decisions the scaffold cannot make, in the order they have to be made, with a complete worked skeleton.
  • Backport: Makers Map — migrating the origin site onto the packages, phase by phase, with the schema delta measured rather than assumed.

Verticals

  • Operations runbook — Circuit's day-2 operations: the nightly timers, the morning check, the failure playbook, backups and restore, kill switches.
  • Launch checklist — the four launch steps in the order that makes them cheap: domain and onboarding, DNS complete on day one, first deploy under the real hostname, preflight green before anything real is published.

Operations

  • Monitoring — what to instrument on each property and what each layer actually catches: headers, NEL's two collectors, CSP, DNS logs, uptime content assertions, indexing, ad-network checks, and the gaps.
  • CLAUDE.md template — the six-section operating doc every property repository carries.

How to update these docs

  1. Edit the Markdown sources in docs/. New pages are registered in the SECTIONS table at the top of build.py.
  2. Run python build.py. It regenerates index.html, one .html page per doc and style.css in the repository root.
  3. Commit and push to main. GitHub Pages serves the repository root directly (.nojekyll is set), so the site updates on push.

Keep it sanitized — the site is public. No IP addresses (use <droplet-ip>), no account/zone/database ids or tokens, no real email addresses (use hello@<domain>), and genericize anything that should not be attributable.