Retrieval-Augmented Generation (RAG) has become the go-to pattern for building AI applications that need access to domain-specific knowledge without the cost of fine-tuning.

### Why RAG?

Fine-tuning large language models is expensive and slow to update. RAG lets you keep your knowledge base separate from the model — meaning you can update your data without retraining.

### The Stack

- **AWS Bedrock** — managed inference for foundation models (Claude, Titan, etc.)
- **Qdrant** — high-performance vector database for semantic search
- **llama.cpp** — local inference for cost-sensitive workloads
- **LangChain** — orchestration layer tying everything together

### Embedding Documents

The first step is chunking your documents and embedding them into vector space:

```python
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.embeddings import BedrockEmbeddings

splitter = RecursiveCharacterTextSplitter(chunk_size=512, chunk_overlap=64)
chunks = splitter.split_documents(docs)

embeddings = BedrockEmbeddings(model_id="amazon.titan-embed-text-v1")
vectorstore = Qdrant.from_documents(chunks, embeddings, url="http://localhost:6333")
```

### Retrieval & Generation

At query time, embed the user's question and retrieve the top-k chunks, then pass them as context to the LLM:

```python
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})
chain = RetrievalQA.from_chain_type(llm=bedrock_llm, retriever=retriever)
answer = chain.run("What are the key benefits of serverless architecture?")
```

### Lessons Learned

1. **Chunk size matters** — too small loses context, too large dilutes relevance.
2. **Metadata filtering** speeds up retrieval dramatically on large corpora.
3. **Hybrid search** (keyword + vector) outperforms pure vector search in many domains.

RAG is not a silver bullet but it's the right tool for most knowledge-intensive enterprise AI use cases.

A deep dive into architecting retrieval-augmented generation pipelines using AWS Bedrock, Qdrant vector store, and llama.cpp for production AI applications.

Building RAG Pipelines with AWS Bedrock

Running LLMs in the cloud is convenient, but sometimes you need inference without cloud dependency — for privacy, cost, or latency reasons. This post walks through building a local LLM inference setup using llama.cpp and HuggingFace Transformers, and then evaluating it against cloud-hosted models.

### Why Go Local?

There are several compelling reasons to run models on-premise:

- **Data privacy** — sensitive documents never leave your infrastructure
- **Cost control** — no per-token API charges at scale
- **Latency** — no network round-trip for time-sensitive applications
- **Air-gapped environments** — regulated industries (finance, healthcare) often prohibit cloud calls

### Setting Up llama.cpp

llama.cpp is a C++ inference engine for running quantized GGUF models. It's blazing fast on CPU and supports GPU offloading via Metal and CUDA.

```bash
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make -j8
# Download a GGUF model, e.g. Mistral-7B-Instruct Q4_K_M
./llama-cli -m mistral-7b-instruct-v0.2.Q4_K_M.gguf -p "Explain RAG in one paragraph." -n 200
```

For a Python interface, use the llama-cpp-python binding:

```python
from llama_cpp import Llama

llm = Llama(model_path="mistral-7b-instruct-v0.2.Q4_K_M.gguf", n_ctx=4096, n_gpu_layers=32)
response = llm("What is retrieval-augmented generation?", max_tokens=256)
print(response["choices"][0]["text"])
```

### Using HuggingFace Transformers Locally

For models that are not yet in GGUF format, HuggingFace Transformers is the go-to library:

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_id = "mistralai/Mistral-7B-Instruct-v0.2"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map="auto")

inputs = tokenizer("Explain vector search:", return_tensors="pt").to("cuda")
output = model.generate(**inputs, max_new_tokens=200)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

### Building an Evaluation Pipeline

Comparing local vs. cloud models requires a structured evaluation pipeline. Here's the framework I use:

```python
import time
from dataclasses import dataclass
from typing import Callable

@dataclass
class EvalResult:
    model_name: str
    latency_ms: float
    answer: str
    relevance_score: float

def evaluate_model(model_fn: Callable, questions: list[str], contexts: list[str]) -> list[EvalResult]:
    results = []
    for q, ctx in zip(questions, contexts):
        start = time.perf_counter()
        answer = model_fn(q, ctx)
        latency = (time.perf_counter() - start) * 1000
        score = compute_relevance(answer, ctx)  # custom metric
        results.append(EvalResult("local", latency, answer, score))
    return results
```

### Benchmark Results

