feat: add mermaid charts for filter, lp, store, connection manager

This commit is contained in:
Arseniy Klempner 2025-08-07 23:57:02 -07:00
parent 52e5c34520
commit 050e88645d
No known key found for this signature in database
GPG Key ID: 51653F18863BD24B
4 changed files with 509 additions and 0 deletions

159
connectionmanager_chart.md Normal file
View File

@ -0,0 +1,159 @@
```mermaid
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 (entry points)
User[[User Application]]:::userNode
%% Core Components
CM{{ConnectionManager}}:::processNode
DD{{DiscoveryDialer}}:::processNode
DIAL{{Dialer}}:::processNode
CL{{ConnectionLimiter}}:::processNode
KAM{{KeepAliveManager}}:::processNode
NM{{NetworkMonitor}}:::processNode
SR{{ShardReader}}:::processNode
%% External Systems
LP2P[/libp2p\]:::externalNode
PStore[/libp2p PeerStore\]:::externalNode
RELAY[/Relay\]:::externalNode
BNET[/Browser Network\]:::externalNode
%% Data Types / Events
CMOpts[/ConnectionManagerOptions/]:::coreType
KAOpts[/KeepAliveOptions/]:::coreType
ShardInfo[/ShardInfo/]:::wireType
PeerPingMeta[/PeerStore metadata ping/]:::wireType
PeerShardMeta[/PeerStore metadata shardInfo/]:::wireType
E_DISC[/libp2p 'peer:discovery'/]:::wireType
E_CONN[/libp2p 'peer:connect'/]:::wireType
E_DISCNT[/libp2p 'peer:disconnect'/]:::wireType
E_NET[/browser online or offline/]:::wireType
E_WAKU[/IWaku 'waku:connection' event/]:::wireType
%% API Functions
CM_start(start):::functionNode
CM_stop(stop):::functionNode
CM_dial(dial):::functionNode
CM_hang(hangUp):::functionNode
CM_peers(getConnectedPeers):::functionNode
%% Subsystem Functions
DD_onDisc(onPeerDiscovery):::functionNode
DIAL_enqueue(enqueue dial):::functionNode
DIAL_process(process queue):::functionNode
DIAL_should(skip peer checks):::functionNode
CL_onConnEvt(onWakuConnectionEvent):::functionNode
CL_onDiscEvt(onDisconnectedEvent):::functionNode
CL_maintain(maintainConnections):::functionNode
KAM_startPeer(startPingForPeer):::functionNode
KAM_stopPeer(stopPingForPeer):::functionNode
KAM_relayTick(relayKeepAliveTick):::functionNode
NM_onConn(onConnectedEvent):::functionNode
NM_onDisc(onDisconnectedEvent):::functionNode
NM_dispatch(dispatchNetworkEvent):::functionNode
SR_has(hasShardInfo):::functionNode
SR_onTopic(isPeerOnTopic):::functionNode
SR_onShard(isPeerOnShard):::functionNode
%% ============== Flows ==============
%% User controls ConnectionManager
User --> CM_start --> CM
User --> CM_stop --> CM
User --> CM_dial --> CM
User --> CM_hang --> CM
User --> CM_peers --> CM
%% Config into components
CMOpts -.-> CM
KAOpts -.-> KAM
%% Composition wiring
CM --> DD
CM --> DIAL
CM --> CL
CM --> KAM
CM --> NM
CM --> SR
%% Discovery to Dial path
E_DISC --> DD_onDisc --> DD
DD --> PStore
DD --> DIAL_enqueue --> DIAL
DIAL --> DIAL_should --> SR
SR --> PStore
DIAL --> DIAL_process --> LP2P
%% Direct dial API
CM_dial --> LP2P
%% Maintain connections periodic
CL --> CL_maintain --> LP2P
%% Auto-recovery on disconnect
E_DISCNT --> NM_onDisc --> NM --> E_WAKU
E_DISCNT --> CL_onDiscEvt --> CL --> DIAL_enqueue
E_WAKU --> CL_onConnEvt --> CL --> DIAL_enqueue --> DIAL
%% Connectivity propagation from libp2p and browser
E_CONN --> NM_onConn --> NM --> E_WAKU
E_NET --> NM_dispatch --> NM --> E_WAKU
%% Keepalive on peer connect
E_CONN --> KAM_startPeer --> KAM --> LP2P
KAM --> PeerPingMeta --> PStore
KAM_relayTick --> RELAY
%% getConnectedPeers reads PeerStore and uses ping
CM_peers --> PStore
PeerPingMeta -.-> CM_peers
%% Shard gating reads shard info
PeerShardMeta -.-> SR_has
SR_has -.-> SR
%% Browser network external source
BNET --> E_NET
%% Emphasis styles for components and externals
style CM font-size:18px,stroke-width:3px
style DD font-size:18px,stroke-width:3px
style DIAL font-size:18px,stroke-width:3px
style CL font-size:18px,stroke-width:3px
style KAM font-size:18px,stroke-width:3px
style NM font-size:18px,stroke-width:3px
style SR font-size:18px,stroke-width:3px
style LP2P font-size:18px,stroke-width:3px
style PStore font-size:18px,stroke-width:3px
style RELAY font-size:18px,stroke-width:3px
style BNET font-size:18px,stroke-width:3px
%% ============== Legend (shapes + colors) ==============
subgraph Legend
direction TB
L1[[User Interface]]:::userNode
L2{{Component}}:::processNode
L3[/External System\]:::externalNode
L4[/Data Type/]:::wireType
L5(Function):::functionNode
LC_wire[Wire Format/Protocol or Events]:::wireType
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
```

