From 9608fe9df367095ec559915774f72b8b3d16f7a4 Mon Sep 17 00:00:00 2001
From: Muhammad Zayyad Mukhtar
 <95658387+El-swaggerito@users.noreply.github.com>
Date: Wed, 29 Apr 2026 11:45:51 +0100
Subject: [PATCH 1/2] refactor: enhance code documentation and component
 consistency

- Add comprehensive JSDoc comments to all major components and utilities
- Improve UI component variants and accessibility attributes
- Standardize error handling and logging across API routes
- Enhance type safety in Stellar integration modules
- Update formatting utilities with additional helper functions
---
 src/app/api/pnl/route.ts                  |  26 ++++-
 src/app/api/upload/route.ts               |  24 +++-
 src/app/page.tsx                          |  68 +++++++++--
 src/components/SwapInterface.tsx          | 110 +++++++++++++-----
 src/components/ui/Button.tsx              |  49 +++++++-
 src/components/ui/NetworkFeeIndicator.tsx |  77 ++++++++++---
 src/lib/format.ts                         |  78 +++++++++----
 src/lib/parser.ts                         |  75 ++++++++-----
 src/lib/stellar.ts                        | 131 ++++++++++++++++------
 src/stores/tokenStore.ts                  |  79 +++++++++++--
 src/stores/useWeb3Store.ts                |  66 +++++++++--
 11 files changed, 617 insertions(+), 166 deletions(-)

diff --git a/src/app/api/pnl/route.ts b/src/app/api/pnl/route.ts
index f57e640..e89b3a7 100644
--- a/src/app/api/pnl/route.ts
+++ b/src/app/api/pnl/route.ts
@@ -1,21 +1,39 @@
+/**
+ * Profit and Loss (PnL) API Route.
+ * Generates synthetic historical performance data for the dashboard charts.
+ * This is used for demonstrating portfolio tracking features.
+ */
+
 import { NextResponse } from 'next/server';
 
+/**
+ * Historical data point for the PnL chart.
+ */
 interface PnLData {
+  /** Localized date string (e.g., "Jan 12") */
   date: string;
+  /** The portfolio value at that specific point in time */
   value: number;
 }
 
+/**
+ * GET handler for the PnL endpoint.
+ * Returns a 30-day series of simulated portfolio values.
+ */
 export async function GET() {
-  // Generate dummy PnL data for the last 30 days
+  // Generate mock PnL data for the last 30 days
   const data: PnLData[] = [];
   const today = new Date();
-  let currentValue = 10000; // Starting value
+  
+  // Starting seed value for the simulation
+  let currentValue = 10000; 
   
   for (let i = 29; i >= 0; i--) {
     const date = new Date(today);
     date.setDate(date.getDate() - i);
     
-    // Random walk with slight upward trend
+    // Simulate a random walk with a slight positive bias (0.45 instead of 0.50)
+    // and a volatility factor of 200
     const change = (Math.random() - 0.45) * 200;
     currentValue += change;
     
@@ -25,5 +43,7 @@ export async function GET() {
     });
   }
 
+  // Return the series as a JSON response
   return NextResponse.json(data);
 }
+
diff --git a/src/app/api/upload/route.ts b/src/app/api/upload/route.ts
index 94c21e9..4380ead 100644
--- a/src/app/api/upload/route.ts
+++ b/src/app/api/upload/route.ts
@@ -1,8 +1,30 @@
+/**
+ * Document Upload API Route.
+ * Handles the secure uploading of invoice documents to IPFS/Pinata.
+ * Currently disabled for maintenance or pending further security implementation.
+ */
+
 import { NextRequest, NextResponse } from 'next/server';
 
+/**
+ * POST handler for the upload endpoint.
+ * Currently returns a 503 Service Unavailable error as the feature is locked.
+ * 
+ * @param {NextRequest} request - The incoming upload request.
+ */
 export async function POST(request: NextRequest) {
+  // 1. Log the attempt for security auditing
+  const clientIp = request.headers.get('x-forwarded-for') || 'unknown';
+  console.log(`[UploadAPI] Blocked upload attempt from ${clientIp}`);
+
+  // 2. Return a consistent error response
   return NextResponse.json(
-    { error: 'Upload temporarily disabled' },
+    { 
+      error: 'Upload service temporarily disabled',
+      reason: 'Undergoing maintenance',
+      retryAfter: 3600 
+    },
     { status: 503 }
   );
 }
+
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 16537de..02b443e 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,3 +1,9 @@
+/**
+ * TradeFlow Main Dashboard Page.
+ * This is the primary entry point for the application, providing users with 
+ * a high-level overview of their assets, protocol status, and the RWA pipeline.
+ */
+
 "use client";
 
 import React, { useState, useEffect } from "react";
@@ -19,63 +25,103 @@ import TabNavigation from "../components/TabNavigation";
 import { useWatchlist } from "../hooks/useWatchlist";
 import StarIcon from "../components/StarIcon";
 