Running Mistral-7B Q4_K_M locally versus Claude 3 Haiku on a 100-question domain QA dataset:

- **Latency**: Local — 1.2s average; Cloud — 0.8s average (with network)
- **Accuracy**: Local — 71%; Cloud — 79%
- **Retrieval relevance** (RAGAS score): Local — 0.68; Cloud — 0.74

The gap is smaller than most people expect, especially for domain-specific retrieval tasks where the context window provides most of the signal.

### Key Takeaways

1. **Quantization is your friend** — Q4_K_M gives ~90% of the quality at 25% of the memory footprint.
2. **GPU offloading matters** — even partial offload to a consumer GPU cuts latency by 3–5x.
3. **Evaluation is non-negotiable** — never deploy a local model without benchmarking it against your specific use case.

Local LLMs are no longer a researcher's toy. With the right tooling, they are production-ready for many enterprise workloads.

How to run and evaluate large language models entirely on-premise using llama.cpp and HuggingFace Transformers — benchmarking local inference against cloud-hosted counterparts on latency, accuracy, and retrieval relevance.

Local LLM Development with llama.cpp and HuggingFace

One of the most interesting projects I have shipped is a Video Assistant that autonomously joins Microsoft Teams meetings and delivers real-time news briefings relevant to the ongoing conversation. This post explains the architecture from ingestion to delivery.

### The Problem

Enterprise teams spend hours manually researching context before meetings. The goal was to build a system that automatically surfaces the most relevant news and internal documents during a live meeting — without any human curation.

### Architecture Overview

The system has four main stages:

- **Ingestion** — scrape news sources on a schedule, chunk and embed documents
- **Indexing** — store embeddings in Qdrant with rich metadata
- **Retrieval** — semantic search triggered by meeting transcript segments
- **Delivery** — a bot that joins Teams calls and posts briefings in the chat

### Stage 1: News Ingestion with AWS Lambda

```python
import boto3
import feedparser
from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct

def handler(event, context):
    feeds = ["https://feeds.reuters.com/reuters/topNews", "https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml"]
    articles = []
    for feed_url in feeds:
        feed = feedparser.parse(feed_url)
        for entry in feed.entries[:20]:
            articles.append({"title": entry.title, "summary": entry.summary, "published": entry.published})
    embed_and_index(articles)
    return {"indexed": len(articles)}
```

A CloudWatch Events rule triggers this Lambda every 15 minutes, keeping the index fresh.

### Stage 2: Embedding and Indexing with Qdrant

```python
from langchain_aws import BedrockEmbeddings
from qdrant_client.models import Distance, VectorParams

embeddings = BedrockEmbeddings(model_id="amazon.titan-embed-text-v1", region_name="us-east-1")
client = QdrantClient(url=QDRANT_URL, api_key=QDRANT_API_KEY)

client.recreate_collection(
    collection_name="news",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
)

def embed_and_index(articles):
    points = []
    for i, article in enumerate(articles):
        text = f"{article['title']}. {article['summary']}"
        vector = embeddings.embed_query(text)
        points.append(PointStruct(id=i, vector=vector, payload=article))
    client.upsert(collection_name="news", points=points)
```

### Stage 3: Real-Time Retrieval

During a meeting, the Teams bot captures transcript segments and triggers retrieval:

```python
def retrieve_relevant_news(transcript_segment: str, top_k: int = 5):
    query_vector = embeddings.embed_query(transcript_segment)
    results = client.search(
        collection_name="news",
        query_vector=query_vector,
        limit=top_k,
        score_threshold=0.72,
    )
    return [r.payload for r in results]
```

The score threshold (0.72) was tuned empirically to filter noise while keeping high-signal results.

### Stage 4: Teams Bot Delivery

The bot uses the Microsoft Bot Framework SDK to join meetings and post briefings:

```python
async def on_message_activity(self, turn_context: TurnContext):
    transcript = turn_context.activity.text
    news_items = retrieve_relevant_news(transcript)
    if news_items:
        summary = format_briefing(news_items)
        await turn_context.send_activity(MessageFactory.text(summary))
```

### Lessons Learned

1. **Rate-limit your ingestion** — news APIs and RSS feeds have quotas; use SQS to buffer bursts.
2. **Tune your score threshold carefully** — too low gives noise, too high misses useful context.
3. **Async delivery matters** — posting synchronously in the bot handler causes timeouts in Teams; always use background tasks.
4. **Monitor your vector store** — Qdrant collection sizes grow fast; implement TTL-based cleanup for stale news.

