Add review to markdown docs

.env.example

@@ -0,0 +1,9 @@
+# Nitrolite WebSocket URL for real-time communication
+# Replace with your actual Nitrolite WebSocket endpoint
+VITE_NITROLITE_WS_URL=wss://your-nitrolite-websocket-url
+
+# Example for development:
+# VITE_NITROLITE_WS_URL=wss://dev-nitrolite.example.com/ws
+
+# Example for production:  
+# VITE_NITROLITE_WS_URL=wss://nitrolite.example.com/ws

README.md

@@ -41,6 +41,8 @@ In this workshop, we will use a sample content platform application as a practic
 3.  **Set up environment variables:**
     Create a file named `.env.local` in the root of the project and add your Nitrolite WebSocket URL:
 
+    TODO: Specify the clearnode RPC or add link on how to set up a local Clearnode instance.
+
     ```env
     # .env.local
     VITE_NITROLITE_WS_URL=wss://your-rpc-endpoint.com/ws

docs/chapter-1-wallet-connect.md

@@ -48,6 +48,7 @@ npm install viem
 First, modify `src/components/PostList/PostList.tsx` to accept a prop `isWalletConnected` and use it to enable or disable a new "Sponsor" button.
 
 ```tsx
+// TODO: I would add an alias (`@/`) to the `tsconfig.json` to avoid relative imports and improve readability.
 // filepath: src/components/PostList/PostList.tsx
 import { type Post } from '../../data/posts';
 import styles from './PostList.module.css';
@@ -176,6 +177,7 @@ Finally, modify `src/App.tsx` to manage the `walletClient` and `account` state,
 // filepath: src/App.tsx
 import { useState } from 'preact/hooks';
 import { createWalletClient, custom, type Address, type WalletClient } from 'viem';
+// TODO: specify that we are using only the mainnet chain or move to a separate file for chains, to easily change it.
 import { mainnet } from 'viem/chains';
 import { PostList } from './components/PostList/PostList';
 import { posts } from './data/posts';
@@ -201,6 +203,7 @@ export function App() {
     const formatAddress = (address: Address) => `${address.slice(0, 6)}...${address.slice(-4)}`;
 
     return (
+        // TODO: either use styles as a string or as an imported object. Because it looks strange to have different styles usage in neighboring code snippets
         <div className="app-container">
             <header className="header">
                 <div className="header-content">

docs/chapter-2-ws-connection.md

@@ -68,6 +68,7 @@ class WebSocketService {
         };
         this.socket.onmessage = (event) => {
             try {
+                // TODO: It's better to use provided RPC parser from Nitrolite SDK, and since it parses the string -- do not use JSON.parse directly.
                 const data = JSON.parse(event.data);
                 this.messageListeners.forEach((listener) => listener(data));
             } catch (error) {
@@ -79,6 +80,8 @@ class WebSocketService {
     }
 
     public send(method: string, params: any) {
+        // TODO: requestId increment might be dangerous (because of lack of mutex), consider using timestamp
+        // And use request constructor from Nitrolite SDK: NitroliteRPC.createRequest(...);
         const payload = JSON.stringify({ jsonrpc: '2.0', id: this.requestId++, method, params });
         if (this.socket?.readyState === WebSocket.OPEN) this.socket.send(payload);
         else this.messageQueue.push(payload);
@@ -242,7 +245,9 @@ Before running the application, make sure to set the WebSocket URL in your `.env
 
 ```bash
 # Nitrolite Configuration
+#TODO: Specify somewhere that this is a Clearnode RPC, that was used to open a channel
 VITE_NITROLITE_WS_URL=wss://clearnet.yellow.com/ws
+# TODO: what is this URL?
 VITE_NITROLITE_API_URL=http://localhost:8080
 
 # Application Configuration

docs/chapter-3-session-auth.md

@@ -33,6 +33,8 @@ sequenceDiagram
     App->>App: 9. Enable authenticated features
 ```
 
+TODO: add a separate diagram for the JWT re-authentication flow.
+
 ## Key Tasks
 
 1. **Create Helper Utilities**: Build simple helpers for session keys and JWT storage.
@@ -52,6 +54,7 @@ npm install @erc7824/nitrolite
 ### 2. Create Helper Utilities
 
 Create `src/lib/utils.ts` with session key generation and JWT helpers:
+TODO: explain what is a session key and why we need it. Or leave url to the docs.
 
 ```typescript
 // filepath: src/lib/utils.ts
@@ -287,6 +290,7 @@ useEffect(() => {
             webSocketService.send(payload);
         });
     }
+// TODO: too much dependencies, it might cause message spam (e.g. when session key and account become true at the same time)
 }, [account, sessionKey, wsStatus, isAuthenticated, isAuthAttempted]);
 ```
 
@@ -305,6 +309,7 @@ useEffect(() => {
             response.method === RPCMethod.AuthChallenge &&
             walletClient &&
             sessionKey &&
+            // TODO: account is not needed here
             account &&
             sessionExpireTimestamp
         ) {
@@ -347,6 +352,7 @@ useEffect(() => {
 
     webSocketService.addMessageListener(handleMessage);
     return () => webSocketService.removeMessageListener(handleMessage);
+    // Again, too many dependencies might cause unpredictable behavior, consider adding message listener only once on mount (perhaps use ref)
 }, [walletClient, sessionKey, sessionExpireTimestamp, account]);
 ```