# Freenet Core Crate Architecture

```mermaid
graph LR
    %% Client Application
    Client[Client Application]
    Client -->|"Requests"| WebSocket

    subgraph Core[Freenet Core]
        %% Client Interface Layer
        WebSocket[WebSocket API]
        Server[Server] --> WebSocket
        WebSocket -->|"Messages"| ClientEvents
        Server -->|"ClientConnection"| ClientEvents
        
        %% Central Node Event Loop
        subgraph NodeLoop[Node Event Loop]
            Node[Node]
            Node -->|"Messages"| EventChannelIn[(Incoming Channel)]
            EventChannelOut[(Outgoing Channel)] --> Node
        end

        %% Event Loop Connections
        ClientEvents -->|"OpenRequest"| EventChannelIn
        OpManager -->|"Op Results"| EventChannelIn
        ContractHandler -->|"Contract Events"| EventChannelIn
        NetworkBridge -->|"Net Messages"| EventChannelIn

        EventChannelOut -->|"Client Responses"| ClientEvents
        EventChannelOut -->|"Operations"| OpManager
        EventChannelOut -->|"Contract Queries"| ContractHandler
        EventChannelOut -->|"Network Messages"| NetworkBridge

        %% Operations Management
        subgraph OpLoop[OpManager Event Loop]
             OpManager -->|"States"| OpChannelIn[(Op In Channel)]
             OpChannelOut[(Op Out Channel)] -->|"Updates"| OpManager
        end

        OpMachines[Operation State Machines]
        OpManager -->|"Process"| OpMachines
        OpMachines -->|"Transitions"| OpChannelIn
        OpChannelOut -->|"Messages"| NetworkBridge

        %% Contract System
        subgraph ContractHandling[Contract Processing]
            Executor[Executor]
            WasmRuntime[Runtime]
            StateStore[StateStore]
        end

        ContractHandler -->|"Execute"| Executor
        Executor -->|"WASM"| WasmRuntime
        Executor -->|"State"| StateStore
        
        subgraph ExecutorLoop[Executor Callback Loop]
            ExecutorEvents[Executor Event Handler]
            ExecutorCallback[Callback Channel]
            ExecutorEvents -->|"Tx ID"| ExecutorCallback
            ExecutorCallback -->|"Results"| ExecutorEvents
        end
        
        Executor --> ExecutorEvents
        ExecutorCallback --> OpManager

        %% Network Stack
        subgraph NetStack[Network Stack]
            Ring[Ring]
            Transport[Transport]
            NetMessage[(NetMessage)]
        end

        subgraph NetworkLoop[Network Event Listener]
            HandshakeHandler[Handshake Handler]
            ConnManager[Connection Manager]
            HandshakeHandler --> ConnManager
            ConnManager --> HandshakeHandler
        end
        
        NetworkBridge --> NetworkLoop
        NetworkLoop --> Ring
        NetworkLoop --> Transport
    end

    Peers[Peer Nodes]
    Transport <-->|"Packets"| Peers

    %% Style Definitions
    %% Client Interface Layer
    classDef clientInterface fill:#c6dcef,stroke:#2874a6,stroke-width:1px,color:#000;
    class Client,WebSocket,Server,ClientEvents clientInterface;
    
    %% Node Core
    classDef nodeCore fill:#d5f5e3,stroke:#1e8449,stroke-width:1px,color:#000;
    class Node,EventChannelIn,EventChannelOut nodeCore;
    
    %% Operations
    classDef operations fill:#fdebd0,stroke:#d35400,stroke-width:1px,color:#000;
    class OpManager,OpMachines,OpChannelIn,OpChannelOut operations;
    
    %% Contracts
    classDef contracts fill:#e8daef,stroke:#8e44ad,stroke-width:1px,color:#000;
    class ContractHandler,Executor,WasmRuntime,StateStore,ExecutorEvents,ExecutorCallback contracts;
    
    %% Network - Changed to a more distinct teal color
    classDef network fill:#d1f2eb,stroke:#16a085,stroke-width:1px,color:#000;
    class NetworkBridge,HandshakeHandler,ConnManager,Ring,Transport,NetMessage,Peers network;
    
    %% Event Loops
    classDef eventLoop fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    class NodeLoop,OpLoop,ExecutorLoop,NetworkLoop eventLoop;
    
    %% Boundary
    classDef boundary fill:#ebf5fb,stroke:#3498db,stroke-width:2px;
    class Core boundary;
    
    %% Link Styling - Colored by SOURCE component - Fixed version
    %% Client Interface links (blue)
    linkStyle 0,1,2,3,6 stroke:#2874a6,stroke-width:2px;
    
    %% Node Core links (green)
    linkStyle 4,5,10,11,12,13 stroke:#1e8449,stroke-width:2px;
    
    %% Operation links (orange) 
    linkStyle 7,14,15,16,17,18 stroke:#d35400,stroke-width:2px;
    
    %% Contract links (purple)
    linkStyle 8,19,20,21,22,23,24 stroke:#8e44ad,stroke-width:2px;
    
    %% Network links - Changed to teal
    linkStyle 9,25,26,27,28 stroke:#16a085,stroke-width:2px;
```

