Forem: Eresh Gorantla

Architecture Breaks Silently. Now There's a Tool That Investigates.

Eresh Gorantla — Sun, 05 Apr 2026 18:10:36 +0000

There's a class of bugs that no single-file view will ever reveal.

Working in IoT, I've seen failures surface in one place while the real cause lived somewhere completely different. A device message handler would fail under load -- but the handler code looked correct. The root cause was spread across multiple files: a config value that disabled a cache, three async paths racing against the same shared resource, and a state recomputation that should never have been happening on every request. Each file was fine in isolation. The bug only existed in how they interacted at runtime.

This pattern keeps showing up in every complex system I've worked on. The hardest bugs aren't syntax errors. They're architectural -- config that silently changes downstream behavior, interface contracts that drift, concurrent paths that only break under real load.

Fixing them requires investigation: trace the failure, read the caller chain, inspect config, connect behavior across modules. That's exactly the workflow I wanted to automate.

So I built Archexa

What it does

Archexa is a VS Code extension powered by the Archexa CLI -- a self-contained binary that scans your project with tree-sitter, then uses an LLM agent to investigate across files.

Six commands, all from right-click or keyboard shortcuts:

Review (Cmd+Shift+R) -- Architecture-aware code review. Findings appear as inline squiggles, just like ESLint or TypeScript diagnostics.
Diagnose (Cmd+Shift+D) -- Paste an error or stack trace. It traces the call chain to the root cause across files.
Impact (Cmd+Shift+I) -- "What breaks if I change this?" Traces callers and interface contracts.
Query (Cmd+Alt+Q) -- Ask anything about your codebase. Evidence-backed answers with file references.
Gist -- Quick codebase overview. Great for day-one onboarding.
Analyze -- Full architecture documentation with Mermaid diagrams.

Setup (60 seconds)

# From VS Code Marketplace — search "Archexa" and click Install
# Or from the command line:
code --install-extension EreshGorantla.archexa

The setup wizard downloads the CLI binary automatically (~20 MB). No Python, no pip, no runtime dependencies.

Then: Sidebar > Settings > Connection > set your API key + endpoint.

Works with any OpenAI-compatible provider:

OpenAI (gpt-4o)
OpenRouter (gemini-2.5-flash, claude-sonnet-4-20250514, etc.)
Ollama (llama3.1 -- fully local, zero code leaves your machine)
vLLM, Azure OpenAI, LiteLLM

How it works

Every command follows the same three-phase approach:

1. Scan -- The CLI parses your project with tree-sitter AST parsing. Maps imports, function signatures, call sites, and module boundaries. Runs offline in seconds. Results are cached.

2. Investigate -- The LLM becomes an agent with tools: read_file, grep_pattern, trace_callers, list_directory. It decides what to read and when it has enough evidence. Typical run: 3-6 iterations, 10-20 tool calls, 5-15 files examined.

Here's a real investigation trace:

Step 1: Read error handler -> found verify_token()
Step 2: Search verify_token -> 8 references, 5 files. Read cache module -> no synchronization
Step 3: Trace callers of cache.get_token -> 3 async handlers. Read config -> TTL=0
Step 4: Root cause: race condition. Concurrent handlers, unprotected cache, caching disabled by config.

The agent followed the trail across files, just like an experienced engineer would -- in under a minute.

3. Synthesize -- All evidence assembled into one context-optimized prompt. The LLM generates the final output with file references and severity ratings.

The Archexa CLI

The extension is the UI layer. The real engine is the Archexa CLI -- a standalone binary that handles:

Tree-sitter AST parsing across 13 languages
Agent orchestration with tool-calling loops
Progressive context pruning as evidence grows
Streaming LLM communication via any OpenAI-compatible API

The binary communicates with the extension over stdout (streaming markdown) and stderr (JSON events). One download, chmod +x, works everywhere.

Design principles

Fresh investigation every time. No memory between runs. Every analysis starts from a fresh scan of current code. The answer is always grounded in your codebase as it exists right now, not a cached version from last week. Tree-sitter caching keeps the structural scan fast.

Your data stays yours. Zero telemetry -- not usage stats, not crash reports. The binary talks to exactly one service: the LLM endpoint you configure. API keys are stored in VS Code's encrypted credential store and passed via environment variable. Never written to config files.

No gatekeeping. No accounts, no sign-up, no Archexa API key. Bring your own LLM provider. Open source under Apache 2.0.

Fully local option

brew install ollama
ollama pull llama3.1

# In Archexa settings:
# Endpoint: http://localhost:11434/v1/
# Model: llama3.1

Zero code leaves your machine. AST parsing is offline. LLM runs locally.

Platform support

	Supported
OS	macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), Windows (x64)
Languages	Python, TypeScript, JavaScript, Go, Java, Rust, Ruby, C#, Kotlin, Scala, C++, C, PHP
LLM Providers	Any OpenAI-compatible endpoint

Beta notice

Archexa is currently in beta. The core pipeline is stable, but the CLI binary is not yet code-signed.

macOS users: Gatekeeper may block the binary on first run since it's unsigned. The extension handles quarantine removal automatically in most cases. If you see a "cannot be opened" dialog, a notification with a "Fix Permissions" button will appear. Full troubleshooting steps are in the Usage Guide.

What's next

CI integration (findings as GitHub PR comments)
Custom agent tools (project-specific scripts during deep mode investigation)
Auto-fix after review (investigate a finding, generate the fix, apply with your approval)

From Stack Trace to Root Cause - Archexa's New Diagnose Command

Eresh Gorantla — Sun, 22 Mar 2026 10:38:04 +0000

Archexa's new diagnose command correlates errors with actual source code to find the root cause, not just the symptom.

Archexa v0.2.1-beta. Apache 2.0 license. Single binary — macOS, Linux, Windows.

GitHub: github.com/ereshzealous/archexa

A stack trace tells you where your code failed. It doesn't tell you why.

NullPointerException at UserService.java:42 is the symptom. The root cause is three files upstream — a repository method that returns null instead of Optional, called by a service that doesn't check for it, triggered by a controller that passes through an unvalidated ID.

Finding that chain takes time. You read the failing line. You find the caller. You read the caller. You check what data it passed. You follow that data to where it originated. You do this across 3, 5, sometimes 10 files until you find the actual bug.

Most developers paste the stack trace into ChatGPT. It gives a plausible-sounding answer — but it doesn't have your code. It guesses based on the error message. It can't read your UserRepository.java to see that findManagerByDepartment() always returns null. It can't grep your codebase to find three other methods with the same missing null check.

That gap is what Archexa's new diagnose command fills. It has the stack trace and your codebase.

Three Ways to Feed It an Error

1. Stack Trace File (`--trace`)

Save your stack trace — from a console, crash report, or exception log — to a file:

archexa diagnose --config archexa.yaml --trace stacktrace.txt

Archexa parses stack frames from six languages:

Language	Stack Frame Format
Python	`File "path.py", line 42, in func`
Java / Kotlin	`at com.package.Class.method(File.java:42)`
Go	`/path/file.go:42 +0x1a4`
JavaScript / TypeScript	`at func (file.ts:42:10)`
Rust	`panicked at src/file.rs:42`
C#	`at Namespace.Class.Method() in File.cs:line 42`