This project showed me that the hardest part of a RAG system is not the LLM — it's data freshness and retrieval quality tuning.

A walkthrough of architecting an end-to-end RAG pipeline that scrapes live news, indexes it into Qdrant, and autonomously joins Microsoft Teams meetings to deliver contextually relevant briefings — built entirely on AWS.

Building a Real-Time Video Assistant with RAG on AWS

TextQL is an open-source project from org45 that turns plain English into SQL queries. You describe what you want, and TextQL generates the SQL, runs it, and returns the results — no SQL knowledge required. This post walks through the pipeline architecture and the prompt engineering decisions that made it work reliably.

### Why Text-to-SQL is Hard

LLMs can write SQL, but making them write *correct* SQL for *your specific schema* is the challenge:

- They hallucinate table and column names
- They use the wrong JOIN type when the schema is ambiguous
- They produce valid SQL that answers the wrong question
- They format output inconsistently, making parsing brittle

The solution is structured prompting + schema injection + output validation.

### The Pipeline

```
User query → Schema injection → Prompt construction → Gemini → SQL extraction → Validation → Execution → Result
```

### FastAPI Backend

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import google.generativeai as genai
import sqlalchemy

app = FastAPI()
genai.configure(api_key=GEMINI_API_KEY)
model = genai.GenerativeModel("gemini-1.5-flash")

class QueryRequest(BaseModel):
    question: str
    database_url: str

@app.post("/query")
async def run_query(req: QueryRequest):
    schema = get_schema(req.database_url)
    sql = generate_sql(req.question, schema)
    results = execute_sql(req.database_url, sql)
    return {"sql": sql, "results": results}
```

### Schema Injection

The LLM needs to know the exact schema — table names, column names, and types:

```python
def get_schema(database_url: str) -> str:
    engine = sqlalchemy.create_engine(database_url)
    inspector = sqlalchemy.inspect(engine)
    lines = []
    for table_name in inspector.get_table_names():
        columns = inspector.get_columns(table_name)
        col_defs = ", ".join(f"{c['name']} {c['type']}" for c in columns)
        lines.append(f"CREATE TABLE {table_name} ({col_defs});")
    return "\n".join(lines)
```

Injecting the actual schema (not a description of it) dramatically reduces hallucination.

### Prompt Engineering

The prompt structure that worked best follows a few rules: provide the schema, give a clear instruction, demand a specific output format, and show one example:

```python
def build_prompt(question: str, schema: str) -> str:
    return f"""You are a SQL expert. Given the following database schema, write a SQL query that answers the user's question.

SCHEMA:
{schema}

RULES:
- Return ONLY the SQL query, no explanation.
- Wrap the SQL in <sql> tags.
- Use only table and column names that appear in the schema above.
- Prefer simple queries over complex ones.

EXAMPLE:
Question: How many users signed up last month?
<sql>SELECT COUNT(*) FROM users WHERE created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month') AND created_at < DATE_TRUNC('month', NOW());</sql>

Question: {question}
"""
```

The `<sql>` tags make extraction trivial and reliable:

```python
import re

def extract_sql(response_text: str) -> str:
    match = re.search(r"<sql>(.*?)</sql>", response_text, re.DOTALL)
    if not match:
        raise ValueError("LLM did not return SQL in expected format")
    return match.group(1).strip()
```

### SQL Validation Before Execution

Never execute LLM-generated SQL without validation. We use SQLAlchemy's text() with a dry-run explain:

```python
def validate_sql(database_url: str, sql: str) -> None:
    engine = sqlalchemy.create_engine(database_url)
    with engine.connect() as conn:
        conn.execute(sqlalchemy.text(f"EXPLAIN {sql}"))
```

This catches hallucinated table names before they hit production data.

### Executing and Returning Results

```python
def execute_sql(database_url: str, sql: str) -> list[dict]:
    validate_sql(database_url, sql)
    engine = sqlalchemy.create_engine(database_url)
    with engine.connect() as conn:
        result = conn.execute(sqlalchemy.text(sql))
        return [dict(row._mapping) for row in result.fetchall()]