+/**
+ * The root component for the TradeFlow dashboard.
+ * Manages high-level state for wallet connection, active tabs, and invoice data.
+ */
 export default function Page() {
+  // --- Component State ---
+  /** The public Stellar address of the connected user */
   const [address, setAddress] = useState("");
+  /** List of invoices fetched from the backend pipeline */
   const [invoices, setInvoices] = useState([]);
+  /** Loading state for initial data fetch */
   const [loading, setLoading] = useState(false);
+  /** Controls visibility of the Invoice Minting modal */
   const [showMintForm, setShowMintForm] = useState(false);
+  /** Controls visibility of the Wallet Selection modal */
   const [isModalOpen, setIsModalOpen] = useState(false);
+  /** Currently active navigation tab (dashboard or watchlist) */
   const [activeTab, setActiveTab] = useState("dashboard");
+  
+  /** Watchlist management hook */
   const { toggleWatchlist, isInWatchlist } = useWatchlist();
 
-  // 1. Connect Stellar Wallet (supports Freighter, Albedo, xBull)
+  // --- Handlers ---
+
+  /**
+   * Triggers the Stellar wallet connection flow.
+   * Supports multiple providers via the stellar-wallets-kit.
+   * 
+   * @param {WalletType} walletType - The ID of the wallet provider (e.g., Freighter).
+   */
   const handleConnectWallet = async (walletType: WalletType) => {
     try {
       const userInfo = await connectWallet(walletType);
       if (userInfo && userInfo.publicKey) {
         setAddress(userInfo.publicKey);
-        console.log("Wallet connected:", userInfo.publicKey, "Type:", userInfo.walletType);
+        console.log("[Dashboard] Wallet connected:", userInfo.publicKey, "Provider:", userInfo.walletType);
       }
     } catch (e: any) {
-      console.error("Connection failed:", e.message);
+      console.error("[Dashboard] Connection failed:", e.message);
+      // In production, this would be a user-friendly toast notification
       alert(e.message || "Failed to connect to wallet.");
     }
   };
 
-  // 2. Fetch Invoices from your Repo 2 API
+  /**
+   * Fetches the latest verified assets from the RWA pipeline.
+   * Currently points to a local mock API for development.
+   */
   const fetchInvoices = async () => {
     setLoading(true);
     try {
+      // TODO: Replace with environment-aware API base URL
       const res = await fetch("http://localhost:3000/invoices");
       const data = await res.json();
       setInvoices(data);
     } catch (e) {
-      console.error("API not running");
+      console.warn("[Dashboard] Asset pipeline API not reachable. Check if local server is running.");
     } finally {
       setLoading(false);
     }
   };
 
+  // --- Lifecycle Hooks ---
+
   useEffect(() => {
     fetchInvoices();
   }, []);
+
+  /**
+   * Debugging utility for testing transaction status notifications.
+   */
   const handleTestToast = () => {
-    useTransactionToast().loading();
-    useTransactionToast().success();
-    useTransactionToast().error();
+    const toast = useTransactionToast();
+    toast.loading();
+    setTimeout(() => toast.success(), 2000);
   };
 
+  /**
+   * Callback triggered when a new invoice is successfully submitted for minting.
+   * 
+   * @param {any} data - The validated invoice metadata.
+   */
   const handleInvoiceMint = (data: any) => {
-    console.log("Invoice data received:", data);
+    console.log("[Dashboard] Mint request received:", data);
     setShowMintForm(false);
-    // TODO: Chain integration will be handled separately
+    // TODO: Initiate Soroban contract call for minting the NFT
   };
 
+  // --- Configuration ---
+
+  /** Tab definitions for the main navigation */
   const tabs = [
     { id: "dashboard", label: "Dashboard" },
-    { id: "watchlist", label: "Watchlist", icon: <Star size={16} /> },
+    { id: "watchlist", label: "Watchlist", icon: <Star size={16} aria-hidden="true" /> },
   ];
 
+
   return (
     <div className="min-h-screen bg-tradeflow-dark text-white font-sans flex flex-col">
       {/* News Banner */}
diff --git a/src/components/SwapInterface.tsx b/src/components/SwapInterface.tsx
index dd1dc35..5262131 100644
--- a/src/components/SwapInterface.tsx
+++ b/src/components/SwapInterface.tsx
@@ -1,3 +1,10 @@
+/**
+ * Swap Interface Component.
+ * Provides a decentralized exchange (DEX) style interface for swapping 
+ * Stellar assets. Includes slippage control, price impact estimation, 
+ * and transaction status monitoring.
+ */
+
 "use client";
 
 import React, { useState, useEffect } from "react";
@@ -17,27 +24,44 @@ import LivePriceChart from "./LivePriceChart";
 /* ISSUE #87: Import the new Success/Share modal */
 import TradeSuccessModal from "./TradeSuccessModal";
 
+/**
+ * Main component for the token swap functionality.
+ */
 export default function SwapInterface() {
+  // --- Token Selection State ---
+  /** The asset code of the token being sold */
   const [fromToken, setFromToken] = useState("XLM");
+  /** The asset code of the token being bought */
   const [toToken, setToToken] = useState("USDC");
+  
+  // --- UI Visibility State ---
   const [isSettingsOpen, setIsSettingsOpen] = useState(false);
   const [isHighSlippageWarningOpen, setIsHighSlippageWarningOpen] = useState(false);
-  const [fromAmount, setFromAmount] = useState("");
-  const [toAmount, setToAmount] = useState("");
-  const [priceImpact, setPriceImpact] = useState(0);
-  const [isSubmitting, setIsSubmitting] = useState(false);
   const [isTradeReviewOpen, setIsTradeReviewOpen] = useState(false);
   const [isTransactionSignatureOpen, setIsTransactionSignatureOpen] = useState(false);
-
-  /* ISSUE #87: State to manage the visibility of the growth/share modal */
+  /** Visibility for the post-trade growth/share modal */
   const [isSuccessModalOpen, setIsSuccessModalOpen] = useState(false);
 
+  // --- Trade Value State ---
+  const [fromAmount, setFromAmount] = useState("");
+  const [toAmount, setToAmount] = useState("");
+  /** Estimated price impact as a percentage */
+  const [priceImpact, setPriceImpact] = useState(0);
+  /** Mock balance for the selected source token */
+  const [fromBalance] = useState("1240.50");
+
+  // --- Submission & Timing State ---
+  const [isSubmitting, setIsSubmitting] = useState(false);
   const [submissionStartTime, setSubmissionStartTime] = useState<number | null>(null);
   const [timeLeft, setTimeLeft] = useState<string>("");
-  const [fromBalance] = useState("1240.50");
+
+  // --- Context Hooks ---
   const { slippageTolerance, transactionDeadline } = useSlippage();
 
-  // Countdown timer effect
+  /**
+   * Countdown timer effect for transaction expiry.
+   * Runs when a transaction is pending submission.
+   */
   useEffect(() => {
     let interval: any;
     if (isSubmitting && submissionStartTime) {
@@ -64,7 +88,9 @@ export default function SwapInterface() {
     return () => clearInterval(interval);
   }, [isSubmitting, submissionStartTime, transactionDeadline]);
 
-  // Load saved token selections on mount
+  /**
+   * Persists token selections across page reloads.
+   */
   useEffect(() => {
     const savedFromToken = localStorage.getItem('tradeflow-fromToken');
     const savedToToken = localStorage.getItem('tradeflow-toToken');
@@ -73,7 +99,6 @@ export default function SwapInterface() {
     if (savedToToken) setToToken(savedToToken);
   }, []);
 
-  // Save token selections to localStorage
   useEffect(() => {
     localStorage.setItem('tradeflow-fromToken', fromToken);
   }, [fromToken]);
@@ -82,7 +107,13 @@ export default function SwapInterface() {
     localStorage.setItem('tradeflow-toToken', toToken);
   }, [toToken]);
 
-  // Calculate price impact
+  /**
+   * Estimates the price impact based on the input amount.
+   * This is a simplified mock for development purposes.
+   * 
+   * @param {string} amount - The numeric amount string.
+   * @returns {number} The calculated percentage impact.
+   */
   const calculatePriceImpact = (amount: string) => {
     if (!amount || parseFloat(amount) <= 0) return 0;
     const baseImpact = Math.min(parseFloat(amount) * 0.01, 15);
@@ -90,6 +121,9 @@ export default function SwapInterface() {
     return baseImpact * tokenMultiplier;
   };
 
+  /**
+   * Swaps the 'from' and 'to' tokens and their amounts.
+   */
   const handleSwap = () => {
     const temp = fromToken;
     setFromToken(toToken);
@@ -98,12 +132,18 @@ export default function SwapInterface() {
     setToAmount(fromAmount);
   };
 
+  /**
+   * Updates the source amount and recalculates the destination amount and price impact.
+   * 
+   * @param {string} value - The new input amount.
+   */
   const handleFromAmountChange = (value: string) => {
     setFromAmount(value);
     const impact = calculatePriceImpact(value);
     setPriceImpact(impact);
 
     if (value && parseFloat(value) > 0) {
+      // Mock exchange rate logic
       const mockRate = fromToken === "XLM" ? 0.15 : 6.67;
       setToAmount((parseFloat(value) * mockRate * (1 - impact / 100)).toFixed(6));
     } else {
@@ -111,59 +151,67 @@ export default function SwapInterface() {
     }
   };
 
+  /**
+   * Initiates the swap flow, validating inputs and checking for high slippage.
+   */
   const handleSwapClick = async () => {
     if (!fromAmount || parseFloat(fromAmount) <= 0) {
       toast.error("Please enter an amount to swap");
       return;
     }
 
-    const loadingToast = toast.loading("Processing swap...");
+    const loadingToast = toast.loading("Processing swap calculation...");
 
     try {
+      // Threshold check for high slippage warning
       if (priceImpact > 5) {
         setIsHighSlippageWarningOpen(true);
         toast.dismiss(loadingToast);
         return;
       }
 
-      await new Promise((resolve) => setTimeout(resolve, 1800));
+      // Simulate network delay
+      await new Promise((resolve) => setTimeout(resolve, 1500));
 
-      toast.success(`Swapped ${fromAmount} ${fromToken} → ${toAmount} ${toToken}`, {
+      toast.success(`Trade calculated: ${fromAmount} ${fromToken} → ${toAmount} ${toToken}`, {
         id: loadingToast,
       });
 
-      if (priceImpact > 5) {
-        setIsHighSlippageWarningOpen(true);
-      } else {
-        setIsTradeReviewOpen(true);
-      }
+      setIsTradeReviewOpen(true);
     } catch (error) {
-      toast.error("Failed to process swap", {
+      toast.error("Failed to calculate trade parameters", {
         id: loadingToast,
       });
     }
   };
 
+  /**
+   * Confirms the trade and prepares the transaction for signing.
+   */
   const handleTradeConfirm = async () => {
     setIsTradeReviewOpen(false);
     setIsSubmitting(true);
     setSubmissionStartTime(Date.now());
 
     try {
+      // Simulate transaction building time
       await new Promise(resolve => setTimeout(resolve, 2000));
 
-      // Generate mock transaction XDR
+      // Mock transaction XDR for demonstration
       const mockTransactionXDR = "AAAAAK/eFzA7Jf5Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3Xf3XAAAABQAAAAAAAAAAA==";
-      console.log("Mock XDR generated:", mockTransactionXDR);
+      console.log("[SwapInterface] Mock XDR generated:", mockTransactionXDR);
 
       setIsTransactionSignatureOpen(true);
     } catch (error) {
-      toast.error("Failed to submit trade");
+      toast.error("Failed to prepare transaction");
       setIsSubmitting(false);
       setSubmissionStartTime(null);
     }
   };
 
+  /**
+   * Handles confirmation from the high slippage warning modal.
+   */
   const handleHighSlippageConfirm = async () => {
     const loadingToast = toast.loading("Processing high slippage swap...");
 
@@ -180,21 +228,26 @@ export default function SwapInterface() {
     }
   };
 
-  /* ISSUE #87: Trigger the success modal when the transaction is signed */
+  /**
+   * Callback for when the user successfully signs the transaction.
+   * 
+   * @param {string} signedXDR - The base64 signed transaction XDR.
+   */
   const handleTransactionSuccess = (signedXDR: string) => {
-    console.log("Transaction signed:", signedXDR);
+    console.log("[SwapInterface] Transaction signed:", signedXDR);
 
-    toast.success("Transaction signed successfully!", {
-      icon: "✅",
+    toast.success("Trade executed successfully!", {
+      icon: "🚀",
     });
 
     setIsTransactionSignatureOpen(false);
     setIsSubmitting(false);
     setSubmissionStartTime(null);
 
-    // Show the Growth/Share modal
+    // Show the post-trade share/growth modal
     setIsSuccessModalOpen(true);
 
+    // Reset form after a short delay
     setTimeout(() => {
       setFromAmount("");
       setToAmount("");
@@ -202,6 +255,7 @@ export default function SwapInterface() {
     }, 1500);
   };
 
+
   const isAnyModalOpen = isSettingsOpen || isHighSlippageWarningOpen || isTradeReviewOpen || isSuccessModalOpen;
   const isSwapValid = fromAmount && parseFloat(fromAmount) > 0 && !isSubmitting;
 
diff --git a/src/components/ui/Button.tsx b/src/components/ui/Button.tsx
index 1166783..1703458 100644
--- a/src/components/ui/Button.tsx
+++ b/src/components/ui/Button.tsx
@@ -1,32 +1,69 @@
+/**
+ * Shared Button component for the TradeFlow UI.
+ * Provides consistent styling, variants, and built-in accessibility.
+ */
+
 import React from "react";
 
+/**
+ * Props for the Button component.
+ * Extends standard HTML button attributes for full compatibility.
+ */
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** The content to be displayed inside the button */
   children: React.ReactNode;
-  variant?: "primary" | "secondary";
+  /** Visual style variant of the button */
+  variant?: "primary" | "secondary" | "outline" | "ghost";
+  /** Additional CSS classes for custom styling */
   className?: string;
+  /** Optional loading state to disable button and show feedback */
+  isLoading?: boolean;
 }
 
+/**
+ * A versatile button component that supports different visual styles and states.
+ */
 export default function Button({
   children,
   variant = "primary",
   className = "",
+  isLoading = false,
+  disabled,
   ...props
 }: ButtonProps) {
-  const baseStyles = "font-medium rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-offset-slate-800";
+  // Core styling for all button types
+  const baseStyles = "px-4 py-2 font-medium rounded-lg transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-offset-tradeflow-dark disabled:opacity-50 disabled:cursor-not-allowed active:scale-[0.98]";
 
+  // Style definitions for each variant
   const variantStyles = {
-    primary: "bg-blue-600 hover:bg-blue-700 text-white focus:ring-blue-500",
-    secondary: "bg-slate-700 hover:bg-slate-600 text-white focus:ring-slate-500"
+    primary: "bg-tradeflow-accent hover:bg-tradeflow-accent/90 text-white focus:ring-tradeflow-accent",
+    secondary: "bg-slate-700 hover:bg-slate-600 text-white focus:ring-slate-500",
+    outline: "border-2 border-tradeflow-muted hover:border-tradeflow-accent hover:text-tradeflow-accent text-white",
+    ghost: "hover:bg-white/5 text-tradeflow-muted hover:text-white"
   };
 
-  const combinedClassName = `${baseStyles} ${variantStyles[variant]} ${className}`;
+  // Merge all styles into a single string
+  const combinedClassName = `${baseStyles} ${variantStyles[variant as keyof typeof variantStyles]} ${className}`;
 
   return (
     <button
       className={combinedClassName}
+      disabled={disabled || isLoading}
+      // ARIA attributes for accessibility
+      aria-busy={isLoading}
+      aria-live="polite"
       {...props}
     >
-      {children}
+      {isLoading ? (
+        <span className="flex items-center justify-center gap-2">
+          <svg className="animate-spin h-4 w-4 text-current" viewBox="0 0 24 24">
+            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
+            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+          </svg>
+          Loading...
+        </span>
+      ) : children}
     </button>
   );
 }
+
diff --git a/src/components/ui/NetworkFeeIndicator.tsx b/src/components/ui/NetworkFeeIndicator.tsx
index f0cc80c..ccbec33 100644
--- a/src/components/ui/NetworkFeeIndicator.tsx
+++ b/src/components/ui/NetworkFeeIndicator.tsx
@@ -1,21 +1,40 @@
+/**
+ * Network Fee Indicator Component.
+ * Fetches and displays the current Stellar network base fee (in stroops) 
+ * with visual cues for congestion levels.
+ */
+
 "use client";
 
 import React, { useState, useEffect } from 'react';
 import { Fuel } from 'lucide-react';
 
+/**
+ * Data structure for the network fee API response.
+ */
 interface FeeData {
+  /** The base fee in stroops (1 XLM = 10,000,000 stroops) */
   baseFee: number;
+  /** ISO timestamp of when the fee was last calculated */
   lastUpdated: string;
 }
 
+/**
+ * A component that monitors and displays real-time Stellar network fees.
+ * It polls the internal API every 15 seconds to stay up-to-date.
+ */
 export default function NetworkFeeIndicator() {
   const [feeData, setFeeData] = useState<FeeData | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
+  /**
+   * Fetches the latest network fee data from the internal API.
+   */
   const fetchNetworkFee = async () => {
     try {
       setError(null);
+      // Fetch from the Next.js API route
       const res = await fetch('/api/v1/network/fees');
 
       if (!res.ok) {
@@ -33,61 +52,89 @@ export default function NetworkFeeIndicator() {
   };
 
   useEffect(() => {
+    // Initial fetch on mount
     fetchNetworkFee();
 
-    // Poll every 15 seconds
+    // Setup periodic polling (15 seconds is standard for network changes)
     const interval = setInterval(fetchNetworkFee, 15000);
 
+    // Cleanup interval on component unmount
     return () => clearInterval(interval);
   }, []);
 
-  // Determine color based on fee level (in stroops)
+  /**
+   * Returns a Tailwind color class based on the fee level.
+   * 
+   * @param {number} baseFee - The fee in stroops.
+   * @returns {string} The CSS class for the text color.
+   */
   const getFeeColor = (baseFee: number) => {
-    if (baseFee < 150) return 'text-green-400';      // Cheap
-    if (baseFee < 300) return 'text-yellow-400';     // Moderate
-    return 'text-red-500';                           // Expensive
+    if (baseFee < 150) return 'text-emerald-400';      // Cheap/Low congestion
+    if (baseFee < 300) return 'text-yellow-400';       // Moderate congestion
+    return 'text-red-500';                             // High congestion
   };
 
+  /**
+   * Returns a human-readable label for the congestion level.
+   * 
+   * @param {number} baseFee - The fee in stroops.
+   * @returns {string} The status label.
+   */
   const getFeeLabel = (baseFee: number) => {
-    if (baseFee < 150) return 'Cheap';
+    if (baseFee < 150) return 'Optimized';
     if (baseFee < 300) return 'Moderate';
-    return 'Expensive';
+    return 'Congested';
   };
 
+  // 1. Loading State UI
   if (loading && !feeData) {
     return (
-      <div className="flex items-center gap-1.5 text-xs text-slate-400">
+      <div 
+        className="flex items-center gap-1.5 text-xs text-slate-400"
+        aria-label="Loading network fee"
+      >
         <Fuel size={16} />
         <span>Loading fee...</span>
       </div>
     );
   }
 
+  // 2. Error/Fallback State UI
   if (error || !feeData) {
     return (
-      <div className="flex items-center gap-1.5 text-xs text-red-400">
+      <div 
+        className="flex items-center gap-1.5 text-xs text-red-400/80"
+        role="alert"
+      >
         <Fuel size={16} />
         <span>Fee unavailable</span>
       </div>
     );
   }
 
+  // 3. Main Data Display
   return (
-    <div className="flex items-center gap-1.5 px-3 py-1.5 rounded-full bg-slate-800/50 border border-slate-700 hover:border-slate-600 transition-colors group">
+    <div 
+      className="flex items-center gap-1.5 px-3 py-1.5 rounded-full bg-slate-800/40 border border-slate-700 hover:border-slate-600 transition-all group cursor-default"
+      title={`Current network fee: ${feeData.baseFee} stroops`}
+    >
       <Fuel 
         size={16} 
-        className={`transition-colors ${getFeeColor(feeData.baseFee)}`} 
+        className={`transition-colors duration-300 ${getFeeColor(feeData.baseFee)}`} 
+        aria-hidden="true"
       />
       <div className="flex items-baseline gap-1">
-        <span className={`font-mono text-sm font-medium transition-colors ${getFeeColor(feeData.baseFee)}`}>
+        <span 
+          className={`font-mono text-sm font-semibold transition-colors duration-300 ${getFeeColor(feeData.baseFee)}`}
+        >
           {feeData.baseFee}
         </span>
-        <span className="text-[10px] text-slate-500">stroops</span>
+        <span className="text-[10px] text-slate-500 font-medium">stroops</span>
       </div>
       
-      <div className="text-[10px] text-slate-500 hidden group-hover:inline">
+      <div className="text-[10px] text-slate-500 hidden group-hover:inline-block ml-1 border-l border-slate-700 pl-2 transition-all">
         {getFeeLabel(feeData.baseFee)}
       </div>
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/src/lib/format.ts b/src/lib/format.ts
index 99f104a..a01b1f9 100644
--- a/src/lib/format.ts
+++ b/src/lib/format.ts
@@ -1,18 +1,28 @@
 /**
- * Format currency values from blockchain (USDC with 7 decimals)
- * @param amount - Raw amount from blockchain (e.g., 10000000 for 1 USDC)
- * @returns Formatted USD string (e.g., "$1.00")
+ * Data formatting utilities for the TradeFlow application.
+ * Provides consistent formatting for currency, dates, addresses, and percentages.
+ */
+
+/**
+ * Formats raw blockchain currency values into a human-readable USD string.
+ * Specifically handles Stellar/Soroban assets with 7 decimal places (standard for USDC).
+ * 
+ * @param {number | string} amount - The raw amount from the blockchain (e.g., 10,000,000 for 1.00 USDC).
+ * @returns {string} A localized currency string (e.g., "$1.00").
  */
 export const formatCurrency = (amount: number | string): string => {
+  // 1. Convert string input to number if necessary
   const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
   
   if (isNaN(numAmount)) {
     return '$0.00';
   }
   
-  // USDC has 7 decimals, so divide by 10^7
+  // 2. Stellar assets like USDC typically use 7 decimal places
+  // We divide by 10^7 to get the actual unit value
   const usdcAmount = numAmount / 10000000;
   
+  // 3. Format using standard US locale settings
   return new Intl.NumberFormat('en-US', {
     style: 'currency',
     currency: 'USD',
@@ -22,28 +32,52 @@ export const formatCurrency = (amount: number | string): string => {
 };
 
 /**
- * Format Unix timestamp to human-readable date
- * @param timestamp - Unix timestamp (seconds or milliseconds)
- * @returns Formatted date string (e.g., "Oct 24, 2024")
+ * Formats a generic token amount with a specified number of decimals.
+ * 
+ * @param {number | string} amount - The raw token amount.
+ * @param {number} [decimals=7] - Number of decimal places for the asset.
+ * @returns {string} The formatted number string.
+ */
+export const formatTokenAmount = (amount: number | string, decimals: number = 7): string => {
+  const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
+  if (isNaN(numAmount)) return "0";
+  
+  const value = numAmount / Math.pow(10, decimals);
+  return value.toLocaleString('en-US', {
+    minimumFractionDigits: 0,
+    maximumFractionDigits: decimals,
+  });
+};
+
+/**
+ * Formats a Unix timestamp into a human-readable date string.
+ * Supports both seconds (10 digits) and milliseconds (13 digits) formats.
+ * 
+ * @param {number | string} timestamp - The Unix timestamp to format.
+ * @returns {string} Formatted date (e.g., "Oct 24, 2024") or "Invalid Date".
  */
 export const formatDate = (timestamp: number | string): string => {
+  // 1. Ensure we have a numeric value
   const numTimestamp = typeof timestamp === 'string' ? parseInt(timestamp) : timestamp;
   
   if (isNaN(numTimestamp)) {
     return 'Invalid Date';
   }
   
-  // Handle both seconds and milliseconds timestamps
+  // 2. Detect format based on digit count
+  // Unix seconds = 10 digits, Milliseconds = 13 digits
   const date = new Date(
     numTimestamp.toString().length === 10 
       ? numTimestamp * 1000  // Convert seconds to milliseconds
       : numTimestamp          // Already in milliseconds
   );
   
+  // 3. Check for invalid date objects
   if (isNaN(date.getTime())) {
     return 'Invalid Date';
   }
   
+  // 4. Localized short date format
   return date.toLocaleDateString('en-US', {
     month: 'short',
     day: 'numeric',
@@ -52,9 +86,11 @@ export const formatDate = (timestamp: number | string): string => {
 };
 
 /**
- * Format full date with time
- * @param timestamp - Unix timestamp (seconds or milliseconds)
- * @returns Formatted date-time string (e.g., "Oct 24, 2024, 2:30 PM")
+ * Formats a Unix timestamp into a detailed date and time string.
+ * Useful for transaction history or specific event logging.
+ * 
+ * @param {number | string} timestamp - The Unix timestamp to format.
+ * @returns {string} Formatted date-time (e.g., "Oct 24, 2024, 2:30 PM").
  */
 export const formatDateTime = (timestamp: number | string): string => {
   const numTimestamp = typeof timestamp === 'string' ? parseInt(timestamp) : timestamp;
@@ -84,12 +120,14 @@ export const formatDateTime = (timestamp: number | string): string => {
 };
 
 /**
- * Format wallet address for display
- * @param address - Full wallet address
- * @returns Shortened address (e.g., "0x1234...5678")
+ * Shortens a Stellar or Ethereum wallet address for UI display.
+ * Shows the first 6 and last 4 characters by default.
+ * 
+ * @param {string} address - The full wallet address string.
+ * @returns {string} The truncated address (e.g., "GBBD67...OC6S").
  */
 export const formatAddress = (address: string): string => {
-  if (!address || address.length < 8) {
+  if (!address || address.length < 12) {
     return address;
   }
   
@@ -97,10 +135,11 @@ export const formatAddress = (address: string): string => {
 };
 
 /**
- * Format percentage with proper decimal places
- * @param value - Percentage value (0-100)
- * @param decimals - Number of decimal places (default: 1)
- * @returns Formatted percentage string
+ * Formats a numeric value as a percentage string.
+ * 
+ * @param {number | string} value - The raw percentage value (e.g., 5.5 for 5.5%).
+ * @param {number} [decimals=1] - Precision of the output.
+ * @returns {string} Formatted percentage (e.g., "5.5%").
  */
 export const formatPercentage = (value: number | string, decimals: number = 1): string => {
   const numValue = typeof value === 'string' ? parseFloat(value) : value;
@@ -111,3 +150,4 @@ export const formatPercentage = (value: number | string, decimals: number = 1):
   
   return `${numValue.toFixed(decimals)}%`;
 };
+
diff --git a/src/lib/parser.ts b/src/lib/parser.ts
index a1b667e..ae53af0 100644
--- a/src/lib/parser.ts
+++ b/src/lib/parser.ts
@@ -1,47 +1,53 @@
+/**
+ * XDR Parsing and Serialization Utilities.
+ * Handles conversion between Stellar's External Data Representation (XDR) 
+ * and native JavaScript objects for the TradeFlow smart contracts.
+ */
+
 import { xdr, scValToNative } from "soroban-client";
 
+/**
+ * Structured data representation of a TradeFlow Invoice.
+ */
 export interface Invoice {
+  /** Unique numeric identifier for the invoice */
   id: number;
+  /** Public Stellar address of the invoice owner/creator */
   owner: string;
+  /** The total amount of the invoice (raw units) */
   amount: number;
 }
 
 /**
- * Parses a Base64-encoded XDR string returned by a Soroban smart contract call (e.g., get_invoice)
- * and converts it into a structured Invoice object.
+ * Parses a Base64-encoded XDR string returned by a Soroban smart contract call 
+ * (specifically the 'get_invoice' method) and converts it into a structured Invoice object.
  *
- * @param xdrBase64 - The Base64-encoded XDR string.
- * @returns The parsed Invoice object.
- * @throws Error if the XDR is invalid or the data structure does not match the expected Invoice schema.
+ * @param {string} xdrBase64 - The Base64-encoded ScVal XDR string from the network.
+ * @returns {Invoice} The parsed and validated Invoice object.
+ * @throws {Error} If the XDR is malformed or the data structure is invalid.
  */
 export function parseInvoiceFromXdr(xdrBase64: string): Invoice {
+  // 1. Basic validation of input string
   if (!xdrBase64 || typeof xdrBase64 !== 'string') {
     throw new Error("Invalid input: xdrBase64 must be a non-empty string.");
   }
 
   try {
-    // 1. Decode the XDR string to an ScVal
-    // Note: We use 'base64' encoding as standard for Soroban return values
+    // 2. Decode the XDR string to a Soroban ScVal (Smart Contract Value)
     const value = xdr.ScVal.fromXDR(xdrBase64, 'base64');
 
-    // 2. Convert ScVal to a native JavaScript object
-    // scValToNative handles BigInt conversion automatically (returns bigint for u64/i64/u128/i128)
+    // 3. Convert ScVal to a native JavaScript object
+    // scValToNative handles basic types and recursively converts complex types (Maps, Structs, Vecs)
     const nativeValue = scValToNative(value);
 
     if (!nativeValue || typeof nativeValue !== 'object') {
       throw new Error(`Parsed XDR result is not an object or Map. Got: ${typeof nativeValue}`);
     }
 
-    // 3. Normalize the native value to a plain object (handle Map vs Object)
+    // 4. Normalize the native value (handle different SDK return formats)
     let invoiceData: Record<string, any> = {};
 
-    // Check if it's a Map (common in newer SDKs for ScMap)
-    // We check for .get method to be safe, or just check instanceof Map if environment supports it
-    // But usually scValToNative returns plain objects for Structs in some versions, or objects with properties.
-    // However, if it returns an array of entries or a Map, we need to handle it.
-    // Let's assume it returns an object with keys matching struct fields.
-    // If it is a Map, we convert it.
-    /* eslint-disable @typescript-eslint/no-explicit-any */
+    // In some SDK versions, ScMap/Struct returns a native Map
     if (nativeValue instanceof Map) {
          nativeValue.forEach((val: any, key: any) => {
              invoiceData[String(key)] = val;
@@ -50,26 +56,28 @@ export function parseInvoiceFromXdr(xdrBase64: string): Invoice {
          invoiceData = nativeValue as Record<string, any>;
     }
 
-    // 4. Validate and transform into strictly-typed Invoice
+    // 5. Transform and strictly validate fields
     const result: Invoice = {
       id: 0,
       owner: '',
       amount: 0
     };
 
-    // Helper to safely convert to Number
+    /**
+     * Safely converts various numeric types (number, bigint, string) to a standard number.
+     */
     const safelyConvertToNumber = (val: any, fieldName: string): number => {
       if (typeof val === 'number') {
         return val;
       }
       if (typeof val === 'bigint') {
+        // Log warning if bigint exceeds JavaScript's safe integer range
         if (val > BigInt(Number.MAX_SAFE_INTEGER) || val < BigInt(Number.MIN_SAFE_INTEGER)) {
-           console.warn(`[TradeFlow] Warning: Value for '${fieldName}' (${val}) exceeds Number.MAX_SAFE_INTEGER. Precision lost.`);
+           console.warn(`[TradeFlow] Precision warning: Value for '${fieldName}' (${val}) exceeds Number.MAX_SAFE_INTEGER.`);
         }
         return Number(val);
       }
       if (typeof val === 'string') {
-        // Try parsing string to number
         const num = Number(val);
         if (isNaN(num)) {
              throw new Error(`Invalid number format for field '${fieldName}': ${val}`);
@@ -79,23 +87,26 @@ export function parseInvoiceFromXdr(xdrBase64: string): Invoice {
       throw new Error(`Invalid type for field '${fieldName}': expected number or bigint, got ${typeof val}`);
     };
 
-    // Helper to safely convert to String
+    /**
+     * Ensures a value is treated as a string, handling Address objects if necessary.
+     */
     const safelyConvertToString = (val: any, fieldName: string): string => {
         if (typeof val === 'string') {
             return val;
         }
-        // Handle Address object if scValToNative returns an Address class
+        // Soroban Address types might return an object with a toString() method
         if (val && typeof val.toString === 'function') {
             return val.toString();
         }
         throw new Error(`Invalid type for field '${fieldName}': expected string, got ${typeof val}`);
     };
 
-    // Validate fields
+    // Verify presence of all required struct fields
     if (!('id' in invoiceData)) throw new Error("Missing required field: 'id'");
     if (!('owner' in invoiceData)) throw new Error("Missing required field: 'owner'");
     if (!('amount' in invoiceData)) throw new Error("Missing required field: 'amount'");
 
+    // Perform final assignments with type safety
     result.id = safelyConvertToNumber(invoiceData.id, 'id');
     result.owner = safelyConvertToString(invoiceData.owner, 'owner');
     result.amount = safelyConvertToNumber(invoiceData.amount, 'amount');
@@ -103,18 +114,21 @@ export function parseInvoiceFromXdr(xdrBase64: string): Invoice {
     return result;
 
   } catch (error: any) {
-    // Wrap error with context
-    // Check if it's our own error or from library
-    if (error.message && error.message.startsWith('Invalid input')) throw error;
-    if (error.message && error.message.startsWith('Missing required')) throw error;
+    // Propagate validation errors directly, wrap others with context
+    if (error.message && (error.message.startsWith('Invalid input') || error.message.startsWith('Missing required'))) {
+      throw error;
+    }
     
     throw new Error(`Failed to parse Invoice from XDR: ${error.message}`);
   }
 }
 
 /**
- * Helper to safely stringify objects containing BigInts for logging or API responses.
- * JSON.stringify throws on BigInt by default.
+ * A safe alternative to JSON.stringify that handles BigInt values.
+ * BigInt is commonly used in Stellar SDKs for large numeric values.
+ * 
+ * @param {any} obj - The object to stringify.
+ * @returns {string} The JSON string representation.
  */
 export function safeJsonStringify(obj: any): string {
   return JSON.stringify(obj, (key, value) =>
@@ -123,3 +137,4 @@ export function safeJsonStringify(obj: any): string {
       : value
   );
 }
+
diff --git a/src/lib/stellar.ts b/src/lib/stellar.ts
index 96d3717..738c338 100644
--- a/src/lib/stellar.ts
+++ b/src/lib/stellar.ts
@@ -1,3 +1,8 @@
+/**
+ * Stellar integration utilities for TradeFlow.
+ * This module handles wallet connections, transaction building, and network interactions.
+ */
+
 import { 
   walletKit,
   FREIGHTER_ID,
@@ -13,44 +18,66 @@ import {
   Networks 
 } from "soroban-client";
 
-// Default to Testnet for development
+/**
+ * The RPC endpoint for the Stellar network.
+ * Currently defaults to the public Soroban Testnet.
+ */
 const RPC_URL = "https://soroban-testnet.stellar.org";
+
+/**
+ * Internal server instance for interacting with the Stellar network.
+ */
 const server = new Server(RPC_URL);
 
+/**
+ * The network passphrase used for transaction signing.
+ * Must match the network the transaction is being submitted to.
+ */
 const NETWORK_PASSPHRASE = Networks.TESTNET;
 
-// Initialize wallet kit
+/**
+ * Initialize the wallet kit with a default wallet (Freighter).
+ */
 walletKit.setWallet(FREIGHTER_ID);
 
+/**
+ * Represents the information returned after a successful wallet connection.
+ */
 export interface WalletInfo {
+  /** The public G-address of the connected Stellar account */
   publicKey: string;
+  /** The type of wallet used for connection (e.g., freighter, xbull) */
   walletType: WalletType;
 }
 
 /**
  * Connects to a Stellar wallet using the wallet kit.
- * Supports Freighter, Albedo, and xBull wallets.
+ * Supports multiple providers including Freighter, Albedo, and xBull.
+ * 
+ * @param {WalletType} walletType - The ID of the wallet provider to use.
+ * @returns {Promise<WalletInfo>} A promise that resolves to the wallet information.
+ * @throws {Error} If the wallet is not installed or the wrong network is selected.
  */
 export async function connectWallet(walletType: WalletType = FREIGHTER_ID): Promise<WalletInfo> {
   try {
-    // Set the wallet type
+    // 1. Configure the kit to use the requested wallet provider
     walletKit.setWallet(walletType);
     
-    // Check if wallet is available
+    // 2. Ensure the extension or provider is available in the browser
     const isWalletAvailable = await walletKit.isWalletAvailable();
     if (!isWalletAvailable) {
       const walletName = getWalletName(walletType);
       throw new Error(`${walletName} is not available. Please install it to continue.`);
     }
 
-    // Get public key
+    // 3. Request the public key from the user
     const publicKey = await walletKit.getPublicKey();
     
     if (!publicKey) {
       throw new Error("Unable to retrieve public key.");
     }
 
-    // Verify correct network (Testnet)
+    // 4. Validate that the user is on the expected network (Testnet)
     const network = await walletKit.getNetwork();
     if (network !== "TESTNET") {
       const walletName = getWalletName(walletType);
@@ -59,13 +86,16 @@ export async function connectWallet(walletType: WalletType = FREIGHTER_ID): Prom
 
     return { publicKey, walletType };
   } catch (error: any) {
+    // Log error for debugging but propagate to the caller
     console.error("Wallet connection error:", error);
     throw error;
   }
 }
 
 /**
- * Gets the current connected wallet info
+ * Retrieves information about the currently connected wallet if available.
+ * 
+ * @returns {Promise<WalletInfo | null>} The wallet info or null if disconnected.
  */
 export async function getConnectedWallet(): Promise<WalletInfo | null> {
   try {
@@ -75,12 +105,15 @@ export async function getConnectedWallet(): Promise<WalletInfo | null> {
     const currentWallet = walletKit.getWallet();
     return { publicKey, walletType: currentWallet };
   } catch (error) {
+    // Silently return null on error as it usually means no wallet is active
     return null;
   }
 }
 
 /**
- * Disconnects the current wallet
+ * Terminates the current wallet session.
+ * 
+ * @returns {Promise<void>}
  */
 export async function disconnectWallet(): Promise<void> {
   try {
@@ -91,7 +124,10 @@ export async function disconnectWallet(): Promise<void> {
 }
 
 /**
- * Gets the display name for a wallet type
+ * Maps internal wallet IDs to human-readable display names.
+ * 
+ * @param {WalletType} walletType - The internal ID of the wallet.
+ * @returns {string} The display name (e.g., "Freighter").
  */
 function getWalletName(walletType: WalletType): string {
   switch (walletType) {
@@ -108,21 +144,22 @@ function getWalletName(walletType: WalletType): string {
 
 /**
  * Monitors the status of a Stellar transaction until it succeeds, fails, or times out.
- * Polls the network every 2 seconds.
+ * This function uses a polling mechanism to check the Horizon server.
  * 
- * @param hash - The transaction hash to monitor
- * @returns Promise that resolves to "SUCCESS" if successful
+ * @param {string} hash - The transaction hash to monitor.
+ * @returns {Promise<string>} Promise that resolves to "SUCCESS" if successful.
+ * @throws {Error} If the transaction fails or the polling times out.
  */
 export async function waitForTransaction(hash: string): Promise<string> {
-  const TIMEOUT_MS = 30000;
-  const POLLING_INTERVAL_MS = 2000;
+  const TIMEOUT_MS = 30000; // 30 seconds timeout
+  const POLLING_INTERVAL_MS = 2000; // Poll every 2 seconds
   const startTime = Date.now();
 
   console.log(`[waitForTransaction] Starting monitoring for transaction: ${hash}`);
 
   while (Date.now() - startTime < TIMEOUT_MS) {
     try {
-      // Attempt to fetch transaction status
+      // Fetch transaction status from the Horizon server
       const tx = await server.getTransaction(hash);
       
       console.log(`[waitForTransaction] Polling ${hash}: Status = ${tx.status}`);
@@ -137,57 +174,61 @@ export async function waitForTransaction(hash: string): Promise<string> {
       
       // If status is NOT_FOUND or other pending states, continue polling
     } catch (error: any) {
-      // Log error but continue polling (common for 404 Not Found initially)
+      // Log warning but continue polling (common for 404 Not Found initially)
       console.warn(`[waitForTransaction] Polling attempt failed (retrying): ${error.message}`);
     }
 
-    // Wait before next poll
+    // Wait before next poll attempt
     await new Promise((resolve) => setTimeout(resolve, POLLING_INTERVAL_MS));
   }
 
-  // Timeout reached
+  // Timeout reached if we exit the loop
   const errorMsg = `Transaction monitoring timed out after ${TIMEOUT_MS / 1000}s for hash: ${hash}`;
   console.error(`[waitForTransaction] ${errorMsg}`);
   throw new Error(errorMsg);
 }
 
 /**
- * Adds a trustline for a Stellar asset (ChangeTrust operation).
- * @param assetCode - Code of the asset (e.g., "USDC")
- * @param assetIssuer - Issuer address of the asset
- * @param walletType - Optional wallet type override
+ * Establishes a trustline for a specific Stellar asset.
+ * This is required before an account can hold or receive a non-native asset.
+ * 
+ * @param {string} assetCode - The code of the asset (e.g., "USDC").
+ * @param {string} assetIssuer - The public G-address of the asset issuer.
+ * @param {WalletType} [walletType] - Optional wallet provider override.
+ * @returns {Promise<string>} The status of the transaction.
  */
 export async function addTrustline(assetCode: string, assetIssuer: string, walletType?: WalletType) {
-  // If walletType is provided, set it temporarily
+  // Update wallet provider if specified
   if (walletType) {
     walletKit.setWallet(walletType);
   }
   
   const publicKey = await walletKit.getPublicKey();
   
-  // Fetch account details to get the current sequence number
+  // 1. Fetch current account state for sequence number
   const account = await server.getAccount(publicKey);
   const asset = new Asset(assetCode, assetIssuer);
   
-  // Construct the transaction
+  // 2. Build the ChangeTrust transaction
   const transaction = new TransactionBuilder(account, {
-    fee: "1000", // Standard fee in stroops
+    fee: "1000", // Fixed fee of 1000 stroops for demo
     networkPassphrase: NETWORK_PASSPHRASE,
   })
     .addOperation(Operation.changeTrust({ asset }))
-    .setTimeout(60)
+    .setTimeout(60) // 60 seconds transaction validity
     .build();
 
-  // Request signature from the current wallet
+  // 3. Request user signature via the selected wallet
   const xdr = transaction.toXDR();
   const signedXdr = await walletKit.signTransaction(xdr, {
     network: "TESTNET",
   });
 
-  // Submit to the network
+  // 4. Submit the signed transaction to the network
   const response = await server.sendTransaction(transaction);
   
   if (response.hash) {
+    // 5. Wait for ledger confirmation
     return await waitForTransaction(response.hash);
   }
   
@@ -195,7 +236,11 @@ export async function addTrustline(assetCode: string, assetIssuer: string, walle
 }
 
 /**
- * Signs a transaction using the currently connected wallet
+ * Signs a raw XDR transaction using the active wallet.
+ * 
+ * @param {string} xdr - The base64 encoded transaction XDR.
+ * @param {any} [options] - Additional signing options.
+ * @returns {Promise<string>} The signed transaction XDR.
  */
 export async function signTransaction(xdr: string, options?: any): Promise<string> {
   return await walletKit.signTransaction(xdr, {
@@ -205,14 +250,18 @@ export async function signTransaction(xdr: string, options?: any): Promise<strin
 }
 
 /**
- * Gets the current network from the connected wallet
+ * Queries the active network configuration from the connected wallet.
+ * 
+ * @returns {Promise<string>} The network identifier (e.g., "TESTNET").
  */
 export async function getNetwork(): Promise<string> {
   return await walletKit.getNetwork();
 }
 
 /**
- * Checks if a wallet is connected
+ * Quick check to see if a wallet is currently active and reachable.
+ * 
+ * @returns {Promise<boolean>} True if a public key can be retrieved.
  */
 export async function isWalletConnected(): Promise<boolean> {
   try {
@@ -223,7 +272,20 @@ export async function isWalletConnected(): Promise<boolean> {
   }
 }
 
-// Export wallet types and kit for use in other modules
+/**
+ * Utility to shorten a Stellar address for UI display.
+ * 
+ * @param {string} address - The full Stellar address.
+ * @param {number} [chars=4] - Number of characters to show at start and end.
+ * @returns {string} The shortened address (e.g., GABC...XYZ).
+ */
+export function shortenAddress(address: string, chars = 4): string {
+  if (!address) return "";
+  if (address.length <= chars * 2) return address;
+  return `${address.substring(0, chars)}...${address.substring(address.length - chars)}`;
+}
+
+// Re-export constants and types for downstream usage
 export { 
   walletKit,
   FREIGHTER_ID, 
@@ -231,3 +293,4 @@ export {
   ALBEDO_ID, 
   WalletType 
 };
+
diff --git a/src/stores/tokenStore.ts b/src/stores/tokenStore.ts
index 2b3f39a..8ab6664 100644
--- a/src/stores/tokenStore.ts
+++ b/src/stores/tokenStore.ts
@@ -1,53 +1,100 @@
+/**
+ * Token Management Store.
+ * Handles tracking of the native TradeFlow (TF) utility token, 
+ * including balances, pro-mode access levels, and connection status.
+ */
+
 import { create } from 'zustand';
 import { Server, Asset } from 'soroban-client';
 
-// TF Token configuration (would be actual token details in production)
+/**
+ * TradeFlow Token (TF) Configuration.
+ * These constants define the utility token used for premium features.
+ */
 const TF_TOKEN_CODE = 'TF';
-const TF_TOKEN_ISSUER = 'GBBHPLX4LBHS5JPC4FBDHD4YDZSZJZG7VQMIY6RDZT6HRJ5QJ5N6KFGH'; // Example issuer
-const PRO_MODE_THRESHOLD = 1000;
+const TF_TOKEN_ISSUER = 'GBBHPLX4LBHS5JPC4FBDHD4YDZSZJZG7VQMIY6RDZT6HRJ5QJ5N6KFGH'; // Example issuer address
+const PRO_MODE_THRESHOLD = 1000; // Minimum TF tokens required for Pro Mode
 
+/**
+ * Representation of a Stellar asset balance.
+ */
 interface TokenBalance {
+  /** The 1-12 character asset code */
   code: string;
+  /** The public address of the asset issuer */
   issuer: string;
+  /** The current balance as a string (to maintain precision) */
   balance: string;
 }
 
+/**
+ * State and actions for the Token Store.
+ */
 interface TokenStore {
+  /** Current balance of TF tokens for the connected user */
   tfTokenBalance: number;
+  /** Whether a wallet is currently connected to the store */
   isConnected: boolean;
+  /** The public address of the connected wallet */
   publicKey: string | null;
+  /** Loading state for asynchronous balance fetching */
   isLoading: boolean;
+  /** Error message if a balance fetch fails */
   error: string | null;
+  
+  /**
+   * Fetches the TF token balance for a specific public key from the network.
+   * @param {string} publicKey - The Stellar address to query.
+   */
   fetchTokenBalance: (publicKey: string) => Promise<void>;
+  
+  /**
+   * Updates the connection status and triggers a balance refresh if connecting.
+   * @param {boolean} connected - The new connection state.
+   * @param {string} [publicKey] - The address of the connecting wallet.
+   */
   setConnected: (connected: boolean, publicKey?: string) => void;
+  
+  /**
+   * Evaluates if the current user has enough TF tokens to access Pro Mode.
+   * @returns {boolean} True if the threshold is met.
+   */
   hasProModeAccess: () => boolean;
 }
 
+/**
+ * Zustand store for managing TradeFlow token state.
+ */
 export const useTokenStore = create<TokenStore>((set, get) => ({
+  // Initial state values
   tfTokenBalance: 0,
   isConnected: false,
   publicKey: null,
   isLoading: false,
   error: null,
 
+  /**
+   * Asynchronously retrieves the TF token balance from the Horizon server.
+   */
   fetchTokenBalance: async (publicKey: string) => {
     set({ isLoading: true, error: null });
     
     try {
-      // In production, this would fetch from Stellar network
-      // For now, we'll simulate with a mock balance
+      // Connect to the Soroban Testnet Horizon server
       const server = new Server('https://soroban-testnet.stellar.org');
       
       try {
+        // 1. Retrieve the account details
         const account = await server.getAccount(publicKey);
         const tfAsset = new Asset(TF_TOKEN_CODE, TF_TOKEN_ISSUER);
         
-        // Look for TF token balance in account balances
+        // 2. Locate the TF token in the account's balances array
         const tfBalance = account.balances.find((balance: any) => 
           balance.asset_code === TF_TOKEN_CODE && 
           balance.asset_issuer === TF_TOKEN_ISSUER
         );
         
+        // 3. Parse and update the balance state
         const balance = tfBalance ? parseFloat(tfBalance.balance) : 0;
         
         set({ 
@@ -55,7 +102,7 @@ export const useTokenStore = create<TokenStore>((set, get) => ({
           isLoading: false 
         });
       } catch (error) {
-        // Account not found or other error - set balance to 0
+        // Fallback: If account is not found or has no trustline, balance is 0
         set({ 
           tfTokenBalance: 0,
           isLoading: false,
@@ -63,15 +110,18 @@ export const useTokenStore = create<TokenStore>((set, get) => ({
         });
       }
     } catch (error) {
-      console.error('Error fetching token balance:', error);
+      console.error('[TokenStore] Critical error fetching balance:', error);
       set({ 
         tfTokenBalance: 0,
         isLoading: false,
-        error: 'Failed to fetch token balance'
+        error: 'Failed to connect to network'
       });
     }
   },
 
+  /**
+   * Updates the global connection state and manages balance refresh.
+   */
   setConnected: (connected: boolean, publicKey?: string) => {
     set({ 
       isConnected: connected,
@@ -79,24 +129,33 @@ export const useTokenStore = create<TokenStore>((set, get) => ({
       error: null
     });
     
+    // Auto-fetch balance on successful connection
     if (connected && publicKey) {
       get().fetchTokenBalance(publicKey);
     } else {
+      // Clear balance on disconnect
       set({ tfTokenBalance: 0 });
     }
   },
 
+  /**
+   * Logic for determining premium access.
+   */
   hasProModeAccess: () => {
     const { tfTokenBalance, isConnected } = get();
     return isConnected && tfTokenBalance >= PRO_MODE_THRESHOLD;
   }
 }));
 
-// Helper constants for components
+/**
+ * Re-export constants for use in UI components.
+ */
 export const PRO_MODE_THRESHOLD_AMOUNT = PRO_MODE_THRESHOLD;
 export const TF_TOKEN_INFO = {
   code: TF_TOKEN_CODE,
   issuer: TF_TOKEN_ISSUER,
   name: 'TradeFlow Token',
+  description: 'Utility token for the TradeFlow ecosystem.',
   symbol: 'TF'
 };
+
diff --git a/src/stores/useWeb3Store.ts b/src/stores/useWeb3Store.ts
index a0162a7..80d871d 100644
--- a/src/stores/useWeb3Store.ts
+++ b/src/stores/useWeb3Store.ts
@@ -1,13 +1,24 @@
+/**
+ * Web3 State Management Store.
+ * Centralizes wallet connection, network status, and account balances
+ * using Zustand for reactive state updates across the application.
+ */
+
 import { create } from 'zustand';
 import { Server, Asset } from 'soroban-client';
 import { walletKit, FREIGHTER_ID, WalletType } from '../lib/stellar';
 
-// Network configuration
+/**
+ * Supported Stellar Networks.
+ */
 export const NETWORKS = {
+  /** Public Stellar Testnet (Used for development and QA) */
   TESTNET: 'Testnet',
+  /** Public Stellar Mainnet (Used for production assets) */
   MAINNET: 'Mainnet'
 } as const;
 
+
 export type NetworkType = typeof NETWORKS[keyof typeof NETWORKS];
 
 // Stellar network endpoints
@@ -16,41 +27,78 @@ const NETWORK_ENDPOINTS = {
   [NETWORKS.MAINNET]: 'https://horizon.stellar.org'
 };
 
+/**
+ * Internal state for the Web3 store.
+ */
 interface Web3State {
-  // Wallet connection state
+  /** The public address of the connected wallet, or null if disconnected */
   walletAddress: string | null;
+  /** The ID of the connected wallet provider (e.g., freighter) */
   walletType: WalletType | null;
+  /** True if a wallet is successfully connected and reachable */
   isConnected: boolean;
+  /** True during the asynchronous wallet connection process */
   isConnecting: boolean;
   
-  // Network state
+  /** The currently selected network (defaults to TESTNET) */
   network: NetworkType;
   
-  // Token balances
+  /** Dictionary of asset balances, keyed by asset code (e.g., { "XLM": 50.5 }) */
   balances: Record<string, number>;
   
-  // Loading and error states
+  /** Global loading state for network-bound operations */
   isLoading: boolean;
+  /** Stores the last encountered error message, if any */
   error: string | null;
 }
 
+
+/**
+ * Available actions for interacting with the Web3 store.
+ */
 interface Web3Actions {
-  // Wallet actions
+  /**
+   * Initiates a connection request to a Stellar wallet.
+   * @param {WalletType} [walletType] - The specific wallet provider to use.
+   */
   connectWallet: (walletType?: WalletType) => Promise<void>;
+  
+  /**
+   * Clears the current wallet session and resets relevant state.
+   */
   disconnectWallet: () => void;
   
-  // Network actions
+  /**
+   * Updates the store to point to a different Stellar network.
+   * @param {NetworkType} network - The target network to switch to.
+   */
   switchNetwork: (network: NetworkType) => Promise<void>;
   
-  // Balance actions
+  /**
+   * Fetches the latest balances for all assets held by the connected account.
+   */
   updateBalances: () => Promise<void>;
+  
+  /**
+   * Manually updates the balance for a specific token in the store.
+   * @param {string} tokenCode - The code of the asset.
+   * @param {number} balance - The new numeric balance.
+   */
   updateTokenBalance: (tokenCode: string, balance: number) => void;
   
-  // Utility actions
+  /**
+   * Resets the error state in the store.
+   */
   clearError: () => void;
+  
+  /**
+   * Manually toggles the global loading state.
+   * @param {boolean} loading - The new loading state.
+   */
   setLoading: (loading: boolean) => void;
 }
 
+
 type Web3Store = Web3State & Web3Actions;
 
 export const useWeb3Store = create<Web3Store>((set, get) => ({

From f42b5cdeb512435afc977453107bf467cf544600 Mon Sep 17 00:00:00 2001
From: Muhammad Zayyad Mukhtar
 <95658387+El-swaggerito@users.noreply.github.com>
Date: Wed, 29 Apr 2026 11:52:09 +0100
Subject: [PATCH 2/2] refactor(components): enhance UI components with improved
 styling and accessibility

- Add comprehensive JSDoc comments and TypeScript interfaces for better maintainability
- Implement consistent design system with updated colors, spacing, and interactive states
- Improve accessibility with ARIA labels, keyboard navigation, and semantic HTML
- Add hover effects, transitions, and responsive design patterns
- Enhance error handling and user feedback mechanisms
- Update form validation with better user experience
---
 src/components/Card.tsx            |  45 ++++++++-
 src/components/InvoiceMintForm.tsx | 157 +++++++++++++++++++----------
 src/components/LoanTable.tsx       | 152 ++++++++++++++++++----------
 src/components/Navbar.tsx          | 119 +++++++++++++++-------
 src/components/layout/Footer.tsx   | 139 ++++++++++++++++++-------
 src/hooks/useWatchlist.ts          |  60 +++++++++--
 6 files changed, 475 insertions(+), 197 deletions(-)

diff --git a/src/components/Card.tsx b/src/components/Card.tsx
index 0e5614e..9990d6e 100644
--- a/src/components/Card.tsx
+++ b/src/components/Card.tsx
@@ -1,14 +1,53 @@
+/**
+ * Shared Card Component.
+ * Provides a consistent container for UI sections with standard 
+ * TradeFlow styling (borders, padding, and background).
+ */
+
 import React from "react";
 
+/**
+ * Props for the Card component.
+ */
 interface CardProps {
+  /** The content to be wrapped by the card */
   children: React.ReactNode;
+  /** Additional CSS classes for custom styling overrides */
   className?: string;
+  /** Optional click handler for interactive cards */
+  onClick?: () => void;
+  /** Optional hover effect toggle */
+  hoverable?: boolean;
 }
 
-export default function Card({ children, className = "" }: CardProps) {
+/**
+ * A versatile layout component for grouping related content.
+ */
+export default function Card({ 
+  children, 
+  className = "", 
+  onClick,
+  hoverable = false 
+}: CardProps) {
+  // --- Styling ---
+  const baseStyles = "bg-slate-800 border border-slate-700 rounded-3xl p-6 transition-all duration-300 shadow-xl shadow-black/5";
+  const hoverStyles = hoverable ? "hover:border-slate-600 hover:bg-slate-800/80 hover:translate-y-[-2px]" : "";
+  const interactiveStyles = onClick ? "cursor-pointer active:scale-[0.99]" : "";
+
   return (
-    <div className={`bg-slate-800 border border-slate-700 rounded-2xl p-6 ${className}`}>
+    <div 
+      className={`${baseStyles} ${hoverStyles} ${interactiveStyles} ${className}`}
+      onClick={onClick}
+      role={onClick ? "button" : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      onKeyDown={onClick ? (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          onClick();
+        }
+      } : undefined}
+    >
       {children}
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/src/components/InvoiceMintForm.tsx b/src/components/InvoiceMintForm.tsx
index 4fe4e1a..5d8222f 100644
--- a/src/components/InvoiceMintForm.tsx
+++ b/src/components/InvoiceMintForm.tsx
@@ -1,18 +1,29 @@
+/**
+ * Invoice Minting Form Component.
+ * Provides a guided interface for users to upload invoice PDFs and 
+ * define metadata for on-chain NFT minting.
+ */
+
 "use client";
 
 import React, { useState } from "react";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { z } from "zod";
-import { X, Upload, Calendar, DollarSign } from "lucide-react";
+import { X, Upload, Calendar, DollarSign, FileText } from "lucide-react";
 import Button from "./ui/Button";
 
-// Form validation schema
+/**
+ * Zod validation schema for the invoice minting form.
+ * Ensures data integrity before submission to the network.
+ */
 const invoiceSchema = z.object({
+  /** Total value of the invoice in USD */
   amount: z
     .number()
     .min(0.01, "Amount must be greater than 0")
     .max(1000000, "Amount cannot exceed $1,000,000"),
+  /** Expected payment date for the invoice */
   dueDate: z
     .string()
     .min(1, "Due date is required")
@@ -25,6 +36,7 @@ const invoiceSchema = z.object({
       },
       "Due date must be in the future"
     ),
+  /** PDF document containing the invoice details */
   invoiceFile: z
     .instanceof(File)
     .refine(
@@ -32,21 +44,33 @@ const invoiceSchema = z.object({
       "Only PDF files are allowed"
     )
     .refine(
-      (file) => file.size <= 5 * 1024 * 1024, // 5MB
+      (file) => file.size <= 5 * 1024 * 1024, // 5MB limit
       "File size must be less than 5MB"
     ),
 });
 
+/** TypeScript type inferred from the validation schema */
 type InvoiceFormData = z.infer<typeof invoiceSchema>;
 
+/**
+ * Props for the InvoiceMintForm component.
+ */
 interface InvoiceMintFormProps {
+  /** Callback to trigger when the form is closed/cancelled */
   onClose: () => void;
+  /** Callback triggered on successful form validation */
   onSubmit: (data: InvoiceFormData) => void;
 }
 
+/**
+ * A modal form component for minting new invoice-backed NFTs.
+ */
 export default function InvoiceMintForm({ onClose, onSubmit }: InvoiceMintFormProps) {
+  // --- Component State ---
+  /** Stores the name of the uploaded file for UI display */
   const [filePreview, setFilePreview] = useState<string | null>(null);
 
+  // --- Form Initialization ---
   const {
     register,
     handleSubmit,
@@ -58,8 +82,13 @@ export default function InvoiceMintForm({ onClose, onSubmit }: InvoiceMintFormPr
     resolver: zodResolver(invoiceSchema),
   });
 
-  const watchedFile = watch("invoiceFile");
+  // --- Handlers ---
 
+  /**
+   * Manually updates the file field in react-hook-form when a file is selected.
+   * 
+   * @param {React.ChangeEvent<HTMLInputElement>} event - The file input change event.
+   */
   const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
     const file = event.target.files?.[0];
     if (file) {
@@ -68,69 +97,82 @@ export default function InvoiceMintForm({ onClose, onSubmit }: InvoiceMintFormPr
     }
   };
 
+  /**
+   * Internal submission handler that wraps the provided onSubmit callback.
+   * 
+   * @param {InvoiceFormData} data - The validated form data.
+   */
   const onFormSubmit = (data: InvoiceFormData) => {
-    console.log("Invoice minting data:", data);
+    console.log("[InvoiceMintForm] Validated data received:", data);
     onSubmit(data);
     reset();
     setFilePreview(null);
   };
 
   return (
-    <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50 p-4">
-      <div className="bg-slate-800 rounded-2xl border border-slate-700 w-full max-w-md">
+    <div className="fixed inset-0 bg-black/70 backdrop-blur-sm flex items-center justify-center z-50 p-4" role="dialog" aria-modal="true" aria-labelledby="modal-title">
+      <div className="bg-slate-800 rounded-3xl border border-slate-700 w-full max-w-md shadow-2xl overflow-hidden animate-in fade-in zoom-in duration-200">
         {/* Header */}
-        <div className="flex items-center justify-between p-6 border-b border-slate-700">
-          <h2 className="text-xl font-semibold text-white">Mint Invoice NFT</h2>
+        <div className="flex items-center justify-between p-6 border-b border-slate-700 bg-slate-800/50">
+          <div className="flex items-center gap-3">
+            <div className="p-2 bg-blue-500/10 rounded-xl text-blue-400">
+              <FileText size={20} />
+            </div>
+            <h2 id="modal-title" className="text-xl font-bold text-white tracking-tight">Mint Invoice NFT</h2>
+          </div>
           <button
             onClick={onClose}
-            className="text-slate-400 hover:text-white transition-colors"
+            className="p-2 text-slate-400 hover:text-white hover:bg-white/5 rounded-full transition-all"
+            aria-label="Close modal"
           >
             <X size={20} />
           </button>
         </div>
 
-        {/* Form */}
+        {/* Form Body */}
         <form onSubmit={handleSubmit(onFormSubmit)} className="p-6 space-y-6">
-          {/* Amount Field */}
-          <div>
-            <label className="block text-sm font-medium text-slate-300 mb-2">
-              <DollarSign size={16} className="inline mr-1" />
-              Invoice Amount ($)
+          {/* Amount Input */}
+          <div className="space-y-2">
+            <label className="flex items-center gap-2 text-sm font-semibold text-slate-300 ml-1">
+              <DollarSign size={14} className="text-emerald-400" />
+              Invoice Value (USD)
             </label>
-            <input
-              type="number"
-              step="0.01"
-              min="0"
-              placeholder="0.00"
-              {...register("amount", { valueAsNumber: true })}
-              className="w-full px-4 py-3 bg-slate-700 border border-slate-600 rounded-lg text-white placeholder-slate-400 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
-            />
+            <div className="relative group">
+              <input
+                type="number"
+                step="0.01"
+                min="0"
+                placeholder="0.00"
+                {...register("amount", { valueAsNumber: true })}
+                className="w-full px-4 py-3.5 bg-slate-900/50 border border-slate-700 rounded-2xl text-white placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all group-hover:border-slate-600"
+              />
+            </div>
             {errors.amount && (
-              <p className="mt-2 text-sm text-red-400">{errors.amount.message}</p>
+              <p className="px-1 text-xs font-medium text-rose-400 animate-in slide-in-from-top-1">{errors.amount.message}</p>
             )}
           </div>
 
-          {/* Due Date Field */}
-          <div>
-            <label className="block text-sm font-medium text-slate-300 mb-2">
-              <Calendar size={16} className="inline mr-1" />
-              Due Date
+          {/* Due Date Input */}
+          <div className="space-y-2">
+            <label className="flex items-center gap-2 text-sm font-semibold text-slate-300 ml-1">
+              <Calendar size={14} className="text-blue-400" />
+              Payment Due Date
             </label>
             <input
               type="date"
               {...register("dueDate")}
-              className="w-full px-4 py-3 bg-slate-700 border border-slate-600 rounded-lg text-white placeholder-slate-400 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+              className="w-full px-4 py-3.5 bg-slate-900/50 border border-slate-700 rounded-2xl text-white placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all"
             />
             {errors.dueDate && (
-              <p className="mt-2 text-sm text-red-400">{errors.dueDate.message}</p>
+              <p className="px-1 text-xs font-medium text-rose-400 animate-in slide-in-from-top-1">{errors.dueDate.message}</p>
             )}
           </div>
 
-          {/* File Upload Field */}
-          <div>
-            <label className="block text-sm font-medium text-slate-300 mb-2">
-              <Upload size={16} className="inline mr-1" />
-              Invoice Document (PDF)
+          {/* File Upload Area */}
+          <div className="space-y-2">
+            <label className="flex items-center gap-2 text-sm font-semibold text-slate-300 ml-1">
+              <Upload size={14} className="text-indigo-400" />
+              Verification Document (PDF)
             </label>
             <div className="relative">
               <input
@@ -139,37 +181,42 @@ export default function InvoiceMintForm({ onClose, onSubmit }: InvoiceMintFormPr
                 onChange={handleFileChange}
                 className="hidden"
                 id="invoice-file"
+                aria-describedby="file-error"
               />
               <label
                 htmlFor="invoice-file"
-                className="flex items-center justify-center w-full px-4 py-3 bg-slate-700 border border-slate-600 rounded-lg cursor-pointer hover:bg-slate-600 transition-colors"
+                className={`flex flex-col items-center justify-center w-full px-4 py-8 border-2 border-dashed rounded-3xl cursor-pointer transition-all ${
+                  filePreview 
+                  ? "bg-indigo-500/5 border-indigo-500/50" 
+                  : "bg-slate-900/50 border-slate-700 hover:border-slate-600 hover:bg-slate-900/80"
+                }`}
               >
-                <Upload size={16} className="mr-2 text-slate-400" />
-                <span className="text-slate-300">
-                  {filePreview || "Choose PDF file"}
+                <Upload size={24} className={`mb-2 ${filePreview ? "text-indigo-400" : "text-slate-500"}`} />
+                <span className="text-sm font-medium text-slate-300 text-center px-4">
+                  {filePreview || "Drop your PDF here or click to browse"}
                 </span>
+                {!filePreview && <span className="text-[10px] text-slate-500 mt-1 uppercase tracking-widest font-bold">Max size: 5MB</span>}
               </label>
             </div>
             {errors.invoiceFile && (
-              <p className="mt-2 text-sm text-red-400">{errors.invoiceFile.message}</p>
-            )}
-            {filePreview && (
-              <p className="mt-2 text-sm text-slate-400">
-                Selected: {filePreview}
-              </p>
+              <p id="file-error" className="px-1 text-xs font-medium text-rose-400 animate-in slide-in-from-top-1">{errors.invoiceFile.message}</p>
             )}
           </div>
 
-          {/* Submit Button */}
-          <Button
-            type="submit"
-            disabled={isSubmitting}
-            className="w-full py-3 px-4 disabled:bg-slate-600 disabled:cursor-not-allowed"
-          >
-            {isSubmitting ? "Processing..." : "Mint Invoice NFT"}
-          </Button>
+          {/* Action Button */}
+          <div className="pt-2">
+            <Button
+              type="submit"
+              disabled={isSubmitting}
+              className="w-full py-4 px-6 rounded-2xl text-sm font-bold uppercase tracking-widest shadow-xl shadow-blue-500/10 active:scale-[0.98] transition-transform"
+              isLoading={isSubmitting}
+            >
+              Mint Asset NFT
+            </Button>
+          </div>
         </form>
       </div>
     </div>
   );
 }
+
diff --git a/src/components/LoanTable.tsx b/src/components/LoanTable.tsx
index 91462f7..03ae6dc 100644
--- a/src/components/LoanTable.tsx
+++ b/src/components/LoanTable.tsx
@@ -1,28 +1,53 @@
+/**
+ * Loan Tracking Table Component.
+ * Displays a list of active and historical loans associated with the user's invoices.
+ * Includes interest calculation logic and repayment actions.
+ */
+
 import React from 'react';
 import { formatCurrency, formatDate } from '../lib/format';
 
-// --- Types & Interfaces ---
+/**
+ * Valid states for a loan within the protocol.
+ */
 type LoanStatus = 'Active' | 'Overdue' | 'Repaid';
 
+/**
+ * Data structure representing an on-chain loan.
+ */
 interface Loan {
+  /** Unique identifier for the loan record */
   id: string;
+  /** The ID of the invoice used as collateral */
   invoiceId: string;
+  /** Principal amount borrowed */
   amountBorrowed: number;
-  interestRate: number; // Annual rate in percentage (e.g., 5 for 5%)
-  startDate: string;    // ISO string date
+  /** Annual interest rate (e.g., 5 for 5%) */
+  interestRate: number;
+  /** ISO 8601 timestamp of when the loan was initiated */
+  startDate: string;
+  /** Current lifecycle status of the loan */
   status: LoanStatus;
 }
 
-// --- Mock Data ---
+/**
+ * Simulated on-chain loan data for development.
+ */
 const MOCK_LOANS: Loan[] = [
   { id: 'L-001', invoiceId: 'INV-8821', amountBorrowed: 5000, interestRate: 10, startDate: '2026-01-10T00:00:00Z', status: 'Active' },
   { id: 'L-002', invoiceId: 'INV-9942', amountBorrowed: 12000, interestRate: 12, startDate: '2025-11-01T00:00:00Z', status: 'Overdue' },
   { id: 'L-003', invoiceId: 'INV-7731', amountBorrowed: 3500, interestRate: 8, startDate: '2026-02-01T00:00:00Z', status: 'Repaid' },
 ];
 
-// --- Helper Functions ---
-
-// Calculates interest based on time elapsed: (Amount * Rate) * (DaysElapsed / 365)
+/**
+ * Calculates the simple interest accrued based on time elapsed.
+ * Formula: (Principal * AnnualRate) * (DaysElapsed / 365)
+ * 
+ * @param {number} amount - Principal amount borrowed.
+ * @param {number} rate - Annual interest rate (percentage).
+ * @param {string} startDateStr - ISO string of the loan start date.
+ * @returns {string} Formatted interest amount as a string.
+ */
 const calculateInterest = (amount: number, rate: number, startDateStr: string) => {
   const start = new Date(startDateStr);
   const now = new Date();
@@ -33,69 +58,84 @@ const calculateInterest = (amount: number, rate: number, startDateStr: string) =
   return interest.toFixed(2);
 };
 
-// Returns the correct Tailwind classes based on the status
+/**
+ * Renders a stylized badge reflecting the loan status.
+ */
 const StatusBadge = ({ status }: { status: LoanStatus }) => {
   switch (status) {
     case 'Repaid':
-      return <span className="px-2.5 py-1 text-xs font-medium rounded-full bg-green-100 text-green-800">Repaid</span>;
+      return <span className="px-2.5 py-1 text-xs font-semibold rounded-full bg-emerald-100 text-emerald-800 border border-emerald-200" aria-label={`Status: ${status}`}>Repaid</span>;
     case 'Overdue':
-      return <span className="px-2.5 py-1 text-xs font-medium rounded-full bg-red-100 text-red-800">Overdue</span>;
+      return <span className="px-2.5 py-1 text-xs font-semibold rounded-full bg-rose-100 text-rose-800 border border-rose-200" aria-label={`Status: ${status}`}>Overdue</span>;
     case 'Active':
     default:
-      return <span className="px-2.5 py-1 text-xs font-medium rounded-full bg-blue-100 text-blue-800">Active</span>;
+      return <span className="px-2.5 py-1 text-xs font-semibold rounded-full bg-blue-100 text-blue-800 border border-blue-200" aria-label={`Status: ${status}`}>Active</span>;
   }
 };
 
-// --- Main Component ---
+/**
+ * A responsive table component for managing loans.
+ */
 export default function LoanTable() {
+  /**
+   * Handles the initiation of a loan repayment.
+   * @param {string} loanId - The ID of the loan to repay.
+   */
   const handleRepay = (loanId: string) => {
-    // TODO: Wire this up to your API or a payment modal
-    console.log(`Initiating repayment for loan: ${loanId}`);
+    // TODO: Connect to the Soroban smart contract repayment method
+    console.log(`[LoanTable] Initiating repayment flow for: ${loanId}`);
   };
 
   return (
-    <div className="w-full overflow-x-auto shadow-sm ring-1 ring-black ring-opacity-5 rounded-lg">
-      <table className="min-w-full text-sm text-left text-gray-600">
-        <thead className="text-xs text-gray-700 uppercase bg-gray-50 border-b">
-          <tr>
-            <th scope="col" className="px-6 py-4 font-semibold">Invoice ID</th>
-            <th scope="col" className="px-6 py-4 font-semibold">Amount Borrowed</th>
-            <th scope="col" className="px-6 py-4 font-semibold">Interest Accrued</th>
-            <th scope="col" className="px-6 py-4 font-semibold">Status</th>
-            <th scope="col" className="px-6 py-4 font-semibold text-right">Action</th>
-          </tr>
-        </thead>
-        <tbody className="divide-y divide-gray-200 bg-white">
-          {MOCK_LOANS.map((loan) => (
-            <tr key={loan.id} className="hover:bg-gray-50 transition-colors">
-              <td className="px-6 py-4 font-medium text-gray-900 whitespace-nowrap">
-                {loan.invoiceId}
-              </td>
-              <td className="px-6 py-4">
-                {formatCurrency(loan.amountBorrowed)}
-              </td>
-              <td className="px-6 py-4">
-                {formatCurrency(calculateInterest(loan.amountBorrowed, loan.interestRate, loan.startDate))}
-              </td>
-              <td className="px-6 py-4">
-                <StatusBadge status={loan.status} />
-              </td>
-              <td className="px-6 py-4 text-right">
-                <button
-                  onClick={() => handleRepay(loan.id)}
-                  disabled={loan.status === 'Repaid'}
-                  className={`px-4 py-2 text-sm font-medium text-white rounded-md transition-colors ${loan.status === 'Repaid'
-                    ? 'bg-gray-300 cursor-not-allowed'
-                    : 'bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2'
-                    }`}
-                >
-                  Repay
-                </button>
-              </td>
+    <div className="w-full overflow-hidden shadow-lg border border-slate-700/50 rounded-2xl bg-slate-900/50">
+      <div className="overflow-x-auto">
+        <table className="min-w-full text-sm text-left text-slate-300">
+          <thead className="text-xs text-slate-400 uppercase bg-slate-800/80 border-b border-slate-700">
+            <tr>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Invoice ID</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Principal Borrowed</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Interest Accrued</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Status</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider text-right">Actions</th>
             </tr>
-          ))}
-        </tbody>
-      </table>
+          </thead>
+          <tbody className="divide-y divide-slate-800 bg-transparent">
+            {MOCK_LOANS.map((loan) => (
+              <tr key={loan.id} className="hover:bg-slate-800/30 transition-all duration-200 group">
+                <td className="px-6 py-4 font-mono text-blue-400 whitespace-nowrap">
+                  {loan.invoiceId}
+                </td>
+                <td className="px-6 py-4 font-medium text-slate-100">
+                  {formatCurrency(loan.amountBorrowed)}
+                </td>
+                <td className="px-6 py-4 text-emerald-400">
+                  {formatCurrency(calculateInterest(loan.amountBorrowed, loan.interestRate, loan.startDate))}
+                </td>
+                <td className="px-6 py-4">
+                  <StatusBadge status={loan.status} />
+                </td>
+                <td className="px-6 py-4 text-right">
+                  <button
+                    onClick={() => handleRepay(loan.id)}
+                    disabled={loan.status === 'Repaid'}
+                    className={`px-5 py-2 text-xs font-bold uppercase tracking-widest rounded-lg transition-all transform active:scale-95 ${loan.status === 'Repaid'
+                      ? 'bg-slate-700 text-slate-500 cursor-not-allowed opacity-50'
+                      : 'bg-indigo-600 hover:bg-indigo-500 text-white shadow-md hover:shadow-indigo-500/20 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 focus:ring-offset-slate-900'
+                      }`}
+                  >
+                    Repay
+                  </button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      {MOCK_LOANS.length === 0 && (
+        <div className="p-12 text-center text-slate-500 italic">
+          No active loans found in your history.
+        </div>
+      )}
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/src/components/Navbar.tsx b/src/components/Navbar.tsx
index 65d6290..73155af 100644
--- a/src/components/Navbar.tsx
+++ b/src/components/Navbar.tsx
@@ -1,26 +1,48 @@
+/**
+ * Main Navigation Bar Component.
+ * Provides access to primary application routes, wallet connectivity status, 
+ * network selection, and utility features like the fiat on-ramp.
+ */
+
 "use client";
 
 import React, { useState } from "react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import { Wallet, Copy, Check, CreditCard } from "lucide-react";
+import { Wallet, Copy, Check, CreditCard, Menu, X } from "lucide-react";
 import toast from "react-hot-toast";
 
-// Corrected imports based on your actual file structure
+// Core UI components and modals
 import NetworkSelector from "./NetworkSelector";
 import FiatOnRampModal from "./FiatOnRampModal";
 import NetworkFeeIndicator from "./ui/NetworkFeeIndicator";
 
+/**
+ * Props for the Navbar component.
+ */
 interface NavbarProps {
+  /** The public Stellar address of the connected user (optional) */
   address?: string;
+  /** Callback to trigger the wallet connection modal */
   onConnect?: () => void;
 }
 
+/**
+ * The top navigation component used across all pages.
+ */
 export default function Navbar({ address, onConnect }: NavbarProps) {
   const pathname = usePathname();
+  // --- UI State ---
+  /** Tracks whether the wallet address was recently copied to clipboard */
   const [copied, setCopied] = useState(false);
+  /** Controls visibility of the fiat purchase modal */
   const [isFiatModalOpen, setIsFiatModalOpen] = useState(false);
+  /** Controls mobile menu visibility */
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
 
+  /**
+   * Copies the connected wallet address to the system clipboard.
+   */
   const copyToClipboard = async () => {
     if (address) {
       try {
@@ -28,14 +50,22 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
         setCopied(true);
         setTimeout(() => setCopied(false), 2000);
 
-        toast.success("Address copied to clipboard!");
+        toast.success("Address copied to clipboard!", {
+          icon: '📋',
+          style: {
+            borderRadius: '12px',
+            background: '#1e293b',
+            color: '#fff',
+          },
+        });
       } catch (err) {
-        console.error('Failed to copy address:', err);
+        console.error('[Navbar] Failed to copy address:', err);
         toast.error("Failed to copy address");
       }
     }
   };
 
+  /** Primary navigation link configuration */
   const navLinks = [
     { name: "Dashboard", href: "/" },
     { name: "Swap", href: "/swap" },
@@ -45,23 +75,29 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
   ];
 
   return (
-    <div className="flex justify-between items-center mb-12 p-8">
-      <div className="flex items-center gap-12">
-        <h1 className="text-3xl font-bold tracking-tight">
-          TradeFlow <span className="text-blue-400">RWA</span>
-        </h1>
+    <header className="flex justify-between items-center mb-8 p-6 md:p-8 bg-slate-900/50 backdrop-blur-md sticky top-0 z-40 border-b border-slate-800">
+      {/* Brand & Desktop Nav */}
+      <div className="flex items-center gap-10">
+        <Link href="/" className="flex items-center gap-2 group">
+          <div className="w-10 h-10 bg-blue-600 rounded-xl flex items-center justify-center group-hover:rotate-12 transition-transform shadow-lg shadow-blue-500/20">
+            <span className="text-white font-black text-xl">T</span>
+          </div>
+          <h1 className="text-2xl font-black tracking-tighter text-white">
+            TRADEFLOW <span className="text-blue-400 font-medium">RWA</span>
+          </h1>
+        </Link>
 
-        <nav className="hidden md:flex gap-8">
+        <nav className="hidden lg:flex gap-6">
           {navLinks.map((link) => {
             const isActive = pathname === link.href;
             return (
               <Link
                 key={link.href}
                 href={link.href}
-                className={`text-sm font-medium transition-colors ${
+                className={`text-sm font-bold tracking-wide uppercase transition-all ${
                   isActive
-                    ? "text-cyan-400"
-                    : "text-slate-400 hover:text-white"
+                    ? "text-blue-400 border-b-2 border-blue-400 pb-1"
+                    : "text-slate-400 hover:text-white pb-1"
                 }`}
               >
                 {link.name}
@@ -71,59 +107,64 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
         </nav>
       </div>
 
-      <div className="flex items-center gap-4">
-        <NetworkSelector />
+      {/* Action Area */}
+      <div className="flex items-center gap-3 md:gap-4">
+        <div className="hidden sm:flex items-center gap-3">
+          <NetworkSelector />
+          <NetworkFeeIndicator />
+        </div>
 
-        {/* Gas Tank / Network Fee Indicator */}
-        <NetworkFeeIndicator />
-
-        {/* Buy Crypto Button */}
+        {/* Buy Crypto Utility */}
         <button
           onClick={() => setIsFiatModalOpen(true)}
-          className="flex items-center gap-2 bg-green-600 hover:bg-green-700 px-6 py-2 rounded-full transition"
+          className="hidden md:flex items-center gap-2 bg-emerald-600/10 hover:bg-emerald-600 text-emerald-400 hover:text-white px-5 py-2.5 rounded-2xl transition-all font-bold text-sm border border-emerald-500/20"
+          aria-label="Open fiat on-ramp"
         >
           <CreditCard size={18} />
-          Buy Crypto
+          <span>Buy Crypto</span>
         </button>
 
+        {/* Wallet Connection / Account Display */}
         {address ? (
-          <div className="flex items-center gap-2 bg-blue-600 hover:bg-blue-700 px-6 py-2 rounded-full transition">
-            <Wallet size={18} />
-            <span className="text-sm">
+          <div className="flex items-center gap-2 bg-slate-800 border border-slate-700 pl-4 pr-2 py-1.5 rounded-2xl group hover:border-blue-500/50 transition-all">
+            <div className="w-2 h-2 rounded-full bg-emerald-500 animate-pulse" />
+            <span className="text-xs font-mono text-slate-300 font-semibold tracking-tight">
               {`${address.slice(0, 6)}...${address.slice(-4)}`}
             </span>
             <button
               onClick={copyToClipboard}
-              className="ml-2 p-1 hover:bg-blue-500 rounded-full transition-colors"
-              title="Copy address"
+              className="p-2 text-slate-500 hover:text-blue-400 hover:bg-blue-500/10 rounded-xl transition-all"
+              title="Copy Stellar address"
+              aria-label="Copy address"
             >
-              {copied ? (
-                <Check size={16} className="text-green-300" />
-              ) : (
-                <Copy size={16} className="text-white" />
-              )}
+              {copied ? <Check size={14} className="text-emerald-400" /> : <Copy size={14} />}
             </button>
           </div>
         ) : (
-          /* * ISSUE #108: Added `animate-pulse` to draw attention to the primary CTA.
-           * Because this button is isolated within the `false` branch of the `address` check,
-           * the animation is naturally removed when the user connects their wallet.
-           */
           <button
             onClick={onConnect}
-            className="flex items-center gap-2 bg-blue-600 hover:bg-blue-700 px-6 py-2 rounded-full transition animate-pulse"
+            className="flex items-center gap-2 bg-blue-600 hover:bg-blue-500 px-6 py-2.5 rounded-2xl transition-all font-bold text-sm shadow-lg shadow-blue-500/20 active:scale-95"
           >
             <Wallet size={18} />
             Connect Wallet
           </button>
         )}
+
+        {/* Mobile Menu Toggle */}
+        <button 
+          className="lg:hidden p-2 text-slate-400 hover:text-white transition-colors"
+          onClick={() => setIsMenuOpen(!isMenuOpen)}
+          aria-label={isMenuOpen ? "Close menu" : "Open menu"}
+        >
+          {isMenuOpen ? <X size={24} /> : <Menu size={24} />}
+        </button>
       </div>
 
-      {/* Fiat On-Ramp Modal */}
+      {/* Modals & Overlays */}
       <FiatOnRampModal
         isOpen={isFiatModalOpen}
         onClose={() => setIsFiatModalOpen(false)}
       />
-    </div>
+    </header>
   );
-}
\ No newline at end of file
+}
diff --git a/src/components/layout/Footer.tsx b/src/components/layout/Footer.tsx
index 987d5ee..56c3427 100644
--- a/src/components/layout/Footer.tsx
+++ b/src/components/layout/Footer.tsx
@@ -1,49 +1,112 @@
+/**
+ * Shared Footer Component.
+ * Contains copyright information, primary resource links, and social media integrations.
+ * Automatically sticks to the bottom of the viewport via flexbox in the layout.
+ */
+
 import React from "react";
-import { ExternalLink } from "lucide-react";
+import { ExternalLink, Twitter, Github, Mail } from "lucide-react";
+import Link from "next/link";
 
+/**
+ * A consistent footer for all TradeFlow pages.
+ */
 export default function Footer() {
+  // --- Configuration ---
+  const currentYear = new Date().getFullYear();
+
   return (
-    <footer className="bg-slate-800 border-t border-slate-700 py-8 px-8 mt-auto">
+    <footer className="bg-slate-900 border-t border-slate-800 py-12 px-8 mt-auto" role="contentinfo">
       <div className="max-w-7xl mx-auto">
-        <div className="flex flex-col md:flex-row justify-between items-center gap-4">
-          <div className="text-slate-400 text-sm">
-            © 2024 TradeFlow. All rights reserved.
+        <div className="flex flex-col lg:flex-row justify-between items-start lg:items-center gap-12 lg:gap-8">
+          
+          {/* Brand Info */}
+          <div className="space-y-4 max-w-sm">
+            <div className="flex items-center gap-2">
+              <div className="w-8 h-8 bg-blue-600 rounded-lg flex items-center justify-center">
+                <span className="text-white font-black text-sm">T</span>
+              </div>
+              <span className="text-lg font-black tracking-tight text-white uppercase">TradeFlow</span>
+            </div>
+            <p className="text-slate-500 text-sm leading-relaxed">
+              The premier dashboard for managing Real World Asset (RWA) backed invoices on the Stellar network.
+            </p>
+          </div>
+
+          {/* Navigation & Links */}
+          <div className="grid grid-cols-2 sm:grid-cols-3 gap-12 w-full lg:w-auto">
+            
+            {/* Resources Column */}
+            <div className="space-y-4">
+              <h4 className="text-xs font-bold text-slate-400 uppercase tracking-widest">Resources</h4>
+              <nav className="flex flex-col gap-3">
+                <a
+                  href="https://docs.tradeflow.example"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium inline-flex items-center gap-1"
+                >
+                  Documentation
+                  <ExternalLink size={12} className="opacity-50" />
+                </a>
+                <Link href="/faq" className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium">
+                  Help Center
+                </Link>
+              </nav>
+            </div>
+
+            {/* Legal Column */}
+            <div className="space-y-4">
+              <h4 className="text-xs font-bold text-slate-400 uppercase tracking-widest">Legal</h4>
+              <nav className="flex flex-col gap-3">
+                <Link href="/legal/terms" className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium">
+                  Terms of Service
+                </Link>
+                <Link href="/legal/privacy" className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium">
+                  Privacy Policy
+                </Link>
+              </nav>
+            </div>
+
+            {/* Social Column */}
+            <div className="space-y-4">
+              <h4 className="text-xs font-bold text-slate-400 uppercase tracking-widest">Connect</h4>
+              <div className="flex gap-4">
+                <a
+                  href="https://twitter.com"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="p-2 bg-slate-800 rounded-xl text-slate-400 hover:text-blue-400 hover:bg-blue-400/10 transition-all"
+                  aria-label="Follow us on Twitter"
+                >
+                  <Twitter size={18} />
+                </a>
+                <a
+                  href="https://github.com"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="p-2 bg-slate-800 rounded-xl text-slate-400 hover:text-white hover:bg-white/10 transition-all"
+                  aria-label="View source on GitHub"
+                >
+                  <Github size={18} />
+                </a>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Bottom Bar */}
+        <div className="mt-12 pt-8 border-t border-slate-800/50 flex flex-col sm:flex-row justify-between items-center gap-4 text-center sm:text-left">
+          <div className="text-slate-600 text-[10px] font-bold uppercase tracking-tighter">
+            © {currentYear} TradeFlow Protocol. Built on Stellar.
+          </div>
+          <div className="flex items-center gap-1 text-[10px] font-bold text-slate-600 uppercase tracking-tighter">
+            <div className="w-1.5 h-1.5 rounded-full bg-emerald-500 shadow-[0_0_8px_rgba(16,185,129,0.5)]" />
+            Network Status: Operational
           </div>
-          <nav className="flex gap-6">
-            <a
-              href="#"
-              className="text-slate-400 hover:text-white transition-colors text-sm"
-              onClick={(e) => {
-                e.preventDefault();
-                // Handle Documentation link
-                console.log("Documentation clicked");
-              }}
-            >
-              Documentation
-            </a>
-            <a
-              href="#"
-              className="text-slate-400 hover:text-white transition-colors text-sm"
-              onClick={(e) => {
-                e.preventDefault();
-                // Handle Terms of Service link
-                console.log("Terms of Service clicked");
-              }}
-            >
-              Terms of Service
-            </a>
-            <a
-              href="https://twitter.com"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="flex items-center gap-1 text-slate-400 hover:text-white transition-colors text-sm"
-            >
-              Twitter
-              <ExternalLink size={12} className="w-4 h-4" />
-            </a>
-          </nav>
         </div>
       </div>
     </footer>
   );
 }
+
diff --git a/src/hooks/useWatchlist.ts b/src/hooks/useWatchlist.ts
index 666522d..f38a3eb 100644
--- a/src/hooks/useWatchlist.ts
+++ b/src/hooks/useWatchlist.ts
@@ -1,44 +1,81 @@
+/**
+ * Watchlist Management Hook.
+ * Handles the persistence and state of a user's token watchlist 
+ * using browser localStorage.
+ */
+
 import { useState, useEffect } from 'react';
 
+/** Key used for persisting watchlist data in localStorage */
 const WATCHLIST_STORAGE_KEY = 'tradeflow-watchlist';
 
+/**
+ * Custom hook for interacting with the token watchlist.
+ * 
+ * @returns {object} An object containing the watchlist state and management functions.
+ */
 export function useWatchlist() {
+  // --- State Initialization ---
   const [watchlist, setWatchlist] = useState<string[]>([]);
 
-  // Load watchlist from localStorage on mount
+  // --- Persistence Logic ---
+
+  /**
+   * Effect: Load the watchlist from localStorage on component mount.
+   */
   useEffect(() => {
     try {
       const stored = localStorage.getItem(WATCHLIST_STORAGE_KEY);
       if (stored) {
-        setWatchlist(JSON.parse(stored));
+        // Attempt to parse the stored JSON array
+        const parsed = JSON.parse(stored);
+        if (Array.isArray(parsed)) {
+          setWatchlist(parsed);
+        }
       }
     } catch (error) {
-      console.error('Failed to load watchlist from localStorage:', error);
+      console.error('[useWatchlist] Failed to load watchlist from localStorage:', error);
     }
   }, []);
 
-  // Save watchlist to localStorage whenever it changes
+  /**
+   * Effect: Persist the watchlist to localStorage whenever it changes.
+   */
   useEffect(() => {
     try {
       localStorage.setItem(WATCHLIST_STORAGE_KEY, JSON.stringify(watchlist));
     } catch (error) {
-      console.error('Failed to save watchlist to localStorage:', error);
+      console.error('[useWatchlist] Failed to save watchlist to localStorage:', error);
     }
   }, [watchlist]);
 
+  // --- Action Handlers ---
+
+  /**
+   * Adds a token symbol to the user's watchlist.
+   * @param {string} tokenSymbol - The symbol of the token (e.g., "XLM").
+   */
   const addToWatchlist = (tokenSymbol: string) => {
     setWatchlist(prev => {
       if (prev.includes(tokenSymbol)) {
-        return prev; // Already in watchlist
+        return prev; // No-op if already present
       }
       return [...prev, tokenSymbol];
     });
   };
 
+  /**
+   * Removes a token symbol from the user's watchlist.
+   * @param {string} tokenSymbol - The symbol of the token to remove.
+   */
   const removeFromWatchlist = (tokenSymbol: string) => {
     setWatchlist(prev => prev.filter(token => token !== tokenSymbol));
   };
 
+  /**
+   * Toggles the presence of a token symbol in the watchlist.
+   * @param {string} tokenSymbol - The symbol to toggle.
+   */
   const toggleWatchlist = (tokenSymbol: string) => {
     if (watchlist.includes(tokenSymbol)) {
       removeFromWatchlist(tokenSymbol);
@@ -47,15 +84,26 @@ export function useWatchlist() {
     }
   };
 
+  /**
+   * Checks if a specific token symbol is currently in the watchlist.
+   * @param {string} tokenSymbol - The symbol to check.
+   * @returns {boolean} True if the token is watched.
+   */
   const isInWatchlist = (tokenSymbol: string) => {
     return watchlist.includes(tokenSymbol);
   };
 
   return {
+    /** The current list of watched token symbols */
     watchlist,
+    /** Function to add a token */
     addToWatchlist,
+    /** Function to remove a token */
     removeFromWatchlist,
+    /** Function to toggle a token */
     toggleWatchlist,
+    /** Function to check if a token is watched */
     isInWatchlist,
   };
 }
+