Architecture Decisions

The conversation opened from a creature/world-builder framing inspired by games like Spore. That framing suggested a large permutation space of creature creation. The idea quickly proved too shallow: the compelling part was not morphology b

The concept needed a central character. The strongest candidate became YY: your real stuffed squirrel, already established elsewhere as your first storytelling partner and the thread through your identity arc. This turned the project from g

At first the system implicitly leaned toward an indefinitely long root timeline. That threatened clarity, onboarding, narrative shape, and compute discipline. A better structure emerged: each root is a finite arc, usually one calendar month

The product needed a clean branching logic. Abstract trait mutation and weird parallel selves were initially interesting, but the cleaner form became: same YY, shared root, then a branch where YY acquires a skill, language, or capability. T

The event engine evolved from generic world events to a stronger idea: use real-world events as seeds, abstracted enough to remain universal but still tied to actual dates. Later, historical rewind emerged: start in a past month or period,

The concept oscillated between two incompatible desires: 1. a clean system for measuring how a skill changes processing 2. a messy emergent world where branches or agents can collide Initially, crossings were exciting. Then they were stripp

The surface evolved through several forms: rich narrative logs, SNES dialog, then SMS/emoji. Cost and usability converged on a mobile-first daily check-in product. The site should be fast to open, instantly readable, and usable on any phone

Once multiple branches exist, users need both attachment and reference. The winning interaction pattern became: let users follow/bookmark a branch they care about, but keep the root or canonical baseline instantly accessible so meaning neve

Real-time simulation was attractive in theory but unnecessary and expensive. A better architecture emerged: every night the world advances, artifacts are generated and cached, and during the day users browse static pages and JSON. This mirr

The project repeatedly confronted cost. The core insight was that pictures and clever text are the expensive parts, while structured state transitions are cheap. This led to a layered compute strategy: local models or rules for deterministi

A major late insight: canonical YY may need refinement over time. Rather than silently changing YY, the system should version canon. Each root or branch can explicitly reference the YY version it used. YY itself can have an independent time

The project needed high-fidelity tracking. The strongest architectural model became financial: like orders and refunds, original facts remain immutable; later corrections or interpretations are added as ledger events. The database must pres

Once the database of truth hardened, manifests regained a narrower but essential role. The system needs machine-readable summaries of what exists, what is stale, what depends on what, and what needs recomputation. This helps AI operate safe

The product depends on comparison. Recomputing diffs on every view would be wasteful. Since most branches and YY versions are mostly static once generated, branch diffs and YY version diffs can be computed once and cached. Pairwise explosio

There was concern that the product might become too cutesy and accidentally look child-directed. At the same time, the intention is that peers might selectively share it with their families. Existing YY properties and Case 002 both suggest

The product is easier to show than explain. YouTube Shorts emerged as the best top-of-funnel: same event, multiple branches, quick outcome. Email emerged later as a Substack-like daily note for people following a branch. The site remains th

The desired early stack is cheap and simple: Vercel for static site delivery and Neon Postgres for source-of-truth storage. The early launch is explicitly hobby-scale and mostly static, with small branch counts and minimal media. This must

In the distant future, others may become involved and stronger verification or distributed attestation may matter. The right response is not to build on blockchain now, but to preserve the hooks that make later verification possible without

Case-002 (yymethod-home) defined YY's World as a kids-only, read-only, outward-only property: primary audience ages 8–14, COPPA compliance by structural elimination, no data collection of any kind, no monetization, dandelion seeds with no t

The system has two layers: a public GitHub Pages layer (JSONL ledger, markdown ADRs, JSON projections, static site, visible pipeline) and a private Vercel + Neon layer (generation pipeline, database of truth, API routes, paid features). The

As the site approaches launch, three distinct discoverability problems must be resolved:

YYBW-021 established a URL structure using `/root/2026-04/` as the path prefix for run data. That prefix has no character scoping — as soon as a second character exists, it becomes ambiguous. Separately, the human-facing and machine-readabl

On 2026-04-14, the first real content was written for the April run. During setup, two questions surfaced simultaneously:

YYBW-023 established that `story_day` in a branch file records the number of days that have completed the full pipeline cycle, and that "the nightly pipeline is the sole authority for incrementing `story_day`." The implied model was:

YYBW-020 established a public/private two-layer architecture: the private layer holds source truth; the public layer holds the rendered, gated surface. The distinction between "what the pipeline has processed" and "what visitors can see" wa

On 2026-04-14, two canon integrity failures were caught during first-content validation:

In public, multi-domain systems, authorship and authority are typically asserted through claims: branding, marketing, explicit declarations of ownership. These claims are fragile over time — origin becomes unclear, attribution is contested,

On 2026-04-15, the Day 2 artifacts for both branches were reviewed before publication and found to be significantly below quality bar. This ADR documents what failed, why rewriting was permitted, and the rules it establishes going forward.

The April 2026 root was initialized without two things that significantly affect generation quality:

After designing the world seed and voice register (YYBW-029), the April 2026 run was framed as a gap — a root that started without proper governance. The natural next question was whether to tighten constraints immediately or run the month