```

### Results on a Sample Dataset

Testing TextQL on a 10-table e-commerce database with 50 natural language questions:

- **Correct SQL generated**: 82%
- **Schema hallucination rate**: 4% (down from 31% without schema injection)
- **Average response time**: 1.1s (Gemini Flash)

The 18% failure cases were mostly ambiguous questions where even a human would need clarification.

### Lessons Learned

1. **Schema injection is the single most impactful prompt technique** for text-to-SQL.
2. **Structured output tags** (`<sql>`) are more reliable than asking the model to "only output SQL".
3. **Always validate before executing** — an `EXPLAIN` is cheap; a bad query on production data is not.
4. **Short, fast models often outperform larger ones** for well-structured prompts — Gemini Flash matched Flash 1.5 Pro on this task.

TextQL is open source under org45. Contributions welcome.

How we built TextQL, an open-source tool that converts natural language questions into structured SQL using Google Gemini and FastAPI — with prompt engineering patterns that make LLM output reliably parseable.

Building TextQL — an LLM-Powered Text-to-SQL Pipeline

Enterprise document search has always been painful. Traditional keyword search misses context and synonyms. After joining Upland Software, I tackled this head-on.

### The Problem

2 million+ SharePoint documents. Users searching for things like "quarterly budget projections" but documents are titled "Q3 Financial Outlook FY2023".

### The Solution

Azure OpenAI embeddings + Azure AI Search with vector fields:

```typescript
import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
import { OpenAIClient } from "@azure/openai";

async function embedQuery(query: string): Promise<number[]> {
  const response = await openAIClient.getEmbeddings("text-embedding-ada-002", [query]);
  return response.data[0].embedding;
}

async function semanticSearch(query: string) {
  const vector = await embedQuery(query);
  return await searchClient.search("*", {
    vectorSearchOptions: {
      queries: [{ vector, fields: ["contentVector"], kNearestNeighborsCount: 10 }]
    }
  });
}
```

### Scale Challenges

- **Incremental indexing** — crawl only changed documents using SharePoint change tokens.
- **Rate limiting** — batch embedding calls and respect Azure OpenAI TPM limits.
- **Cost control** — cache embeddings for unchanged content.

### Results

Search relevance improved dramatically and user satisfaction scores jumped after rollout.

How I engineered enterprise-scale semantic vector search over 2M+ SharePoint documents using Azure OpenAI embeddings and Azure AI Search.

Semantic Search over SharePoint with Azure OpenAI

Grafana is one of the most active open-source projects on GitHub. Contributing to it taught me more than any course ever could.

### Getting Started

The first challenge is just finding something to work on. I started with "good first issue" labels and moved to bug fixes once I understood the codebase.

```bash
git clone https://github.com/grafana/grafana
cd grafana
make deps
make run
```

### Navigating a Large Codebase

Grafana has both a Go backend and a TypeScript/React frontend. Key tips:

1. **Read the contributing guide first** — seriously.
2. **Run existing tests** before touching anything.
3. **Use grep/ripgrep** to trace data flow across packages.

### Writing Good PRs

A good PR in a large project has:
- A clear description of the problem being solved
- Minimal diff — touch only what is necessary
- Tests that prove the fix works
- Screenshots for UI changes

### The Culture

Maintainers are friendly but busy. Be patient, responsive to feedback, and don't take rejections personally. Every rejected PR is a learning opportunity.

### Impact

My contributions improved panel rendering performance and fixed edge cases in the query editor. Seeing your name in the contributors list is genuinely satisfying.

What I learned from contributing to grafana/grafana — navigating a large codebase, writing good PRs, and the culture of open-source collaboration.

Contributing to Grafana: Open Source Lessons

In 2023, org45 ran a free React Bootcamp for developers. Here's what we learned.

### Why We Did It

Nepal has a lot of talented developers but limited access to quality structured learning. We wanted to change that — for free.

### What We Covered

- React fundamentals (JSX, components, props, state)
- Hooks deep dive (useState, useEffect, useContext, custom hooks)
- State management with Redux Toolkit
- Testing with React Testing Library
- Building and deploying a real project

### What Worked

**Project-based learning** — participants learned fastest when building real things, not just following tutorials.

**Community Discord** — async Q&A meant people could get unstuck at 2am.

**Guest sessions** — bringing in working engineers to share real-world experience was invaluable.

### What Didn't Work

We underestimated the range of baseline knowledge. Next time we'll do a better pre-assessment and offer tiered tracks.

### Results

40+ developers completed the bootcamp. Several landed their first engineering jobs shortly after. That makes everything worth it.

### What's Next

We're planning an advanced bootcamp focused on performance optimization and architecture patterns. Stay tuned on our [LinkedIn](https://www.linkedin.com/company/org45).

Reflections on running a free React Bootcamp for developers in 2023 — what worked, what didn't, and how 40+ developers leveled up their skills.

React Bootcamp 2023: A Retrospective

When I joined 0chain as a Software Engineer, the blockchain explorer had accumulated significant technical debt. The JavaScript SDK had inconsistent APIs, the React frontend was tightly coupled to implementation details, and adding new features required changes in too many places. This post covers how we rebuilt it.

### The Starting Point

The original explorer was a single-page React app that called the blockchain node APIs directly from components. There was no abstraction layer — each component built its own fetch calls, handled its own errors, and formatted its own data. The result was a tangled mess of duplicated logic.

### Redesigning the SDK Layer

The first step was designing a clean JavaScript SDK that provided a stable interface between the UI and the blockchain:

```javascript
// Before — scattered direct calls in components
const fetchBlock = async (hash) => {
  const res = await fetch(`${NODE_URL}/v1/block/get?hash=${hash}`);
  if (!res.ok) throw new Error("fetch failed");
  const data = await res.json();
  return data;
};