It extracts every file path, line number, and function name from the trace — then maps them to actual files in your repository.

2. Log File (`--logs`)

Point it at your application logs:

archexa diagnose --config archexa.yaml --logs /var/log/app.log

It parses the log line by line, identifies error entries (lines containing ERROR, FATAL, EXCEPTION, panic, etc.), groups each error with its stack trace (subsequent indented lines), and extracts timestamps for filtering.

Filter by time window to focus on recent errors:

archexa diagnose --config archexa.yaml --logs app.log --last 1h      # last hour
archexa diagnose --config archexa.yaml --logs app.log --last 30m     # last 30 minutes
archexa diagnose --config archexa.yaml --logs app.log --last 2d      # last 2 days

Specify the log timezone if your timestamps aren't UTC:

archexa diagnose --config archexa.yaml --logs app.log --last 4h --tz "UTC+5:30"
archexa diagnose --config archexa.yaml --logs app.log --last 1h --tz "UTC-5"

The tool converts your log timestamps to UTC before comparing against the --last window. This way, a log entry at 10:15:33 in UTC+5:30 is correctly treated as 04:45:33 UTC.

When multiple errors are found, it analyzes the 20 most recent ones.

3. Inline Error (`--error`)

For a quick diagnosis from a single error message:

archexa diagnose --config archexa.yaml --error "NullPointerException at UserService.java:42"

It extracts any file:line references from the message and treats the whole string as the error to investigate.

Config Support

All diagnose options can be set in your archexa.yaml so you don't have to type them every time. CLI flags override config values.

archexa:
  source: "."

  openai:
    model: "google/gemini-2.5-flash"
    endpoint: "https://openrouter.ai/api/v1/"

  diagnose:
    logs: "logs/application.log"
    trace: ""
    error: ""
    last: "4h"
    tz: "UTC+5:30"

  prompts:
    diagnose: |
      Focus on the root cause, not the symptom.
      Show the exact code path that failed.
      Recommend a fix with before/after code.

With this config, you can just run:

archexa diagnose --config archexa.yaml

And it will read logs/application.log, filter errors from the last 4 hours in UTC+5:30. Override any field on the fly:

# Different log file, same config for everything else
archexa diagnose --config archexa.yaml --logs /tmp/crash.log

# Different time window
archexa diagnose --config archexa.yaml --last 1h

# Use a trace file instead of logs
archexa diagnose --config archexa.yaml --trace stacktrace.txt

What Happens Under the Hood

When you run diagnose, this is the sequence:

Parse — The input is parsed into structured data: error messages, file paths, line numbers, function names, timestamps, severity levels. A single log file might contain multiple errors — each is extracted as a separate entry with its associated stack trace lines.

Map — File paths from the stack trace are matched to actual files in your repository. UserService.java:42 becomes src/main/java/com/example/service/UserService.java. Files that don't exist in the repo (framework internals, third-party libraries) are noted but the agent focuses on what it can find.

Scan — Your repository is indexed — directory layout, file list, language distribution. No heavy parsing. Just enough for the agent to orient itself.

Investigate — This is where diagnose differs from everything else. The AI agent opens the files referenced in the stack trace at the reported line numbers. It reads the surrounding function. It finds the caller using find_references. It traces the data that caused the failure upstream using grep_codebase. It checks for similar patterns elsewhere. It makes 10-30 autonomous decisions about what to read next — exactly like a developer debugging unfamiliar code.

Synthesize — Everything the agent learned is distilled into a structured root cause analysis document.

What the Output Looks Like

The generated document follows a consistent structure:

1. Error Summary — What happened, where, and severity assessment.

2. Root Cause — The underlying reason, distinguished from the error location. "The error manifests at line 34, but the root cause is at line 37 where null originates."

3. Execution Flow — Step-by-step trace from entry point to failure, with file:line references at each step.

4. Affected Code — Table of every file involved in the error chain, what each does, and how it's affected.

5. Related Issues — Similar patterns elsewhere in the codebase that might have the same vulnerability.

6. Fix Recommendation — What to change, where, with before/after code snippets.

7. Prevention — Specific tests to write, validation to add, and monitoring suggestions.

Real Example: Spring Boot NullPointerException

I built a Spring Boot application with a deliberate bug to test diagnose:

A UserController with a /api/users/{id}/profile endpoint
A UserService that fetches the user and their department manager
A UserRepository where findManagerByDepartment() always returns null
The service calls manager.getName() without checking for null

Hit the endpoint, get a 500. Copy the stack trace, run diagnose:

archexa diagnose --config archexa.yaml --trace trace.txt

The agent traced the full chain:

Controller (UserController.java:28) → calls userService.getUserProfile(id)

Service (UserService.java:24) → calls userRepository.findManagerByDepartment(user.getDepartment())

Repository (UserRepository.java:37) → findManagerByDepartment() always returns null

Back to Service (UserService.java:34) → manager.getName() throws NullPointerException

It correctly distinguished the error location (line 34 where NPE occurs) from the root cause (line 37 where null originates).

It also found two additional bugs I hadn't asked about:

findById() returns null instead of Optional — a similar NPE waiting to happen
getActiveUser() doesn't check the active flag before returning

The fix it proposed: change the repository to return Optional<User>, add null checks in the service — with complete before/after code.

Scaling Test: FastAPI (2,600+ Files)

To test on a real-world codebase, I ran diagnose against the FastAPI framework with a simulated dependency injection cycle error.

archexa diagnose --config config-diagnose.yaml --logs sample-trace.txt --last 1d --tz "UTC+5:30"

The agent read fastapi/dependencies/utils.py (600+ lines), traced the recursive solve_dependencies function, and identified that dependency_cache caches solved values but doesn't track in-progress resolutions — meaning circular dependencies cause infinite recursion instead of a clear error.

It proposed the fix: a _solving_dependencies set parameter threaded through recursive calls, checked before each resolution. The standard cycle detection algorithm, applied to FastAPI's specific dependency resolution architecture.

18 tool calls across 10 iterations. 2,661 files scanned. 44 seconds total.

Why Deep Mode Is the Default

Every other Archexa command defaults to pipeline mode — you opt into deep mode with --deep. Diagnose is the exception. It defaults to deep mode because root cause analysis inherently requires reading actual source files.

A pipeline mode analysis can tell you "the error is probably in UserService.java." But it can't open the file, read the function, find the caller, and trace the data flow upstream. That requires the agent's tools — read_file, grep_codebase, find_references.

Use --no-deep if you want a quick pipeline assessment:

archexa diagnose --config archexa.yaml --trace crash.txt --no-deep

But the real value is in the investigation.

No Evidence Extraction

Diagnose skips Archexa's evidence extraction pipeline entirely in deep mode. The other commands (gist, analyze, query) scan every file and build AST blocks, dependency maps, and communication links before the agent starts. That takes 4-5 seconds on a large repo and produces data the agent mostly ignores because it reads the actual files anyway.

Diagnose is a focused command — the stack trace tells it exactly where to start. The agent gets a lightweight repo summary (file list, directory structure, language distribution) and the matched error files. Then it investigates with tools. No wasted work.