121
filter_chart.md Normal file
View File

@ -0,0 +1,121 @@
```mermaid
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)
FSReq[/FilterSubscribeRequest/]:::wireType
FSResp[/FilterSubscribeResponse/]:::wireType
MPush[/MessagePush/]:::wireType
WMsg[/WakuMessage/]:::wireType
%% SDK/API Types
IDec[/IDecoder<T>/]:::sdkType
IDMsg[/IDecodedMessage/]:::sdkType
CB[/Callback<T>/]:::sdkType
FOpts[/FilterProtocolOptions/]:::sdkType
%% Core/Internal Types
CPR[/CoreProtocolResult/]:::coreType
%% Components/Processes
S_Filter{{Filter}}:::processNode
S_Sub{{Subscription}}:::processNode
C_Filter{{FilterCore}}:::processNode
C_StreamMgr{{StreamManager}}:::processNode
%% External Systems
Libp2p[/libp2p\]:::externalNode
Remote[/Remote Waku Node\]:::externalNode
%% Functions (Methods)
subscribe1(subscribe):::functionNode
unsubscribe1(unsubscribe):::functionNode
subAdd(add):::functionNode
subRemove(remove):::functionNode
subInvoke(invoke):::functionNode
onIncoming(filter.onIncomingMessage):::functionNode
keepAliveTick(keepAlive tick):::functionNode
subscribe2(FilterCore.subscribe):::functionNode
unsubscribe2(FilterCore.unsubscribe):::functionNode
ping2(FilterCore.ping):::functionNode
getStream(StreamManager.getStream):::functionNode
createSubReq(FilterSubscribeRpc.createSubscribeRequest):::functionNode
createUnsubReq(FilterSubscribeRpc.createUnsubscribeRequest):::functionNode
createPingReq(FilterSubscribeRpc.createSubscriberPingRequest):::functionNode
decodeSubResp(FilterSubscribeResponse.decode):::functionNode
onPush(FilterCore.onRequest):::functionNode
decodePush(FilterPushRpc.decode):::functionNode
%% ============== Flows ==============
%% User input to SDK subscribe
User --> subscribe1 --> S_Filter --> subAdd --> S_Sub
IDec -.-> subscribe1
CB -.-> subscribe1
FOpts -.-> S_Sub
%% Subscription to Core: SUBSCRIBE
S_Sub --> subscribe2 --> C_Filter
subscribe2 --> getStream --> C_StreamMgr
subscribe2 --> createSubReq --> FSReq
FSReq --> Libp2p --> Remote
%% Response path (SUBSCRIBE, UNSUBSCRIBE, PING)
Remote --> Libp2p --> FSResp --> decodeSubResp --> CPR --> S_Sub
%% Incoming PUSH (remote -> app)
Remote --> Libp2p --> MPush --> decodePush --> onPush --> C_Filter
C_Filter --> onIncoming --> S_Filter --> S_Sub
WMsg -.-> subInvoke
IDec -.-> subInvoke
subInvoke --> IDMsg --> CB
%% Unsubscribe flow
User --> unsubscribe1 --> S_Filter --> subRemove --> S_Sub
S_Sub --> unsubscribe2 --> C_Filter
unsubscribe2 --> getStream
unsubscribe2 --> createUnsubReq --> FSReq --> Libp2p --> Remote
%% Keep-alive ping flow
S_Sub --> keepAliveTick --> ping2 --> C_Filter
ping2 --> getStream
ping2 --> createPingReq --> FSReq --> Libp2p --> Remote
%% Emphasis styles to make components and externals larger/more central
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
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
```