// After — SDK with consistent interface
class ZChainSDK {
  constructor(nodeUrl) {
    this.nodeUrl = nodeUrl;
  }

  async getBlock(hash) {
    return this._request(`/v1/block/get`, { hash });
  }

  async getTransaction(txnHash) {
    return this._request(`/v1/transaction/get/confirmation`, { hash: txnHash });
  }

  async _request(endpoint, params) {
    const url = new URL(this.nodeUrl + endpoint);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
    const res = await fetch(url.toString());
    if (!res.ok) throw new ZChainError(res.status, await res.text());
    return res.json();
  }
}
```

### React Architecture

With the SDK in place, components became simple consumers of clean data:

```jsx
import { useZChain } from '../hooks/useZChain';

function BlockDetail({ hash }) {
  const { data: block, error, loading } = useZChain('getBlock', hash);

  if (loading) return <Terminal text="fetching block..." />;
  if (error) return <ErrorPanel message={error.message} />;

  return (
    <BlockCard
      hash={block.hash}
      round={block.round}
      transactions={block.transactions}
      miner={block.miner_id}
    />
  );
}
```

The `useZChain` hook handles caching, deduplication, and error normalisation — a thin wrapper around React Query.

### Handling Real-Time Updates

Blockchain explorers need live data. We used WebSocket subscriptions for new blocks:

```javascript
class ZChainSDK {
  subscribeToBlocks(onBlock) {
    const ws = new WebSocket(`${this.wsUrl}/v1/blocks/stream`);
    ws.onmessage = (event) => {
      const block = JSON.parse(event.data);
      onBlock(block);
    };
    return () => ws.close();
  }
}
```

```jsx
useEffect(() => {
  const unsubscribe = sdk.subscribeToBlocks((block) => {
    setLatestBlocks((prev) => [block, ...prev].slice(0, 20));
  });
  return unsubscribe;
}, []);
```

### Results

- **Developer onboarding time** dropped from days to hours — new engineers had a single SDK entry point to learn.
- **Bug surface** reduced by ~40% — duplicated fetch logic was one of the main sources of inconsistencies.
- **Feature velocity** improved — adding a new explorer page no longer required touching networking code.

### Key Lessons

1. **Separate your data layer early** — mixing fetch logic into components is a debt that compounds fast.
2. **Design for the consumer** — the SDK API should match how the UI thinks about data, not how the blockchain exposes it.
3. **Typed interfaces pay dividends** — even in JavaScript, JSDoc types (or migrating to TypeScript) prevent entire classes of bugs.

Rebuilding with a clean SDK layer was one of the highest-leverage decisions of that project.

How I re-architected 0chain's blockchain explorer from scratch — redesigning the JavaScript SDK layer for better developer experience, API consistency, and long-term maintainability.

Rebuilding a Blockchain Explorer with React and a JavaScript SDK

During my time at 0chain, I owned two Go-based CLI tools that developers used to interact with the decentralized storage protocol: zwalletCLI for wallet operations and zboxCLI for storage management. This post shares what I learned about designing ergonomic, reliable CLI tools in Go.

### Why Go for CLI Tools?

Go produces statically linked, cross-platform binaries with zero runtime dependencies — perfect for developer tooling. The standard library has strong support for networking, cryptography, and concurrency, all of which matter when you're talking to a blockchain.

### CLI Structure with Cobra

Both tools used the Cobra library for command structure:

```go
package main

