feat(docs): visually model data types and function flow for core protocols

[adklempner]

Description

User Story

Proposed Solution / Feature Design

Optional: Diagram or Draft of Design

Notes

[weboko]

@adklempner can you add description and update state of the issue?

[adklempner]

Filter:

---
config:
  layout: fixed
---
flowchart TB
 subgraph Legend["Legend"]
    direction TB
        L1[["User Interface"]]
        L2{{"Component"}}
        L3[/"External System"\]
        L4[/"Data Type"/]
        L5("Function")
        LC_wire["Wire Format/Protocol"]
        LC_sdk["SDK/API Types"]
        LC_core["Core/Internal Types"]
        LC_process["Components/Processes"]
        LC_external["External Systems"]
        LC_function["Functions/Methods"]
        LC_user["User Interface"]
  end
    User[["User Application"]] --> subscribe1("subscribe") & unsubscribe1("unsubscribe")
    subscribe1 --> S_Filter{{"Filter"}}
    S_Filter --> subAdd("add") & subRemove("remove")
    subAdd --> S_Sub{{"Subscription"}}
    IDec[/"IDecoder"/] -.-> subInvoke("invoke")
    CB[/"Callback"/] -.-> subscribe1
    FOpts[/"FilterProtocolOptions"/] -.-> S_Sub
    S_Sub --> unsubscribe2("FilterCore.unsubscribe") & keepAliveTick("keepAlive tick")
    subscribe2("FilterCore.subscribe") --> C_Filter{{"FilterCore"}} & getStream("StreamManager.getStream") & createSubReq("FilterSubscribeRpc.createSubscribeRequest")
    getStream --> C_StreamMgr{{"StreamManager"}}
    createSubReq --> FSReq[/"FilterSubscribeRequest"/]
    FSReq --> Libp2p[/"libp2p"\] & Libp2p & Libp2p
    Libp2p --> FSResp[/"FilterSubscribeResponse"/] & MPush[/"MessagePush"/]
    FSResp --> decodeSubResp("FilterSubscribeResponse.decode")
    decodeSubResp --> CPR[/"CoreProtocolResult"/]
    CPR --> S_Sub
    MPush --> decodePush("FilterPushRpc.decode")
    decodePush --> onPush("FilterCore.onRequest")
    onPush --> C_Filter
    C_Filter --> onIncoming("filter.onIncomingMessage")
    onIncoming --> S_Filter
    WMsg[/"WakuMessage"/] -.-> subInvoke
    subInvoke --> IDMsg[/"IDecodedMessage"/]
    IDMsg --> CB
    unsubscribe1 --> S_Filter
    subRemove --> S_Sub
    unsubscribe2 --> C_Filter & getStream & createUnsubReq("FilterSubscribeRpc.createUnsubscribeRequest")
    createUnsubReq --> FSReq
    keepAliveTick --> ping2("FilterCore.ping")
    ping2 --> C_Filter & getStream & createPingReq("FilterSubscribeRpc.createSubscriberPingRequest")
    createPingReq --> FSReq
     L1:::userNode
     L2:::processNode
     L3:::externalNode
     L4:::wireType
     L5:::functionNode
     LC_wire:::wireType
     LC_sdk:::sdkType
     LC_core:::coreType
     LC_process:::processNode
     LC_external:::externalNode
     LC_function:::functionNode
     LC_user:::userNode
     User:::userNode
     subscribe1:::functionNode
     unsubscribe1:::functionNode
     S_Filter:::processNode
     subAdd:::functionNode
     subRemove:::functionNode
     S_Sub:::processNode
     IDec:::sdkType
     subInvoke:::functionNode
     CB:::sdkType
     FOpts:::sdkType
     unsubscribe2:::functionNode
     keepAliveTick:::functionNode
     subscribe2:::functionNode
     C_Filter:::processNode
     getStream:::functionNode
     createSubReq:::functionNode
     C_StreamMgr:::processNode
     FSReq:::wireType
     Libp2p:::externalNode
     FSResp:::wireType
     MPush:::wireType
     decodeSubResp:::functionNode
     CPR:::coreType
     decodePush:::functionNode
     onPush:::functionNode
     onIncoming:::functionNode
     WMsg:::wireType
     IDMsg:::sdkType
     createUnsubReq:::functionNode
     ping2:::functionNode
     createPingReq:::functionNode
    classDef wireType fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef sdkType fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef coreType fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef processNode fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef externalNode fill:#fce4ec,stroke:#ad1457,stroke-width:2px
    classDef functionNode fill:#ffebee,stroke:#c62828,stroke-width:1px
    classDef userNode fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    style S_Filter font-size:18px,stroke-width:3px
    style S_Sub font-size:18px,stroke-width:3px
    style C_Filter font-size:18px,stroke-width:3px
    style C_StreamMgr font-size:18px,stroke-width:3px
    style Libp2p font-size:18px,stroke-width:3px