The same optimization applies to impact and review in deep mode as of this release.

Try It

# Install or update
curl -fsSL https://raw.githubusercontent.com/ereshzealous/archexa/main/install.sh | bash

# Create config
archexa init

# From a stack trace
archexa diagnose --config archexa.yaml --trace stacktrace.txt

# From logs with timezone
archexa diagnose --config archexa.yaml --logs app.log --last 4h --tz "UTC+5:30"

# From an error message
archexa diagnose --config archexa.yaml --error "ConnectionError at db_client.py:42"

Works with any OpenAI-compatible model. Tested with Gemini Flash via OpenRouter (~$0.03-0.05 per diagnosis). Use a larger model for complex multi-service errors.

Building a SQL Tokenizer and Formatter From Scratch — Supporting 6 Dialects

Eresh Gorantla — Sat, 21 Mar 2026 17:19:02 +0000

Try it: devprix.dev/tools/sql-formatter

This is part of DevPrix — 56 free developer tools that run entirely in your browser. No sign-up, no tracking, no server calls.

SQL formatting seems simple until you try to build it. Keyword capitalization? Easy. Proper indentation of subqueries, CASE expressions, and JOINs across PostgreSQL, MySQL, SQL Server, Oracle, SQLite, and BigQuery? That's a compiler problem.

Architecture: Tokenizer + State Machine

I chose a two-stage approach: tokenize the SQL into a stream of typed tokens, then format by iterating through tokens with a state machine. No AST (Abstract Syntax Tree) needed — SQL formatting doesn't require understanding query semantics, just structure.

Stage 1: The Tokenizer

The tokenizer is a single-pass, character-by-character scanner. It produces an array of typed tokens:

type TokenType =
  | "keyword" | "identifier" | "string" | "number"
  | "operator" | "punctuation" | "comma"
  | "open_paren" | "close_paren"
  | "comment_single" | "comment_multi"
  | "whitespace" | "dot" | "semicolon"
  | "wildcard" | "unknown";

interface Token {
  type: TokenType;
  value: string;
}

String Literals: Four Quoting Styles

Different SQL dialects use different quoting:

// Single-quoted strings (standard SQL)
if (ch === "'") {
  let str = "'";
  i++;
  while (i < sql.length) {
    if (sql[i] === "'" && sql[i + 1] === "'") {
      str += "''";  // escaped quote
      i += 2;
    } else if (sql[i] === "'") {
      str += "'";
      i++;
      break;
    } else {
      str += sql[i]; i++;
    }
  }
  tokens.push({ type: "string", value: str });
}

The tokenizer also handles:

Double-quoted identifiers: "column_name" (PostgreSQL, standard SQL)
Backtick identifiers: `table_name` (MySQL)
Square bracket identifiers: [column] (SQL Server)

Each has its own escape rules — SQL uses doubled quotes ('', "") rather than backslashes.

The Wildcard Problem

Is * a wildcard or a multiplication operator? It depends on context:

SELECT * FROM users          -- wildcard
SELECT price * quantity      -- multiplication
SELECT COUNT(*) FROM users   -- wildcard inside function

The tokenizer disambiguates by looking at the previous non-whitespace token:

if (sql[i] === "*") {
  const lastNonWs = tokens.findLast(t => t.type !== "whitespace");
  if (!lastNonWs ||
      lastNonWs.type === "keyword" ||
      lastNonWs.type === "comma" ||
      lastNonWs.type === "open_paren") {
    token.type = "wildcard";   // SELECT *, COUNT(*)
  } else {
    token.type = "operator";   // price * qty
  }
}

Compound Keywords

SQL has multi-word keywords: ORDER BY, GROUP BY, INNER JOIN, INSERT INTO, UNION ALL. The tokenizer uses lookahead to detect these:

const remaining = sql.slice(i + word.length);
const compoundMatch = remaining.match(
  /^\s+(BY|INTO|JOIN|ALL|TABLE|FROM|INDEX|KEY|EXISTS)\b/i
);

if (compoundMatch) {
  const compound = word.toUpperCase() + " " + compoundMatch[1].toUpperCase();
  if (MAJOR_CLAUSE_KEYWORDS.has(compound)) {
    token.value = compound;
    i += word.length + compoundMatch[0].length;
  }
}

This is preferable to treating them as separate tokens because ORDER alone might be an identifier in some contexts, but ORDER BY is always a keyword.

Dialect-Specific Keywords

Each dialect extends the base keyword set:

const dialectKeywords: Record<string, Set<string>> = {
  mysql: new Set(["ENGINE", "INNODB", "SHOW", "DESCRIBE", "ENUM", "JSON", ...]),
  postgresql: new Set(["RETURNING", "ILIKE", "JSONB", "LATERAL", "LISTEN", ...]),
  sqlserver: new Set(["TOP", "NOLOCK", "NVARCHAR", "PIVOT", "UNPIVOT", ...]),
  oracle: new Set(["ROWNUM", "SYSDATE", "DECODE", "NVL", "CONNECT", ...]),
  sqlite: new Set(["AUTOINCREMENT", "PRAGMA", "ATTACH", "GLOB", ...]),
};

When tokenizing, a word is checked against both the base keywords and the dialect-specific set.

Stage 2: The Formatter

The formatter is a state machine that tracks context as it iterates through tokens:

