What does this platform actually do?
Thirteen diagrams — each one answers a specific question about how the platform works in production, vetted against code, anchored by file:line pointers. Split into user-perspective (how a user experiences the app) and system-perspective (how the machinery works).
User-perspective
What a user sees and does in the app, screen by screen. Start here for understanding how the product actually feels to use.
Signup + First Use
From "I want to try FuzzyCode" to a parent actively using it with a child — what screens do they actually see?
- One template · eight panels — URL never changes during signup/OTP/reset
- Children share the parent's login page — reset / sign-up links fail silently
- Parent step-up modal on every credential change
- Account recovery is admin-resolved, not self-service
- No in-editor context switcher
The Creative Loop
A user has an idea. How do they turn it into a published page — and what are all the ways they can modify it in between?
- Editor UI map + only 1 real creation entry + 7 load paths
- 20 distinct update mechanisms, grouped
- 5-direction swipe compass (up/down/left/right/center)
- Version dropdown = branching tree that silently branches
- 3 publish outcomes — "Public" means "request approval"
Where Does Your Work Live?
The user makes a change. Browser crashes, session expires, switches devices, switches from parent to child — what survives?
- 4 storage tiers — memory, sessionStorage, IndexedDB (360d per-child), Redis temp_page (30d)
- No autosave; prompt text in sessionStorage only
- Survival matrix across 9 events × 4 stores
- Three user-facing "history" surfaces, each different backing store
- No fork button — duplicate via URL load only
How Assets End Up On Your Page
Images, sounds, and sprites appear in the editor. Where do they come from — and what are all the ways a user can bring them in?
- No "generate asset" button on main editor
- AI writes URLs; browser fetching = generation
- 9 image + 4 sound + 4 sprite paths enumerated
- Per-asset 429s are silent — broken image, no signal
- Moderation is prompt-level, not asset-level
Multi-Asset Sheet
How does one AI call produce a whole spritesheet of style-consistent game assets, and how does each sprite end up cropped and transparent?
- The
<multi-asset-sheet>HTML tag contract - Synchronous prewarm pipeline: declare → prewarm → Gemini-slice → cache
- Hash-key formula — what changes regenerate everything
spritesheet_reffor cross-sheet style consistency- All failure modes with UX evidence
System-perspective
What the platform actually does under the hood — services, flows, state machines, and topology. Read these when you need to change the system, not when you're learning the product.
Page Publish
What happens from click-publish to the page being live at pages.fuzzycode.dev?
- Two-hop browser-orchestrated — no server-to-server call
- CDNBuddy is not on the publish path
- Page lifecycle encoded across 4 fields, no
statuscolumn - Client silently swallows 14 of 15 server error paths
Auth & JWT Lifecycle
When a user logs in, how are tokens issued, refreshed, and revoked — and what's the real contract between FuzzyCode and every sibling service?
- 12 cookies with roles, TTLs, and evidence
- Redis-guarded refresh with
REFRESH_IN_PROGRESS409 - JWKS-first verification ladder with HS256 fallback
- Active-context flag state: UAT on · prod off
VerifiedActor Hydration
Given an incoming request, what "kind of user" does FuzzyCode decide is making it — and how can that decision go wrong?
- Undocumented keystone of server-side auth
- 5 principal states: anonymous · blocked · child_direct · parent_direct · parent_acting_for_child
- 9-step check ordering, any of which can fail
- Revocation latency gap explicitly surfaced
Parental Consent Lifecycle
The docs say 5 clean states; the database has no consent_state column. What does the lifecycle actually look like?
- 5 enums across 5 tables combine to express one lifecycle
- Copy-pasteable SQL for "verified active children" etc.
- Transition ownership matrix — who writes what
- TTL cleanup is a manual dry-run script
Content Moderation Pipeline
What moderation actually runs on user prompts — and why doesn't the published architecture match the code?
- "Shared moderation service" is a doc fiction — no service calls it at runtime
moderation_core/is vendored into 5 repos- Fail-mode diverges: SoundBuddy closed, ImageBuddy open on init
- FuzzyCode has zero content moderation integration
Asset Lifecycle
How does a generated image / sound / sprite / upload travel from creation to browser — and what happens to it over time?
- 3 distinct topologies — R2+KV Workers · CloudFront+S3 · direct-to-Replit
- Sprite sheets served from ephemeral container disk
- No TTL or deletion in code, for any asset type
- "Signed URLs" in UploaderBuddy have no expiry
PII Firewall Boundary Map
Which services actually screen user text for PII before acting on it — and which ones don't?
- Wired in: FuzzyCode · SoundBuddy · ImageBuddy · SpriteBuddy
- Not wired: UploaderBuddy (EXIF / filenames / embedded text bypass)
- Bedrock classifier, fail-closed, 3-state (not 5-state)
- Single env var
PII_FIREWALL_MODE=offdisables everywhere
Platform Service Topology
What services exist, how are they configured per environment, and who calls whom?
- YAML source → Mermaid + HTML, one data file
- 10 production services + 4 infra / external nodes
env_stateper service captured explicitly- Non-edges (e.g., FuzzyCode→Pages server hop) documented as absent
How these were built
Every diagram follows the same rule: code is truth, docs are claims. Before a diagram is drafted, one or more verification subagents read the actual code and produced evidence reports (under 01_platform_scan/verification/). Only then is the diagram authored, with file:line pointers in each diagram's frontmatter.
The consequence: every diagram corrects at least one claim from prior architecture docs. That's not a side effect — it's a signal the pattern is working.
Two companion documents make this reproducible:
WIP_DOC_STRATEGY/02_strategy/DOC_ARCHITECTURE.md— where each diagram lives in the target tree, frontmatter, update triggers.WIP_DOC_STRATEGY/04_maintenance/MAINTENANCE_PLAN.md— how agents keep diagrams in sync with code on every PR.