Loading

[adklempner]

LightPush:

graph TB
    %% ============== Style definitions ==============
    classDef wireType fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef sdkType fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef coreType fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef processNode fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef externalNode fill:#fce4ec,stroke:#ad1457,stroke-width:2px
    classDef functionNode fill:#ffebee,stroke:#c62828,stroke-width:1px
    classDef userNode fill:#e0f2f1,stroke:#00695c,stroke-width:2px

    %% ============== Nodes (no layer grouping) ==============
    %% User Interface
    User[[User Application]]:::userNode

    %% Wire Types (Protocol)
    LPR[/PushRequest/]:::wireType
    LPS[/PushResponse/]:::wireType
    LPRpc[/PushRpc/]:::wireType
    WMsg[/WakuMessage/]:::wireType

    %% SDK/API Types
    IMsg[/IMessage/]:::sdkType
    IEnc[/IEncoder/]:::sdkType
    SDKRes[/SDKProtocolResult/]:::sdkType
    SOptions[/ISendOptions/]:::sdkType

    %% Core/Internal Types
    CPR[/CoreProtocolResult/]:::coreType

    %% Components/Processes
    SDK_LP{{LightPush}}:::processNode
    SDK_PM{{PeerManager}}:::processNode
    SDK_RM{{RetryManager}}:::processNode
    CORE_LP{{LightPushCore}}:::processNode
    CORE_SM{{StreamManager}}:::processNode

    %% External Systems
    Libp2p[/libp2p\]:::externalNode
    Remote[/Remote Waku Node\]:::externalNode

    %% Functions (Methods)
    send1(LightPush.send):::functionNode
    getPeers(PeerManager.getPeers):::functionNode
    aggregate(SDK aggregate results):::functionNode
    retryPush(RetryManager.push):::functionNode

    send2(LightPushCore.send):::functionNode
    prep(preparePushMessage):::functionNode
    sizeCheck(isMessageSizeUnderCap):::functionNode
    toProto(toProtoObj):::functionNode
    createPush(PushRpc.createRequest):::functionNode

    getStream(StreamManager.getStream):::functionNode
    lpEncode(lp.encode):::functionNode
    lpDecode(lp.decode):::functionNode
    encRpc(PushRpc.encode):::functionNode
    decRpc(PushRpc.decode):::functionNode

    %% ============== Flows ==============
    %% User input to SDK send
    User --> send1 --> SDK_LP --> getPeers --> SDK_PM
    IEnc -.-> send1
    IMsg -.-> send1
    SOptions -.-> send1

    %% SDK selects peers and calls Core send (per peer)
    SDK_LP --> send2 --> CORE_LP

    %% Core prepare and encode
    send2 --> prep
    prep --> sizeCheck
    prep --> toProto
    toProto --> WMsg
    prep --> createPush --> LPRpc

    %% Stream and wire path
    send2 --> getStream --> CORE_SM
    LPRpc --> encRpc --> lpEncode --> Libp2p --> Remote

    %% Response path back
    Remote --> Libp2p --> lpDecode --> decRpc --> LPRpc
    decRpc --> LPS --> CPR --> SDK_LP

    %% SDK aggregates results to SDKProtocolResult
    SDK_LP --> aggregate --> SDKRes --> User

    %% Auto-retry side path
    aggregate --> retryPush --> SDK_RM --> send2

    %% Parameter flows
    IEnc -.-> toProto
    IMsg -.-> toProto

    %% Emphasis styles to make components and externals larger/more central
    style SDK_LP font-size:18px,stroke-width:3px
    style SDK_PM font-size:18px,stroke-width:3px
    style SDK_RM font-size:18px,stroke-width:3px
    style CORE_LP font-size:18px,stroke-width:3px
    style CORE_SM font-size:18px,stroke-width:3px
    style Libp2p font-size:18px,stroke-width:3px
    style Remote font-size:18px,stroke-width:3px

    %% ============== Legend (shapes + colors) ==============
    subgraph Legend
        direction TB
        %% Shape legend (with corresponding colors)
        L1[[User Interface]]:::userNode
        L2{{Component}}:::processNode
        L3[/External System\]:::externalNode
        L4[/Data Type/]:::wireType
        L5(Function):::functionNode
        %% Color legend
        LC_wire[Wire Format/Protocol]:::wireType
        LC_sdk[SDK/API Types]:::sdkType
        LC_core[Core/Internal Types]:::coreType
        LC_process[Components/Processes]:::processNode
        LC_external[External Systems]:::externalNode
        LC_function[Functions/Methods]:::functionNode
        LC_user[User Interface]:::userNode
    end

Loading