Skip to content

Project Journal

This journal documents every major decision in the Continuous GTFS platform, from early experiments through production deployment — written as the decisions were made, not after the fact.

How It Works

Each entry answers a plain-English question: How should we serve realtime feeds? What does the production infrastructure look like? Are real feeds actually flowing? Early posts (001–009) come from running focused experiments against real Sound Transit data. Later posts (010–014) cover the build phases — going from validated experiments to a live production system processing thousands of pipeline runs.

Every post follows the same structure:

  1. The Question — what we needed to decide and why it matters
  2. What We Tried — approaches and variations tested
  3. What We Found — numbered findings with real numbers from real data
  4. What It Looks Like — diagrams, code, and live output showing the decision in action
  5. The Decision — one bold sentence
  6. What This Means — downstream impact
  7. Open Questions — what's still unresolved

When a later post supersedes an earlier decision, the older post has an admonition pointing to the update.

Reading Order

Posts are listed newest-first in the nav, but they tell a story from bottom to top:

  • 001–009: Experiments — validating individual components (CDN latency, transform patterns, deployment models, orchestration)
  • 010–014: Build phases — from framework to live production (transform framework → orchestrator → infrastructure → E2E integration → REST API)

Relationship to Other Docs

Document Audience Purpose
Journal posts Everyone Why we made each decision, with the evidence
System specs Engineers Detailed design for each component
Experiment specs Engineers What we tested and how
Architecture overview Everyone Bird's eye view of the current system

Writing New Posts

Journal posts are authored with the /journalist skill in Claude Code. Invoke it when an experiment closes, a significant decision is made, or a synthesis emerges across multiple experiments:

/journalist cover the asset-registry experiment
/journalist write up the deployment decision

The skill handles post structure, formatting conventions, mkdocs nav updates, and reviewing older posts for superseded content.