import (
    "fmt"
    "os"
    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "zwallet",
    Short: "0chain wallet CLI",
}

var createWalletCmd = &cobra.Command{
    Use:   "create",
    Short: "Create a new wallet",
    RunE:  runCreateWallet,
}

func init() {
    rootCmd.AddCommand(createWalletCmd)
    createWalletCmd.Flags().StringP("name", "n", "", "wallet name (required)")
    createWalletCmd.MarkFlagRequired("name")
}

func main() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
```

### Talking to the Blockchain

Blockchain calls require signing transactions with the wallet's private key. Here is a simplified version of the signing flow:

```go
import (
    "crypto/ed25519"
    "encoding/hex"
)

type Transaction struct {
    ClientID  string `json:"client_id"`
    ToClientID string `json:"to_client_id"`
    Value     int64  `json:"value"`
    Hash      string `json:"hash"`
    Signature string `json:"signature"`
}

func signTransaction(txn *Transaction, privateKey ed25519.PrivateKey) error {
    hash := computeHash(txn)
    txn.Hash = hash
    sig := ed25519.Sign(privateKey, []byte(hash))
    txn.Signature = hex.EncodeToString(sig)
    return nil
}
```

Every transaction is hashed and signed before being submitted to a consensus node.

### Storage Operations in zboxCLI

zboxCLI handled file uploads, downloads, and allocation management on 0chain's decentralized storage network:

```go
var uploadCmd = &cobra.Command{
    Use:   "upload",
    Short: "Upload a file to 0chain storage",
    RunE: func(cmd *cobra.Command, args []string) error {
        localPath, _ := cmd.Flags().GetString("localpath")
        remotePath, _ := cmd.Flags().GetString("remotepath")
        allocationID, _ := cmd.Flags().GetString("allocation")

        return uploadFile(allocationID, localPath, remotePath)
    },
}

func uploadFile(allocationID, localPath, remotePath string) error {
    allocation, err := sdk.GetAllocation(allocationID)
    if err != nil {
        return fmt.Errorf("get allocation: %w", err)
    }
    return allocation.UploadFile(localPath, remotePath, nil)
}
```

### Error Handling and User Feedback

Good CLI tools give clear, actionable error messages. We made a rule: never surface raw Go error strings to the user.

```go
func runCreateWallet(cmd *cobra.Command, args []string) error {
    name, _ := cmd.Flags().GetString("name")
    wallet, err := sdk.CreateWallet(name)
    if err != nil {
        return fmt.Errorf("failed to create wallet %q: %w", name, err)
    }
    fmt.Printf("Wallet created successfully.\nAddress: %s\n", wallet.ClientID)
    return nil
}
```

We also added a `--json` flag for machine-readable output, enabling scripting and CI integration.

### Testing CLI Commands

Testing CLI tools in Go is straightforward using the Cobra testing pattern:

```go
func TestCreateWalletCommand(t *testing.T) {
    cmd := rootCmd
    buf := new(bytes.Buffer)
    cmd.SetOut(buf)
    cmd.SetArgs([]string{"create", "--name", "test-wallet"})

    err := cmd.Execute()
    assert.NoError(t, err)
    assert.Contains(t, buf.String(), "Wallet created successfully")
}
```

### Lessons Learned

1. **Use Cobra from day one** — manual flag parsing becomes unmaintainable fast.
2. **Wrap errors with context** — `fmt.Errorf("operation: %w", err)` makes debugging dramatically easier.
3. **Separate SDK from CLI** — the blockchain SDK should be a standalone package; the CLI is just one consumer.
4. **Provide both human and machine output** — `--json` flags are a small effort with high value for power users.

Maintaining these tools taught me that developer experience is a feature, not an afterthought.

A deep dive into maintaining and extending two Go-based CLI tools — zwalletCLI and zboxCLI — that interface directly with the 0chain decentralized blockchain for wallet and storage operations.

Building Go CLI Tools for Blockchain Wallet and Storage Management

When browser clients needed direct access to 0chain's Go storage SDK, the team faced a choice: rewrite in JavaScript, or compile Go to WebAssembly. We chose WASM — and it was mostly the right call. Here's what we learned.

### The Problem with a Pure Go Backend for Browser Clients

The original architecture required all storage operations to go through a backend server: the browser talked to our server, our server talked to the blockchain. This introduced latency, a single point of failure, and scaling costs.

The goal was to enable the browser to communicate directly with blockchain nodes — without an intermediary server. Since the core SDK was in Go, the path of least resistance was compiling it to WASM.

### Compiling Go to WebAssembly

Go has first-class WASM support:

```bash
GOOS=js GOARCH=wasm go build -o main.wasm ./cmd/wasm
cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" ./public/
```

Expose Go functions to JavaScript using `syscall/js`:

```go
//go:build js && wasm