122
lightpush_chart.md Normal file
View File

@ -0,0 +1,122 @@
```mermaid
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
```

107
store_chart.md Normal file
View File

@ -0,0 +1,107 @@
```mermaid
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)
SQReq[/StoreQueryRequest/]:::wireType
SQResp[/StoreQueryResponse/]:::wireType
WMsg[/WakuMessage/]:::wireType
%% SDK/API Types
IDMsg[/IDecodedMessage/]:::sdkType
IDec[/IDecoder<T>/]:::sdkType
QParams[/QueryRequestParams/]:::sdkType
%% Core/Internal Types
Cursor[/StoreCursor/]:::coreType
%% Components/Processes
SDK_Store{{Store}}:::processNode
SDK_PM{{PeerManager}}:::processNode
CORE_Store{{StoreCore}}:::processNode
CORE_SM{{StreamManager}}:::processNode
%% External Systems
Libp2p[/libp2p\]:::externalNode
Remote[/Remote Waku Store Node\]:::externalNode
%% Functions (Methods)
queryGen(Store.queryGenerator):::functionNode
buildParams(buildQueryParams):::functionNode
getPeer(Store.getPeerToUse):::functionNode
queryPerPage(StoreCore.queryPerPage):::functionNode
getStream(StreamManager.getStream):::functionNode
encodeReq(StoreQueryRequest.create):::functionNode
lpEncode(lp.encode):::functionNode
lpDecode(lp.decode):::functionNode
decodeResp(StoreQueryResponse.decode):::functionNode
toProtoMsg(toProtoMessage):::functionNode
decodeFromProto(decoder.fromProtoObj):::functionNode
%% ============== Flows ==============
%% User triggers query generator
User --> queryGen --> SDK_Store --> buildParams
IDec -.-> queryGen
QParams -.-> queryGen
%% Select peer and invoke core per query option
buildParams --> getPeer --> SDK_PM
SDK_Store --> queryPerPage --> CORE_Store
%% Core: build request and stream
queryPerPage --> encodeReq --> SQReq
queryPerPage --> getStream --> CORE_SM
%% Send over libp2p
SQReq --> lpEncode --> Libp2p --> Remote
%% Receive and decode
Remote --> Libp2p --> lpDecode --> decodeResp --> SQResp
%% Map to decoder promises (per message)
SQResp -.-> WMsg
WMsg -.-> toProtoMsg
toProtoMsg --> decodeFromProto --> IDMsg
%% Yield page of promises back to SDK and user
CORE_Store --> SDK_Store --> User
%% Emphasis styles to make components and externals larger/more central
style SDK_Store font-size:18px,stroke-width:3px
style SDK_PM font-size:18px,stroke-width:3px
style CORE_Store 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
```