Architecture#

How the data donation task is built and how its parts work together.

Reading order#

If you’re new to the codebase, read these in order:

System overview — what it is, how it fits with Eyra mono
The run cycle — the Python↔JS co-routine that drives everything
Command protocol — the four command types and their responses
FlowBuilder — the per-platform flow lifecycle
Extraction — zip reading, validation, ExtractionResult
Logging — two paths to the host, PII rules
Error handling — ScriptWrapper, error_flow, the PII boundary
Rendering — how commands become React components, the factory system, consent form round-trip

Question	Document
What is data-donation-task and how does it talk to Eyra?	Overview
How does Python run in a browser?	Run cycle
What is a Command? What types exist?	Command protocol
What does FlowBuilder do? How do I extend it?	FlowBuilder
How does extraction work?	Extraction
How do log messages reach the host?	Logging
What happens when Python throws an exception?	Error handling
Where is the PII safety boundary?	Error handling § PII safety
What is the difference between LiveBridge and FakeBridge?	Overview § The bridge
How do Python commands turn into React UI?	Rendering
What is the factory system? How do I add a custom component?	Rendering § Prompt factories
What is data-collector vs feldspar?	Rendering § The two packages
Can the participant edit data before donating?	Rendering § Consent form round-trip
How does the iframe communicate with Eyra mono?	Rendering § Iframe lifecycle