**Key Components & Communication:**

- **[Server](src/server.rs):** Handles HTTP and WebSocket endpoints for client connections. The `ClientConnection` enum in [client_api.rs](src/server/client_api.rs) defines the interface between the server and client events system. The server manages the WebSocket API and passes client requests to the ClientEvents subsystem.

- **[Node](src/node.rs):** Central coordinator with the main event loop implemented in `run_event_loop()`. This function contains the core `tokio::select!` loop that dispatches events to appropriate handlers like `handle_network_message()`, `handle_node_event()`, and `handle_client_request()`. 

- **[ClientEvents](src/client_events.rs):** Bridges client connections to the Node system through the `ClientEventsProxy` trait in [client_events.rs](src/client_events.rs). The WebSocket implementation in [websocket.rs](src/client_events/websocket.rs) provides key methods like `websocket_interface()` and `process_client_request()` that handle client connections.

- **[OpManager](src/operations/op_manager.rs):** Tracks operation state using internal hash maps for each operation type. The `push()` and `pop()` methods manage operation lifecycle, while `garbage_cleanup_task()` runs as a background task to remove stale transactions. Other important methods include `notify_op_change()` and `notify_node_event()` for event notification.

- **[ContractHandler](src/contract/handler.rs):** Manages contract interactions through `ContractHandlerChannel<T>` with different halves for different communication directions. The `send_to_handler()` and `recv_from_sender()` methods implement the bidirectional communication protocol for contract operations.

- **[ContractExecutor](src/contract/executor.rs):** Executes WASM contract code with network capabilities defined by the `ContractExecutor` trait. The `Executor<R>` implementation connects contracts to the network using `ComposeNetworkMessage<Op>` implementations like `GetContract`, `PutContract`, and `UpdateContract`.

- **[WasmRuntime](src/wasm_runtime.rs):** Provides the sandboxed execution environment through the `ContractRuntimeInterface` and `DelegateRuntimeInterface` traits defined in [wasm_runtime.rs](src/wasm_runtime.rs). These traits include methods for contract instantiation and function invocation.

- **[StateStore](src/contract/storages.rs):** Handles persistent contract state through the `StateStore<S>` implementation, which provides methods like `get_state()` and `put_state()`. The backing store is abstracted through the `Storage` trait.

- **[NetworkBridge](src/node/network_bridge.rs):** Abstracts network communication via the `NetworkBridge` trait in [network_bridge.rs](src/node/network_bridge.rs). The primary implementation is `P2pConnManager` in [p2p_protoc.rs](src/node/network_bridge/p2p_protoc.rs), which provides the `run_event_listener()` method containing the network event loop.

- **[Ring](src/ring.rs):** Manages network topology through the `Ring` struct and `ConnectionManager` in [ring.rs](src/ring.rs). Key methods include `add_connection()` for peer registration and `route()` for determining message paths.