package main

import (
    "encoding/json"
    "syscall/js"
)

func uploadFile(this js.Value, args []js.Value) interface{} {
    allocationID := args[0].String()
    remotePath := args[1].String()
    fileBytes := args[2] // ArrayBuffer

    // perform upload using the Go SDK
    result, err := sdk.UploadFileBrowser(allocationID, remotePath, toGoBytes(fileBytes))
    if err != nil {
        return map[string]interface{}{"error": err.Error()}
    }
    data, _ := json.Marshal(result)
    return map[string]interface{}{"result": string(data)}
}

func main() {
    js.Global().Set("zboxUploadFile", js.FuncOf(uploadFile))
    // keep the Go runtime alive
    select {}
}
```

### TypeScript Wrapper Layer

Raw WASM calls are unergonomic from TypeScript. We wrote a typed wrapper that hid all the WASM plumbing:

```typescript
declare const zboxUploadFile: (allocationID: string, remotePath: string, data: ArrayBuffer) => {
    result?: string;
    error?: string;
};

async function loadWasm(): Promise<void> {
    const go = new Go();
    const result = await WebAssembly.instantiateStreaming(fetch('/main.wasm'), go.importObject);
    go.run(result.instance);
}

export async function uploadFile(allocationID: string, remotePath: string, file: File): Promise<UploadResult> {
    const buffer = await file.arrayBuffer();
    const response = zboxUploadFile(allocationID, remotePath, buffer);
    if (response.error) throw new Error(response.error);
    return JSON.parse(response.result!);
}
```

### Performance Improvements

The WASM approach eliminated the server intermediary for read-heavy operations:

- **Download latency** dropped by ~40% — no proxy hop
- **Concurrent transfers** improved — browser handles parallelism natively via Web Workers
- **Bundle size** was the trade-off — the WASM binary was ~8MB; we used lazy loading to mitigate startup impact

### Loading WASM in a Web Worker

For CPU-intensive operations, moving WASM to a Web Worker prevents main thread blocking:

```typescript
// worker.ts
importScripts('/wasm_exec.js');

const go = new Go();
WebAssembly.instantiateStreaming(fetch('/main.wasm'), go.importObject).then(result => {
    go.run(result.instance);
    self.postMessage({ ready: true });
});

self.onmessage = (event) => {
    const { type, payload } = event.data;
    if (type === 'upload') {
        const result = zboxUploadFile(payload.allocationID, payload.remotePath, payload.data);
        self.postMessage({ type: 'upload_result', result });
    }
};
```

### Pitfalls We Hit

1. **WASM binary size** — Go's garbage collector and runtime ship with every binary. TinyGo can reduce size but loses some stdlib compatibility.
2. **Debugging** — stack traces from WASM are cryptic; source maps help but are not perfect.
3. **Memory sharing** — passing large files between JS and WASM requires careful use of the WASM linear memory buffer.
4. **Browser compatibility** — WASM is well-supported, but streaming instantiation (`instantiateStreaming`) needs HTTPS or localhost.

### Key Takeaways

1. **WASM is a great fit when you have an existing Go library** — rewriting core crypto and storage logic in JS is risky.
2. **Always wrap WASM with a typed TypeScript layer** — callers should never touch raw WASM globals.
3. **Use Web Workers for heavy WASM work** — blocking the main thread destroys user experience.
4. **Measure first** — WASM is not always faster than well-optimized JS for simpler tasks.

The migration succeeded, but it required discipline to keep the TypeScript surface clean and the WASM internals hidden from application code.

Lessons from migrating a legacy Go storage module to a TypeScript + WebAssembly architecture — improving browser-side performance, portability, and developer ergonomics for a decentralized storage protocol.

// ls /blog