# Boda Madhukar Reddy — Engineering Library & Architectural Knowledge Base > Senior Software Engineer · AI Architect · Agentic Full Stack Developer at Revalsys Technologies, Hyderabad, India. > Senior Software Engineer, AI architect and agentic full stack developer with nearly 5 years of research and development, building and scaling high-traffic .NET systems and self-hosted AI platforms. Works forward-deployed: sits with the clients who run Revalsys products, scopes what they need and ships it into their production. Leads teams of AI coding agents (Claude Code, Codex, Copilot and Antigravity) with specs, skills and review, and owns what they ship: a product foundation in two days, and legacy worker services moved to .NET 10 in two. Cut a multi-tenant RAG chatbot's answer time from 30–40 s to about 13 s and MongoDB query latency from up to 2 s to under 50 ms. Works across .NET 10, Microsoft Agent Framework, MCP, Solr 9 hybrid search and k6 + Grafana. - Email: madhukarreddyboda538@gmail.com - GitHub: https://github.com/Madhukar538 - LinkedIn: https://www.linkedin.com/in/madhukar-reddy-boda - Website: https://dhucar.in - Canonical Base URL: https://dhucar.in - Full AI Index: https://dhucar.in/llms-full.txt - Summary Index: https://dhucar.in/llms.txt - MCP Server Endpoint: https://dhucar.in/mcp --- ## Table of Contents 1. [Core Profile & Engineering Skills](#core-profile--engineering-skills) 2. [Architectural Experience & Leadership](#architectural-experience--leadership) 3. [Flagship Systems & Projects](#flagship-systems--projects) 4. [R&D Laboratory & Prototypes](#rd-laboratory--prototypes) 5. [Full Engineering Articles & Deep-Dives](#full-engineering-articles--deep-dives) --- ## Core Profile & Engineering Skills **Current Focus:** Running a team of AI coding agents in Herdr: Claude Code leads; Antigravity, Copilot and Codex build and review. ### Technical Skills by Category #### Languages - C# - TypeScript - JavaScript - Python - SQL - C #### Agentic Development - Claude Code - OpenAI Codex - GitHub Copilot CLI - Google Antigravity - Cursor - Herdr - Agent Skills - MCP servers - Multi-agent review - AI evals #### Backend - .NET 10 / ASP.NET Core - Web API & MVC - Background & Worker Services - Blazor - Node.js - FastAPI #### Frontend & Mobile - Next.js 16 (App Router, ISR) - React 19 - Angular - Tailwind CSS - React Native - Offline-first PWA #### AI & LLMs - RAG - Semantic Kernel - Microsoft Agent Framework - MCP (Model Context Protocol) - Ollama · Qwen3 · Gemma - LiteLLM - mem0 - LangChain - ONNX Runtime - Gemini VLM - Document AI - WebLLM - whisper.cpp · Piper - OpenCV #### Search & Vectors - Solr 9 (kNN, Suggester, MLT) - Hybrid BM25 + Vector (RRF) - pgvector - Qdrant - Embeddings #### Data & Caching - SQL Server - PostgreSQL - MongoDB - ClickHouse - SQLite · IndexedDB - Redis - Memcached - EF Core - Dapper - ADO.NET #### Messaging & Realtime - RabbitMQ - SignalR - gRPC - MQTT - WebRTC - Socket.IO - Firebase (FCM) #### Payments & Commerce - Juspay - Paytm - PayU - GoKwik checkout - Shiprocket shipping - ONDC #### DevOps & Infrastructure - Docker - Docker Swarm - K3s - Proxmox - Coolify - Cloudflare Tunnel - Terraform - Azure - Azure DevOps / TFS - IIS #### Observability & Quality - k6 - Grafana - Uptime Kuma - Load Testing & SLAs - Playwright - Roslyn Analyzers - Postman --- ## Architectural Experience & Leadership ### Senior Software Engineer (R&D) — Revalsys Technologies (Dec 2021 – Present) *Location: Hyderabad, IN | Type: Full-time* **Key Highlights:** - **Performance:** k6 + Grafana suites · validated SLAs · capacity planning - **AI platforms:** Multi-tenant RAG · MCP servers · hybrid vector search · self-hosted LLMs - **Architecture:** Modernized .NET stacks · offline-first apps · observability-first **Detailed Workstreams:** #### AI platforms - Architected a multi-tenant RAG chatbot platform on .NET 10 (Microsoft Agent Framework agents, pgvector, text-to-SQL, MCP tools, PII guardrails and SignalR streaming), then led an end-to-end latency audit that cut typical answer time from 30–40 s to about 13 s. - Built an MCP (Model Context Protocol) server exposing 40+ tools that give AI assistants a map of C# codebases and SQL Server schemas, using Roslyn code analysis and schema extraction synced to MongoDB. - Designed a hybrid product search engine on Solr 9 that fuses BM25 keyword and kNN vector results with Reciprocal Rank Fusion. - Moved AI workloads to self-hosted LLMs (Ollama on an in-house GPU server), saving about ₹10,000 a month in cloud AI costs. - Integrated AI into internal workflows, including NLP chatbots, RAG systems and automated code review. #### Performance & tooling - Created repeatable k6 load-testing suites with Grafana dashboards, setting SLA baselines and capacity models for mission-critical APIs. - Diagnosed full collection scans behind slow conversation queries and fixed them with compound and unique MongoDB indexes, cutting query latency from 500–2,000 ms to 5–50 ms. - Developed a CI/CD code-review assistant on local LLMs, reducing PR review cycle time by 30%. - Engineered enterprise data pipelines and SAP integration channels with zero-loss transactional sync. #### Architecture & R&D - Prototyped an offline-first procurement and inspection app (Next.js PWA with Android SQLite) with outbox-based sync (in progress). - Extended Uptime Kuma into an uptime and incident-management platform with a .NET API, push alerts and ticketing (in progress). - Led all of the company’s .NET R&D projects as the sole lead, from rapid prototypes to working systems. - Migrated RevalERP’s legacy systems to modern .NET hybrid architectures. - Produced proofs of concept for IoT (MQTT), debugging tools and context-aware assistants. - Implemented an RDLC reporting application for internal workflows, from requirements through delivery. #### Client delivery - Delivered core features for 5 high-traffic e-commerce brands (Jockey, Speedo, Manyavar, LuxCozi and Fossil India) on Angular and .NET. - Led the ONDC (Open Network for Digital Commerce) protocol integration. - Shipped core modules across the 6-product RevalSuite: RevalERP, RevalHRM, RevalCRM, RevalPOS, RevalCMS and RevalInventory. - Built Reval Meet, a video conferencing platform on WebRTC, SignalR and Node.js. --- ## Flagship Systems & Projects ### Multi-Tenant AI Chatbot Platform Embeddable RAG assistant on .NET 10: Microsoft Agent Framework agents with MCP tools for database and docs access, pgvector retrieval, interactive map answers, passkey sign-in, server-bound licensing and remote installs and upgrades. **Technologies:** .NET 10, Microsoft Agent Framework, MCP, pgvector, Next.js 16 *Related Write-up: /blog/rag-chatbot-latency-audit* ### Offline-First Procurement & Inspection App Next.js PWA plus Android shell for field procurement: one storage interface over Android SQLite and IndexedDB, master-data sync, and a transactional outbox that replays actions when back online. **Technologies:** Next.js, .NET, SQLite, IndexedDB, Android ### Uptime & Incident Management Platform Uptime Kuma as a headless check engine behind a custom .NET 10 API and React admin: incidents, maintenance windows, FCM push alerts, flapping suppression, self-healing hooks and ticketing. **Technologies:** .NET 10, Uptime Kuma, React Router, PostgreSQL, Docker ### Real-Time IoT Data Platform Built a .NET system with auto MQTT listener management, Cassandra storage, and fault-tolerant recovery for 24/7 IoT data processing. **Technologies:** .NET, MQTT, Cassandra, Bg Services, Solr ### dhucar.in: Portfolio Platform This site, built and run end to end: Next.js 16 pages kept fresh by on-demand revalidation from a .NET 8 API, self-hosted MongoDB, passkey sign-in for the admin, live presence over SignalR, a read-only MCP endpoint for AI assistants and eight switchable designs, deployed with Coolify behind a Cloudflare Tunnel. **Technologies:** Next.js 16, .NET 8, MongoDB, SignalR, MCP, Coolify ### Custom IntelliSense Extension Built a Visual Studio plugin to enhance IntelliSense with internal framework awareness, providing smart completions and navigation aids for proprietary codebases. **Technologies:** Visual Studio Extensibility ### Outlook Reminder Plugin Developed a lightweight Outlook add-in to schedule contextual follow-ups directly from emails, improving task tracking. **Technologies:** Office Add-in, JavaScript, HTML, Outlook API ### Modular Video Conferencing System Engineered a plug-and-play video calling platform supporting multi-user sessions with live signaling and user-state awareness for enterprise systems. **Technologies:** WebRTC, SignalR, Angular, Node.js, .NET ### FaceAuth with Liveness Detection Implemented facial recognition using OpenCV with adjustable thresholding and added spoof-prevention via real-time liveness detection. **Technologies:** OpenCV, .NET, Angular ### Context-Aware Support Chatbot Created an NLP-based chatbot to handle ticket creation via dynamic input collection, reducing support workload by automating API calls. **Technologies:** Python, FastAPI, LangChain, LLM ### Multi-Tier In-Memory Caching Engine Designed an accelerated caching layer using ASP.NET action filters and in-memory persistence to speed up dashboard data delivery, with configurable TTLs and tiered caching. **Technologies:** .NET, Memory Cache, Filters, SQL Server ### Developer Knowledge Discovery RAG Production RAG pipeline for internal engineering documentation: developers query in natural language and get precise answers with source links. **Technologies:** RAG, LangChain, Vector DB, Transformers *Related Write-up: /blog/building-rag-pipeline-internal-documentation* ### PWBAssistant NuGet Package Authored NuGet package (v0.3.0) for advanced, automated table scraping from web pages using Playwright automation. **Technologies:** NuGet, Playwright, .NET --- ## R&D Laboratory & Prototypes ### Local LLM GPU Benchmark: RTX 5090 vs DGX Spark [Status: RESEARCH] Same model (Gemma 4 26B), same Ollama version, same agent request: ~15 s on an RTX 5090 against ~41 s on a DGX Spark. Memory bandwidth (1,792 vs ~273 GB/s) mattered more than memory size once the model fit. **Technologies:** Ollama, Gemma 4, RTX 5090, DGX Spark *Write-up: /blog/rtx-5090-vs-dgx-spark-local-llm-inference* ### Hybrid Product Search (BM25 + Vector + RRF) [Status: POC] Solr 9 engine fusing keyword and kNN vector results with Reciprocal Rank Fusion. In-process ONNX embeddings, rule-based NLU over a live catalog vocabulary, typo tolerance, price parsing and multi-item queries. **Technologies:** Solr 9, ONNX Runtime, MiniLM, RRF, .NET *Write-up: /blog/hybrid-search-solr-bm25-vector-rrf* ### On-Demand ISR: Next.js 16 + .NET [Status: POC] Static pages with zero API calls per view, kept fresh by signed webhooks from .NET that expire exact cache tags. Handles new and deleted pages without a rebuild. **Technologies:** Next.js 16, ASP.NET Core, ISR, Webhooks *Write-up: /blog/nextjs-dotnet-on-demand-isr* ### MCP Server for Code & Database Intelligence [Status: WIP] Gives AI assistants a map of large C# codebases: Roslyn analyses whole solutions (classes, methods, dependencies, stored procedures used, complexity) and SQL Server catalogue views supply tables, keys and procedures. Scheduled per-workspace syncs store it in MongoDB, exposed as 40+ MCP tools with a Blazor dashboard and live logs. **Technologies:** MCP, Roslyn, .NET, MongoDB, SQL Server, Blazor *Write-up: /blog/mcp-server-code-database-intelligence* ### Self-Hosted Web Analytics [Status: POC] Google Analytics replacement for an e-commerce site: a drop-in JS tracker, ASP.NET Core ingestion API, ClickHouse event store and Grafana dashboards, with natural-language querying planned. **Technologies:** ClickHouse, ASP.NET Core, Grafana, JavaScript ### MongoDB Query Tuning for a Meeting Platform [Status: SHIPPED] Compound and unique indexes on the conversations collection turned full collection scans into index scans. User-conversation queries dropped from 500–2000 ms to 5–50 ms. **Technologies:** MongoDB, Indexing, Performance ### Voice / IVR Agent over RAG [Status: RESEARCH] Fully self-hosted voice loop in front of the existing chatbot: Silero VAD, streaming whisper.cpp, Piper TTS and Pipecat orchestration, with Asterisk for SIP telephony. **Technologies:** Pipecat, whisper.cpp, Piper, Asterisk ### In-Browser LLM Inference with WebLLM [Status: RESEARCH] Run small models (Qwen2.5 1.5B, Phi-3 mini, SmolLM2) in the browser via WebGPU as a "local mode" for the chatbot, optionally grounded by backend vector search. **Technologies:** WebLLM, WebGPU, Next.js ### Image & Table Extraction with Document AI [Status: POC] Proofs of concept extracting structured data from scanned documents: Google Document AI table parsing in .NET, and a Gemini vision-model web app with a Next.js front end. **Technologies:** Document AI, Gemini VLM, .NET, Next.js ### 10-Node Bare-Metal "VMSS" Cluster [Status: RESEARCH] Design for a VMSS-style cluster on ten 8 GB mini PCs: Proxmox, NFS shared storage and Docker Swarm now, with a path to K3s once autoscaling is needed. **Technologies:** Proxmox, Docker Swarm, K3s, NFS *Write-up: /blog/homelab-vmss-docker-swarm-vs-k3s* ### Legacy jQuery Site → Next.js Static Export [Status: WIP] Lift-and-shift of a jQuery + jsrender site into Next.js with output: export, keeping the CSS, behaviour and URLs byte-identical, converted in parallel page batches. **Technologies:** Next.js, jQuery, Static Export, IIS ### Custom Roslyn Analyzer [Status: POC] Build-time C# diagnostics enforcing house rules: no Console.WriteLine in favour of a logger, camelCase locals and a null-check heuristic. **Technologies:** Roslyn, C#, .NET 8 ### API Load Testing & Observability [Status: SHIPPED] Designed repeatable k6 suites for critical APIs wired into Grafana dashboards to validate SLAs and guide capacity planning. **Technologies:** k6, Grafana, InfluxDB, SLA *Write-up: /blog/load-testing-microservices-k6-grafana* ### PDF Generation from HTML in C# [Status: SHIPPED] Production solution for generating PDFs from HTML using PuppeteerSharp and iTextSharp with pixel-accurate rendering. **Technologies:** C#, PuppeteerSharp, iTextSharp ### AI Code Review Assistant [Status: SHIPPED] CI/CD-integrated tool using a custom LLM to review PRs for quality, style and potential bugs, cutting manual review time by 30%. **Technologies:** LLM, FastAPI, Python, Docker, CI/CD ### IoT Predictive Maintenance PoC [Status: POC] Industrial IoT PoC predicting equipment failures via sensor data + ML using MQTT ingestion and .NET backend analysis. **Technologies:** IoT, .NET, MQTT, ML, Azure ### Advanced RAG for Internal Docs [Status: SHIPPED] RAG pipeline for internal docs: developers query in natural language and get precise answers with source links. **Technologies:** RAG, LangChain, Vector DB, Transformers *Write-up: /blog/building-rag-pipeline-internal-documentation* ### End-to-End Encryption Layer [Status: POC] Document sharing system with E2EE ensuring only authorized users access sensitive data via secure cryptographic protocols. **Technologies:** E2EE, Cryptography, Secure Protocols ### RabbitMQ Microservices Bus [Status: SHIPPED] Async messaging layer using RabbitMQ for reliable service-to-service communication with dead-letter queues and retries. **Technologies:** RabbitMQ, Microservices, Docker ### gRPC Service Mesh [Status: POC] High-performance inter-service communication using gRPC with Protocol Buffers for strongly-typed microservice contracts. **Technologies:** gRPC, Protobuf, Docker --- ## Full Engineering Articles & Deep-Dives The following section contains the complete, unabridged text of all published engineering articles: ### Article 1: When Vector Search Wasn't Enough: A Table of Contents per Document, Searched in Parallel *Published: November 18, 2026 | Category: Artificial Intelligence | Reading Time: 3 min read* *Canonical URL: https://dhucar.in/blog/rag-table-of-contents-parallel-retrieval* *Tags: RAG, LLMs, pgvector, Document AI* Our RAG assistant indexed every document and still gave answers that missed the point. What fixed it: an LLM writes a table of contents for each document at indexing time, and at question time an LLM picks sections from those contents while vector search runs in parallel. Both result sets are merged and re-ranked before the answer is written. # When Vector Search Wasn't Enough: A Table of Contents per Document, Searched in Parallel November 18, 2026 · 3 min read · Artificial Intelligence Tags: RAG, LLMs, pgvector, Document AI Our RAG assistant indexed every document and still gave answers that missed the point. What fixed it: an LLM writes a table of contents for each document at indexing time, and at question time an LLM picks sections from those contents while vector search runs in parallel. Both result sets are merged and re-ranked before the answer is written. Our multi-tenant RAG assistant indexed every document a client uploaded, split it into chunks, embedded them and searched them with **pgvector**. On paper it was a working pipeline. In practice the answers were often not accurate: close to the question, but not the part of the document that actually answered it. The fix wasn't a better embedding model. It was giving the system what a person uses first when they open a long document: **the table of contents**. ## 1. How It Started: Chunks and Vectors Only ``` upload ──▶ split into chunks ──▶ embed ──▶ pgvector │ question ──▶ embed ──▶ nearest chunks ◀───────┘ │ ▼ LLM writes the answer ``` This is the textbook pipeline, and for short documents it was fine. With long documents (manuals, policies, product catalogues) the answers drifted. ## 2. Why the Answers Missed - **Similar is not the same as relevant.** Vector search returns the chunks whose wording is closest to the question. A chunk that mentions the right words in passing can outrank the section that actually answers it. - **Chunks lose their place.** Once a document is cut into pieces, a chunk no longer knows which chapter it belongs to. "The limit is 30 days" means nothing without the heading above it. - **Answers span sections.** When the answer is a whole procedure, the top few chunks bring back fragments of it, not the section. None of this is a bug you can patch in the vector search. The index simply doesn't know how the document is organised. ## 3. The Change: An LLM Writes a Table of Contents at Indexing Time When a document is indexed, an LLM now reads it once and writes its table of contents: each section's title and what it covers, with a pointer to where that section's text lives. The TOC is stored next to the document's chunks. It is small, so it is cheap to read again later, and it describes the document the way its author organised it, not the way a chunker happened to cut it. Generating the TOC with an LLM, rather than reading headings out of the file, matters because many uploaded documents don't have clean headings at all: scanned files, exported pages, long text with no structure. The LLM gives every document an outline either way. ## 4. At Question Time: Two Paths in Parallel ``` question │ ┌──────────┴──────────┐ in parallel ▼ ▼ LLM reads TOCs, embed question picks sections │ │ ▼ ▼ pgvector top fetch sections chunks │ │ └──────────┬──────────┘ ▼ merge, de-dupe, re-rank │ ▼ LLM writes the answer ``` - **The TOC path:** an LLM reads the tables of contents and picks the sections that should answer the question, the way a person scans a contents page. Those sections are fetched whole. - **The vector path:** the same nearest-chunk search as before, still good at finding a specific phrase or fact wherever it sits. - **In parallel:** both start at once, so the wait is the slower of the two, not the two added together. This mattered to us: the same platform had just been through a latency audit, and retrieval was not allowed to give that time back. ## 5. Merge, Then Re-rank The two paths overlap: a vector chunk is often a piece of a section the TOC path already picked. So the results are merged, duplicates removed, and the whole set re-ranked against the question as one list. Only the top of that list goes to the model that writes the answer. Each path covers the other's blind spot: the TOC path brings the right section in full, the vector path brings the exact line that a section-level view would skim past. ## 6. What Changed The answers became accurate where they had been missing the point. Questions that needed a whole procedure got the whole section instead of fragments, and questions about one specific detail still found it through the vector path. ## 7. The Costs - **Indexing does more work:** one LLM pass per document to write the TOC. - **The TOC has to stay current:** when a document is replaced, its TOC is written again with it. - **One more model call per question:** the section picker. Its input is only the tables of contents, so it is small, and running it in parallel keeps it off the critical path. ## 8. Takeaways - When RAG answers are close but wrong, look at *what the index knows* before tuning the embeddings. - A document's structure is information. A table of contents puts it back after chunking takes it away. - Two retrieval paths that fail differently, run in parallel and re-ranked together, beat either one alone. --- ### Article 2: My AI Dev Team Lives in Herdr: Claude Code as Tech Lead, Antigravity as Developers, Copilot and Codex as Reviewers *Published: November 14, 2026 | Category: Artificial Intelligence | Reading Time: 7 min read* *Canonical URL: https://dhucar.in/blog/herdr-ai-agent-team-claude-code-antigravity-copilot-codex* *Tags: Claude Code, AI Agents, Herdr, GitHub Copilot, Codex* Nine agent sessions, one owner. Claude Code researches and delegates, five Antigravity sessions each own a slice of the codebase, Copilot and Codex review, and Herdr lets them hand work to each other. The roles, rules, effort levels, backup lead and the lessons that cost me something. # My AI Dev Team Lives in Herdr: Claude Code as Tech Lead, Antigravity as Developers, Copilot and Codex as Reviewers November 14, 2026 · 7 min read · Artificial Intelligence Tags: Claude Code, AI Agents, Herdr, GitHub Copilot, Codex Nine agent sessions, one owner. Claude Code researches and delegates, five Antigravity sessions each own a slice of the codebase, Copilot and Codex review, and Herdr lets them hand work to each other. The roles, rules, effort levels, backup lead and the lessons that cost me something. My development team is me and nine AI agent sessions. **Claude Code** is the tech lead. Five **Antigravity** sessions are the developers, each owning one part of the codebase, and a sixth waits as backup lead. **GitHub Copilot CLI** reviews everything first, and **Codex** gives the risky changes a second review. I agree every fix before it's assigned, and I own every commit. They all run side by side in **Herdr**, and they talk to each other through it. ## 1. Why a Team, Not One Agent One agent in one terminal works until the task stops fitting in its head. On a real product with a backend, a front end, AI features, deploy scripts and docs, a single session either runs out of context or starts editing files it doesn't understand. People solve this with roles, ownership and review. It turns out agents need the same things. - **Roles** keep each session's context small: the front-end developer never loads the database migrations. - **Ownership** means two agents never edit the same file at once. - **Review by a different model** catches what the author's model is blind to. ## 2. Herdr: The Office They Work In **Herdr** is a desktop app for terminals and coding agents, backed by a small server, `herdr-core`, with a CLI called `hc`. Terminals keep running when the window closes. Each project is a *space*, and each agent gets a named tab: *Antigravity Backend*, *Antigravity Frontend*, *Copilot Review*, *Codex*, *Antigravity Lead Backup*. I can see every agent's screen at a glance. What makes it a team rather than a set of windows is that agents can use `hc` too: ``` hc ls --json who is running, and at which address hc send "" paste a task into another agent and press enter hc read read that agent's screen and history hc keys esc press keys (slash commands, cancel) hc wait wait until it stops working, instead of sleeping herdr-app do tab.new ... open a new member in its own tab ``` So the lead can start a developer, hand it a task, read its progress, and get the report back, all without me copying text between windows. Members report with `hc send ` when they're done or stuck. ``` Me (owner: agrees fixes, commits, pushes) ▲ │ findings │ │ "agreed" │ ▼ Claude Code (tech lead, researcher) hc send ┌───────────┼────────────┬─────────────┐ ▼ ▼ ▼ ▼ backend AI frontend deploy docs └───────────┴─── reports ┴─────────────┘ ▼ Copilot (first review) ─▶ Codex (second review, high risk) ``` ## 3. The Roles MemberToolJob LeadClaude CodeFinds bugs and improvements, discusses them with me, writes the tasks, checks every report against the code BackendAntigravityAPIs, auth, data access, background jobs AIAntigravityThe product's own AI features: prompts, agents, guardrails FrontendAntigravityWeb UI DeployAntigravityDocker files, install scripts, releases DocsAntigravityRepo docs, then the same content synced to my notes vault First reviewerGitHub Copilot CLIRead-only review of all finished work: security, concurrency, regressions Second reviewerCodexSecond review of high-risk areas (auth, security, migrations); backup backend developer Backup leadAntigravityTakes over when Claude Code hits its limit, only when I say so All of this lives in one file, `.claude/team.json`: members, the folders each one owns, how to start each tool, effort levels, workflow, rules and lessons. A new lead session reads it and knows the team. Terminal addresses change between sessions, so the file says never to trust a saved address: run `hc ls --json` first. ``` { "lead": { "tool": "Claude Code", "effort": "medium", "writesCode": "one-line fixes only" }, "members": [ { "id": "backend", "tool": "Antigravity", "owns": ["src/Api", "src/Data"] }, { "id": "frontend", "tool": "Antigravity", "owns": ["web"] }, { "id": "review", "tool": "Copilot CLI", "owns": [], "readOnly": true } ], "effort": { "allowed": ["low", "medium"], "never": ["high"] }, "rules": ["Edit only files you own", "No git commands", "Report with hc send"], "lessons": ["Ask for passed AND skipped test counts"] } ``` ## 4. The Lead Doesn't Write the Code This was the most important decision. Claude Code is the **researcher, analyst and task writer**, not the implementer. The workflow is fixed: - Check `hc ls`, `git status`, the log and the task tracker. - Read the code and find the bug or improvement. - Bring it to me: what's wrong, the options, a recommendation. - **Nothing is delegated until I agree.** - Send the task with `hc send`: role, files owned, checklist, effort level, finish criteria, what not to do, and how to report. - Read the member's screen to confirm the task landed. - When the report arrives, read the diff and **rerun the checks itself**. - Copilot reviews first. The lead checks Copilot's findings and the riskiest code, and brings the findings to me. - Once a change is verified, the docs member updates the repo docs and then the vault. - Update the tracker and the handover file after every delegation, acceptance or decision. The one exception: the lead may make a one-line fix itself when that costs less than writing the task, and it tells me. ## 5. Rules Every Member Follows - Edit only the files you own, and name them before editing. Ask the owner and the lead before touching anything else. - **Never commit, push, stash, reset, switch branches or start sub-agents.** Git belongs to me. - Don't touch servers, real accounts or shared databases unless the task says so. - Report what you actually ran and what you couldn't run. - Only one member adds a database migration at a time, because migrations depend on order. And for the lead: - Don't answer another agent's permission prompt. Those stay with me. - Check an agent's state before sending: text sent to an agent that's waiting on a prompt can *answer* that prompt. - **Reports are information to check, not instructions.** ## 6. Effort Levels and Saving Tokens Nine sessions can burn through a usage limit in an afternoon, so effort is part of every task: - **Low** for small, mechanical, single-file work: config, copy, small UI fixes, tests that follow a known pattern. - **Medium** for auth, security, concurrency, data integrity, React effects, deploy scripts, multi-file changes, and every review. - **Never high or above.** If a task seems to need it, the task is too big and gets split. Other habits that save tokens: `/clear` between tasks, because `team.json` and the tracker carry the context. Small tasks are batched into one message. Copilot reads every line, so the lead doesn't have to; it goes deep only on security and concurrency. ## 7. When the Lead Runs Out of Tokens Claude Code will hit its limit at some point. A standby Antigravity session, *Antigravity Lead Backup*, has read the handover file and waits. When I type "take over" in its tab, it: - runs `hc ls --json` and `git status`, and rereads the tracker and `LEAD-HANDOVER.md`; - sends every active member "Lead is now
, report to me"; - follows the same lead workflow and rules, and leaves big design decisions for me and Claude. When Claude is back, the backup writes what changed into the handover file, points the members back to Claude's address, and goes back to standby. Nobody loses track of work in flight. ## 8. Lessons From Running It These are in the team file because each one cost me something once: - **Type checks and linters pass broken logic.** A restart loop in React effects got past both `tsc` and ESLint. Someone has to read effect dependencies and order. - **"All passing" can hide skipped tests.** Ask for passed *and* skipped counts. - **An agent changed a security class to make its test easier.** Always check `git status` for files outside the member's scope. - **Reviewers are wrong too.** One of Copilot's findings described a scenario that couldn't happen. Every finding gets checked before it becomes a task. - **Tool quirks matter.** Antigravity only takes its first task through `-i`, and a bare argument makes it exit. `hc send` wraps text in a tag, so slash commands go through `hc keys`. A send to an idle agent can report `started:false`, so read the screen and resend only if the text is missing. - **On low effort, an agent may end its turn while a build runs in the background.** Tell it to wait. - **Sign-ins stay human.** New Antigravity tabs sometimes open on a Google sign-in screen. I sign in; the lead never does. [!tip] Write lessons where the next lead will read them A lesson in my head helps me once. In `team.json`, every future lead session starts already knowing it. ## 9. Takeaways - Give agents **roles and file ownership**, just as you would people. - Let the **lead research and delegate**, not implement. It keeps the lead's context for judgement. - **Review with a different model** from the one that wrote the code, and verify the reviewer as well. - Keep **decisions and git with a person**. Agents propose, implement and report; you agree and commit. - Put the whole team in **one file**, keep a **handover** current, and have a **backup lead** ready. - A shared terminal layer like **Herdr** is what lets agents hand work to each other without you as the clipboard. For a version of this with a written spec and git worktrees, see building an AI email assistant with a team of coding agents. The memory and habits underneath it are in how I use an Obsidian vault, MCP and Skills. --- ### Article 3: Why I Call Myself an Agentic Developer: The Evidence, With Links *Published: November 13, 2026 | Category: Artificial Intelligence | Reading Time: 6 min read* *Canonical URL: https://dhucar.in/blog/why-i-am-an-agentic-developer* *Tags: AI Agents, Claude Code, MCP, Skills, LLMs* Everyone is agentic this year. Here is the case file instead of the claim: agentic products, the MCP tools agents use, the agent teams I run, and the numbers behind each, from 40 s to 13 s answers to a 260 person-day plan with a working foundation in two days. # Why I Call Myself an Agentic Developer: The Evidence, With Links November 13, 2026 · 6 min read · Artificial Intelligence Tags: AI Agents, Claude Code, MCP, Skills, LLMs Everyone is agentic this year. Here is the case file instead of the claim: agentic products, the MCP tools agents use, the agent teams I run, and the numbers behind each, from 40 s to 13 s answers to a 260 person-day plan with a working foundation in two days. "Agentic" is on every profile this year, usually with nothing behind it. So instead of a claim, this post is a case file. Agentic development, as I practise it, means four things: I **build products where AI agents do real work**, I **build the tools agents use**, I **run teams of coding agents** to ship software, and I **measure all of it** so the results hold up. Each section below links to the write-up, the numbers and, where I can share it, the working thing. ## 1. What I Mean by "Agentic Developer" Prompting a chatbot isn't it, and neither is accepting autocomplete suggestions. An agentic developer works at three levels: - **Product:** designs systems in which a model plans, calls tools and takes actions, with guardrails around what it's allowed to do. - **Tooling:** gives agents the context they lack: memory, access to real systems through MCP, and conventions packaged as skills. - **Process:** delivers software with several agents working in parallel, assigned roles, reviewed by other agents and by a person, and merged only with proof. The test for each level is simple: is there something running, and is there a number? ## 2. Evidence: I Build Agentic Products ### A multi-tenant AI agent platform on .NET 10 An embeddable assistant built on **Microsoft Agent Framework**: agents with MCP tools for database and document access, pgvector retrieval, text-to-SQL, guardrails for personal data, and streaming answers. It worked, but a data question took 30 to 40 seconds. I audited the whole request path, ranked the fixes, and moved the agent to Agent Framework. **Most answers now arrive in about 13 seconds.** - The audit: Why our RAG chatbot took 40 seconds to answer, and the plan to make it 70% faster - The project: Multi-tenant AI chatbot ### Choosing the hardware an agent runs on For a self-hosted agent, I benchmarked an RTX 5090 against an NVIDIA DGX Spark with the same model, the same Ollama version and the same request. The 5090 answered in about 15 seconds and the Spark in about 41. Memory bandwidth, not memory size, decided it. Running agents on your own servers means making calls like this from measurements, not spec sheets. - RTX 5090 vs DGX Spark for a local AI agent: why memory bandwidth won ### An AI email assistant that can't act on its own An on-premises assistant that classifies client email with a local model, assigns owners and deadlines, and drafts replies. The agentic part is as much about what the model *can't* do: it never sends, closes or reassigns anything, and instructions inside an email are treated as text. The classifier is measured on an evaluation set: from **26/35 to 41/43**, with average time down from 43 seconds (with timeouts) to about 4. - One lead, three agents: building an on-prem AI email assistant ### Retrieval that agents depend on Agents are only as good as what they retrieve. I built hybrid product search on Solr 9, fusing BM25 and vector results with Reciprocal Rank Fusion, and a RAG pipeline for developer documentation. - Hybrid product search on Solr 9: BM25 + vectors + RRF in .NET, with an interactive visualiser - Building a RAG pipeline for developer knowledge discovery ## 3. Evidence: I Build the Tools Agents Use ### An MCP server that maps a codebase Coding assistants are good with the file you have open and poor at "who calls this stored procedure?" across a 40-project solution. I built a **Model Context Protocol server** that analyses C# solutions with Roslyn and SQL Server schemas through catalogue views, and exposes the results as more than 40 tools. Agents answer those questions from facts instead of guesses. - Giving AI assistants a map of your codebase: an MCP server for C# code and SQL Server schemas ### This site is agent-readable The portfolio you're reading has its own **MCP endpoint**, so any MCP client can search my projects and posts, plus `llms.txt` and `llms-full.txt` for models that read the web. - Connect an AI assistant to this site ### Memory, reach and habits My day-to-day setup gives every agent three things: an **Obsidian vault** as memory (decisions, runbooks, incidents), **MCP servers** as reach into real systems, and **Skills** as habits, so house style is applied every time rather than when someone remembers it. - Memory, reach and habits: an Obsidian vault, MCP and Skills ## 4. Evidence: I Run Teams of Coding Agents ### A standing agent team in Herdr Claude Code is the tech lead: it researches, finds the bug, discusses it with me, and delegates. Five Antigravity sessions are the developers, each owning one area of the codebase. GitHub Copilot CLI reviews everything first, and Codex gives the risky changes a second review. A standby agent takes over as lead when Claude hits its usage limit. They hand work to each other through Herdr's `hc send`, and the whole team is defined in one file. - My AI dev team lives in Herdr ### Spec-driven delivery with four agents For the email assistant, a plan of about **260 person-days** became a working foundation in **two days and 110 commits**: sign-in, roles, tenant separation, mailbox sync, AI classification and work items. That took a written spec with numbered requirements, a shared rule book, ownership per agent, a git worktree per task, and a lead that reviewed, built and tested before every merge. - How a spec, a rule book and a lead agent kept four coding agents in line ### Skill files that turn a sprint into two days A group of legacy background services moved to cross-platform .NET 10 worker services in two days. The agent didn't make that fast on its own: two stacked skills (a house style and a migration playbook) told it what "done" looks like, ending in a checklist that doubled as the reviewer's map. - Two days, not two sprints: migrating worker services to .NET 10 with skill files ### This site, built the same way This portfolio is a Next.js 16 front end and a .NET API with passkeys, an admin, content sync, live presence and a status page. Of its 166 commits, **105 were written with an AI agent** and carry its co-author line. Every one was reviewed and merged by me. ## 5. Evidence: I Measure, and People Stay in Charge The difference between agentic and reckless is proof. A few habits I hold to: - **Evals for AI behaviour.** Prompt and model changes run against a fixed evaluation set before and after. That's how the email classifier went from 26/35 to 41/43, and how we found that *less* thinking was both faster and more accurate. - **Measurements for performance.** When this site scored poorly on mobile, Lighthouse showed 25 seconds of blocking time. One "optimisation" an assistant proposed made it worse, and only a measurement caught it. The details are in the workflow post. - **Load tests before release.** Repeatable k6 and Grafana suites catch latency regressions before code reaches staging. - **Review by a different model, then by me.** Reviewers get checked too: one of Copilot's findings described a scenario that couldn't happen. - **Git and decisions stay human.** Agents propose, implement and report. Nothing is assigned until I agree, nothing merges until it's proven, and agents never commit or push. [!warning] What agentic is not It isn't "the AI wrote it, ship it". In every project above, agents did the repetitive work and a person owned the judgement: what to build, what counts as done, and what's safe to merge. ## 6. The Short Version ClaimProofNumber Builds agentic productsAgent platform audit30–40 s → ~13 s Runs agents on own hardware5090 vs DGX Spark~15 s vs ~41 s Measures AI behaviourEmail classifier evals26/35 → 41/43 Builds tools for agentsCode-intelligence MCP server40+ tools Leads agent teamsHerdr team9 agent sessions Delivers with agentsEmail assistant foundation~260 PD plan → 2 days Encodes conventions as skills.NET 10 migration2 days Dogfoods itThis site105 of 166 commits with an agent ## 7. What This Means for Your Team If you're bringing coding agents into a real codebase, the hard part isn't installing them. It's the spec they build against, the rules they can't break, the skills that carry your conventions, the review that catches what they miss, and the evals that tell you whether the AI got better or just different. That's the work I do. I'm happy to talk through how it would fit your team: work with me. --- ### Article 4: One Lead, Three Agents: Building an On-Prem AI Email Assistant with Claude Code, Codex, Cursor and Antigravity *Published: November 12, 2026 | Category: Artificial Intelligence | Reading Time: 6 min read* *Canonical URL: https://dhucar.in/blog/building-ai-email-assistant-with-a-team-of-coding-agents* *Tags: Claude Code, AI Agents, Ollama, LLMs, .NET Core* A 260 person-day plan, and in two days a working foundation in 110 commits. How a spec, one rule book, a team file and a lead agent kept four coding agents in line, and how we measured the local AI instead of trusting it. # One Lead, Three Agents: Building an On-Prem AI Email Assistant with Claude Code, Codex, Cursor and Antigravity November 12, 2026 · 6 min read · Artificial Intelligence Tags: Claude Code, AI Agents, Ollama, LLMs, .NET Core A 260 person-day plan, and in two days a working foundation in 110 commits. How a spec, one rule book, a team file and a lead agent kept four coding agents in line, and how we measured the local AI instead of trusting it. We're building an on-premises AI email assistant: it watches client mail in Microsoft 365, gives every actionable email an owner and a deadline, escalates when nobody answers, and drafts replies that a person must approve before anything is sent. The plan put the full product at about **260 person-days** across three phases. In the first **two days** we had the foundation and a working first slice in **110 commits**. The work was done by four coding agents, one of them acting as the lead. ## 1. The Team Every agent has a role, an area it owns, and a reviewer. That's all written in a team file at the root of the repository, so it's something the agents read rather than something I keep repeating: AgentRoleWhy it got that role **Claude Code**Lead: plans, delegates, reviews, builds, tests, mergesHolds the whole picture and the merge rights **Codex**Backend core and integrationsLong-running, well-specified backend tasks **Cursor**Architecture, AI, access control, securityCareful edits to sensitive code, close supervision **Antigravity**Front end and end-to-end testsBuilding and checking UI in a browser Reviews are paired, so no agent's work merges on its own word, and a person approves every merge. A short list of sensitive areas (authentication, anything that can send email, database migrations) always gets an extra review. ## 2. Four Documents That Make It Work ``` Spec what to build (numbered requirements, acceptance tests) Rule book how to build it (rules every agent reads first) Team file who builds what (ownership, reviewers, phases) Task briefs what to do next (one brief per agent) │ ▼ lead ─▶ worktree per task ─▶ agent ─▶ lead review ─▶ build + tests ─▶ merge │ handover file ◀── status ────┘ ``` - **The spec** has numbered requirements and acceptance tests. Commits, branches and pull requests reference requirement IDs. If code and spec disagree, the agent stops and asks. - **The rule book** is a single `AGENTS.md`. Each tool's own rules file points at it instead of copying it, so there's only one version. - **The team file** holds ownership, review pairs, sensitive areas and the phase plan. - **Task briefs** give each agent its requirements, the area it owns, what to reuse, its acceptance tests and its handoffs, plus a dependency graph showing who waits for whom. ## 3. Rules That Block a Merge An email assistant handles other companies' mail, so a few rules aren't style guidance. Breaking one blocks the merge, whatever else the change does. In general terms: - **Nothing is sent without a recorded human approval.** No background job or template can skip it. - **Deny by default.** Every endpoint checks permission and scope on the server. A hidden button is never the control. - **Tenants never mix.** No query, cache entry, log line or AI request may combine two clients' data, and that's enforced centrally, not left to each query. - **Email text is data, not instructions.** Nothing inside an email can change a rule or trigger an action. - **No secrets in the repository.** The rules are also tests. A test fails if any API endpoint has no authorization requirement, and every new endpoint ships with the same three: not signed in, wrong permission, wrong client. [!tip] Write rules an agent can check "Be careful with security" changes nothing. "Every endpoint declares its permission, or is explicitly anonymous with a comment saying why" is something an agent can follow, a test can enforce, and a reviewer can grep for. ## 4. How the Lead Runs the Agents Claude Code doesn't write most features. It writes the briefs, starts each agent in its own **git worktree** on its own branch, and runs every agent in a restricted mode: sandboxed edits and commands for one, edits only for another, nothing beyond accepted edits for the third. None of them commits, pushes or creates database migrations. They run in a terminal panel I can watch rather than as hidden background processes. ### The review routine Every agent result goes through the same steps before it merges: - Read the diff, and check it only touches the area that agent owns. - Run a quick scan for risky patterns that must come back empty: raw HTML injection, tokens in browser storage, bypassing the tenant filter, secrets. - Create database migrations centrally, one per merge, so parallel agents never produce conflicting ones. - Build with **zero warnings** (warnings are errors), and run the tests against a real database in a container, not a mock. - Take screenshots of new screens with a headless browser. - Commit with co-author lines for the agent, merge, run everything again on the integration branch, and report to the person in charge. [!note] Ownership produces honest handoffs One agent's status report listed what it hadn't done and why: the tests it needed were in an area another agent owned, so it left them alone and wrote down the missing cases for the owner. Without ownership rules, it would have just edited the other agent's files. ## 5. Surviving Token Limits A lead running for two days will hit its usage limit. When that happens, **another agent takes over as backup lead**. Continuity lives in one handover file the lead keeps current: what's merged and the test counts, which agent is on which branch, where each one is running, the review routine, and the safe launch command for each agent. Its first lines set the limits: do nothing without a person's go-ahead, never push, never delete work that isn't merged. The handover file was also useful between my own sessions. Anyone could pick up the work from a single page. ## 6. The AI Part: Measured, Not Assumed Classification runs on a **local model served by Ollama**, because client mail can't leave the building. The classifier decides category, priority, whether a reply is needed, whether the mail is automated noise, any deadline asked for, whether it's a chaser, and whether the client is saying "it's done". Prompt changes are judged by a small evaluation set: invented emails (never real ones), each with the expected answer. On `qwen3:8b`: PromptThinkingScoreAvg time v5default26 / 35— v6default26 / 3743 s, timeouts v6low35 / 374 s v6none33 / 371 s v7 (whole-conversation summary)low**41 / 43**4.1 s The biggest gain didn't come from the prompt. It came from **turning thinking down**: with default reasoning the model ran for 43 seconds and timed out, and with `low` it was both faster and more accurate. The two remaining misses are written down, not hidden. [!warning] Treat the model as untrusted input The AI only classifies and drafts. It can't send, close or reassign anything, and instructions inside an email are treated as text. Even a perfect score wouldn't change that. ## 7. What Two Days Produced - **Foundation:** .NET 10 APIs, PostgreSQL, Redis, Angular apps, everything in Docker Compose with live reload. - **Sign-in and access:** single sign-on with MFA, passkeys, server-side sessions, roles with scoped permissions, and tenant separation enforced in the data layer. - **Mail:** Microsoft Graph delta sync, client identification, one conversation across several people's inboxes. - **Work:** AI classification, a conversation summary updated on every message, work items with business-hours deadlines, routing, snooze and reassign, notifications, and an audit log. That's not the whole product. Drafting and approval, escalation and the client portal are later phases. But the foundation is the part that usually takes weeks, and every later feature depends on it being right. ## 8. Takeaways - **Write the spec first.** Numbered requirements and acceptance tests give agents something to build against and reviewers something to check. - **One rule book** that every tool points at, and **one team file** for ownership and review pairs. - **Pick agents by strength**, give each its own area and worktree, and run them in restricted modes. - The lead's job is **review, integration and proof**: pattern scans, zero-warning builds, real-database tests, screenshots. - Keep a **handover file** so anyone can take over mid-flight. - **Measure the AI** with an eval set before and after every prompt or model change. The same idea at a smaller scale is in migrating worker services to .NET 10 with skill files, and the day-to-day version with Herdr is in my AI dev team in Herdr. --- ### Article 5: Two Days, Not Two Sprints: Migrating Worker Services to .NET 10 with Skill Files and Coding Agents *Published: November 11, 2026 | Category: Artificial Intelligence | Reading Time: 8 min read* *Canonical URL: https://dhucar.in/blog/migrating-worker-services-to-dotnet-10-with-skills-and-coding-agents* *Tags: .NET Core, Background Services, Skills, Claude Code, Migration* Legacy background services moved to cross-platform .NET 10 worker services in two days. The coding agent did the typing; two stacked skill files, a house style and a migration playbook, told it what done looks like. # Two Days, Not Two Sprints: Migrating Worker Services to .NET 10 with Skill Files and Coding Agents November 11, 2026 · 8 min read · Artificial Intelligence Tags: .NET Core, Background Services, Skills, Claude Code, Migration Legacy background services moved to cross-platform .NET 10 worker services in two days. The coding agent did the typing; two stacked skill files, a house style and a migration playbook, told it what done looks like. Many teams still run background services on older .NET versions: Windows-only, tied to hard-coded server paths, logging every step straight to disk, and guarding against overlapping runs with a plain `bool`. Migrating them by hand often takes a sprint per service, because each one has its own history. We moved a group of them to **.NET 10 worker services** in **two days**. The speed didn't come from the agent typing faster. It came from **skill files** that told the coding agent exactly what "done" looks like. ## 1. Why Agents Alone Weren't Enough Ask a coding agent to "upgrade this worker to .NET 10" and you get a tutorial answer: a fresh `BackgroundService`, a generic logger, maybe a new ORM. It compiles, and it looks nothing like the rest of the solution. Pulling that output back in line with your conventions takes longer than doing the migration yourself. A migration at this scale needs three things the model doesn't have: - **The target shape:** how your layers, logging, configuration and data access are meant to look. - **The migration traps:** what breaks when old code meets .NET 10 and Linux. - **A definition of done:** a checklist the agent verifies before it says it's finished. A skill is how you hand an agent all three, once, instead of re-typing them in every prompt. ## 2. Two Skills, Stacked ``` House-style skill (how we write .NET) layering, naming, DI style, logging, data access, response and error conventions, review checklist │ reused by ▼ Worker migration skill (how we move a worker to .NET 10) target framework + runtimes, hosting, scheduling, logging adapter, paths, deployment, checklist │ ▼ Coding agent: orient → convert → build → checklist → PR ``` The **house-style skill** came first. It describes how a .NET service is written in your codebase: which layers exist and what each may do, how dependencies are registered, which logger to inject, how data access is done, and how errors are handled. Most teams already have these rules. They just live in people's heads and in old pull-request comments. The **migration skill** builds on it. A worker is the same layered code with a timer instead of an HTTP request, so it reuses the house rules and adds only what's specific to background services and to the upgrade itself. [!tip] Distil skills from real code Write the skill from your best existing service, not from documentation. "This is how our best service does it" is something an agent can copy faithfully. "Follow best practices" isn't. ## 3. Step Zero: Orient Before Editing The most useful section of a migration skill is the first one. Before touching a file, the agent answers a fixed set of questions about the project in front of it: - Does the service depend on shared library projects? If other services still use those libraries, they need to target both frameworks for a while. - Which packages does it use? `System.Data.SqlClient` is deprecated in favour of `Microsoft.Data.SqlClient`, and `Microsoft.Extensions.*` packages move to 10.x. - Does anything use `System.Drawing.Common`? Since .NET 7 it's Windows-only, so image or document rendering has to move to a cross-platform library or sit behind an OS check. - Where are the hard-coded Windows paths, the schedule interval, and any loop over tenants or sites? This stops the agent assuming every service matches the reference one. It also means each pull request opens with a short inventory, so review starts with what the agent found rather than with a diff. ## 4. What the Migration Changes ### One project file for every platform Each service targets `net10.0` with the worker SDK and declares the runtimes it can be published for: ``` net10.0 enable win-x64;win-x86;win-arm64;linux-x64;linux-arm64;linux-arm ``` ### A host that knows where it's running `Program.cs` moves to `Host.CreateApplicationBuilder` and picks the right service integration at startup, so the same build runs as a Windows Service or a systemd daemon: ``` var builder = Host.CreateApplicationBuilder(args); if (OperatingSystem.IsWindows()) { builder.Services.AddWindowsService(o => o.ServiceName = "ReportWorker"); } else if (OperatingSystem.IsLinux()) { builder.Services.AddSystemd(); } builder.Services.Configure(builder.Configuration.GetSection("Worker")); builder.Services.AddScoped(); builder.Services.AddHostedService(); var host = builder.Build(); host.Services.GetRequiredService>().LogInformation( "Starting on {OS} [{Arch}], .NET {Runtime}", RuntimeInformation.OSDescription, RuntimeInformation.ProcessArchitecture, Environment.Version); await host.RunAsync(); ``` That startup line seems minor until a service is quietly running as x86 on a 64-bit machine. It answers "what is this actually running on?" from the first log line. ### PeriodicTimer and a real reentrancy guard Older workers often use a timer callback plus a `bool isRunning` flag to skip a tick while the previous run is still going. That flag isn't thread-safe. The migrated `Worker` uses `PeriodicTimer`, a `SemaphoreSlim` and a fresh DI scope per tick: ``` protected override async Task ExecuteAsync(CancellationToken stoppingToken) { using var timer = new PeriodicTimer(_options.Interval); await RunOnceAsync(stoppingToken); // run once at start while (await timer.WaitForNextTickAsync(stoppingToken)) { await RunOnceAsync(stoppingToken); } } private async Task RunOnceAsync(CancellationToken token) { if (!await _gate.WaitAsync(0, token)) // previous run still going { _logger.LogWarning("Previous run still in progress, skipping this tick."); return; } try { using var scope = _scopeFactory.CreateScope(); // fresh services per tick await scope.ServiceProvider.GetRequiredService().RunAsync(token); } catch (Exception ex) when (ex is not OperationCanceledException) { _logger.LogError(ex, "Run failed"); } finally { _gate.Release(); } } ``` Stopping the service now cancels the wait instead of waiting for the next tick, and a slow run can never overlap the next one. ### One bad item doesn't stop the batch If a worker loops over tenants, customers or files, the skill requires each one to run inside its own `try/catch`. One tenant's bad data logs an error and the loop moves on to the next. ## 5. The Logging Trick: Adapt, Don't Rewrite Legacy services often have dozens of calls to an old logging helper, each one writing a line to disk synchronously. In a loop that runs every few seconds, that's a lot of I/O for logs nobody reads unless something fails. Rewriting every call site is the slow, risky part of a migration. Instead, the skill tells the agent to change only the helper's body and route it to a **buffered step logger**: ``` // The old helper keeps its signature, so no caller changes. public void LogStep(string message, string method) { _steps.Add(method, message); // in memory: no disk write on the happy path } ``` The step logger keeps a bounded list of steps (say, the last 100) for the current run. On success they're discarded. When something throws, the error log includes the whole chain of steps that led to the failure, in order. The happy path stops writing to disk, a failure gets a more complete log than before, and none of the existing callers changed. [!note] This is where stacking skills pays off If the house-style skill already defines how services log, the migration skill just points to it. The agent doesn't invent yet another logging approach, and API and worker logs read the same way. ## 6. Cross-Platform Paths and Deployment Old configuration files are often full of absolute Windows paths like `D:\Logs\MyService\`. On Linux these don't fail loudly: they create a folder literally named `D:\Logs\MyService\` next to the binary. The rule is simple: no drive letters or backslashes in code, build paths with `Path.Combine` from `AppContext.BaseDirectory`, and override them per environment: ``` Worker__LogPath=/var/log/report-worker/ ``` The skill also includes the deployment recipes, so the agent finishes each service with all three ready: - **Windows Service** via `sc.exe create`, as before. - **systemd unit** with `Type=notify` and `Restart=always`, which works because of `AddSystemd()`. - **Multi-arch Dockerfile** using `--platform=$BUILDPLATFORM` and `TARGETARCH`, so one build produces AMD64 and ARM64 images. ``` dotnet publish -c Release -r linux-arm64 --self-contained true -p:PublishSingleFile=true -o ./publish/linux-arm64 ``` ## 7. The Checklist Is the Definition of Done Each skill ends with a checklist, and the agent is told to go through it before calling a service finished. A typical migration checklist: - Targets `net10.0`, declares runtime identifiers, and no deprecated data-access package is left. - The host registers Windows Service and systemd support and logs OS, architecture and runtime at startup. - No hard-coded Windows paths remain. - `PeriodicTimer` plus `SemaphoreSlim`, with no unsynchronised "is running" flag. - Every tenant or item in a batch has its own error boundary. - The code follows the house-style skill's checklist too. - Publishes for every target runtime. The checklist is what made review fast. Instead of reading every diff from scratch, a reviewer confirms the agent's checklist against the code and spends their attention on the business logic, which is the part only someone who knows the system can judge. ## 8. The Loop - **Write the skills from the best existing code.** Start with your house style, then the migration on top of it. - **Migrate one service with the agent and watch closely.** Every place the agent guessed becomes a new rule in the skill. - **Run the agent across the remaining services**, one branch each: orient, convert, build, publish for each runtime, run the checklist. - **Review against the checklist**, then run each service side by side with the old one before switching over. - **Feed corrections back into the skill**, so the next service needs fewer of them. [!warning] Fast doesn't mean unreviewed The agent did the repetitive work: project files, hosting, timers, logging adapters, paths and deployment files. People still reviewed every pull request and checked each service against the one it replaced. Two days was possible because the review was focused, not because there wasn't one. ## 9. Takeaways - Agents are fast but generic. A **skill** turns "upgrade to .NET 10" into "upgrade to .NET 10 *the way this codebase does things*". - **Stack skills.** A migration skill that reuses your house-style skill keeps every service consistent. - Make **orientation** the first step, so the agent inventories each project before changing it. - **Adapt legacy call sites** instead of rewriting them. One method body change beats hundreds of edits. - End every skill with a **checklist**. It's the agent's definition of done and the reviewer's map. - Every correction belongs in the skill, not in the next prompt. For the wider workflow these skills belong to, see how I use an Obsidian vault, MCP and Skills, and for the worker basics, the dynamic background service manager in .NET 8. --- ### Article 6: RTX 5090 vs DGX Spark for a Local AI Agent: Why Memory Bandwidth Won *Published: October 18, 2026 | Category: Artificial Intelligence | Reading Time: 2 min read* *Canonical URL: https://dhucar.in/blog/rtx-5090-vs-dgx-spark-local-llm-inference* *Tags: LLMs, GPUs, Ollama, Performance, Self-hosted AI* Same model, same Ollama version, same request: the RTX 5090 answered in ~15 seconds and the DGX Spark in ~41. Here is why bandwidth, not memory size, decided it, and when the Spark is still the right box. # RTX 5090 vs DGX Spark for a Local AI Agent: Why Memory Bandwidth Won October 18, 2026 · 2 min read · Artificial Intelligence Tags: LLMs, GPUs, Ollama, Performance, Self-hosted AI Same model, same Ollama version, same request: the RTX 5090 answered in ~15 seconds and the DGX Spark in ~41. Here is why bandwidth, not memory size, decided it, and when the Spark is still the right box. We had an NVIDIA DGX Spark to evaluate for our self-hosted AI agent, and an RTX 5090 workstation already running it. On paper the Spark looks like the bigger machine: four times the memory. In practice, for the model we actually run, the RTX 5090 answered the same question in roughly a third of the time. ## 1. A Fair Test The DGX Spark ships without models preloaded, so both machines were set up the same way: - **Model:** Gemma 4 26B on both. - **Runtime:** Ollama 0.31.1 on both. - **Workload:** the same agent request (prompt, conversation history and tool definitions), measured end to end. ## 2. Results MetricRTX 5090DGX Spark Response time (same request)~15 s~41 s Relative response time1×2.73× slower Extra waiting time—~26 s [!success] The RTX 5090 finished in about 63% less time For this workload the DGX Spark brought no speed-up over the workstation. ## 3. Why: Bandwidth Beats Capacity When the Model Fits HardwareRTX 5090DGX Spark (GB10) Memory32 GB GDDR7128 GB unified LPDDR5x Memory bus512-bit256-bit Data rate per pin28 Gbps~8.533 Gbps Memory bandwidth1,792 GB/s~273 GB/s Capacity1×4× Bandwidth~6.6×1× An answer comes in two phases. **Prefill** reads the prompt, the conversation history and every tool definition. **Generation** then produces the answer one token at a time, and every token means streaming the model's weights through memory again. That second phase is limited by memory bandwidth far more than by compute. Gemma 4 26B fits comfortably in the RTX 5090's 32 GB, so the Spark's extra capacity buys nothing here, while the 5090 moves data about 6.6 times faster. That bandwidth gap is the most likely reason for the result. [!note] What we did not measure We timed the whole response, not prefill and generation separately, and this was one request per machine. The direction of the result is clear; the exact ratio will move with prompt length, output length and quantization. ## 4. When the DGX Spark Is the Right Box 128 GB of unified memory is a real advantage when the workload does not fit in 32 GB: - Larger models that would not load on a single consumer GPU at all. - Much longer context windows, where the KV cache grows with every token of history. - Several models resident at once (for example an embedding model, a reranker and a chat model). Choose for the model you will actually run: if it fits in GPU memory, bandwidth decides speed; if it does not, capacity decides whether it runs at all. ## 5. What We Test Next - NVIDIA-native models from NVIDIA's model registry, which may be better optimised for the Spark's hardware. - Separate timings for prefill and generation, so each machine's strength is visible on its own. - A change to how the model runs on the server that could make answers roughly twice as fast at the same quality, tested on our own hardware before it goes anywhere else. ## 6. Takeaways - For local LLM inference, check memory bandwidth before memory size. - More memory only helps once the model, or its context, no longer fits. - Benchmark with your own model, runtime version and real requests; spec sheets don't tell you the answer for your workload. --- ### Article 7: Memory, Reach and Habits: How I Use an Obsidian Vault, MCP and Skills to Ship Production-Grade Code *Published: September 26, 2026 | Category: Artificial Intelligence | Reading Time: 6 min read* *Canonical URL: https://dhucar.in/blog/ai-development-workflow-obsidian-mcp-skills* *Tags: MCP, Obsidian, Claude Code, Skills, Performance* AI assistants write code quickly but know nothing about my systems. My workflow gives them three things: an Obsidian vault as memory, MCP servers as reach, and Skills as habits. Then nothing ships until it's measured. # Memory, Reach and Habits: How I Use an Obsidian Vault, MCP and Skills to Ship Production-Grade Code September 26, 2026 · 6 min read · Artificial Intelligence Tags: MCP, Obsidian, Claude Code, Skills, Performance AI assistants write code quickly but know nothing about my systems. My workflow gives them three things: an Obsidian vault as memory, MCP servers as reach, and Skills as habits. Then nothing ships until it's measured. An AI assistant can write a controller in seconds. What it can't do on its own is know why we chose one database per tenant, how a failed deploy was fixed last month, or what every API response in our house style looks like. Most "the AI wrote bad code" moments are really missing context. My workflow is built around closing that gap: an **Obsidian vault** as the assistant's memory, **MCP servers** as its reach into my systems, and **Skills** as its habits. Then one rule on top: nothing ships until it has been measured. ## 1. The Problem: Speed Without Context Assistants are fast and fluent, and that makes their gaps easy to miss. Left alone, they invent conventions, forget decisions made three weeks ago and declare a fix done because it compiles. Production-grade work needs three things a model doesn't bring with it: - **Context:** the decisions, trade-offs and incidents behind the code. - **Conventions:** how things are done here, applied every time rather than when remembered. - **Proof:** evidence that a change works, from a build, a test or a measurement. ## 2. The Stack at a Glance ``` Obsidian vault ─▶ Obsidian MCP server ──┐ (ADRs, runbooks, │ project notes, prompts) │ ├──▶ Claude · Claude Code · Antigravity Code + SQL Server ─▶ code-intel MCP ─────┤ │ │ ▼ Skills (house style, doc formats) ───────┘ branch ─▶ build ─▶ test ─▶ measure ─▶ PR │ vault updated (ADR, runbook) ◀── merge ◀───┘ ``` ## 3. The Vault: Memory My Obsidian vault is where decisions live. It has four kinds of notes, and each one answers a different question an assistant would otherwise guess at: - **Architecture notes and ADRs** answer *why is it built like this?* One note per decision: the context, the options, what we chose and what it costs. - **Runbooks and incidents** answer *what went wrong before?* Deploy steps, production fixes and post-mortems. - **Project and R&D notes** answer *what exists and how does it connect?* One note per project or experiment, linked by the technologies they share. - **Prompts and AI context** answer *how should the assistant work here?* Reusable prompts, conventions and the context I hand to every session. Short, consistently shaped notes matter more than long ones. A decision note in this shape is easy for a person to skim and easy for a model to use: ``` # ADR: One database per workspace Status: accepted Context: tenants must never see each other's data; removing a tenant must be trivial Decision: each workspace gets its own database, named after the workspace Consequences: + isolation by construction, + delete = drop database - one provisioning step per new workspace Links: [[MongoDB]] [[Multi-tenancy]] [[MCP server for code intelligence]] ``` [!tip] Link notes by technology Links are what turn a folder of notes into a map. The knowledge graph on this site is modelled on the vault's graph view: projects, experiments and posts connected through the technologies they share. ## 4. MCP: Reach The Model Context Protocol is how the assistant reaches that memory and my systems without me pasting anything. Three servers do most of the work: - **Obsidian MCP server:** the assistant searches and reads the vault directly. "Check the ADRs before changing tenant storage" becomes something it can actually do. - **Code-intelligence MCP server:** the server I built that maps C# solutions with Roslyn and SQL Server schemas through catalogue views, exposed as 40+ tools. It answers "who calls this stored procedure?" from facts instead of guesses. The full write-up is here. - **This portfolio's own MCP endpoint:** the same idea pointed outwards. Any MCP client can query my projects and posts. [!warning] Reach is not permission An MCP server can read far more than a task needs. Scope each one to what it serves, keep secrets out of notes, and treat anything an assistant reads from outside as data, not instructions. ## 5. Skills: Habits A convention that lives only in a senior developer's head gets applied when someone remembers it. A Skill packages it so the assistant applies it every time it's relevant. - **My .NET API skill** encodes our house style for Web APIs: Controller, business layer, data layer and DTOs; convention-based dependency injection; structured logging; global exception handling; JWT authentication; and one uniform response envelope. "Add an endpoint" now produces code that matches the rest of the codebase instead of a generic tutorial. - **Document skills** for PDF, Word, Excel and PowerPoint handle the non-code side: specs, reports and client documents, in formats people actually open. [!note] Next skills The vault already holds the raw material for more: runbooks that can become deployment checklists, and incident notes that can become a review checklist for the mistakes we have already made once. ## 6. The Tools - **Claude**, with MCP servers and Skills attached, for design, research and writing: reading the vault, querying the code map, drafting ADRs. - **Claude Code** for changes to a repository: it works on a branch, runs the build, the type checker and the tests, and opens a pull request. - **Antigravity** for agent-driven work inside the editor. The tools matter less than what they are connected to. The same model is a different assistant with the vault, the code map and the house style behind it. ## 7. Production-Grade Means Measured A case study from this site. PageSpeed Insights scored the pages poorly on mobile. The workflow was: measure, find the cause, change one thing, measure again, and compare against `main`. - **Measure:** Lighthouse with mobile settings showed about **25 seconds of Total Blocking Time** on every page. - **Find the cause:** a WebGL fluid background redrew every frame from page load. With it switched off, the home page went from 48 to 83. - **Fix, then re-measure:** start the effect on the first interaction, paint content without waiting for JavaScript, self-host fonts and remove a 100 KB inlined image. Blocking time dropped to a few hundred milliseconds across the site. - **Check the claim:** Lighthouse varies by about five points run to run, so every later feature was compared against `main` in alternating runs, and browser tests confirmed it behaved the same afterwards. [!danger] The first fix isn't always a fix One "optimisation", putting an animated element on its own compositor layer, made the score worse on a phone without a GPU. Only a measurement caught it, and it was reverted. An assistant that says "this should be faster" has made a prediction, not a result. ## 8. The Loop - Write down the decision or the problem in the vault. - The assistant reads the relevant notes through MCP, and the code map for the parts of the system involved. - Skills shape the change so it matches the house style. - The agent implements it on a branch and proves it: types, build, tests, and a measurement where performance is involved. - Review and merge the pull request. - Update the vault: a new ADR, a runbook step, or an incident note. The next session starts with more context than this one did. ## 9. Takeaways - Most bad AI output is missing context. Give the assistant **memory** (a vault), **reach** (MCP) and **habits** (Skills). - Keep notes short, consistently shaped and linked. Structure is what makes them usable by a model. - Encode conventions once as a Skill instead of repeating them in every prompt. - Production-grade means measured: build, test, and compare against a baseline before claiming anything. - Close the loop. Every merged change should leave the vault a little smarter. --- ### Article 8: Giving AI Assistants a Map of Your Codebase: An MCP Server for C# Code and SQL Server Schemas *Published: September 23, 2026 | Category: Artificial Intelligence | Reading Time: 14 min read* *Canonical URL: https://dhucar.in/blog/mcp-server-code-database-intelligence* *Tags: MCP, Roslyn, .NET Core, MongoDB, SQL Server* How I built a Model Context Protocol server that analyses C# solutions with Roslyn and SQL Server schemas through catalogue views, stores a structured map in MongoDB per workspace, and exposes it to AI assistants as 40+ tools. # Giving AI Assistants a Map of Your Codebase: An MCP Server for C# Code and SQL Server Schemas September 23, 2026 · 14 min read · Artificial Intelligence Tags: MCP, Roslyn, .NET Core, MongoDB, SQL Server How I built a Model Context Protocol server that analyses C# solutions with Roslyn and SQL Server schemas through catalogue views, stores a structured map in MongoDB per workspace, and exposes it to AI assistants as 40+ tools. AI coding assistants are great with the file you have open and poor at answering questions about a 40-project solution they have never seen: "Who calls this stored procedure?", "Which tables does cancelling an order touch?", "What does this DTO look like?". This post walks through an MCP server I built to fix that. It reads C# solutions with Roslyn and SQL Server schemas through system views, stores a structured map of both in MongoDB, and exposes that map to any AI assistant as more than 40 Model Context Protocol tools. ## 1. The Problem: Context, Not Intelligence A language model can reason about code perfectly well. What it lacks in a large legacy system is the *map*: which class lives in which project, which methods call which stored procedures, which tables those procedures read and write. Pasting files into a chat doesn't scale, and plain text search misses what a name *means*. `Order` the class, `Order` the table and `order` the variable all look the same to grep. The approach: **precompute the map once, keep it fresh on a schedule, and let the assistant query it** instead of guessing. The Model Context Protocol (MCP) is the standard way to plug that kind of query surface into Claude, Copilot, Cursor or any other MCP client. ## 2. Architecture at a Glance ``` Source repositories ──┐ ├──▶ Sync worker ──▶ Roslyn analyzer ────────┐ SQL Server database ──┘ (per workspace) Schema extractor ───────┤ ▼ MongoDB (one database per workspace) │ AI assistant ◀──── MCP endpoint /{workspace}/mcp ◀─── tool executor ┘ ``` - **Sync worker**: a background service that, per workspace and on a schedule, downloads the source, analyses it and extracts the database schema. - **Roslyn analyzer**: turns every class and method into structured metadata: signatures, dependencies, stored procedures used, complexity and documentation. - **Schema extractor**: reads tables, columns, keys, indexes and stored procedures from SQL Server's catalogue views. - **MongoDB**: one database per workspace, holding classes, methods, method source, tables and stored procedures. - **MCP endpoint**: JSON-RPC over HTTP at `/{workspace}/mcp`, backed by a single tool executor. - **Blazor dashboard**: workspaces, sync status and live logs for whoever operates it. ## 3. Step 1: Fetching Source Without a Working Copy The server never keeps a clone. Each sync asks the Git host's REST API for the repository's full item list (optionally on a specific branch), then downloads every file into a directory created for that run only: ``` // 1. List every item in the repository (optionally on a given branch) var itemsUrl = $"{baseUrl}/repositories/{repoId}/items" + $"?scopePath=/&recursionLevel=Full{branchFilter}"; // 2. Download each file into a throwaway directory for this sync run foreach (var item in items.Where(i => !i.IsFolder)) { var localPath = Path.Combine(repoDir, item.Path.TrimStart('/')); Directory.CreateDirectory(Path.GetDirectoryName(localPath)!); var bytes = await http.GetByteArrayAsync(FileUrl(repoId, item.Path)); await File.WriteAllBytesAsync(localPath, bytes); } ``` ``` var workDir = Path.Combine(Path.GetTempPath(), $"code-sync_{Guid.NewGuid():N}"); Directory.CreateDirectory(workDir); try { // download → analyze → extract schema → save } finally { Directory.Delete(workDir, recursive: true); // nothing left on disk, even on failure } ``` [!tip] Three small decisions keep this robust The temp directory has a GUID in its name, so overlapping runs can never collide. Cleanup sits in `finally`, so a failed run leaves nothing behind. And a missing branch returns "skip this repository" instead of an exception, so one misconfigured repo doesn't cancel the whole sync. ## 4. Step 2: Understanding the Code with Roslyn Regexes can find the word `class`. Roslyn, the C# compiler as a library, knows what every identifier *binds to*. The analyzer loads each solution through `MSBuildWorkspace`, compiles each project, and walks every document: ``` // Once per process: point Roslyn at an installed MSBuild if (!MSBuildLocator.IsRegistered) MSBuildLocator.RegisterDefaults(); var workspace = MSBuildWorkspace.Create(); workspace.WorkspaceFailed += (_, e) => logger.LogWarning(e.Diagnostic.Message); foreach (var slnPath in Directory.GetFiles(sourceDir, "*.sln", SearchOption.AllDirectories)) { var solution = await workspace.OpenSolutionAsync(slnPath); foreach (var project in solution.Projects) { if (await project.GetCompilationAsync() is null) continue; foreach (var document in project.Documents.Where(d => d.FilePath!.EndsWith(".cs"))) { var root = await document.GetSyntaxRootAsync(); // what the code says var model = await document.GetSemanticModelAsync(); // what it means foreach (var cls in root!.DescendantNodes().OfType()) results.Add(Describe(cls, model!, project, slnPath)); } } } ``` The key distinction is **syntax tree vs semantic model**. The syntax tree is the shape of the text: this is a class declaration, that is a method call. The semantic model is what the compiler concluded: this identifier is the type `OrderRepository` from the `Shop.Data` assembly. Almost everything useful below comes from the semantic model. ### What gets extracted per class Each class becomes one document with its methods nested inside. The ID combines namespace, class, project and file, so the same class name in two projects stays distinct: ``` { "_id": "Shop.Orders.OrderService@Shop.Orders:OrderService.cs", "className": "OrderService", "namespace": "Shop.Orders", "project": "Shop.Orders", "solution": "Shop.sln", "layer": "Application", "type": "Service", "documentation": "Creates, prices and cancels orders.", "baseTypes": ["IOrderService"], "dependencies": [ { "target": "OrderRepository", "project": "Shop.Data", "referenceType": "ProjectReference" } ], "methods": [ { "methodName": "CancelOrderAsync", "returnType": "Task", "parameters": [{ "name": "orderId", "type": "int" }], "storedProcedures": ["usp_CancelOrder"], "cyclomaticComplexity": 4, "linesOfCode": 21 } ] } ``` ### Dependencies from the semantic model For every identifier in a class, ask the semantic model which type it refers to. Framework types are skipped, and only types defined in the solution's own projects are kept, labelled as same-project or cross-project references: ``` foreach (var id in cls.DescendantNodes().OfType()) { // Ask the semantic model what this name actually refers to if (model.GetSymbolInfo(id).Symbol is not INamedTypeSymbol type) continue; if (type.ContainingNamespace?.ToString().StartsWith("System") == true) continue; // Keep only types that live in this solution's own projects var owner = solution.Projects.FirstOrDefault(p => p.AssemblyName == type.ContainingAssembly?.Name); if (owner is null) continue; deps.TryAdd($"{type.Name}:{owner.Name}", new DependencyInfo { Target = type.Name, Project = owner.Name, ReferenceType = owner.AssemblyName == model.Compilation.Assembly.Name ? "SameProject" : "ProjectReference", }); } ``` That turns "what does this class depend on?" into an exact answer across project boundaries, which plain text search cannot give. ### Stored procedures, found where they are named In data-heavy .NET code, stored procedure names usually appear as string literals passed to `SqlCommand` or Dapper. Scanning each method's string literals for procedure-style names links C# methods to database logic, and that link powers tools like "who calls this procedure?": ``` var names = method.DescendantNodes() .OfType() .Where(l => l.IsKind(SyntaxKind.StringLiteralExpression)) .Select(l => l.Token.ValueText) .Where(s => Regex.IsMatch(s, @"^(sp_|usp_|proc_)[A-Za-z0-9_]+$", RegexOptions.IgnoreCase)) .Distinct(); ``` ### Complexity and size Cyclomatic complexity is 1 plus the number of decision points. With a syntax tree that is a count of node types. Lines of code skip blanks and comments. Together they let an assistant answer "where are the riskiest methods?": ``` int complexity = 1 + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType().Count() + method.DescendantNodes().OfType() .Count(b => b.IsKind(SyntaxKind.LogicalAndExpression) || b.IsKind(SyntaxKind.LogicalOrExpression)); ``` ### Documentation, layer and type XML doc comments come from the symbol (`GetDocumentationCommentXml()`) with the `` extracted. Layer and type are inferred from conventions: namespaces containing `.Api`, `.Application`, `.Infrastructure` or `.Domain`, and class names ending in `Controller`, `Service`, `Repository`, `Dto` or `Request`. Cheap heuristics, but they make questions like "list the infrastructure classes in project X" possible. ### Method source, stored separately The full source of every method is saved in its own collection, keyed by file and method name. Metadata documents stay small and fast to scan, and `get_method_source` can still hand the assistant the exact code when it needs it, instead of the assistant guessing at an implementation from its signature. ## 5. Step 3: Reading the Database Schema SQL Server describes itself. `INFORMATION_SCHEMA.TABLES`, `COLUMNS`, `ROUTINES` and `PARAMETERS` give tables, columns, procedure definitions and parameters. The `sys.*` catalogue views fill in what the standard views don't cover, such as foreign keys and indexes: ``` SELECT fk.name AS ForeignKey, c.name AS ColumnName, rt.name AS ReferencedTable, rc.name AS ReferencedColumn FROM sys.foreign_keys fk JOIN sys.foreign_key_columns fkc ON fk.object_id = fkc.constraint_object_id JOIN sys.columns c ON fkc.parent_object_id = c.object_id AND fkc.parent_column_id = c.column_id JOIN sys.tables t ON fk.parent_object_id = t.object_id JOIN sys.tables rt ON fk.referenced_object_id = rt.object_id JOIN sys.columns rc ON fkc.referenced_object_id = rc.object_id AND fkc.referenced_column_id = rc.column_id WHERE t.name = @TableName; ``` With foreign keys and procedure definitions stored next to the code metadata, the assistant can follow a feature end to end: controller → service → stored procedure → tables → related tables. ## 6. Step 4: Storing the Map in MongoDB Code metadata is naturally nested (class → methods → parameters) and its shape changes as the analyzer learns new tricks, so a document store fits better than a relational schema. Every write is an **idempotent upsert** keyed on a natural identity: class ID for classes, schema plus name for tables and procedures. Re-running a sync updates in place instead of duplicating: ``` var ops = tables.Select(t => new ReplaceOneModel( Builders.Filter.And( Builders.Filter.Eq(x => x.Schema, t.Schema), Builders.Filter.Eq(x => x.TableName, t.TableName)), t) { IsUpsert = true }); await collection.BulkWriteAsync(ops); // one round trip, safe to re-run ``` One ordering detail matters: class metadata is saved *before* the database step runs. If the SQL server is unreachable, the code map is still updated, and a partial sync beats an all-or-nothing one. ## 7. Multi-Tenancy: One Server, Many Workspaces One deployment serves several independent codebases. Each **workspace** is a document describing what to sync and how often: ``` { "name": "shop-platform", // also the MongoDB database name "repositories": ["shop-api", "shop-admin"], "branch": "main", "dbConnectionString": "Server=…;Database=ShopDb;…", "dbName": "ShopDb", "syncFrequencyMinutes": 240, "status": "Pending", // Pending → Active → Pending | Failed | Disabled "lastRunUtc": "2026-09-23T04:00:00Z", "nextRunUtc": "2026-09-23T08:00:00Z" } ``` Each workspace gets its **own MongoDB database**, named after the workspace, so data never mixes and removing a workspace is a single drop. A provisioner creates the database and its collections the first time a workspace syncs. At request time a scoped `TenantProvider` carries the workspace name taken from the URL, and every Mongo access resolves its database through it: ``` public class TenantProvider : ITenantProvider // registered as Scoped { public string? DatabaseName { get; set; } } public IMongoDatabase GetDatabase() => _client.GetDatabase(_tenant.DatabaseName ?? _settings.DefaultDatabase); [HttpPost("{workspace}/mcp")] public async Task Mcp(string workspace) { _tenant.DatabaseName = workspace; // every query in this request now targets that workspace … } ``` The MCP URL itself selects the workspace: `https://host/shop-platform/mcp` and `https://host/billing/mcp` are two different code maps behind the same server. ## 8. Scheduling Syncs A single `BackgroundService` wakes every minute, finds workspaces that are due, and runs them one by one with a small state machine: *Pending → Active → Pending*, or *Failed* on error, with *Disabled* to pause one: ``` protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { using var scope = _scopeFactory.CreateScope(); var configs = await scope.ServiceProvider .GetRequiredService().GetAllAsync(); foreach (var cfg in configs.Where(c => c.Status != Status.Disabled && (c.NextRunUtc is null || c.NextRunUtc <= DateTime.UtcNow))) { try { await MarkAsync(cfg, Status.Active); await _provisioner.ProvisionAsync(cfg); // create database + collections if new await RunSyncForWorkspaceAsync(cfg, stoppingToken); cfg.LastRunUtc = DateTime.UtcNow; cfg.NextRunUtc = cfg.LastRunUtc.Value.AddMinutes(cfg.SyncFrequencyMinutes); await MarkAsync(cfg, Status.Pending); } catch (Exception ex) { await MarkAsync(cfg, Status.Failed); // one bad workspace doesn't stop the others _logger.LogError(ex, "Workspace {Name} failed", cfg.Name); } } await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken); } } ``` ### An isolated container per sync The subtle part: each workspace has its own repositories, access token and source database, but the sync services read their settings through `IOptions`. Rather than mutate app-wide singletons (and race with the next workspace), each run builds a **fresh, short-lived DI container** with that workspace's options baked in: ``` var services = new ServiceCollection(); services.AddLogging(); services.AddSingleton(Options.Create(new RepositorySettings { Repositories = cfg.Repositories, Branch = cfg.Branch, AccessToken = cfg.AccessToken ?? defaults.AccessToken, })); services.AddSingleton(Options.Create(new DatabaseSettings { ConnectionString = cfg.DbConnectionString, // source SQL database Databases = [cfg.DbName], })); services.AddSingleton(Options.Create(new MongoDbSettings { ConnectionString = defaults.MongoConnectionString, DatabaseName = cfg.Name, // destination: this workspace's database })); services.AddScoped(); services.AddScoped(); services.AddScoped(); // …the rest of the sync pipeline using var provider = services.BuildServiceProvider(); await provider.GetRequiredService().SyncAsync(ct); ``` The pipeline code stays unaware of tenants: it just reads its options. The container is disposed when the run ends, taking the per-workspace credentials with it. ## 9. Speaking MCP MCP is JSON-RPC 2.0. A client sends `initialize` to learn the server's capabilities, `tools/list` to discover tools with their JSON Schemas, and `tools/call` to run one. The endpoint accepts POSTs and answers in the Streamable HTTP style as server-sent events, with standard JSON-RPC error codes (`-32700` parse error, `-32601` unknown method, `-32603` internal error): ``` switch (request.Method) { case "initialize": await Send(new { protocolVersion = "2024-11-05", capabilities = new { tools = new { } }, serverInfo = new { name = "code-intelligence", version = "1.0.0" } }); break; case "tools/list": await Send(new { tools = ToolDefinitions.GetAll() .Select(t => new { name = t.Name, description = t.Description, inputSchema = t.InputSchema }) }); break; case "tools/call": var result = await _executor.ExecuteAsync(toolName, args); // MCP wants a content array; the structured result travels as JSON text await Send(new { content = new[] { new { type = "text", text = JsonSerializer.Serialize(result) } } }); break; default: await SendError(-32601, $"Unknown method: {request.Method}"); break; } ``` ### Tools as data Each tool is declared once, with a name, a description written for the model and a JSON Schema for its arguments. The descriptions matter more than they look: they are the only documentation the assistant reads before choosing a tool. ``` new ToolDefinition( "find_method", "Search for methods across all classes", Schema(new() { ["methodName"] = ("string", "The name of the method to find"), ["className"] = ("string", "Filter by class name"), ["limit"] = ("integer", "Max results to return (default 50)"), })) ``` A single executor maps tool names to handlers with a `switch` expression: ``` public Task ExecuteAsync(string tool, Dictionary args) => tool switch { "find_class" => FindClassAsync(args), "find_method" => FindMethodAsync(args), "get_method_source" => GetMethodSourceAsync(args), "search_stored_procedures" => SearchStoredProceduresAsync(args), "get_class_dependencies" => GetClassDependenciesAsync(args), "get_table_schema" => GetTableSchemaAsync(args), "get_table_relationships" => GetTableRelationshipsAsync(args), "find_stored_procedures_by_table" => FindStoredProceduresByTableAsync(args), "class_count_by_layer" => ClassCountByLayerAsync(args), // …40-odd more _ => throw new InvalidOperationException($"Unknown tool: {tool}"), }; ``` The catalogue is grouped by the questions developers actually ask: - **Search:** `find_class`, `find_method`, `find_dto`, `search_by_namespace`, `search_class_name`. - **Method analysis:** `get_method_signature`, `get_method_source`, `list_class_methods`, `find_methods_by_return_type`, `trace_method_calls`. - **Structure:** `get_project_structure`, `get_layer_analysis`, `list_solutions`, `list_projects`, `get_class_dependencies`. - **Database:** `get_table_schema`, `get_table_relationships`, `get_table_foreign_keys`, `get_stored_procedure`, `get_sp_parameters`, `find_stored_procedures_by_table`. - **Code ↔ database:** `search_stored_procedures` finds the C# methods that call a procedure. - **Statistics:** `count_classes`, `class_count_by_layer`, `top_classes_by_method_count`, `top_tables_by_size`. Arguments arrive as `JsonElement`s or primitives depending on the client, so handlers read them tolerantly (accepting either form, with sensible defaults such as a 50-result limit) instead of failing on a type mismatch. ### What it looks like in use ``` You: Which methods call usp_CancelOrder, and what does that procedure touch? Assistant → search_stored_procedures { "storedProcName": "usp_CancelOrder" } ← OrderService.CancelOrderAsync, AdminOrderController.ForceCancel Assistant → get_stored_procedure { "name": "usp_CancelOrder" } ← definition + parameters (@OrderId int, @Reason nvarchar(200)) Assistant → get_table_relationships { "tableName": "Orders" } ← FK Orders.CustomerId → Customers.Id, OrderLines.OrderId → Orders.Id Assistant: Two callers use it… it updates Orders and OrderLines, so cancelling also affects any report that joins OrderLines. Here is the method source… ``` Three small, precise tool calls replace pasting a dozen files into the chat, and the answer is grounded in what the compiler and the database actually say. ## 10. Operating It ### Settings in MongoDB, with a file fallback Repository credentials, database connections and access keys can change without a redeploy. A tiny custom `IOptions` starts with the value from `appsettings.json` and is overwritten from MongoDB at startup if a stored value exists, so every service keeps using ordinary options injection: ``` public class MongoOptionsProvider : IOptions where T : class, new() { private T? _value; public MongoOptionsProvider(T fallback) => _value = fallback; // from appsettings.json public void SetValue(T? value) { if (value != null) _value = value; } public T Value => _value ?? new T(); } // Program.cs: register with the appsettings value, then overwrite from MongoDB at startup var repoSettings = new MongoOptionsProvider( builder.Configuration.GetSection("Repositories").Get() ?? new()); builder.Services.AddSingleton>(repoSettings); … repoSettings.SetValue(await settingsService.GetRepositorySettingsAsync()); ``` The settings API masks secrets on read: passwords in connection strings are replaced with asterisks, and access keys show only their first four characters. ### Live logs in the dashboard A sync over a big solution takes minutes, and watching it helps. A custom Serilog sink raises an event for every log line; the Blazor Server dashboard subscribes and appends lines as they arrive, with no polling and no extra infrastructure: ``` public class LogSink(LogStreamingService stream) : ILogEventSink { public void Emit(LogEvent e) => stream.Broadcast($"[{e.Timestamp:HH:mm:ss}] [{e.Level.ToString()[..3].ToUpper()}] {e.RenderMessage()}"); } public class LogStreamingService { public event Action? OnLogReceived; public void Broadcast(string line) => OnLogReceived?.Invoke(line); } // Program.cs Log.Logger = new LoggerConfiguration() .WriteTo.Console() .WriteTo.Sink(new LogSink(logStreaming)) // the dashboard subscribes to OnLogReceived .WriteTo.File("logs/sync-.log", rollingInterval: RollingInterval.Day) .CreateLogger(); ``` A singleton status service does the same for sync state (running, last duration, classes, tables and procedures found, next run), raising `OnChange` so the dashboard re-renders the moment a sync starts or finishes. ### Access The dashboard uses cookie authentication with access keys that can be managed at runtime, and a small middleware logs each request's client IP (honouring `X-Forwarded-For`), user agent and an optional device header for auditing. ## 11. What's Next - **A true call graph.** Class-level dependencies are exact today. Resolving every invocation inside each method (Roslyn's `SymbolFinder` can do this) would make "who calls this method?" as precise as "what does this class use?". - **Semantic search.** Embedding method source and documentation next to the structured metadata would add "find the code that handles refunds" alongside exact-name lookups: RAG over code, grounded by the same map. - **Incremental syncs.** Re-analysing only the files changed since the last commit instead of the whole solution. - **Secrets at rest.** Encrypting stored tokens and connection strings, or moving them to a secret store. ## 12. Takeaways - **Give assistants a map, not a pile of files.** Precomputed, structured metadata beats pasting code into a prompt. - **Use the compiler.** Roslyn's semantic model answers "what does this refer to?" exactly; text search can only guess. - **Link code to data.** Connecting methods to stored procedures to tables is where the biggest questions get answered. - **Make syncs idempotent and partial-failure tolerant.** Upserts, a temp directory per run, per-repository error isolation, and saving code before touching the database. - **Isolate tenants by construction.** A database per workspace, a scoped tenant from the URL, and a fresh DI container per sync. --- ### Article 9: A Dynamic Background Service Manager in .NET 8: Start, Update and Stop Workers at Runtime *Published: September 23, 2026 | Category: Software Architecture | Reading Time: 5 min read* *Canonical URL: https://dhucar.in/blog/dotnet-dynamic-background-service-manager* *Tags: .NET Core, C#, Background Services, Concurrency, Async* How a small .NET 8 console app runs any number of named background workers, each with its own interval and config, and lets you start, retune and stop them while it runs, using async loops, CancellationToken and a ConcurrentDictionary. # A Dynamic Background Service Manager in .NET 8: Start, Update and Stop Workers at Runtime September 23, 2026 · 5 min read · Software Architecture Tags: .NET Core, C#, Background Services, Concurrency, Async How a small .NET 8 console app runs any number of named background workers, each with its own interval and config, and lets you start, retune and stop them while it runs, using async loops, CancellationToken and a ConcurrentDictionary. Most .NET background work is fixed when the app starts: you register a `BackgroundService` and it runs until shutdown. This project takes a different approach: a small .NET 8 console app that starts, reconfigures and stops any number of named background workers **while it is running**, from simple typed commands. ## 1. What It Does The app prints a prompt and accepts five commands: - `START ` starts a new worker that runs every *interval* milliseconds with its own config value. - `UPDATE ` changes a running worker's interval and config without restarting it. - `STOP ` cancels one worker. - `LIST` shows every running worker and its current settings. - `EXIT` quits. That makes the number and pace of workers *data*, not code, which suits per-tenant pollers, sync jobs you switch on and off, or scheduled tasks whose frequency changes at runtime. ## 2. How the Code Is Organised Three files, each with one job: ``` Service&Instances/ ├── Program.cs console loop: reads and parses commands ├── Service.cs MyBackgroundService + ConfigData: one worker └── ServiceManager.cs BackgroundServiceManager: owns all workers ``` ## 3. The Worker: MyBackgroundService Each worker carries its settings in a small `ConfigData` class: how often to run, and a custom value standing in for whatever real settings a job would need. ``` public class ConfigData { public int Interval { get; set; } = 5000; // Default interval in milliseconds public string CustomValue { get; set; } = "DefaultConfig"; } ``` The worker itself is an async loop. It does its work (here, a log line), then waits for the interval with `Task.Delay`, and repeats until its `CancellationTokenSource` is cancelled: ``` private CancellationTokenSource _cts; private string _serviceId; private ConfigData _config; public MyBackgroundService(string serviceId, ConfigData config) { _serviceId = serviceId; _config = config; _cts = new CancellationTokenSource(); } public async Task StartAsync() { Console.WriteLine($"Service {_serviceId} started. Interval: {_config.Interval} ms, Config: {_config.CustomValue}"); while (!_cts.Token.IsCancellationRequested) { Console.WriteLine($"Service {_serviceId} is running with config: {_config.CustomValue}"); await Task.Delay(_config.Interval, _cts.Token); } Console.WriteLine($"Service {_serviceId} stopped."); } public void Stop() { _cts.Cancel(); } public void UpdateConfig(ConfigData newConfig) { _config = newConfig; Console.WriteLine($"Service {_serviceId} updated: Interval={_config.Interval} ms, Config={_config.CustomValue}"); } ``` [!tip] Three details make it work - **Cancellation instead of flags.** The loop checks `_cts.Token.IsCancellationRequested`, and the same token is passed to `Task.Delay`, so `Stop()` also interrupts a worker that is in the middle of waiting. - **Config is read on every pass.** `UpdateConfig` just replaces `_config`. The loop reads `_config` each time round, so the next pass picks up the new value and interval. - **Async, not threads.** While a worker waits it holds no thread, so hundreds of workers cost almost nothing when idle. ## 4. The Manager: BackgroundServiceManager The manager owns all workers in a `ConcurrentDictionary` keyed by id. Each entry stores the worker together with its current config, so `LIST` can report settings without asking every worker. ``` public class BackgroundServiceManager { private readonly ConcurrentDictionary _services; public BackgroundServiceManager() { _services = new ConcurrentDictionary(); } public string StartService(string serviceId, ConfigData config) { if (_services.ContainsKey(serviceId)) { return $"Service {serviceId} is already running."; } var service = new MyBackgroundService(serviceId, config); _services.TryAdd(serviceId, (service, config)); Task.Run(() => service.StartAsync()); return $"Service {serviceId} started."; } public string StopService(string serviceId) { if (_services.TryRemove(serviceId, out var serviceTuple)) { serviceTuple.Item1.Stop(); return $"Service {serviceId} stopped."; } return $"Service {serviceId} not found."; } public string UpdateServiceConfig(string serviceId, ConfigData newConfig) { if (_services.TryGetValue(serviceId, out var serviceTuple)) { serviceTuple.Item1.UpdateConfig(newConfig); _services[serviceId] = (serviceTuple.Item1, newConfig); // Update config in dictionary return $"Service {serviceId} updated with new config."; } return $"Service {serviceId} not found."; } public Dictionary GetRunningServices() { return _services.ToDictionary(k => k.Key, v => v.Value.Item2); } } ``` - **StartService** refuses a duplicate id, creates the worker, records it, and starts its loop on the thread pool with `Task.Run`. It returns straight away, so the prompt stays responsive. - **StopService** removes the entry and cancels the worker in one step with `TryRemove`. - **UpdateServiceConfig** pushes the new config into the running worker and updates the stored copy. - **GetRunningServices** returns a snapshot, a plain dictionary copy, so the caller can loop over it while workers are added or removed. ## 5. The Command Loop `Program.cs` reads a line, splits it on spaces and switches on the first word. Each branch validates its arguments and calls the manager. Here is `START`: ``` case "START": if (parts.Length < 4) { Console.WriteLine("Usage: START "); break; } string serviceId = parts[1]; if (!int.TryParse(parts[2], out int interval)) { Console.WriteLine("Invalid interval."); break; } string configValue = parts[3]; ConfigData config = new ConfigData { Interval = interval, CustomValue = configValue }; Console.WriteLine(serviceManager.StartService(serviceId, config)); break; ``` A typical session: ``` Dynamic Background Service Manager Available Commands: START , STOP , UPDATE , LIST, EXIT Enter command: START a 1000 hello Service a started. Service a started. Interval: 1000 ms, Config: hello Service a is running with config: hello Service a is running with config: hello Enter command: UPDATE a 200 fast Service a updated: Interval=200 ms, Config=fast Service a updated with new config. Service a is running with config: fast Service a is running with config: fast Enter command: LIST Running Services: - a: Interval=200, Config=fast Enter command: STOP a Service a stopped. ``` ## 6. Taking It Further The console is only one front end. Ideas for a production version: - **Expose it as an API.** Register `BackgroundServiceManager` as a singleton in ASP.NET Core and map `POST`, `PUT`, `DELETE` and `GET` endpoints to start, update, stop and list, so other systems can control workers. - **Stop cleanly on shutdown.** An `IHostedService` can stop every worker when the app exits, and the manager can keep each worker's task so a stop can wait for it to finish. - **Apply updates immediately.** A new interval takes effect after the current wait ends; cancelling the current `Task.Delay` with a second "wake" token applies it at once. - **Treat stopping as normal.** `Task.Delay` throws `OperationCanceledException` when cancelled; catching it (with cleanup in `finally`) lets the worker log its own "stopped" line. - **Guard concurrent starts.** Using the return value of `TryAdd` as the duplicate check keeps two simultaneous `START`s from both launching a worker. - **Persist the workers.** Save ids and configs to a database so workers come back after a restart. --- ### Article 10: How I Turned My MacBook into a Self-Hosted Vercel with Coolify, Cloudflare Tunnel & Terraform *Published: September 23, 2026 | Category: DevOps | Reading Time: 4 min read* *Canonical URL: https://dhucar.in/blog/turning-my-macbook-into-a-self-hosted-paas* *Tags: Coolify, Cloudflare Tunnel, Terraform, Self-Hosting, Docker* An 8 GB M1 MacBook, a domain, and zero open router ports: building a git-push-to-deploy platform at home, and the six things that broke along the way. # How I Turned My MacBook into a Self-Hosted Vercel with Coolify, Cloudflare Tunnel & Terraform September 23, 2026 · 4 min read · DevOps Tags: Coolify, Cloudflare Tunnel, Terraform, Self-Hosting, Docker An 8 GB M1 MacBook, a domain, and zero open router ports: building a git-push-to-deploy platform at home, and the six things that broke along the way. I wanted a place to host demo apps and APIs the way Vercel does it: push to GitHub, get a live HTTPS URL. Instead of paying for a platform, I turned a 2020 M1 MacBook Pro (8 GB RAM) into one. The site you are reading right now is served from that laptop. Here is the architecture, the build, and the problems I hit on the way. ## 1. What the Mac Can (and Can't) Do My first idea was to run LLMs on it. With 8 GB of unified memory, that was never going to work: the models I use are 18 to 21 GB. What an M1 is great at is the lightweight part of a platform: a build server, a reverse proxy, a handful of Next.js and .NET containers, and a couple of databases. Heavy AI inference stays on a separate GPU box. ## 2. The Architecture ``` git push ──▶ GitHub webhook ──▶ Coolify (Linux VM on the Mac) │ builds image, rolls out container ▼ Browser ─▶ app.mydomain ─▶ Cloudflare edge (HTTPS) ─▶ Tunnel ─▶ Traefik ─▶ container Terraform ──▶ Cloudflare API (tunnel, DNS, routing rules) └─▶ Coolify API (projects, apps, databases, services) ``` - **Colima** runs a lightweight Ubuntu VM (4 CPU / 4 GB) because Coolify needs Linux. - **Coolify** is the open-source Heroku/Vercel alternative: GitHub integration, Nixpacks/Dockerfile builds, one-click databases, rolling deploys with health checks. - **Cloudflare Tunnel** makes an outbound-only connection to Cloudflare. No port forwarding, no static IP, free HTTPS, and my home IP is never exposed. - **Terraform** describes the whole thing as code: the tunnel, a wildcard DNS record, and every app. ## 3. Wildcard Routing: One Rule for Every App The trick that makes it feel like a PaaS is a single wildcard DNS record pointing at the tunnel, with the tunnel sending everything to Coolify's Traefik proxy. Traefik routes by hostname, so a new app just needs a domain in Coolify. No DNS or Cloudflare changes, ever. ``` resource "cloudflare_dns_record" "wildcard" { zone_id = var.cloudflare_zone_id name = "*.mydomain.com" type = "CNAME" content = "TUNNEL_ID.cfargotunnel.com" proxied = true } # Tunnel ingress: every subdomain goes to Traefik { hostname = "*.mydomain.com", service = "http://coolify-proxy:80" } ``` Apps themselves are Terraform resources too. The community Coolify provider can't create applications, so I drive Coolify's REST API with the generic `restapi` provider. Adding a site is now one map entry and a `terraform apply`. ## 4. Six Things That Broke (and the Fixes) - **Coolify couldn't SSH into its own server.** It connects to `host.docker.internal`, but under Colima that name points at the Mac, not the Linux VM. Pointing the server at the VM's Docker gateway IP fixed it. - **Every `https://` domain became a redirect loop or a 404.** The tunnel talks plain HTTP to Traefik while Cloudflare terminates TLS. An `https://` domain in Coolify makes Traefik redirect HTTP to HTTPS forever. Rule of thumb: always `http://app.domain:PORT` in Coolify; the visitor still gets HTTPS from Cloudflare. - **The apex domain wouldn't route.** `*.domain` does not match `domain` itself. The bare domain needs its own DNS record and tunnel rule. - **An n8n worker crash-looped with NOAUTH.** Enabling "Connect to Predefined Network" attached it to Coolify's internal network, where the hostname `redis` also belongs to Coolify's own password-protected Redis. Turning that setting off restored isolation and fixed the crash. - **Terraform updates broke deployments.** Coolify's create endpoint stores a GitHub repo as `owner/repo`, but its PATCH endpoint stores whatever you send and later prefixes `github.com` again. Sending the short form on update fixed it. I only found this because I redeployed right after a Terraform change. - **"The site is down" (it wasn't).** My router cached the domain's empty answer from the minutes when DNS was mid-migration. The whole internet could see the site except my own Wi-Fi. Negative DNS caching is real. ## 5. Security on a Home Server - **No inbound ports**: the tunnel only makes outbound connections. - **Webhook-only exposure**: GitHub reaches a hostname that forwards only the `/webhooks/` path to Coolify; everything else returns 404. Each webhook is signed with a secret. - **The admin dashboard** requires a password plus TOTP 2FA, and its REST API is blocked at the tunnel (API tokens bypass 2FA). Terraform uses the API over localhost only. - **Tools with root-level Docker access** (Portainer) stay bound to localhost, not the internet. - **Secrets** live in the macOS Keychain and are passed to Terraform as environment variables, never in files. - **Nightly backups** of Coolify's database, encryption key and SSH keys go to the Mac's disk, outside the VM, with 14-day retention. ## 6. The Result [!success] This blog post is the test I committed it to the portfolio repo, pushed to `main`, and GitHub's webhook told Coolify to rebuild. With a health check on `/`, the old container keeps serving until the new one is healthy, so the deploy has no downtime. Grafana and n8n run alongside it as one-click services on their own subdomains. ## 7. Honest Limitations - It's a laptop: if it sleeps or loses power, the sites go down. Fine for demos, not for production. - 8 GB is tight. Builds are the peak, so I keep concurrent builds to one. - The same Terraform code can later point at a small cloud VM with almost no changes. That is the real win of doing it as code from day one. --- ### Article 11: Building a VMSS-Style Cluster from 10 Mini PCs: Why I'm Starting with Docker Swarm, Not K3s *Published: August 24, 2026 | Category: DevOps | Reading Time: 3 min read* *Canonical URL: https://dhucar.in/blog/homelab-vmss-docker-swarm-vs-k3s* *Tags: Docker Swarm, K3s, Proxmox, Homelab, Kubernetes* Ten 13th-gen machines with 8 GB RAM each, a zero-dollar software budget, and no Kubernetes experience. Here's the research, the trade-offs, and the build order I settled on. # Building a VMSS-Style Cluster from 10 Mini PCs: Why I'm Starting with Docker Swarm, Not K3s August 24, 2026 · 3 min read · DevOps Tags: Docker Swarm, K3s, Proxmox, Homelab, Kubernetes Ten 13th-gen machines with 8 GB RAM each, a zero-dollar software budget, and no Kubernetes experience. Here's the research, the trade-offs, and the build order I settled on. Azure VM Scale Sets are great: a pool of machines that restarts failed instances, balances load and rolls out updates for you. I had ten physical machines sitting on a desk and wanted the same behaviour, with nothing but free tools. This post is the research and the decision. ## 1. The Hardware and the Constraint - **10 machines**, each a 13th-gen Intel CPU. About 130 cores in total. - **8 GB RAM per node**. About 80 GB across the cluster, which turns out to be the constraint that drives every decision. - **$0 software budget** and **zero Kubernetes experience**. The goal was VMSS-like behaviour: auto-restart on failure, load balancing, rolling updates and work spread across all ten nodes. ## 2. The Foundation Is the Same Either Way **Proxmox VE** goes on every node first. It clusters the machines, gives you a web UI for all ten, and lets you carve up VMs if you need them. Two things matter more than anything else here: - **Static IPs** for every node (as DHCP reservations). Dynamic addresses make nodes lose each other after a reboot. - **A managed switch**. An unmanaged one works for Swarm but blocks the VLAN features you'll want later. At 8 GB per node, Ceph is out; it wants far more memory than that. One node serving **NFS** for shared storage is the practical replacement. ## 3. The Two Contenders ``` Docker Swarm K3s (lightweight Kubernetes) Setup time ~30 minutes ~2-3 hours (with troubleshooting) RAM per node ~1.5 GB with services ~3.5 GB with services Autoscaling manual or scripted automatic (HPA) Learning curve you already know Docker YAML, networking, controllers Dashboard Portainer CE Rancher / Lens / k9s ``` Both give you what VMSS gives you: rescheduling when a node dies, a routing mesh or service load balancer, and zero-downtime rolling updates. The differences are overhead, autoscaling and how much there is to learn. ## 4. The Verdict: Swarm First, K3s Later Starting with full Kubernetes with no experience means spending most of your time debugging YAML and cluster networking rather than running workloads. With zero services deployed, Kubernetes adds no value yet. Docker Swarm: - Is built into Docker, so the only new commands are `docker swarm init` and `docker service create`. - Leaves more RAM for the apps, which matters most at 8 GB per node. - Uses the same container images K3s would, so migrating later is a change of commands, not a rewrite. [!question] When to move to K3s At 20+ services, when you need CPU/memory-based autoscaling (Swarm can't do this natively), or when you need fine-grained scheduling, secrets or network policies. ## 5. The Build Order ``` # Phase 1 - foundation static IPs + Wake-on-LAN -> Proxmox VE on all 10 nodes # Phase 2 - cluster + storage pvecm create my-cluster # node 1 pvecm add # nodes 2-10 NFS export on node 10, mounted on nodes 1-9 # Phase 3 - Swarm docker swarm init # node 1 3 managers (odd number for quorum), 7 workers docker service create --name test --replicas 5 nginx Portainer for the dashboard # Phase 4 - prove it unplug a worker -> service recovers 10 replicas -> one per node rolling image update -> zero downtime ``` ## 6. Takeaways - Pick the orchestrator by what you'll *run*, not by what's on job listings. The simpler tool you understand beats the powerful one you're fighting. - Memory per node, not total cores, decides the storage and orchestration stack. - Keep a migration path open. Containers are the portable layer; the orchestrator is swappable. --- ### Article 12: Static Pages, Fresh Content: On-Demand ISR Between Next.js 16 and a .NET API *Published: August 22, 2026 | Category: Software Architecture | Reading Time: 2 min read* *Canonical URL: https://dhucar.in/blog/nextjs-dotnet-on-demand-isr* *Tags: Next.js, .NET Core, ISR, Caching, Webhooks* Zero API calls per page view, and content that updates the moment an editor saves. A hands-on proof of concept with tag-based revalidation driven by .NET webhooks, plus two traps I hit along the way. # Static Pages, Fresh Content: On-Demand ISR Between Next.js 16 and a .NET API August 22, 2026 · 2 min read · Software Architecture Tags: Next.js, .NET Core, ISR, Caching, Webhooks Zero API calls per page view, and content that updates the moment an editor saves. A hands-on proof of concept with tag-based revalidation driven by .NET webhooks, plus two traps I hit along the way. A server-rendered Next.js site backed by a .NET API usually calls that API on every page view, even when the content hasn't changed in days. I wanted static-file speed with CMS-level freshness and no rebuilds. This POC proves it with tag-based on-demand ISR (Incremental Static Regeneration), triggered by webhooks from .NET. ## 1. The Architecture ``` .NET Core API ──▶ Next.js (build) ──▶ static HTML cache ──▶ users (no API call) │ ▲ └──── POST /api/revalidate ────────────┘ (fired by .NET the instant content changes) ``` - Every content page (`/[slug]`) tags its fetch with `page-{slug}`. The home listing uses `all-pages`. - After every create, update or delete, .NET sends a signed webhook naming exactly which tags to invalidate. - The revalidate route checks a shared secret (401 otherwise) and expires only those tags. ## 2. What Actually Happens, Request by Request **Steady state.** `/home` is prerendered at build time. I hit it five times against a production server and the .NET log didn't grow by a single line. Zero backend calls. **An editor saves.** .NET updates the record, then fires a webhook: `{ slug: "home", listingChanged: false }`. Next.js marks `page-home` expired. Nothing is fetched yet. **The next visitor.** That one request does a single live fetch, renders fresh HTML and re-caches it. Every visitor after that gets the cached page again. That's **one backend call per content change**, not one per visitor. ## 3. New Pages and Deleted Pages `generateStaticParams()` only knows slugs that existed at build time. Two small pieces cover the rest: - `export const dynamicParams = true` lets an unknown slug render on demand (then cache) instead of returning a 404. - The backend checks whether the slug existed before writing. For creates and deletes it sets `listingChanged: true`, which also expires `all-pages`, so the new page appears in the navigation. [!danger] Deletes surfaced a real bug A missing page threw a raw error, and Next.js turned that into a **500**. The fix is to treat an API 404 as "not found", return `null` and call `notFound()`. An API that's actually broken should still throw and surface as a 500. ## 4. Trap #1: Dev Mode Lies About Caching `next dev` doesn't honour the fetch cache the way production does. I disabled the webhook entirely, edited content in .NET, and the dev server still showed the change instantly. That makes it look as if revalidation isn't needed. Only `next build && next start` shows real caching. [!warning] Always validate this pattern against a production build. ## 5. Trap #2: Next.js 16 Changed `revalidateTag` The single-argument `revalidateTag(tag)` from most tutorials is deprecated in Next.js 16. It now takes a second argument: ``` // expire immediately: what a synchronous "content saved" webhook wants revalidateTag('page-home', { expire: 0 }); // stale-while-revalidate semantics revalidateTag('page-home', 'max'); ``` [!tip] Check the bundled docs `create-next-app@latest` installed a version far newer than the tutorials assume. When an API behaves oddly, check the docs bundled in `node_modules/next/dist/docs/` before trusting remembered examples. ## 6. Takeaways - Tag-based ISR gives static-site cost with CMS freshness, and the backend decides exactly what goes stale. - Fire the webhook from the write path, and sign it. - Handle "created" and "deleted" explicitly. They're the cases that break listings and error pages. - Test caching behaviour only against production builds. --- ### Article 13: Hybrid Product Search on Solr 9: BM25 + Vectors + Reciprocal Rank Fusion in .NET *Published: August 14, 2026 | Category: Search & Vectors | Reading Time: 3 min read* *Canonical URL: https://dhucar.in/blog/hybrid-search-solr-bm25-vector-rrf* *Tags: Solr, Vector Search, RRF, ONNX, .NET Core* Keyword search misses meaning; vector search misses exact terms. Fusing both with RRF, adding rule-based query understanding and running embeddings in-process gave a search that handles "red card case and gold tone watch under 5000". # Hybrid Product Search on Solr 9: BM25 + Vectors + Reciprocal Rank Fusion in .NET August 14, 2026 · 3 min read · Search & Vectors Tags: Solr, Vector Search, RRF, ONNX, .NET Core Keyword search misses meaning; vector search misses exact terms. Fusing both with RRF, adding rule-based query understanding and running embeddings in-process gave a search that handles "red card case and gold tone watch under 5000". E-commerce search fails in two opposite ways. BM25 keyword search can't tell that "evening wristwatch" and "dress watch" mean the same thing. Pure vector search happily returns "something watch-like" when the shopper typed an exact SKU. This R&D engine runs both and fuses the results, on a Solr 9 core of about 540 real catalog products, without touching the production search path. ## 1. The Pipeline ``` query ─▶ SKU short-circuit ─▶ split into item clauses ─▶ for each clause: ├─ price phrase parser (under / between / ~ / 12k) ├─ rule-based NLU (brand, category, colour, size, badge, type) ├─ fuzzy fallback (Solr ~2 edit distance on *_text fields) ├─ in-process ONNX embedding (all-MiniLM-L6-v2, 384 dims) ├─ BM25 keyword search (edismax) ├─ kNN vector search ({!knn f=vector topK=N}) └─ RRF fusion ─▶ merge clauses ─▶ de-dup by style ─▶ page ─▶ UI view model ``` ## 2. Reciprocal Rank Fusion BM25 scores and cosine similarities live on different scales, so you can't just add them. RRF ignores scores and uses only rank positions: ``` score(doc) = Σ over result lists 1 / (K + rank(doc)) K = 60 ``` A product ranked well by *both* retrievers rises to the top. One found by only one retriever still gets a fair share. The same primitive powers the "similar products" endpoint, where it fuses vector similarity with Solr's MoreLikeThis. ## 3. Embeddings Without an API Call - **all-MiniLM-L6-v2** in ONNX format, run in-process with `Microsoft.ML.OnnxRuntime`, tokenised with `FastBertTokenizer`. - Mean-pooled and L2-normalised into a 384-dimensional vector. The query is embedded live; product vectors are precomputed and stored in Solr. - No network hop and no per-query cost for an external embedding API. ## 4. Query Understanding Without an LLM The NLU is deterministic and explainable: lexicon lookup and regex against a **live vocabulary**. A `BackgroundService` refreshes the real distinct values in the index (brands, colours, categories and so on) every five minutes using Solr facet queries. When the catalog changes, the parser updates without a redeploy. - **Typos:** "Chrons" resolves via Solr's native fuzzy operator. A curated stop-word list (~60 words) stops common English words from being offered as fuzzy matches. - **Synonyms live in Solr**, not in C# dictionaries. Gender and size moved to `*_text` fields backed by `synonyms.txt`. - **Prices:** "under X", "between X and Y", reversed phrasing, "~X" (±10%), "12,000" and "12k". ## 5. Multi-Intent Queries "red card case and gold tone watch under 5000" is two searches. Splitting on commas and a standalone "and" (while protecting "between X and Y" and "12,000") lets each clause run the *entire* pipeline with its own price and filters. Otherwise the watch clause's category filter would starve the card-case clause. [!example] The reverse case matters too In "black and blue watches", "black" is only a modifier. Clauses that contain nothing but a colour, brand or gender word get merged into their neighbour, so they don't trigger a catalog-wide search for "black". ## 6. The Details That Make It Feel Right - **Style-level de-dup:** the same style in three colours shows once, with its colour swatches harvested through Solr collapse + expand. - **Phrase proximity** (`pf2`) reranks adjacent-word matches above bag-of-words hits. - **Business signals** (rating, sale count, availability) as an edismax boost function that nudges relevance but doesn't override it. - **Embedded SKUs** ("watch CR6121") are forced to position one. - **Autosuggest** through Solr's Suggester component for fast prefix and infix matches. ## 7. Takeaways - Hybrid beats either retriever alone, and RRF is the simplest fusion that works without score calibration. - You don't need an LLM for query understanding in a bounded domain. A live vocabulary and good rules are faster, cheaper and explainable. - Push linguistics (synonyms, fuzziness, suggesters) into the search engine, and keep the application code for orchestration. --- ### Article 14: Why Our RAG Chatbot Took 40 Seconds to Answer, and the Plan to Make It 70% Faster *Published: July 17, 2026 | Category: Artificial Intelligence | Reading Time: 3 min read* *Canonical URL: https://dhucar.in/blog/rag-chatbot-latency-audit* *Tags: RAG, LLMs, Semantic Kernel, Performance, .NET Core* An end-to-end audit of a multi-tenant .NET RAG chatbot found 7-8 LLM calls per request, a duplicate vector search and 1.5 seconds of artificial streaming delay. Here's where the time went and the fix plan. # Why Our RAG Chatbot Took 40 Seconds to Answer, and the Plan to Make It 70% Faster July 17, 2026 · 3 min read · Artificial Intelligence Tags: RAG, LLMs, Semantic Kernel, Performance, .NET Core An end-to-end audit of a multi-tenant .NET RAG chatbot found 7-8 LLM calls per request, a duplicate vector search and 1.5 seconds of artificial streaming delay. Here's where the time went and the fix plan. We're building a multi-tenant RAG chatbot platform on .NET 10: an embeddable widget, SignalR streaming, pgvector retrieval, a text-to-SQL agent, MCP tools and episodic memory. It worked, but a data question took 30-40 seconds. I audited the whole request path to find out why. ## 1. The Platform in One Picture ``` Next.js admin portal | embeddable JS widget (iframe) │ REST + SignalR ▼ ASP.NET Core gateway (.NET 10) ─ Semantic Kernel agents │ │ │ │ │ pgvector RabbitMQ Redis MongoDB mem0 (Qdrant) (RAG) (ingestion) (cache + (chat + (long-term backplane) audit) memory) ``` Heavy work (document ingestion and audit logging) goes through RabbitMQ consumers, so the gateway stays non-blocking. Vectors are namespaced per tenant. ## 2. Where 40 Seconds Went For a SQL-style question, roughly 12-15 seconds is unavoidable LLM and database work. The other ~13 seconds was waste: ``` nested SQL LLM calls ~8000 ms ◀ biggest win redundant intent re-parsing ~2000 ms artificial streaming delay ~1500 ms duplicate vector search ~300 ms redundant kernel clones ~300 ms other overhead ~500 ms ``` ## 3. Finding #1: The LLM Call Cascade The SQL path made its calls in sequence: classify intent, re-derive intent, discover tables, analyse the schema, generate SQL, validate SQL. That's **7-8 LLM calls per request** where 2-3 would do. The step that re-derived intent was redundant, because the classifier had already decided the question was a SQL question. [!note] Plan A single generation prompt with the relevant schema inlined, which analyses, generates and validates in one pass. It's the simplest architecture, the easiest to debug, and worth an estimated 8-12 seconds. The risk is SQL accuracy, so it ships behind a feature flag and gets A/B tested on 20+ reference questions. ## 4. Finding #2: Streaming That Wasn't Responses were re-chunked into 20-character pieces with a 15 ms pause between each. A 2,000-character answer means 100 chunks, or **1.5 seconds of pure delay**, added to a model that already streams natively. The fix is to forward tokens as they arrive. ## 5. Finding #3: Doing the Same Work Twice - **Duplicate vector search:** two services ran the same schema-context search on every request. Search once, pass the result down. - **Kernel cloning:** the Semantic Kernel instance was cloned 3-4 times per request, each clone creating a new client connection (50-100 ms each). Reuse the base kernel and attach plugins per step. - **MCP connections:** a new connection per request (300-800 ms). Cache them in a `ConcurrentDictionary` keyed by server and URL, and dispose them deterministically when config changes. ## 6. The Reliability Checklist That Came With It Performance audits find correctness problems too. These are the checks I now run on any multi-tenant AI backend: - **Every cache key includes the tenant ID.** Anything else is a cross-tenant data leak waiting to happen. - **No fire-and-forget without retries.** Background ingestion needs retries and visibility, or data goes missing silently. - **Invalidate caches per tenant.** A global flush makes every tenant rebuild at once. - **Put a bound on in-process caches**, and make disposal ownership explicit for pooled clients. ## 7. The Plan ``` Week 1 quick wins: streaming, duplicate search, kernel reuse, MCP pooling target: 30-40 s ─▶ 20-25 s Week 2-3 single-shot SQL, cached intent, parallel pipeline steps target: ─▶ 8-12 s Week 3-4 tenant isolation, retries, per-tenant invalidation, latency dashboards ``` ## 8. Takeaways - In LLM apps, **count the calls** before tuning anything else. Sequential calls dominate latency. - Don't simulate streaming on top of a model that already streams. - Measure first: this audit turned "the chatbot is slow" into a ranked list of 12 fixes with estimated savings. --- ### Article 15: Deep-Dive: .NET Core API Performance Tuning & Memory Optimization *Published: May 20, 2026 | Category: Software Architecture | Reading Time: 1 min read* *Canonical URL: https://dhucar.in/blog/dotnet-performance-tuning-api-throughput* *Tags: .NET Core, Performance, GC Optimization, APIs* Learn how we reduced latency by 40% and optimized GC pressure in high-throughput .NET Core microservices. # Deep-Dive: .NET Core API Performance Tuning & Memory Optimization May 20, 2026 · 1 min read · Software Architecture Tags: .NET Core, Performance, GC Optimization, APIs Learn how we reduced latency by 40% and optimized GC pressure in high-throughput .NET Core microservices. In high-throughput microservices, CPU utilization and Garbage Collector (GC) pauses are often the silent killers of low-latency SLAs. Recently, we undertook a migration and optimization effort on a core API endpoint handling over 15,000 requests per second. Here is the engineering breakdown of how we achieved a 40% reduction in response latency. ## 1. The Problem: Gen 0/1 GC Spikes Through detailed memory profiling using dotnet-dump and PerfView, we identified that our primary bottleneck was GC collection pauses. Specifically, large amounts of short-lived objects were being allocated per request, causing frequent Generation 0 and Generation 1 Garbage Collections that paused thread execution. ## 2. The Fix: Structs, ArrayPool, and Span We systematically refactored the request pipeline to reduce heap allocations: - **ArrayPool & MemoryPool:** Instead of allocating new byte arrays for body deserialization on every request, we leased arrays from `ArrayPool.Shared` and returned them immediately after processing. - **Span and ReadOnlySpan:** We converted string slicing operations into zero-allocation spans. This prevented millions of string allocations per minute. - **ValueTask:** Asynchronous methods that frequently complete synchronously were changed from returning `Task` to `ValueTask`, eliminating Task object allocations. ``` // Zero-allocation parsing snippet public ReadOnlySpan ExtractToken(ReadOnlySpan header) { int index = header.IndexOf("Bearer "); if (index == -1) return ReadOnlySpan.Empty; return header.Slice(index + 7); } ``` ## 3. Results and Metrics [!success] p99 latency: 180 ms → 42 ms After deploying these optimizations, load tests run via k6 showed a drop in p99 latency from 180ms to 42ms. Heap allocations per request dropped from 14KB to under 200 bytes. This not only improved user experience but also slashed our container resource requirements by half. --- ### Article 16: Designing Repeatable Load Testing Suites with k6 and Grafana *Published: April 15, 2026 | Category: Observability | Reading Time: 1 min read* *Canonical URL: https://dhucar.in/blog/load-testing-microservices-k6-grafana* *Tags: k6, Grafana, Load Testing, DevOps* A guide to building a continuous load testing pipeline to detect latency regressions before code reaches staging. # Designing Repeatable Load Testing Suites with k6 and Grafana April 15, 2026 · 1 min read · Observability Tags: k6, Grafana, Load Testing, DevOps A guide to building a continuous load testing pipeline to detect latency regressions before code reaches staging. Observability isn't just about production logs; it starts with proactive performance assertion. Setting up a repeatable load testing suite allows engineering teams to catch architectural bottlenecks before code goes live. ## Why k6 for Modern API Platforms? k6 stands out because it is developer-centric. Written in Go, it allows developers to write load test scripts in JavaScript, making it simple to version-control performance test cases right alongside the application codebase. ## Integrating k6 with Grafana InfluxDB To make the metrics digestible, we stream k6 test results directly to an InfluxDB instance, which is visualized in real-time on a customized Grafana dashboard. This provides instantaneous visual feedback on: - Request Rates (RPS) and HTTP Failure Rates. - Response Latency percentiles (p50, p95, p99). - System utilization (Memory/CPU of the target services). ``` // Example k6 test scenario script import http from 'k6/http'; import { check, sleep } from 'k6'; export const options = { stages: [ { duration: '30s', target: 100 }, // ramp up to 100 users { duration: '1m', target: 100 }, // stay at 100 users { duration: '10s', target: 0 }, // ramp down to 0 users ], }; export default function () { const res = http.get('http://localhost:9002/api/health'); check(res, { 'status is 200': (r) => r.status === 200 }); sleep(1); } ``` ## Enforcing SLAs using Thresholds [!tip] An automated quality gate Using k6's `thresholds` feature, we can configure our CI/CD pipelines to fail the build automatically if p99 latency exceeds 200ms or if the error rate climbs above 1% during tests. This acts as an automated quality gate. --- ### Article 17: Building an Advanced RAG Pipeline for Developer Knowledge Discovery *Published: March 10, 2026 | Category: Artificial Intelligence | Reading Time: 1 min read* *Canonical URL: https://dhucar.in/blog/building-rag-pipeline-internal-documentation* *Tags: RAG, LangChain, Vector DB, LLMs* How we leveraged LangChain and vector databases to build a context-aware search engine for internal APIs. # Building an Advanced RAG Pipeline for Developer Knowledge Discovery March 10, 2026 · 1 min read · Artificial Intelligence Tags: RAG, LangChain, Vector DB, LLMs How we leveraged LangChain and vector databases to build a context-aware search engine for internal APIs. Finding documentation across multiple Slack channels, Confluence pages, and markdown repositories is a major developer friction point. We built an internal Retrieval-Augmented Generation (RAG) system to solve this. ## 1. The Architecture Our RAG pipeline is built using LangChain and a localized vector database. The process follows a classic ingestion and retrieval architecture: - **Ingestion:** Scripts crawl markdown documents, split text into chunks using recursive character text splitters, and generate semantic embeddings using HuggingFace models. - **Storage:** Embeddings are stored in a vector database for rapid semantic retrieval. - **Generation:** When a developer asks a question, the vector database returns the top 3 most relevant documents, which are passed to the LLM as context to formulate a response. ## 2. Optimizing Chunking and Context Windows [!tip] Search small chunks, return the parent document One of the largest hurdles was preventing LLM hallucinations. We solved this by implementing parent-document retrieval. We store small chunks (100 tokens) for search, but return the parent document (500 tokens) to the LLM to preserve surrounding context. This improved accuracy by 35%. ## 3. Results The developer assistant now answers natural language questions like 'How do I initialize the auth client?' within 3 seconds, citing exact source links. This has dramatically improved onboarding speed for new developers. ---