- **[Transport](src/transport.rs):** Implements low-level communication through the `Socket` trait in [transport.rs](src/transport.rs). The `UdpSocket` implementation provides the actual network I/O operations with support for encryption and rate limiting.

- **[NetMessage](src/message.rs):** Defines the message format used for P2P communication through the `NetMessage` enum hierarchy. Each message includes a `Transaction` ID for tracking and contains operation-specific data in variants like `ConnectMsg`, `PutMsg`, and `GetMsg`.

- **[Operation State Machines](src/operations.rs):** Each operation type is implemented in a dedicated module (e.g., [get.rs](src/operations/get.rs), [put.rs](src/operations/put.rs)) with functions like `start_op()` to create initial state and `request_get()` to initiate network operations.

**Event Loops and Channels:**

1. **Node Event Loop:** The primary coordination loop in [node.rs:run_event_loop()](src/node.rs). Channels are created with `event_loop_notification_channel()` in [network_bridge.rs](src/node/network_bridge.rs), which sets up the `EventLoopNotificationsReceiver` and `EventLoopNotificationsSender` for inter-component communication.

2. **OpManager Event Loop:** Implemented as `garbage_cleanup_task()` in [op_manager.rs](src/operations/op_manager.rs). This task continuously monitors for expired transactions and removes them from the system, sending `NodeEvent::TransactionTimedOut` notifications when needed.

3. **Network Event Listener:** The network main loop in [p2p_protoc.rs:run_event_listener()](src/node/network_bridge/p2p_protoc.rs). It uses `wait_for_event()` to multiplex between multiple event sources and routes incoming/outgoing messages appropriately.

4. **Executor Callback Loop:** Created through `executor_channel()` in [executor.rs](src/contract/executor.rs). This allows contract code to initiate network operations and receive results asynchronously while maintaining execution context.

**Request Lifecycle: Client to Network and Back**

A typical client request follows this path through the system:

1. **Client Initiation**
   - Client connects to the WebSocket endpoint at `/v1/contract/command`
   - `websocket_commands()` in `client_events/websocket.rs` handles the connection
   - Client sends a `ClientRequest` (e.g., `ContractRequest::Get{key}`)

2. **Request Processing**
   - `process_client_request()` deserializes the request and assigns a `ClientId`
   - `WebSocketProxy.recv()` wraps it in an `OpenRequest` and sends to the Node
   - Node receives the request in `handle_client_request()` and determines the type

3. **Operation Creation**
   - For GET requests: Node calls `get::start_op()` to create a new `GetOp`
   - `OpManager.push()` stores the operation state in its collections
   - Node initiates the operation with `get::request_get()`
   - A unique `Transaction` ID is assigned to track this operation

4. **Network Traversal**
   - `OpManager` determines the target peer based on the contract key's location
   - It constructs a `NetMessage::V1(NetMessageV1::Get(GetMsg::...))`
   - `NetworkBridge.send()` delivers this to the target peer
   - `P2pConnManager` sends the actual network packet via `UdpSocket.send_to()`

5. **Remote Processing**
   - The receiving peer's `NetworkBridge` gets the message via `UdpSocket.recv_from()`
   - `P2pConnManager.process_message()` forwards to Node's event loop
   - Remote Node processes the Get request in its contract subsystem
   - If the contract exists, a response message is created and sent back

6. **Response Handling**
   - Local `NetworkBridge` receives the response message
   - Node event loop processes it in `handle_network_message()`
   - Message is matched to pending `Transaction` via its ID
   - `OpManager.pop()` retrieves and updates the operation state
   - Contract state from response is stored in `StateStore` if needed

7. **Client Response**
   - Node creates a `HostResponse::ContractResponse(ContractResponse::GetResponse{...})`
   - Response is sent to `WebSocketProxy.send(client_id, result)`
   - `process_host_response()` serializes it in client's preferred format (Flatbuffers/Native)
   - WebSocket connection sends serialized response to client application

This cycle demonstrates how a distributed operation flows through all major components while maintaining transaction context throughout the process. Each step includes error handling and timeout mechanisms to ensure reliability.

_Refer to the diagram above for a visual representation of these interactions._
