WolfP2P software architecture

A file transfer unfolds across several independently changing parts of the system: the coordination service admits participants, each WolfP2P browser client establishes and may lose its peer connection, the browser peers advance through offers, streaming, recovery, and completion, and several interface components must respond consistently. If each component interprets events or maintains its own version of what is happening, those views can drift—showing an action that is no longer legal, presenting stale progress, or giving the two participants incompatible expectations.

WolfP2P therefore needs one explicit source of truth that records the accepted state, distinguishes shared facts from participant-local context, propagates each valid change to every subscriber, rejects stale or contradictory transitions, and allows the interface, deadlines, recovery logic, diagnostics, and tests to derive their behavior from the same model. This is the problem the state machine is chosen to solve.

The model is layered rather than flat. It does not attempt to place every server condition, browser resource, file operation, and visual detail into one enormous list of states. Instead, each kind of fact has an owner and a defined consequence. The layers are then correlated into the view needed by one participant.

Shared operational state answers the questions on which the service or both participants depend. It is composed from four independently owned machines:

1. Coordination availability: whether the browser can currently reach the service that creates tunnels, admits participants, and exchanges connection details.
2. Tunnel membership: which of the two tunnel seats are live or reserved. The coordination server is authoritative for this membership.
3. Peer transport: whether the browser clients are signaling, connected as browser peers, reconnecting, or unable to establish their WebRTC connection. Each client owns its view of that transport.
4. Transfer: whether a file offer is being prepared, considered, streamed, recovered, or completed. This state belongs to the browser clients and peer-transfer protocol rather than to the coordination server.

These machines remain separate because a change in one does not necessarily rewrite the others. For example:

• The coordination service can become temporarily unreachable while established browser peers continue streaming file bytes.
• Both tunnel seats can remain reserved while the browsers lose their peer connection and attempt to reconnect.
• The peer connection can be healthy while an offer waits for the receiver's decision, leaving the transport connected but the transfer inactive.
• Completing the accepted file set changes the transfer outcome, but it does not retroactively change which participant opened the tunnel or which browser occupied each seat.

Collapsing these situations into a single status would lose useful distinctions. “Disconnected,” for example, could mean that the coordination service is unavailable, the peer transport has failed, or the participant has actually left the tunnel—three conditions with different consequences and different next actions.

Roles are scoped for the same reason. The opener and joiner occupy stable tunnel seats. The browsers may take different roles while negotiating a connection. Sender and receiver are established for a particular file transfer. Treating those names as interchangeable would hide changes in authority and could make the wrong action appear available.

A state is not merely a label: it has an entry, a span during which particular events and actions are legal, and an exit caused by an accepted event. Some spans are bounded by declared timers so the system cannot wait forever for participation, signaling, a decision, progress, or recovery. When a deadline wins the race against another event, its expiry is processed as a transition with a defined owner, cause, and resulting state—not as a visual countdown added by the interface.

WolfP2P distinguishes three kinds of timed span. An absolute deadline limits the lifetime of a larger entity, such as a tunnel or transfer session, and continues across relevant phase changes. A phase deadline applies only while its named phase remains current and is replaced when that phase changes. An inactivity deadline is refreshed only by a declared sign of progress; unrelated activity does not extend it. Several deadlines can be active at once, while the interface selects only the ones useful to the participant.

Each runtime deadline instance is tied to the generation that scheduled it. Leaving a state invalidates timers that no longer apply, and a callback from an older generation is rejected as stale. This prevents a late signaling, offer, reconnection, or progress timeout from terminating a newer lifecycle that happens to use a similar state name.

Many important facts belong to only one browser. The following are examples rather than a complete enumeration:

• a native file picker and the browser file objects selected through it;
• destination access and the current result of a browser permission check or request;
• local omissions and the private paths or reasons recorded for entries that cannot be offered;
• observed progress, recovery evidence, and browser-local support records such as activity logs or completion reports.

Keeping a fact local does not make it unimportant. It means the fact does not change what the other participant or the coordination server is entitled to assume. A sender can be choosing a folder without telling the receiver which native picker is open. A receiver can be restoring access to a destination without creating a new peer-visible transfer phase. Private file and filesystem details can remain in the browser client while the shared model carries only the bounded information needed for the transfer.

Local operations are still declared and correlated with the operational state that owns them. The model can therefore prevent a conflicting action while a picker, permission request, inspection, or destination write is pending, without pretending that this private browser activity is shared protocol state.

WolfP2P uses consequences to decide where a fact belongs. A fact enters shared operational state when it changes peer expectations, the legality of a message or action, whose turn it is, a shared deadline, recovery order, or an authority decision. Otherwise it remains participant-local or presentation-local.

Selecting files demonstrates this boundary. The sender's selection is initially a local browser resource. It does not advance the shared transfer state. The first peer-shared fact is the offer deliberately sent to the receiver, containing the file metadata needed to review the proposed transfer. Likewise, a local omission report can explain which selected entries could not be offered without sending those omitted paths to the browser peer or coordination server.

Every proposed transition is checked against the current state. An accepted transition produces the next source-of-truth state and is propagated to its subscribers. A command, peer message, or deadline left over from an earlier state cannot silently act on a newer one: the model rejects it when its authority or generation is stale.

This boundary also governs recovery. A matching relative path and byte size identify a possible destination match, not proof that the content is the same. Reusing a completed file requires matching content evidence, and resuming a partial file requires verified prefix evidence. The receiver verifies the final destination bytes before it can declare durable completion. The detailed user-facing rules are explained in Transfer Recovery and Reliability.

The interface subscribes to a projection of the accepted state for the participant viewing it. That projection supplies the applicable status, explanation, deadlines, notices, and legal actions. Interface components render that result and return declared user intentions; they do not maintain a competing transfer model or infer authority from whichever data happens to be present.

This makes the interface reactively subordinated: reactive because it updates when its source state or relevant local context changes, and subordinated because it cannot invent a transition, action, or product fact. A button may be visually available only when the governing projection returns that action. An error or notice explains an outcome but does not itself change which operations are legal.

Presentation details such as focus, an expanded section, or the visibility of a dialog remain ordinary local interface state unless they cause a declared operation. This keeps visual behavior flexible without allowing layout code to become another source of product truth.