function formatSql(sql: string, options: FormatOptions): string {
  const tokens = tokenize(sql, options.dialect);
  let depth = 0;           // indentation level
  let lineStart = true;    // at beginning of line?
  let inSelect = false;    // inside SELECT clause?
  let inWhere = false;     // inside WHERE clause?
  let afterClause = false; // just saw a clause keyword?
  const subqueryStack: number[] = []; // paren depth for subqueries

The Core Loop

Each token type has formatting rules:

for (let i = 0; i < tokens.length; i++) {
  const token = tokens[i];

  if (token.type === "keyword") {
    const upper = token.value.toUpperCase();

    if (MAJOR_CLAUSE_KEYWORDS.has(upper)) {
      // SELECT, FROM, WHERE, JOIN, etc.
      newLine();
      addIndent();
      result += options.uppercaseKeywords ? upper : token.value.toLowerCase();
      afterClause = true;

      if (upper === "SELECT") inSelect = true;
      if (upper === "FROM") inSelect = false;
      if (upper === "WHERE") inWhere = true;
      // ...
    }
  }
}

Subquery Detection

The trickiest part is detecting subqueries — a SELECT inside parentheses gets extra indentation:

if (token.type === "open_paren") {
  // Peek ahead: is the next non-whitespace token SELECT?
  const next = tokens.slice(i + 1).find(t => t.type !== "whitespace");

  if (next && next.value.toUpperCase() === "SELECT") {
    // It's a subquery — indent
    depth++;
    subqueryStack.push(depth);
    newLine();
    addIndent();
  } else {
    // Regular parenthesis (function call, IN list)
    result += "(";
  }
}

When the matching close paren arrives, we check subqueryStack to know whether to dedent.

Comma Formatting

Two styles — trailing commas (traditional) and leading commas (some teams prefer this):

if (token.type === "comma") {
  if (options.trailingCommas) {
    result += ",";
    if (inSelect) {
      newLine();
      addIndent();
      result += "  "; // extra indent for continuation
    }
  } else {
    // Leading comma style
    newLine();
    addIndent();
    result += ", ";
  }
}

AND/OR in WHERE Clauses

WHERE conditions can be compact or expanded:

if ((upper === "AND" || upper === "OR") && inWhere) {
  if (options.compactWhere) {
    addSpace();
    result += upper;
  } else {
    newLine();
    addIndent();
    result += "  " + upper; // extra indent
  }
}

CASE Expression Formatting

CASE/WHEN/THEN/ELSE/END requires careful indentation tracking:

if (upper === "CASE") {
  addSpace();
  result += upper;
  depth++;
}
if (upper === "WHEN") {
  newLine();
  addIndent();
  result += upper;
}
if (upper === "END") {
  depth--;
  newLine();
  addIndent();
  result += upper;
}

The Minifier

The reverse operation — collapse SQL to a single line while preserving semantics:

function minifySql(sql: string, dialect: string): string {
  const tokens = tokenize(sql, dialect);
  let result = "";
  let lastChar = "";

  for (let i = 0; i < tokens.length; i++) {
    const token = tokens[i];

    if (token.type === "whitespace") {
      // Only add space when needed between identifiers/keywords
      const next = tokens[i + 1];
      if (/[a-zA-Z0-9_]/.test(lastChar) &&
          next && /^[a-zA-Z0-9_'"@#`\[]/.test(next.value[0])) {
        result += " ";
      }
    } else if (token.type === "comment_single") {
      // Convert -- comments to /* */ to avoid line-break dependency
      result += "/* " + token.value.slice(2).trim() + " */";
    } else {
      result += token.value;
    }
    lastChar = result[result.length - 1] || "";
  }
  return result;
}

The single-line comment conversion is a subtle but critical detail. -- comment depends on a newline to terminate. In minified SQL on one line, a -- would comment out everything after it. Converting to /* */ preserves the comment without the line-break dependency.

Syntax Highlighting

The highlighter re-tokenizes the formatted SQL and wraps each token in a <span> with a CSS class:

function highlightSql(sql: string, dialect: string): string {
  const tokens = tokenize(sql, dialect);

  return tokens.map(token => {
    const escaped = token.value
      .replace(/&/g, "&amp;")
      .replace(/</g, "&lt;")
      .replace(/>/g, "&gt;");

    switch (token.type) {
      case "keyword":
        return SQL_FUNCTIONS.has(token.value.toUpperCase())
          ? `<span class="sql-function">${escaped}</span>`
          : `<span class="sql-keyword">${escaped}</span>`;
      case "string":
        return `<span class="sql-string">${escaped}</span>`;
      case "number":
        return `<span class="sql-number">${escaped}</span>`;
      case "comment_single":
      case "comment_multi":
        return `<span class="sql-comment">${escaped}</span>`;
      default:
        return escaped;
    }
  }).join("");
}

Functions (COUNT, SUM, AVG, etc.) get a different color than keywords (SELECT, FROM, WHERE) even though both are tokenized as "keyword" type. A secondary lookup distinguishes them.

Query Complexity Scoring

The tool scores query complexity using a weighted formula:

function analyzeQuery(tokens: Token[]): QueryStats {
  let subqueries = 0, joins = 0, cases = 0, keywords = 0;

  for (const token of tokens) {
    if (token.type === "keyword") {
      keywords++;
      const upper = token.value.toUpperCase();
      if (upper === "SELECT") subqueries++;
      if (upper.includes("JOIN")) joins++;
      if (upper === "CASE") cases++;
    }
  }

  const score = (subqueries - 1) * 3 + joins * 2 + cases * 2
              + Math.floor(keywords / 10);

  return {
    complexity: score >= 12 ? "Very Complex"
              : score >= 7  ? "Complex"
              : score >= 3  ? "Moderate"
              : "Simple"
  };
}

Subqueries contribute the most weight (3 points each) because they're the hardest to read. JOINs and CASE expressions contribute 2 points each. Every 10 keywords adds 1 point for general density.

What I Learned

You don't always need an AST. For formatting (not optimization or execution), a token stream + state machine is sufficient and much simpler. You lose the ability to validate semantics, but formatting doesn't need that.

Compound keywords require lookahead. Treating ORDER and BY as separate tokens makes formatting ambiguous. Combining them during tokenization simplifies everything downstream.

Single-line comment conversion is essential for minification. This is the kind of edge case that seems minor but would break every query that contains a -- comment.

Dialect differences are mostly about keywords. The actual formatting rules are the same across dialects. The main difference is which words are reserved — JSONB in PostgreSQL, NVARCHAR in SQL Server, PRAGMA in SQLite.

I Built a QR Code Encoder From Scratch in TypeScript — Here's How It Works

Eresh Gorantla — Sat, 21 Mar 2026 17:09:53 +0000

Try it yourself: devprix.dev/tools/qr-code-generator

This is part of DevPrix — 56 free developer tools that run entirely in your browser. No sign-up, no tracking, no server calls.

Most developers reach for a library when they need QR codes. I decided to implement the entire QR encoding pipeline from scratch — Reed-Solomon error correction, Galois Field arithmetic, mask pattern optimization, and all. Here's a deep dive into what it took.

The full implementation is of TypeScript with zero dependencies, running entirely in the browser at devprix.dev/tools/qr-code-generator.

What a QR Code Actually Is

A QR code is a 2D barcode that encodes data in a grid of black and white squares called "modules." But there's a lot more going on than just turning data into dots. The encoding pipeline has six stages:

Data analysis — determine what you're encoding
Bit stream encoding — convert data to a binary stream
Error correction — add redundancy using Reed-Solomon codes
Matrix construction — place structural patterns and data
Masking — apply patterns to improve readability
Format information — encode metadata about the QR code itself

Let's walk through each one.

Stage 1: Version Selection

QR codes come in versions 1 through 40. Version 1 is 21x21 modules, and each version adds 4 modules per side (Version 2 = 25x25, Version 10 = 57x57, etc.). The version determines how much data you can store.

Each version also has four error correction levels:

L (Low) — recovers ~7% damage
M (Medium) — recovers ~15% damage
Q (Quartile) — recovers ~25% damage
H (High) — recovers ~30% damage

Higher error correction means less data capacity but more resilience. My implementation supports versions 1-10, which handles up to ~420 characters at the lowest error correction — more than enough for URLs, WiFi credentials, and contact cards.

The encoder automatically picks the smallest version that fits the data:

function chooseVersion(dataLen: number, ecLevel: number): number {
  for (let v = 0; v < VERSION_CAPACITY.length; v++) {
    if (dataLen <= VERSION_CAPACITY[v][ecLevel]) return v + 1;
  }
  return -1; // data too long
}

Stage 2: Bit Stream Encoding

Data gets converted to a binary bit stream. The stream starts with a 4-bit mode indicator (I use byte mode = 0100), followed by a character count indicator (8 bits for versions 1-9), then the actual data bytes.

After the data, the stream gets:

A terminator — up to 4 zero bits
Byte padding — zeros to reach a byte boundary
Fill padding — alternating 0xEC and 0x11 bytes until the stream reaches the exact capacity

That alternating padding pattern isn't random — it's part of the QR spec and ensures the bit stream doesn't accidentally form patterns that confuse scanners.

// Pad to exact capacity with alternating bytes
while (codewords.length < capacity) {
  codewords.push(padToggle ? 0xec : 0x11);
  padToggle = !padToggle;
}

Stage 3: Reed-Solomon Error Correction

This is where it gets mathematically interesting. Reed-Solomon codes add redundancy so the QR code can be read even if parts are damaged or obscured. The math happens in GF(256) — a Galois Field with 256 elements.

Galois Field Arithmetic

Normal arithmetic doesn't work for error correction because we need every operation to stay within 0-255 (one byte). Galois Fields solve this by redefining multiplication using logarithm tables.

First, I precompute exponential and logarithm lookup tables using the primitive polynomial 0x11d:

const GF_EXP = new Uint8Array(512);
const GF_LOG = new Uint8Array(256);

let x = 1;
for (let i = 0; i < 255; i++) {
  GF_EXP[i] = x;
  GF_LOG[x] = i;
  x = x << 1;
  if (x >= 256) x ^= 0x11d; // reduce by primitive polynomial
}
// Extend table for easy wraparound
for (let i = 255; i < 512; i++) GF_EXP[i] = GF_EXP[i - 255];

Now multiplication becomes addition of logarithms:

function gfMul(a: number, b: number): number {
  if (a === 0 || b === 0) return 0;
  return GF_EXP[(GF_LOG[a] + GF_LOG[b]) % 255];
}

This is elegant — we've turned expensive multiplication into a table lookup and an addition. The extended GF_EXP table (512 entries) avoids modulo operations during polynomial math.

Building the Generator Polynomial

The Reed-Solomon generator polynomial is built iteratively. For n error correction codewords, we multiply (x - a^0)(x - a^1)...(x - a^(n-1)) where a = 2 in GF(256):

function rsGenPoly(degree: number): Uint8Array {
  let gen = new Uint8Array([1]);
  for (let i = 0; i < degree; i++) {
    const next = new Uint8Array(gen.length + 1);
    for (let j = 0; j < gen.length; j++) {
      next[j] ^= gen[j];
      next[j + 1] ^= gfMul(gen[j], GF_EXP[i]);
    }
    gen = next;
  }
  return gen;
}

Encoding

The actual encoding is polynomial long division in GF(256). We divide the data polynomial by the generator polynomial, and the remainder becomes our error correction codewords:

function rsEncode(data: Uint8Array, ecCount: number): Uint8Array {
  const gen = rsGenPoly(ecCount);
  const result = new Uint8Array(ecCount);
  for (let i = 0; i < data.length; i++) {
    const coeff = data[i] ^ result[0];
    result.copyWithin(0, 1);
    result[ecCount - 1] = 0;
    for (let j = 0; j < ecCount; j++) {
      result[j] ^= gfMul(gen[j + 1], coeff);
    }
  }
  return result;
}

Block Interleaving

For larger QR codes, data is split into multiple blocks, each encoded independently with its own error correction. The blocks are then interleaved — codewords are taken round-robin from each block. This distributes errors across blocks, so localized damage doesn't wipe out a single block's worth of data.

Stage 4: Matrix Construction

The QR matrix is built in layers:

Finder Patterns

Three 7x7 squares at the top-left, top-right, and bottom-left corners. These are how scanners locate and orient the QR code. Each has a concentric pattern: 7x7 dark border, 5x5 white, 3x3 dark center.

Alignment Patterns

Starting from version 2, smaller 5x5 patterns appear at calculated positions. These help scanners correct for perspective distortion (like scanning at an angle).

Timing Patterns

Alternating dark/light modules along row 6 and column 6, connecting the finder patterns. These establish the grid spacing so scanners know module positions.

Data Placement

Data bits are placed in a zigzag pattern, starting from the bottom-right corner. The path moves in column pairs (two columns wide), alternating between upward and downward passes. It skips the timing pattern column (column 6) and all reserved areas:

// Zigzag right-to-left, alternating up/down
let bitIdx = 0;
for (let right = size - 1; right >= 1; right -= 2) {
  if (right === 6) right = 5; // skip timing column
  for (let vert = 0; vert < size; vert++) {
    const r = upward ? size - 1 - vert : vert;
    for (const c of [right, right - 1]) {
      if (!reserved[r][c] && bitIdx < bits.length) {
        matrix[r][c] = bits[bitIdx++];
      }
    }
  }
  upward = !upward;
}

Stage 5: Masking — The Optimization Problem

Here's where QR encoding becomes an optimization problem. Raw data placement can create patterns that confuse scanners — large uniform areas, patterns that look like finder squares, or uneven dark/light ratios.

The spec defines 8 mask patterns, each a mathematical function that determines whether to flip a module:

Mask 0: (row + col) % 2 === 0         — checkerboard
Mask 1: row % 2 === 0                  — horizontal stripes
Mask 2: col % 3 === 0                  — vertical stripes
Mask 3: (row + col) % 3 === 0         — diagonal
Mask 4: (row/2 + col/3) % 2 === 0     — block grid
Mask 5: (r*c)%2 + (r*c)%3 === 0       — product-based
Mask 6: ((r*c)%2 + (r*c)%3) % 2 === 0 — product variation
Mask 7: ((r+c)%2 + (r*c)%3) % 2 === 0 — mixed

Masks are only applied to data areas — structural patterns are preserved.

Penalty Scoring

Each masked result is scored with four penalty rules:

Rule 1: Consecutive modules — 5+ same-color modules in a row/column scores 3 + (count - 5). This penalizes long runs that blur together.

Rule 2: 2x2 blocks — Each 2x2 block of the same color scores 3. Large uniform areas are bad for scanning.

Rule 3: Finder-like patterns — The sequence 1011101 0000 (or reversed) scores 40 per occurrence. These look like finder patterns and confuse the position detection.

Rule 4: Dark balance — Deviation from 50% dark modules is penalized. The formula rounds the dark percentage to the nearest 5% boundaries and penalizes based on distance from 50%.

// Rule 4: Dark module balance
const darkCount = matrix.flat().filter(Boolean).length;
const total = size * size;
const pct = (darkCount * 100) / total;
const prev5 = Math.floor(pct / 5) * 5;
const next5 = prev5 + 5;
penalty += Math.min(Math.abs(prev5 - 50), Math.abs(next5 - 50)) / 5 * 10;

The encoder evaluates all 8 masks and picks the one with the lowest total penalty. This brute-force approach guarantees the optimal mask for readability.

Stage 6: Format Information

The last step encodes the error correction level and mask pattern as a 15-bit BCH code, placed at two locations around the top-left finder pattern. This is how scanners know which EC level and mask were used.

The format information is pre-computed as a lookup table (32 combinations: 4 EC levels x 8 masks), avoiding BCH calculation at runtime.

The Result

The complete pipeline — from a string like "https://devprix.dev" to a scannable QR matrix — runs in under 50ms in the browser. The output is rendered as SVG for crisp scaling at any size, with PNG export via Canvas API.

The tool also generates specialized payloads:

WiFi — WIFI:T:WPA;S:NetworkName;P:password;;
vCard — structured contact card format
Email — mailto: with subject and body
Phone — tel: format

What I Learned

Galois Field arithmetic is beautiful. Converting multiplication to table lookups via logarithms is one of those elegant mathematical tricks that feels like cheating. The entire GF(256) setup is 15 lines of code.

Penalty scoring is clever engineering. The four rules model human readability heuristics — too much uniformity, finder-like patterns, and dark/light imbalance all make codes harder to scan. Evaluating all 8 masks is brute force but guaranteed optimal.

The zigzag data placement is weird but purposeful. Moving in column pairs, alternating direction, skipping column 6 — it seems arbitrary until you realize it maximizes the distance between adjacent data bits, improving error resilience.

Zero dependencies was worth it. The implementation is 1,161 lines. A library would be smaller to import but adds supply chain risk, bundle size, and a black box. Building from scratch means I understand every bit of the output.

I Built a Schema Migration Tool for Cassandra Because Nothing Else Worked

Eresh Gorantla — Fri, 20 Mar 2026 18:22:05 +0000

Flyway and Liquibase treat Cassandra like PostgreSQL. They miss async DDL, distributed locking, and partial failures. So I built cqltrack — open-source CLI + Python library with schema agreement, LWT locking, and a CQL linter.

And then open-sourced it.

If you manage Apache Cassandra in production, you've felt this pain. You need to add a column, create an index, or restructure a table. So you SSH into a node, open cqlsh, and paste your CQL. Then you do it again on staging. Then someone on your team does the same change slightly differently on another cluster.

Sound familiar?

I looked at existing tools. Flyway has a Cassandra plugin. Liquibase can talk CQL. But they all treat Cassandra like PostgreSQL with a different query language. They miss the hard parts:

DDL is asynchronous. When you CREATE TABLE, the coordinator returns success before all nodes know the table exists. Your next statement — CREATE INDEX on that table — lands on a different node that hasn't seen it yet. It fails. Flyway doesn't handle this. Neither does Liquibase.

There are no DDL transactions. If statement 3 of 5 fails, statements 1 and 2 already executed. You can't roll back. Your database is in a half-migrated state.

Multiple processes can migrate simultaneously. Two CI runners deploying to the same cluster. Both see pending migrations. Both try to apply them. Chaos.

So I built cql-track.

What It Does

cqltrack is a schema migration tool that actually understands Cassandra's distributed nature. Install it with pip:

pip install cql-track

14 commands. One CLI. Everything you need:

cqltrack init         Create keyspace + tracking tables
cqltrack migrate      Apply pending migrations
cqltrack rollback     Undo migrations
cqltrack status       Applied vs pending at a glance
cqltrack history      Full audit trail with timing
cqltrack lint         Static analysis for dangerous CQL
cqltrack diff         Compare schemas across environments
cqltrack snapshot     Export live schema as CQL
cqltrack baseline     Adopt on existing databases
cqltrack pending      CI gate — exit code 1 if unapplied
cqltrack validate     Detect modified migration files
cqltrack repair       Accept intentional file changes
cqltrack new          Scaffold a migration file
cqltrack profiles     List environment profiles

But the real value is in what happens under the hood.

Architecture

Two entry points — CLI for terminal/CI, Python API for embedding in applications. Same engine underneath.

Schema Agreement — The Problem Nobody Talks About

Cassandra propagates schema changes through gossip. After a DDL statement, nodes converge asynchronously. The common "fix" is sleep(5). That's not a fix.

cqltrack polls system.local and system.peers after every DDL statement, waiting until all nodes report the same schema_version UUID. Only then does it proceed.

Configurable timeout (default: 30s). DML statements (INSERT, UPDATE) skip this entirely — they don't need agreement.

Distributed Locking with Cassandra's Own LWT

No external dependencies. No ZooKeeper. No Redis. cqltrack uses Cassandra's Lightweight Transactions to implement a distributed lock.

When two CI runners or Kubernetes pods try to migrate simultaneously:

Key design decisions:

TTL safety net — if a worker crashes without releasing, the lock auto-expires in 10 minutes
Ownership check — DELETE IF owner = me prevents one process from releasing another's lock
SERIAL consistency — full linearizability regardless of your configured consistency level
30 retries, 2s intervals — patient waiting before giving up

Partial Failure Tracking

Statement 3 fails. Statements 1 and 2 already ran. Cassandra has no rollback.

When a migration fails:

It's recorded in the history table with status = failed
cqltrack status shows it as pending — ready for retry
cqltrack history shows it as FAILED — full audit trail
Fix the CQL file, run migrate again — clean retry

The linter helps prevent retryability issues. It warns you if you write CREATE TABLE without IF NOT EXISTS — because on retry, that statement would fail even though the table already exists from the first attempt.

Not Just a CLI — A Python Library

Starting from v1.1.0, cqltrack works as a programmatic API. Embed migrations directly in your application startup:

FastAPI:

from contextlib import asynccontextmanager
from fastapi import FastAPI
from cqltrack import CqlTrack

@asynccontextmanager
async def lifespan(app: FastAPI):
    with CqlTrack("cqltrack.yml") as tracker:
        tracker.init()
        tracker.migrate()
        yield

app = FastAPI(lifespan=lifespan)

Django:

from django.apps import AppConfig
from cqltrack import CqlTrack

class MyAppConfig(AppConfig):
    def ready(self):
        with CqlTrack("cqltrack.yml") as tracker:
            tracker.init()
            tracker.migrate()

Plain Python — no YAML needed:

from cqltrack import CqlTrack

with CqlTrack(contact_points=["127.0.0.1"], keyspace="my_app") as t:
    t.init()
    t.migrate()

The distributed lock ensures only one Gunicorn worker or Kubernetes pod runs migrations. Others wait, then find nothing pending.

Built-in Static Analysis

8 rules that catch real problems:

Rule	What it catches
`no-rollback`	Missing `@down` section
`empty-rollback`	Empty rollback — false sense of safety
`drop-no-if-exists`	`DROP TABLE` without `IF EXISTS` — not idempotent
`create-no-if-not-exists`	`CREATE TABLE` without `IF NOT EXISTS`
`column-drop`	`ALTER TABLE DROP` in UP section — permanent data loss
`truncate`	`TRUNCATE` — wipes all data
`pk-alter`	PRIMARY KEY change — impossible in Cassandra
`type-change`	Column type change — very limited support

Context-aware: ALTER TABLE DROP in @down (rollback) is expected and not flagged. No running Cassandra needed.

Schema Diff Across Environments

$ cqltrack diff --source dev --target prod

Schema diff: myapp_dev <-> myapp_prod

  table       audit_log                     only in dev
  column      users.phone                   only in dev        text
  index       idx_users_email               only in dev

3 difference(s) found.

Compares tables, columns (with types), partition keys, clustering keys, indexes, and UDTs. Works across clusters via profiles or between keyspaces on the same cluster.

Multi-Environment Profiles

One YAML file. All environments:

profiles:
  dev:
    keyspace:
      name: myapp_dev
  prod:
    cassandra:
      contact_points: [prod-1, prod-2, prod-3]
      consistency: LOCAL_QUORUM
    keyspace:
      name: myapp_prod

cqltrack --profile prod migrate
cqltrack --profile dev diff --target-profile prod

Config resolution (last wins):

The Full Migration Lifecycle

How It Compares

	cassandra-migrate	cassandra-migration	cqltrack
Schema agreement	No	No	Yes
Distributed lock (LWT)	No	Basic	Yes + TTL
Partial failure tracking	No	No	Yes
CQL linter	No	No	8 rules
Schema diff	No	No	Yes
Multi-env profiles	No	No	Yes
JSON output for CI	No	No	Yes
Astra DB	No	No	Yes
Baseline adoption	No	No	Yes
Programmatic API	No	No	Yes

Compatibility

Verified with:

Apache Cassandra 3.x, 4.x, 5.x
DataStax Enterprise (DSE)
DataStax Astra DB (cloud)

AWS Keyspaces is not supported yet — it doesn't support Lightweight Transactions the way open-source Cassandra does. It's on the roadmap.

Get Started

pip install cql-track

GitHub: github.com/ereshzealous/cql-track
PyPI: pypi.org/project/cql-track
Docs: USAGE.md
Examples: FastAPI, Django, plain Python

MIT licensed. Contributions welcome.

If you've struggled with Cassandra schema management, give it a try. Star the repo if it saves you time.

If you get a chance to try it out, I'd appreciate any feedback. Feel free to open an issue at github.com/ereshzealous/cql-track/issues if you run into anything.

Archexa: A CLI That Turns Codebases Into Architecture Docs, Impact Analysis, and Reviews

Eresh Gorantla — Fri, 20 Mar 2026 15:10:00 +0000

Built this while working across multiple microservice codebases — would love feedback from folks solving similar problems.

The Problem

Architecture documentation tends to drift over time.

It’s usually written once, when the system is simpler. But as the code evolves — refactors, new services, changing APIs, updated data flows — the documentation doesn’t keep up.

Updating architecture docs is not trivial. It often requires re-understanding the system end-to-end, tracing dependencies, and reconstructing how components interact. In practice, this rarely happens alongside regular development work.

Over time, this creates familiar challenges:

New engineers take longer to ramp up
“Safe” changes can impact downstream systems unexpectedly
Code reviews focus on diffs, not system-wide effects
Important system knowledge lives in people’s heads

The architecture knowledge does exist — it’s all in the code.
But it’s distributed across many files and not easily accessible as a whole.

What I Built: Archexa

To address this, I built Archexa — a CLI tool that analyzes a codebase and generates structured engineering artifacts directly from it.

Instead of maintaining documentation manually, Archexa generates it on demand.

It produces:

Architecture documentation - (component maps, dependency diagrams, communication flows)
Change impact analysis- (likely downstream effects before merging changes)
Architecture-aware code reviews - (cross-file and cross-service insights)
Deep technical Q&A - (structured answers to system-level questions)

Not just docstrings or README templates — actual architecture documents, with references back to source files.

Quick Start

Install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/ereshzealous/archexa/main/install.sh | bash

### Initialize config
archexa init

### Get an overview of your codebase
archexa gist

For Detailed Documentation Please visit - github

Why Archexa

This tool comes from recurring patterns I’ve seen in real projects:

Onboarding takes too long - Understanding how a system fits together often requires exploring many files manually. That knowledge is rarely centralized.
Changes have hidden impact - A small change — like renaming a field — can affect consumers elsewhere (APIs, events, downstream services) that aren’t obvious from local context.
Code reviews miss system-level effects - Reviews are typically scoped to changed files. But system behavior often depends on interactions beyond that diff.

All of these stem from the same root issue - The architecture exists in the code, but it’s not easily visible as a system.

Where Existing Tools Fit

There are strong tools in this space, each solving part of the problem:

Each of these tools is valuable.
Archexa focuses on combining into a single workflow.

code analysis
LLM-based reasoning
structured output
CLI-first workflow

Two Modes: Fast vs Deep

Not every question needs the same depth.

Pipeline Mode (Default)

Scans entire codebase using AST parsing
Extracts structure: imports, classes, APIs, data flows
Generates a system-level overview

Performance:

1–2 AI calls
Seconds to minutes
Low cost

Agent Mode (--deep)

Reads actual source files
Traces dependencies and execution paths
Follows relationships across components

Behavior:

Multiple tool calls (10–50)
More detailed insights
Higher cost

Example (FastAPI — 2,600+ files)

When analyzing dependency injection:

Pipeline mode → high-level overview
Deep mode → traced execution path, identified patterns, documented lifecycle, cited source files

Six Commands, Six Use Cases

`gist` — Codebase Overview

archexa gist --config archexa.yaml
archexa gist --config archexa.yaml --deep

Quick understanding of - architecture, components, request flow

`query` — Ask Questions

archexa query --config archexa.yaml --query "How does authentication work?"
archexa query --config archexa.yaml --query "Explain dependency injection" --deep

Returns structured answers with file references.

`analyze` — Full Architecture Docs

archexa analyze --config archexa.yaml

Generates:

Mermaid architecture diagrams

Component tables with responsibilities

Dependency maps and communication flows

`impact` — Change Impact Analysis

archexa impact --config archexa.yaml --target "src/routing.py" --query "Adding rate limiting parameter"

Surfaces:

Directly and transitively affected files

Likely downstream impact across services

Risk assessment and migration strategy

`review` — Architecture-Aware Review

archexa review --config archexa.yaml --changed --deep
archexa review --config archexa.yaml --branch origin/main..HEAD --deep

Identifies:

Cross-file issues and contract mismatches

System-level concerns (security, performance, error handling)

Areas worth deeper inspection — with exact file and line numbers

`chat` — Interactive Exploration

archexa chat --config archexa.yaml

Ask questions in plain English

Switch between fast and deep mode per turn

Maintain context across turns

Save sessions to file with /save

Works With Multiple LLM Providers

Archexa connects via OpenAI-compatible endpoints, so you can use the provider that works best for you.

OpenAI — GPT-4o, GPT-4.1
Anthropic — Claude Sonnet, Claude Haiku (via OpenRouter)
Google — Gemini Flash (via OpenRouter)
Azure OpenAI
Ollama — fully local, free, code never leaves your machine
Any OpenAI-compatible endpoint — LM Studio, vLLM, corporate proxies

The FastAPI examples in the repo use three different models so you can compare quality across providers.

Single Binary, Runs Locally

Archexa ships as a single binary. No Python install, no package manager — download and run.

curl -fsSL https://raw.githubusercontent.com/ereshzealous/archexa/main/install.sh | bash

macOS (ARM/Intel), Linux (x64/ARM).
windows - Download .exe file manually from releases

Your code stays on your machine. Only extracted evidence goes to the AI API — not your raw source files. Or use Ollama and nothing leaves your machine at all.

A local CLI has a different risk profile from SaaS tools — it stays in your workflow without depending on a hosted product's availability or roadmap decisions.

Real Output: FastAPI (2,661 files)

Every command run against a real open-source project, with configs and generated documents published

Command	Mode	Model	Time	Output
`gist`	Pipeline	Gemini Flash	1m 41s	7.5 KB overview
`gist --deep`	Agent	Gemini Flash	58s	10 KB with file refs
`analyze`	Pipeline	Claude Sonnet 4	1m 55s	10.5 KB, 6 diagrams, 210 citations
`query --deep`	Agent	Claude Sonnet 4	2m 31s	7.5 KB DI deep dive
`review --deep`	Agent	Gemini Flash	1m 46s	6.8 KB, 9 review findings
`impact --deep`	Agent	GPT-4.1	2m 50s	12.4 KB impact analysis

Browse the full examples with generated docs: github.com/ereshzealous/archexa/tree/main/examples/fastapi

Getting Started

Full documentation — installation, config reference, provider setup for every major AI service, all commands, troubleshooting — lives in the repo:

github.com/ereshzealous/archexa

This is a public beta. I'd appreciate any feedback — what works, what doesn't, what you'd want it to do. Issues and stars are both welcome.

License: Apache 2.0

I Built 56 Developer Tools With Zero Dependencies — Here's What I Learned

Eresh Gorantla — Wed, 18 Mar 2026 19:23:32 +0000

I kept opening random websites for small tasks — formatting JSON, decoding JWTs, converting timestamps, generating UUIDs. Different sites, different UX, most wanting sign-ups or tracking everything.

So I built devprix.dev — 56 developer tools that all run in your browser. Nothing sent to any server. Zero npm dependencies for any tool logic.

The Full Tool List

Formatters & Validators

JSON Formatter (beautify, minify, tree view)
SQL Formatter (6 SQL dialects)
Regex Tester (live highlighting, pattern library)
JWT Decoder (header/payload/signature, expiry check)
Cron Expression Parser (visual builder, next run times)
JSON Path Evaluator & JSON Validator

Generators

UUID Generator (v1, v3, v4, v5, v7)
Password & Key Generator (RSA, ECDSA, Ed25519 key pairs)
QR Code Generator (URL, WiFi, vCard — encoder built from scratch)
Test Data Generator (55+ field types)
Hash Generator (MD5, SHA-1/256/384/512, HMAC)

Converters

Timestamp / Epoch Converter (80+ timezones)
Base64 Encoder/Decoder
Color Converter (HEX/RGB/HSL, WCAG contrast checker, palettes)
YAML ↔ JSON (Docker/K8s presets)
JSON → TypeScript (interfaces, Zod schemas)
Curl → Code (Python, JS, Go, Java, PHP, Rust, C#, Ruby)
CSV ↔ JSON, Markdown ↔ HTML, Image → Base64, and more

DevOps & Config

Docker Run → Compose (and reverse)
Chmod Calculator, IP Subnet Calculator
Git Command Builder (18 commands with danger warnings)

CSS & Design

CSS Gradient Generator (linear/radial/conic, 24 presets)
Box Shadow Generator (multi-layer, Tailwind output)
Tailwind CSS Lookup (500+ classes, reverse lookup)
Favicon Generator

...plus diff checker, JSON diff, slug generator, ASCII art generator, line tools, and more.

The Interesting Technical Bits
QR Code Encoder From Scratch

Instead of using a library, I implemented the full QR encoding

Myers Diff Algorithm

The text diff checker uses Eugene Myers' 1986 algorithm — the same one behind git diff. It finds the shortest edit script and then does a second pass for character-level highlighting within changed lines, so you can see exactly which characters were modified.

Curl to Code Parser

Parsing curl commands is surprisingly tricky. The parser handles single and double quoted strings, backslash line continuations, --data-raw vs -d vs --data-binary, multiple -H headers, -u for auth, and generates idiomatic code for 9 languages — not just string concatenation but proper library usage (requests for Python, fetch for JS, net/http for Go).

Client-Side Cryptography

The password generator and hash tools use the Web Crypto API (SubtleCrypto) for RSA, ECDSA, and Ed25519 key pair generation, SHA hashing, and HMAC computation. MD5 is the one exception — since Web Crypto doesn't support MD5, that's implemented from scratch.

Zero dependencies is liberating.
No supply chain risk, no breaking updates, no bundle bloat.
Every algorithm is right there in the codebase. The trade-off is development time — implementing a QR encoder takes longer than npm install qrcode — but the result is faster, smaller, and fully under your control.

Dark mode is table stakes.
The site supports light, dark, and system-preference themes. In 2026, shipping a developer tool without dark mode is leaving users behind.

Try It
→ devprix.dev

All free, all private, all in your browser. I'd love to hear what tools you'd want added.

Forem: Eresh Gorantla

Architecture Breaks Silently. Now There's a Tool That Investigates.

What it does

Setup (60 seconds)

How it works

The Archexa CLI

Design principles

Fully local option

Platform support

Beta notice

What's next

Links

From Stack Trace to Root Cause - Archexa's New Diagnose Command

Three Ways to Feed It an Error

1. Stack Trace File (--trace)

2. Log File (--logs)

3. Inline Error (--error)

Config Support

What Happens Under the Hood

What the Output Looks Like

Real Example: Spring Boot NullPointerException

Scaling Test: FastAPI (2,600+ Files)

Why Deep Mode Is the Default

No Evidence Extraction

Try It

Building a SQL Tokenizer and Formatter From Scratch — Supporting 6 Dialects

Architecture: Tokenizer + State Machine

Stage 1: The Tokenizer

String Literals: Four Quoting Styles

The Wildcard Problem

Compound Keywords

Dialect-Specific Keywords

Stage 2: The Formatter

The Core Loop

Subquery Detection

Comma Formatting

AND/OR in WHERE Clauses

CASE Expression Formatting

The Minifier

Syntax Highlighting

Query Complexity Scoring

What I Learned

I Built a QR Code Encoder From Scratch in TypeScript — Here's How It Works

What a QR Code Actually Is

Stage 1: Version Selection

Stage 2: Bit Stream Encoding

Stage 3: Reed-Solomon Error Correction

Galois Field Arithmetic

Building the Generator Polynomial

Encoding

Block Interleaving

Stage 4: Matrix Construction

Finder Patterns

Alignment Patterns

Timing Patterns

Data Placement

Stage 5: Masking — The Optimization Problem

Penalty Scoring

Stage 6: Format Information

The Result

What I Learned

I Built a Schema Migration Tool for Cassandra Because Nothing Else Worked

What It Does

Architecture

Schema Agreement — The Problem Nobody Talks About

Distributed Locking with Cassandra's Own LWT

Key design decisions:

Partial Failure Tracking

Not Just a CLI — A Python Library

Built-in Static Analysis

Schema Diff Across Environments

Multi-Environment Profiles

The Full Migration Lifecycle

How It Compares

Compatibility

Get Started

Archexa: A CLI That Turns Codebases Into Architecture Docs, Impact Analysis, and Reviews

The Problem

What I Built: Archexa

Quick Start

1. Stack Trace File (`--trace`)

2. Log File (`--logs`)

3. Inline Error (`--error`)

`gist` — Codebase Overview

`query` — Ask Questions

`analyze` — Full Architecture Docs

`impact` — Change Impact Analysis

`review` — Architecture-Aware Review

`chat` — Interactive Exploration