DEV Community: Bibek

CQRS: Read-Write Separation Design Pattern

Bibek — Wed, 02 Sep 2026 15:29:30 +0000

In traditional software architectures, we almost instinctively reach for the CRUD (Create, Read, Update, Delete) paradigm. We design an entity model, map it to a relational schema using an ORM, and use that identical abstraction to both alter state and display data on user dashboards.

For simple applications, this works flawlessly. But as systems scale—both in business complexity and throughput, this dual-purpose model starts showing fractures:

Write logic demands tight validation, transactional boundaries, normalization, and domain invariants.
Read logic demands flat, pre-aggregated, denormalized representations across dozens of tables to serve responsive UIs.

Trying to satisfy both masters with a single schema leads to unwieldy SQL joins, lock contention, compromised domain boundaries, and performance gridlock.

This is where Command Query Responsibility Segregation (CQRS) enters the picture.

1. What is CQRS?

Coined by Greg Young and based on Bertrand Meyer’s Command-Query Separation (CQS) principle, CQRS states that an application should use separate models to update and read data.

At its philosophical core:

Command (Write): Represents an intent to alter domain state (e.g., SubmitOrder, DeactivateUser, ChangeBillingAddress). A command should focus entirely on domain logic, data integrity, and business rules. In strict CQRS, commands do not return domain data — only an acknowledgment, validation failure, or generated entity ID.
Query (Read): Retrieves data without mutating application state (e.g., GetOrderSummaryById, ListCustomerInvoices). Queries should execute side-effect-free operations that return lightweight Data Transfer Objects (DTOs).

         ┌────────────────────────────────────────────────────────┐
         │                       Client                           │
         └─────────────┬────────────────────────────▲─────────────┘
                       │                            │
             Execute Command                    Run Query
                       │                            │
                       ▼                            │
         ┌───────────────────────────┐  ┌───────────┴─────────────┐
         │       Command Model       │  │       Query Model       │
         │ (Validation & Invariants) │  │   (Optimized for DTOs)  │
         └─────────────┬─────────────┘  └───────────▲─────────────┘
                       │                            │
                 Mutates State                Direct Read
                       │                            │
                       ▼                            │
         ┌───────────────────────────┐  ┌───────────┴─────────────┐
         │       Write Storage       │──|    Synchronization      │
         └───────────────────────────┘  │   (Sync / Async CDC)    │
                                        └─────────────────────────┘

2. How CQRS Works in Practice

Let’s trace an end-to-end user interaction in a CQRS system using an e-commerce order:

The Write Path (Command Flow)

Client Action: The user clicks "Place Order", dispatching a PlaceOrderCommand.
Command Handler: The handler receives the command, loads the aggregate (e.g., Order), validates business rules (inventory checks, credit limits), and produces state changes.
Write Persistence: The entity state (or an event stream) is committed to the Write Data Store within an atomic transaction.
Notification / Projection: An event (e.g., OrderPlaced) or a database Change Data Capture (CDC) stream is emitted.

The Read Path (Query Flow)

Read Model Projection: A background projector (or synchronous handler) catches the update and reshapes the data into a denormalized table or document store (order_views).
Client Action: The user visits their dashboard, issuing GetCustomerOrdersQuery.
Query Handler: The query bypasses business validation engines, complex ORM logic, and multi-table SQL joins, executing a direct indexed lookup:
```
SELECT * FROM order_views WHERE customer_id = :customerId;
```
DTO Return: The UI receives ready-to-render JSON data immediately.

3. Types of CQRS Implementations

CQRS is not a binary choice. It exists on an implementation spectrum, ranging from simple code separation to distributed event-driven systems.

Single-Database CQRS (Code-Level Separation)

Both read and write models target the same relational database, but your application code completely decouples the command handling logic from the query handling logic.

How it works: The write path uses domain entities, while the read path uses raw SQL, lightweight micro-ORMs, or database views to fetch flat DTOs.
Consistency: Strong / Immediate. Everything happens within a single ACID transaction.
When to use: When your codebase is becoming bloated with domain logic inside query paths, but you do not have massive scale or high read/write asymmetry.

Dual-Model, Single Database (Synchronous Projection)

The write model updates normalized tables (e.g., orders, order_items, customers). Inside the same database transaction, the application updates a denormalized summary table (order_view_flat).

How it works: The read queries hit the denormalized table, eliminating runtime joins without introducing message queues.
Consistency: Strong / Immediate.
When to use: When you need sub-millisecond query lookups for complex pages, but cannot tolerate the eventual consistency or infrastructure overhead of separate databases.

Split Databases with Asynchronous Sync

The write model targets a dedicated Write DB (e.g., PostgreSQL primary), while the read model targets an independent Read DB (e.g., a denormalized PostgreSQL instance, Elasticsearch, or MongoDB).

How it works: Commits on the write DB publish events or WAL updates. CDC pipelines (Debezium/Kafka) or event subscribers consume these updates, transform the data, and upsert them into the read database.
Consistency: Eventual Consistency. Read views lag slightly behind the write path (typically 25ms–300ms).
When to use: High read-to-write ratios (100:1+), disparate indexing requirements, or where full-text search / flexible document storage is required for queries.

CQRS with Event Sourcing (ES)

Instead of storing the current state of an entity, you store an append-only log of immutable domain events (OrderCreated, ItemAdded, ShippingAddressUpdated).

How it works: The write store is an Event Store. The query models (projections) are derived read representations built by replaying and subscribing to this event stream.
Consistency: Eventual Consistency.
When to use: Systems requiring complete auditability, temporal querying ("what was the state at 2:00 PM yesterday?"), financial ledgers, or complex distributed domains.

4. Alternative Approaches (and Why They Might Fall Short)

Before adopting full CQRS, engineers often evaluate simpler architectural alternatives. Each comes with clear trade-offs:

Traditional Read Replicas

Concept: Direct read traffic to replica instances using standard database replication (e.g., Postgres WAL streaming).
Drawbacks:
- Schema Coupling: Read replicas contain the exact same normalized schema as the primary.
- Query Overhead: Complex joins, subqueries, and aggregations still occur at query time.
- Index Contention: Adding excessive indexes to optimize read queries on replicas creates overhead and replication lag.

Database Materialized Views

Concept: Define views that pre-compute joins and aggregations directly in the database.
Drawbacks:
- Refresh Costs: Standard materialized views require manual or periodic refreshes (REFRESH MATERIALIZED VIEW), locking rows or draining database CPU.
- Incremental Refresh Complexity: Incremental view maintenance (IVM) is either unsupported natively or strictly limited to simple single-table operations without subqueries.

Application-Layer Cache (Redis / Memcached)

Concept: Wrap queries in a caching layer (Cache-Aside pattern).
Drawbacks:
- Cache Invalidation Nightmares: Knowing exactly which cached objects to invalidate when a nested entity updates is notoriously difficult.
- Cold Start Latency: Cache misses force heavy fallbacks onto the relational database.
- Limited Query Flexibility: Key-value caches do not excel at multi-attribute filtering, sorting, or pagination across variable criteria.

5. Addressing the Obvious Doubts & FAQ

"Isn't a denormalized read DB in Postgres just a read replica?"

No. A read replica is an identical physical clone of your write database schema.

In a CQRS split-database setup, the read database contains an entirely different, query-tailored schema. It holds pre-joined JSON documents, flattened tabular projections, and specialized indexes (such as GIN or full-text) that would be too heavy to maintain on your transactional write primary.

"Can I write denormalized tables in the same DB and just replicate them?"

Yes, but watch your write latency. Writing to both normalized tables and denormalized summary tables inside the same transaction increases transaction duration, amplifies WAL generation, and can introduce severe row-lock contention on aggregate records (e.g., multiple orders updating the same merchant total row).

"Do I have to use Event Sourcing to use CQRS?"

No. This is the single most common misconception in system design. CQRS can be implemented with standard state-based ORMs and relational databases. While Event Sourcing almost always requires CQRS (because event streams are difficult to query directly without projections), CQRS does not require Event Sourcing.

"How much latency does eventual consistency introduce?"

In a well-architected CDC and message-broker pipeline, the typical end-to-end lag ranges between 25 ms and 300 ms under normal load.

Spikes can occur during large batch updates, rebalances, or heavy read-side lock contention.

"How do I deal with users seeing stale data immediately after submitting a form?"

When using asynchronous CQRS, navigating immediately to a list page might show outdated data if the projection is lagging by 100ms. Common mitigation patterns include:

Optimistic UI: The frontend client updates its local state immediately upon a successful command dispatch without refetching from the read model.
Command Response Payloads: Return the newly updated projection directly in the command response body for immediate display.
Read-Your-Own-Writes Tokens: The command returns a version identifier (e.g., version=42). The subsequent read query passes this token; if the read store has only caught up to version=41, the query either waits for catch-up or momentarily queries the write primary.

6. Summary: When to Use (and When to Avoid) CQRS

Indicator	Avoid CQRS	Consider CQRS
Domain Complexity	Simple CRUD, small team, standard forms	Intricate domain logic, complex invariants, distinct team ownership
Workload Profile	Balanced read/write, low traffic	Heavy read-to-write asymmetry (e.g., 50:1 to 1000:1)
Data Relationships	Single-table queries, basic joins	High-dimensional views requiring expensive 10-table joins
Consistency Needs	Strict global ACID consistency mandatory	Read views can tolerate 100ms–500ms eventual consistency

CQRS is an architectural investment. While it eliminates performance bottlenecks and disentangles write-side business rules from read-side presentations, it introduces operational overhead, deployment complexity, and eventual consistency challenges. Start with simple CQS at the code level, and introduce split databases only when access patterns and scale justify the trade-off.

Understanding Kubernetes: A Beginner's Guide to Container Orchestration

Bibek — Fri, 28 Aug 2026 19:15:50 +0000

If you have already explored Docker, you know how convenient containers are. You package your application, dependencies, and environment into a neat image, run docker run, and it just works.

Running one container on your local machine is simple. But what happens when your application grows into a real-world product with millions of users?

Imagine you launch an online food delivery app. On a Friday night at 8:00 PM:

Traffic spikes by 10x—you suddenly need 20 copies of your backend container to handle orders.
One of your physical servers overheats and crashes at 2:00 AM, taking down 5 containers with it.
You need to deploy a bug fix to the payment gateway without dropping ongoing user checkouts.
You need a way to distribute incoming user requests evenly across all running containers.

Doing this manually means waking up at 3:00 AM, SSH-ing into servers, running docker run commands by hand, and manually updating Nginx reverse proxy configs.

This is where Kubernetes comes in.

What is Kubernetes?

Kubernetes (often abbreviated as K8s, because there are 8 letters between 'K' and 's') is an open-source container orchestration platform. It automates the deployment, scaling, load balancing, and self-healing of containerized applications across a cluster of servers.

Originally developed by Google (based on over a decade of running Borg internally) and now maintained by the Cloud Native Computing Foundation (CNCF), Kubernetes has become the standard operating system for cloud-native infrastructure.

The Symphony Orchestra Analogy

Think of it this way:

A Docker Container is a single musician (like a violinist playing their sheet music perfectly).
Kubernetes is the orchestra conductor. The conductor ensures every musician plays in sync, brings in extra violinists when the crescendo builds, seamlessly replaces someone if a string snaps, and makes sure the entire performance sounds harmonious to the audience.

                +------------------------------------+
                |        Kubernetes Conductor        |
                | (Monitors, Scales, Heals, Routes)  |
                +-----------------+------------------+
                                  |
    +----------------------------+----------------------------+
    |                            |                            |
    v                            v                            v
[ Container 1 ]           [ Container 2 ]              [ Container 3 ]
 (Musician A)               (Musician B)                 (Musician C)

What Problems Does Kubernetes Solve?

Problems	How Kubernetes Solves It
Server Crash	Self-Healing: Kubernetes detects the dead node and automatically restarts the affected containers on healthy servers within seconds.
Traffic Surges	Horizontal Auto-Scaling: Automatically scales the number of container copies (replicas) up or down based on CPU, memory, or custom metrics.
Zero-Downtime Updates	Rolling Deployments: Updates containers incrementally one by one. If an error occurs, it automatically rolls back to the last stable version.
Traffic Distribution	Service Discovery & Load Balancing: Gives containers a single stable IP/DNS and distributes incoming network traffic evenly among healthy instances.
Secrets & Configs	Centralized Management: Injects environment variables, passwords, and API keys securely without baking them into container images.

Kubernetes Architecture Explained

A Kubernetes setup is called a Cluster. A cluster is made of physical machines or Virtual Machines (VMs) divided into two main layers:

The Control Plane (The Brain): Makes high-level decisions, monitors the cluster, and schedules workloads.
Worker Nodes (The Muscle): The actual machines that run your containerized applications.

+-------------------------------------------------------------------------+
|                              CONTROL PLANE                              |
|                                                                         |
|   +-------------------+   +--------------------+   +----------------+   |
|   |  kube-apiserver   |   |        etcd        |   | kube-scheduler |   |
|   +-------------------+   +--------------------+   +----------------+   |
|             |                                                           |
|   +-------------------------+   +-----------------------------------+   |
|   | kube-controller-manager |   |      cloud-controller-manager     |   |
|   +-------------------------+   +-----------------------------------+   |
+------------------------------------+------------------------------------+
                                     |
              +----------------------+----------------------+
              |                                             |
+-------------v---------------+               +-------------v---------------+
|         WORKER NODE 1       |               |         WORKER NODE 2       |
|                             |               |                             |
|  +-----------------------+  |               |  +-----------------------+  |
|  |        kubelet        |  |               |  |        kubelet        |  |
|  +-----------------------+  |               |  +-----------------------+  |
|  +-----------------------+  |               |  +-----------------------+  |
|  |      kube-proxy       |  |               |  |      kube-proxy       |  |
|  |   (Network Router)    |  |               |  |   (Network Router)    |  |
|  +-----------------------+  |               |  +-----------------------+  |
|  +-----------------------+  |               |  +-----------------------+  |
|  |   Container Runtime   |  |               |  |   Container Runtime   |  |
|  |   [ Pod ]   [ Pod ]   |  |               |  |   [ Pod ]   [ Pod ]   |  |
|  +-----------------------+  |               |  +-----------------------+  |
+-----------------------------+               +-----------------------------+

The Control Plane Components

kube-apiserver:

The main entry point for the entire cluster. Whenever you run a command via kubectl or an automated CI/CD pipeline triggers a deployment, it speaks directly to the API Server. No component talks to the cluster without going through kube-apiserver.
etcd:

A fast, highly available, distributed key-value database. It stores the single source of truth for the entire cluster state (e.g., how many pods should be running, their IPs, secrets, and configurations). If it is not recorded in etcd, it doesn't exist.
kube-scheduler:

When you request a new Pod, the scheduler decides which Worker Node should host it. It checks node capacity, CPU/memory availability, and specific constraints (like "only run on nodes with a GPU") to find the best match.
kube-controller-manager:

Runs background loops that constantly compare the actual state of the cluster to your desired state. If you requested 3 replicas of an app and one crashes (actual = 2), the controller notices the mismatch and commands the cluster to spin up a replacement.
cloud-controller-manager:

Interfaces with cloud providers (AWS, Google Cloud, Azure) to provision external resources like cloud load balancers, storage volumes, and firewall rules.

The Worker Node Components

Every Worker Node in the cluster runs three essential processes:

kubelet: An agent that runs on each node. It receives instructions from the kube-apiserver (e.g., "Run container X on this machine") and makes sure the containers are started and remain healthy.
kube-proxy: Manages network routing rules on each node. It ensures that requests sent to a Service get routed to the correct Pods, handling IP translations and load distribution across Pods.
Container Runtime: The software responsible for pulling container images and running them (e.g., containerd or CRI-O).

Core Kubernetes Objects & Concepts

Let's break down the building blocks you will interact with every day.

1. Pod (The Smallest Deployable Unit)

In Kubernetes, you never deploy a bare container directly. Instead, you deploy a Pod.

A Pod wraps one or more tightly coupled containers that share:

The same network namespace (meaning they can communicate with each other over localhost).
Shared storage volumes.
The same IP address.

Analogy: Think of a Pod as a pea pod. The peas inside are individual containers. Most Pods have just 1 container (e.g., your Node.js API), but some use helper "sidecar" containers (e.g., a logging or metrics collection agent).

+----------------------------------------------------+
| Pod (IP: 10.244.1.15)                              |
|                                                    |
|  +------------------------+  +------------------+  |
|  | Main Web App Container |  | Sidecar (Logger) |  |
|  |      (Port 3000)       |  |   (Port 9000)    |  |
|  +------------------------+  +------------------+  |
|               ^                       |            |
|               +--- talks via localhost --+         |
+----------------------------------------------------+

2. Deployment (The Self-Healing Manager)

Pods are mortal. If a node loses power or a pod crashes due to an out-of-memory error, that individual Pod is gone forever.

A Deployment is a higher-level controller that manages Pods for you. You declare your desired state: "I want 3 replicas of my web app running at all times."

The Deployment:

Creates and tracks the Pods.
Automatically replaces any dead or degraded Pods.
Performs zero-downtime rolling updates when you change the image version.

3. Service (The Stable Front Door)

Because Pods frequently start, stop, and move between nodes, their internal IP addresses are ephemeral and change constantly. If your Frontend needs to talk to your Backend, it cannot rely on hardcoded Pod IPs.

A Service provides a stable, permanent IP address and DNS name that sits in front of a group of Pods and automatically load-balances traffic across them.

Incoming Request
       |
       v
+--------------+
| Service VIP  |  (e.g., backend-service:80)
+-------+------+
        |
        +--------+------------------+
        |                           |
        v                           v
  [ Backend Pod 1 ]           [ Backend Pod 2 ]
  (IP: 10.244.1.5)            (IP: 10.244.2.8)

Common Service types:

ClusterIP (Default): Accessible only inside the Kubernetes cluster.
NodePort: Exposes the service on a static port on each worker node's IP.
LoadBalancer: Automatically provisions a cloud load balancer (e.g., AWS ALB or GCP Network Load Balancer) to expose your service to the internet.

4. Ingress (The Traffic Gatekeeper)

While a LoadBalancer Service gives you a dedicated public IP for a single service, spinning up a new cloud load balancer for every microservice is expensive and hard to manage.

An Ingress acts as a single, smart HTTP/HTTPS reverse proxy and router for your entire cluster:

Routes api.example.com to your backend-service.
Routes example.com to your frontend-service.
Handles SSL/TLS certificate termination in one place.

5. ConfigMap & Secret (Configuration Decoupling)

Following the 12-factor app methodology, your application code should be completely separated from its configuration.

ConfigMap: Stores non-sensitive configuration data (e.g., PORT: 8080, ENVIRONMENT: production, LOG_LEVEL: debug).
Secret: Encrypts and securely stores sensitive data (e.g., database passwords, OAuth tokens, API keys).

These values can be injected into your Pods as environment variables or mounted as configuration files.

6. Volume (Persistent Storage)

By default, container filesystems are temporary (ephemeral). When a container restarts, any files saved to local disk are wiped clean.

A Volume attaches persistent storage (such as AWS EBS, Google Persistent Disk, or NFS) to a Pod so data survives pod restarts and migrations.

The "Glue": How YAML Files Connect (Labels & Selectors)

Beginners often find Kubernetes YAML files confusing because they wonder: How does a Service know which Pods belong to it? How does a Deployment know which Pods it is managing?

The secret is Labels and Selectors:

Labels: Key-value tags attached to resources (e.g., app: my-web-app).
Selectors: Queries used by Deployments and Services to find matching Pods.

Let's see this in action with annotated YAML files.

1. Deployment YAML

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
    name: web-app-deployment
spec:
    # Desired number of copies
    replicas: 3

    # 1. SELECTOR: The Deployment manages Pods with this label
    selector:
        matchLabels:
            app: web-app
            tier: frontend

    # 2. TEMPLATE: Blueprint for creating each Pod
    template:
        metadata:
            # These labels MUST match the selector above!
            labels:
                app: web-app
                tier: frontend
        spec:
            containers:
                - name: web-container
                  image: nginx:1.25-alpine
                  ports:
                      - containerPort: 80
                  envFrom:
                      - configMapRef:
                            name: app-settings

2. Service YAML

service.yaml

apiVersion: v1
kind: Service
metadata:
    name: web-app-service
spec:
    type: ClusterIP
    # The Service routes traffic to any Pod matching these labels:
    selector:
        app: web-app
        tier: frontend
    ports:
        - protocol: TCP
          port: 80 # Port exposed by the Service
          targetPort: 80 # Port on the container inside the Pod

3. ConfigMap YAML

configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
    name: app-settings
data:
    APP_ENV: "production"
    CACHE_ENABLED: "true"

Step-by-Step: What Happens When You Apply the YAML files?

When a developer types kubectl apply -f deployment.yaml, here is the exact sequence of events that unfolds behind the scenes:

+-----------------------------------------------------------------------+
| 1. Developer runs: kubectl apply -f deployment.yaml                   |
+-----------------------------------+-----------------------------------+
                                    |
                                    v
+-----------------------------+           +-----------------------------+
|       kube-apiserver        | <-------> |            etcd             |
|  (Receives & validates API) |           |  (Saves cluster state)      |
+--------------+--------------+           +-----------------------------+
               |
               | 2. Notifies controller of desired state
               v
+-----------------------------+
|   kube-controller-manager   |
| (Creates 3 Pod definitions) |
+--------------+--------------+
               |
               | 3. Detects unscheduled Pods
               v
+-----------------------------+
|       kube-scheduler        |
|  (Finds best Worker Nodes)  |
+--------------+--------------+
               |
               | 4. Dispatches Pods to Node
               v
+-----------------------------+
|           kubelet           |
| (Worker Node Agent receives)|
+--------------+--------------+
               |
               | 5. Pulls image & starts Pod
               v
+-----------------------------+
|      Container Runtime      |
|    (containerd / CRI-O)     | ===> Pod is LIVE & Healthy!
+-----------------------------+

Submission: kubectl sends the YAML manifest via an HTTP POST request to kube-apiserver.
Persistence: kube-apiserver validates the request and saves the record in etcd.
Controller Loop: The Deployment Controller detects that 3 Pods are desired, but 0 are currently running. It creates 3 unscheduled Pod objects.
Scheduling: The kube-scheduler observes the unscheduled Pods, inspects the available Worker Nodes, and assigns each Pod to a node.
Execution: The kubelet on each assigned node detects the Pod assignment, instructs containerd to pull the nginx image, and starts the container.
Network Setup: kube-proxy configures routing so traffic sent to web-app-service reaches the new Pods.

Essential Cheat Sheet for Beginners

Here are the most common kubectl commands you will use daily:

# Check the status of your cluster nodes
kubectl get nodes

# View all running Pods and Deployments
kubectl get pods
kubectl get deployments
kubectl get services

# Deploy or update resources using a YAML file
kubectl apply -f deployment.yaml

# View detailed debugging info and events for a specific Pod
kubectl describe pod <pod-name>

# View real-time logs from a container
kubectl logs -f <pod-name>

# Open an interactive shell inside a running container
kubectl exec -it <pod-name> -- /bin/sh

# Manually scale your deployment up or down
kubectl scale deployment web-app-deployment --replicas=5

# Delete a resource
kubectl delete -f deployment.yaml

When Should You Use Kubernetes (and When Should You Avoid It)?

Kubernetes is powerful, but it comes with a steep operational learning curve. It is not always the right tool for every project.

When to Use Kubernetes:

You run a microservices architecture with dozens or hundreds of services.
You need automated horizontal scaling, self-healing, and multi-cloud portability.
You have a dedicated DevOps or Platform Engineering team to maintain the cluster.
You need complex rolling deployments, canary releases, or blue-green updates.

When to Avoid Kubernetes:

Small projects or MVPs: If you have a single monolithic app or a small side project, Kubernetes will add unnecessary complexity.
Simpler alternatives are sufficient: Managed container services like AWS ECS, Google Cloud Run, Render, or Railway offer 90% of the benefits with zero cluster management overhead.
Local development only: Use docker compose instead.

Docker Demystified: The Ultimate Guide to Containers and Architecture

Bibek — Fri, 28 Aug 2026 17:08:18 +0000

If you have ever dealt with the nightmare of "it works on my machine but crashes in production," you have felt the pain that containerization was built to solve. This post breaks down exactly what Docker is, how it works under the hood, and how it compares to its modern rival, Podman.

What is Docker

For years, deploying software meant provisioning a server, installing the correct operating system, downloading dependencies, and praying no other application on that server caused a conflict. If you deployed a Node.js server directory directly, you were at the mercy of whatever version of Node, Python, or system libraries happened to be installed on that host machine.

Docker is a containerization platform that solves this by packaging your application code alongside its entire environment: the specific OS user space, runtime, and system dependencies, into a single, standardized unit called a container.

Why Do We Need Docker

Consistency: The container runs exactly the same way on a developer's Mac, a testing server, and a production AWS EC2 instance.
Isolation: You can run App A (requiring Node 16) and App B (requiring Node 20) on the exact same server without them fighting over global variables or dependencies.
Fast Deployments & Rollbacks: Because you are pulling a pre-built image rather than running npm install on a live server, deployments take seconds. If an update breaks, rolling back is as simple as running the previous image version.

Key Features of Docker

Immutability: Once an image is built, it cannot be changed. This guarantees that what you tested is exactly what gets deployed.
Lightweight: Unlike Virtual Machines (VMs) that bundle an entire heavy operating system, containers share the host's OS kernel, making them incredibly small (often under 50MB) and fast to boot.
Portability: A Docker image built anywhere can run anywhere Docker is installed.

Docker Architecture (The "Kernel" Trick)

To understand why containers are so lightweight, you have to look at the architecture. Every operating system has two parts: the Kernel (which talks to the CPU and memory) and the User Space (the file system, UI, and system utilities).

No Guest Kernel: Docker images do not include a kernel. They only package the User Space (e.g., the Alpine or Ubuntu file system). When the container runs, it hooks directly into the host machine's existing Linux Kernel.
Client-Server Model: Docker relies on a background service called the Docker Daemon (dockerd). When you type docker run in your terminal (the Client), it sends an API request to the Daemon, which actually does the heavy lifting of building, running, and monitoring the containers.

Managing Environments and Ports

Because containers are isolated boxes, you have to explicitly define how they interact with the outside world.

Environment Management

You should never hardcode passwords or API keys into your code. Docker gives you three ways to inject them safely:

Dockerfile (ENV): Bakes default, non-sensitive variables directly into the image.
Runtime (-e): Injects overrides when the container boots (e.g., docker run -e DB_PASS=secret my-app).
Env Files (--env-file): Loads a list of variables from a local .env file, keeping your CLI commands clean.

Port Management

By default, a container's internal network is completely blocked off.

The EXPOSE Command: Often found in a Dockerfile (e.g., EXPOSE 3000), this does not open the port. It is merely documentation for other developers.
Publishing Ports: To let traffic in, you use the -p flag to map a port on your host server to a port inside the container: docker run -p 80:3000 my-app. This forwards all traffic hitting the host's Port 80 directly into the container's Port 3000.

How Docker Build Works (And The Mac/Ubuntu Magic)

If Docker relies on the host's Linux Kernel, how can a developer build and run Linux containers on a Mac?

When you install Docker Desktop on macOS, it secretly installs a highly optimized, hidden Linux Virtual Machine in the background. When you run docker build, you are actually using that hidden Linux VM to compile a native Linux image. Therefore, when you move that image to an Ubuntu EC2 instance, it feels right at home.

⚠️ The Caveat: CPU Architecture

While the OS difference is handled via the hidden VM, the CPU Architecture is a strict physical boundary.

Modern Macs use ARM64 processors (M1/M2/M3 chips).
Standard AWS EC2 instances use AMD64 (x86) processors.

If you build an image on an M-series Mac and run it on a standard EC2 instance, it will crash with an exec format error. To fix this, you must either cross-compile during the build (docker build --platform linux/amd64) or deploy to an ARM-based server (like AWS Graviton instances).

Registries: Updating and Pulling Images

You do not manually upload Docker images via SSH. Instead, you use a Container Registry—a specialized storage server designed to hold container images.

The Workflow:

Tag: Name your image with the registry URL (e.g., docker tag my-app accnt.dkr.ecr.us-east-1.amazonaws.com/my-app:v2).
Push: Upload the updated code/environment to the registry (docker push ...).
Pull: On your EC2 server, fetch the new image (docker pull ...) and restart the container.

Types of Registries:

Docker Hub: The public default.
AWS ECR: Secure, private, and tightly integrated into AWS.
Self-Hosted: You can run your own registry using Docker itself. However, the Docker Daemon strictly requires HTTPS for registries. If you self-host via plain HTTP, you must explicitly configure the daemon to allow insecure-registries, otherwise it will block the connection.

The Obvious Concerns Clarified

Performance Gap, Latency, and CPU/RAM Consumption

Containers do not run a hypervisor or a separate OS, so they have zero CPU or memory overhead. Your Node.js app runs at bare-metal speeds.
There is a microscopic network latency overhead (about 5-25 microseconds) when using Docker's default "Bridge" network due to internal routing. If you require absolute zero latency, you can use the --network host flag, which binds the container directly to the host's network interface.

Image-to-Image Communication

How does a Node.js container talk to a Redis container on the same server?
They do not use localhost. Instead, Docker creates a private internal network with its own DNS. If you name your cache container redis-server, your Node.js app can connect to it simply via redis://redis-server:6379. The ports never have to be exposed to the public internet.

Volume Storage (Hosting Databases)

Containers are ephemeral. If a container restarts, all data created inside it is permanently destroyed.
If you run a database inside Docker, you must use Docker Volumes. This maps a persistent folder on your host server (e.g., /home/ubuntu/db-data) to the database directory inside the container. When the container dies, the data remains safely on the EC2 drive.

Docker vs. Podman: What is the Difference?

As containerization evolves, Docker is no longer the only option. Podman is a modern alternative that aims to solve a few structural concerns with Docker.

The Architectual Shift:

Daemon vs. Daemonless: Docker relies on the central dockerd background daemon to manage everything. If the daemon crashes, your containers can go down. Podman is daemonless; each container runs as an independent, isolated child process.
Security (Rootless by Default): The Docker daemon requires root privileges, which is a security risk if an attacker breaks out of the container. Podman was built from the ground up to be rootless. You can build and run containers as a standard user without any elevated privileges, drastically reducing the attack surface.
Compatibility: Podman intentionally mimics the Docker CLI. In most CI/CD pipelines or local development environments, you can simply alias docker=podman and your existing scripts will run without modification.

While Docker remains the king of developer experience and tooling, Podman is rapidly becoming the enterprise standard for secure, production-grade Linux environments.

The State Pattern Trap: Why GoF Is Not Always the Best Choice

Bibek — Wed, 26 Aug 2026 09:20:13 +0000

Have you ever tried to use the classic Gang of Four (GoF) State Pattern in real code? You might have hit a wall. You might have thought, "Wait, this feels way too connected."

You are not wrong about that.

In school and many engineering interviews, the GoF State Pattern looks great. It promises to fix big, ugly switch statements. But real business rules are hard. When you use this pattern in real life, it can become a huge mess. Every state knows too much about the other states.

Let us look at why this happens. We will learn the difference between the GoF pattern and a Finite State Machine (FSM). We will also learn when to use each one.

The False Promise of the GoF State Pattern

The main idea of the GoF State Pattern is to spread out the work.

The main object gives its work to state objects. But there is a catch. The state classes themselves must trigger the change to the next state.

Example: The Traffic Light

Think about a simple traffic light. It goes Red to Green to Yellow to Red. It does this forever.

class RedState implements TrafficLightState {
    change(context: TrafficLight): void {
        console.log("RED light, Stop");
        context.setState(new GreenState()); // Very connected!
    }
}

The Problem: RedState is forced to know about GreenState.

This is fine for a simple traffic light. It is a closed loop. The rules will never change.

But what happens when business rules change?
Imagine the city council makes a new rule. From midnight to 5:00 AM, the light must flash yellow.

Now, you must open your RedState and YellowState classes. You have to add new time checks. You have to add the new flashing state. The more states you add, the messier your code gets.

The Better Choice: The Central FSM

In the real world, things do not always happen in a straight line.

An online order does not just go from Pending to Shipped to Delivered. It can jump from Pending to Cancelled. It can go from Shipped to Returned.

If you use GoF here, your PendingState needs to know about many other states. It gets too big.

This is where the Finite State Machine (FSM) comes in.
The main idea here is central control. State classes become simple. They only hold the rules for what happens inside that specific state. A central controller handles the moves between states. We call this central controller an Orchestrator.

Example: Order Processing

const orderRules = {
    PENDING: {
        PAID: "SHIPPED",
        CANCELLED: "CANCELLED",
    },
    SHIPPED: {
        ARRIVED: "DELIVERED",
        RETURNED: "RETURNED",
    },
};

class OrderController {
    currentState = "PENDING";

    handleEvent(event: string) {
        const nextState = orderRules[this.currentState]?.[event];
        if (nextState) {
            this.currentState = nextState;
            // Run the state logic here
        } else {
            console.log("Bad move!");
        }
    }
}

Why this works better:

Not Connected: State handlers do not know about each other.
Clear Rules: You can look at one simple list to understand the whole flow.
Easy to Change: Adding a new state does not break your old code. You just update the rules list.

The Final Choice: Which Should You Use?

Here are some simple rules to follow.

Use the GoF State Pattern when:

The flow is always a simple loop. A traffic light is a good example.
The rules are locked. You are very sure you will never add new states.

Use a Central FSM when:

The rules are complex and can jump around. Online orders and game AI are good examples.
Outside events choose the next state. If a user click or a timer changes things, use an FSM.
You need to track your code. A central FSM makes it very easy to see why a state changed.

Final Thoughts

Do not let old textbooks force you to write bad code. The GoF State Pattern is great for learning and for simple problems. But for complex real world software, a central FSM will save you a lot of stress.

9 RAG Techniques That Actually Improve Retrieval Quality

Bibek — Sat, 22 Aug 2026 19:36:18 +0000

Retrieval-Augmented Generation (RAG) is often described as a simple pipeline:

Query → Retrieve documents → Send context to an LLM → Generate answer

In production, however, retrieval is rarely that simple.

The retriever can return irrelevant documents. Important information may be buried in the middle of a document. A query may be too vague for semantic search. Retrieved chunks may lose their surrounding context. And sometimes the model does not need retrieval at all.

The quality of a RAG system therefore depends heavily on how information is retrieved, filtered, ranked, compressed, and presented to the model.

This guide covers nine techniques that address different parts of the RAG pipeline:

Reranking
Hybrid Search
Chunking Strategies
Multi-Query Retrieval
Parent Document Retrieval
Context Compression
HyDE
Self-RAG
CRAG

1. Reranking

Retrieve candidates. Reranking finds the best.

A vector database may search through hundreds or thousands of documents and return the top 20 candidate chunks.

But the first result from vector search is not necessarily the best result.

For example, suppose the correct answer is ranked at position #19.

If the application only sends the top 3–5 chunks to the LLM, the correct information never reaches the model.

                100 Pages
                    ↓
              Vector Search
                    ↓
           20 Candidate Chunks
                    │
        ┌───────────┴───────────┐
        ↓                       ↓
  Without Reranking       With Reranking
        ↓                       ↓
  Top 3–5 Chunks             Reranker
        ↓                       ↓
        │                 Top 5 Relevant
        │                     Chunks
        ↓                       ↓
        ↓                       ↓
       LLM                     LLM

Without reranking, the most relevant chunk might be ranked #19 and never reach the model.

With reranking, a reranker evaluates the retrieved candidates using both the query and the content of each chunk, promoting the most relevant results to the top.

The reranker can move a previously low-ranked but highly relevant chunk to the top.

What does a reranker do?

A reranker essentially asks:

Which of these retrieved chunks actually answers the user's question best?

Unlike basic vector similarity, a reranker can inspect the relationship between the entire query and the retrieved document.

This helps it:

Understand context better
Find hidden relevance
Filter out noise
Improve the quality of the final answer

Types of rerankers

Common approaches include:

Cross-Encoder
- High accuracy
- Slower
Bi-Encoder + Rerank Model
- Balanced performance
LLM-based Reranker
- Potentially highest quality
- More expensive

Example

Suppose a developer asks:

How can I make a Node.js API handle thousands of simultaneous connections?

A basic vector search might initially return chunks about HTTP status codes, API authentication, or general Node.js syntax.

A reranker can compare each candidate directly against the question and prioritize content discussing connection handling, asynchronous I/O, event loops, connection pooling, and horizontal scaling.

Key takeaway

Retrieve more. Rerank intelligently. Let the LLM see the best context, not merely the first context.

2. Hybrid Search

Meaning + Keywords = Better Retrieval

Semantic vector search and keyword search solve different problems.

Vector search understands meaning.

Keyword search understands exact words.

Using only one can cause important documents to be missed.

The problem

Consider this query:

"Redis connection timeout"

A semantic search might return:

Diagnosing cache connection failures
Distributed cache troubleshooting
Network latency in application infrastructure

These documents may be semantically related, but the exact phrase Redis connection timeout might not appear.

A keyword search such as BM25 can find:

Redis connection timeout configuration
Fixing Redis client timeout errors
Redis socket timeout settings

But keyword search may fail when the document uses different terminology.

Hybrid Search

Hybrid search combines both approaches:

                User Query
                    │
          ┌─────────┴─────────┐
          ↓                   ↓
    Vector Search        Keyword Search
     (Semantic)              (BM25)
          │                   │
          └─────────┬─────────┘
                    ↓
              Merge & Rank
                    ↓
              Final Results

The results from both searches are combined and ranked.

Common ranking methods

Popular approaches include:

Reciprocal Rank Fusion (RRF)
Weighted score combination
Relative score fusion
Rank-based fusion

Why hybrid search works

Vector search is good at understanding intent:

"cache performance troubleshooting"

Keyword search is good at exact terms:

"Redis MISCONF"

A production search system often needs both.

When hybrid search is useful

Hybrid search is particularly useful for:

Technical documentation
Spelling variations
Abbreviations
Exact technical terms
Natural language queries
Systems requiring both high recall and high precision

Key takeaway

Don't choose between meaning and keywords. Use both.

3. Chunking Strategies

Good chunks → Better Retrieval → Better Answers

Chunking is one of the most important decisions in a RAG system.

Documents are usually too large to embed and retrieve as a single unit, so they must be divided into smaller pieces.

But chunk size matters.

Why chunking matters

If a chunk is too large:

Important information can get buried
Retrieval becomes less precise
More irrelevant context reaches the LLM

If a chunk is too small:

Context is lost
More noise can be introduced
Individual chunks may not contain enough information to answer a question

The goal is:

Keep chunks as small as possible for precision, but as large as necessary for completeness.

1. Fixed-Size Chunking

The document is divided into chunks of a fixed number of tokens.

For example:

Document
   ↓
400 tokens
   ↓
400 tokens
   ↓
400 tokens
   ↓
...

An overlap can be added between chunks.

Advantages

Simple
Fast
Works reasonably well for general documents

Disadvantages

Can split sentences or concepts in the middle

2. Sentence-Based Chunking

Instead of splitting at arbitrary token boundaries, the system splits around sentence boundaries.

Sentence 1
Sentence 2
Sentence 3

Sentence 4
Sentence 5
Sentence 6

Advantages

Preserves meaning better
More natural and readable

Disadvantage

Sentence lengths can vary significantly.

3. Semantic Chunking

Semantic chunking groups sentences or paragraphs based on their meaning.

Conceptually:

Topic A
  ├── Authentication configuration
  ├── Token validation
  └── Session management

Topic B
  ├── Database indexing
  ├── Query planning
  └── Connection pooling

Advantages

High topic relevance
Keeps related content together

Disadvantages

More complicated
Requires embeddings

4. Parent Document Chunking

Small chunks are used for retrieval, but the larger parent section is returned to the LLM.

    Large Parent Document
              │
   ┌──────────┼──────────┐
   ↓          ↓          ↓
 Small      Small      Small
 Chunk      Chunk      Chunk

The small chunks provide retrieval precision while the parent document provides context.

5. Sliding Window Chunking

A moving window is used to create overlapping chunks.

Window 1
████████

    Window 2
    ████████

        Window 3
        ████████

This preserves more context across chunk boundaries.

Advantages

Good coverage
Maintains context flow

Disadvantage

More chunks mean more storage and potentially more retrieval cost.

6. Structure-Aware Chunking

The document's structure is used to determine chunk boundaries.

For example:

# Authentication
    ↓
Chunk 1

## Token Validation
    ↓
Chunk 2

- Access token
- Refresh token
    ↓
Chunk 3

Configuration Table
    ↓
Chunk 4

Code Block
    ↓
Chunk 5

This works particularly well for:

Documentation
Code
Structured PDFs
Knowledge bases

How should you choose?

There is no universally best chunking strategy.

The right strategy depends on the data.

A production system may combine multiple approaches:

Structure-aware splitting
        +
Semantic grouping
        +
Parent document retrieval

You should also experiment with chunk sizes such as:

256 tokens
512 tokens
1024 tokens

and measure actual retrieval performance.

Key takeaway

Good chunks bring the right context. The right context helps the LLM produce the right answer.

4. Multi-Query Retrieval

One question. Multiple perspectives. Better results.

A single query can fail because documents may describe the same concept using completely different language.

Even if query expansion improves the wording, searching in only one direction can still miss relevant documents.

The idea

Instead of searching once, ask the LLM to generate multiple versions of the query.

For example:

Original question:

How does OAuth token refresh work?

The system might generate:

What is OAuth token refresh?

How does a refresh token work?

What happens when an access token expires?

How does an application obtain a new access token?

What is the OAuth refresh-token flow?

Each query is searched independently.

               Original Question
                     ↓
               Generate Queries
                     ↓
        ┌────────┬────────┬────────┐
        ↓        ↓        ↓        ↓
      Search   Search   Search   Search
        └────────┴────────┴────────┘
                     ↓
               Merge & Rerank
                     ↓
                Final Chunks

Why this works

Different documents use different terminology.

One document might say:

OAuth token refresh

while another says:

renewing an expired access token

and another says:

obtaining a new bearer token using a refresh credential

Multiple queries give the retriever more opportunities to find relevant information.

Multi-Query vs Query Expansion

These concepts are related but not identical.

Feature	Query Expansion	Multi-Query
Main goal	Better wording	Different viewpoints
Queries	Similar variations	More diverse queries
Focus	Query improvement	Retrieval coverage
Recall	Good	Often higher
Typical use	General search	Production RAG

When it works best

Multi-query retrieval is particularly useful for:

Large knowledge bases
Technical documentation
Enterprise search
Research papers
Legal documents
Medical documents
Production RAG systems

Key takeaway

Don't ask once. Ask in multiple smart ways.

More angles give the retriever more chances to find the right information.

5. Parent Document Retrieval

Small chunks = better search. Parent documents = better understanding.

Small chunks are useful because they make retrieval precise.

But small chunks have a problem:

They can lose context.

Consider retrieving this chunk:

"... it automatically retries failed operations ..."

The chunk might be relevant, but by itself it doesn't tell us what "it" refers to.

The original section might say:

"The job processor automatically retries failed operations when a worker temporarily loses access to the message queue."

The parent document provides the missing context.

How Parent Document Retrieval works

Step 1: Create small chunks

Document
   ↓
Chunk 1
Chunk 2
Chunk 3
Chunk 4
...

Step 2: Search the small chunks

The vector database retrieves the most relevant chunks.

Top Chunks:
1
2
8
9
10

Step 3: Map chunks to their parent

Each chunk stores a reference to its parent section or document.

Chunk 8
   ↓
Parent Document / Section

Step 4: Send the parent context to the LLM

Instead of giving the LLM only the tiny chunk, provide the relevant parent section.

Small chunks → Search

Parent document → Context

This creates a useful separation:

Retrieve small. Read big.

When to use it

Parent document retrieval is useful when:

Chunks are very small
Documents contain many references
Answers require surrounding context
Pronouns and references are common
The meaning depends on information elsewhere in the section

Implementation tip

Store a parent_id with each chunk.

For example:

Chunk:
{
  id: "chunk_123",
  parent_id: "section_42",
  embedding: [...]
}

After retrieval, use parent_id to fetch the larger context.

Key takeaway

Chunks help you find information. Parent documents help the model understand it.

6. Context Compression

Too much context can be as bad as too little.

Imagine a retriever returns 40 chunks, but your LLM can effectively process only 8 useful chunks.

Sending all 40 creates several problems:

Higher token usage
Higher cost
More irrelevant information
More redundancy
Potentially worse answers

This is related to the lost-in-the-middle problem: important information can become harder for the model to use when surrounded by large amounts of irrelevant context.

How context compression works

40 Retrieved Chunks
        ↓
     Compress
        ↓
Keep Relevant Information
        ↓
8 Clean Chunks
        ↓
       LLM

The compressor attempts to remove everything that does not contribute meaningfully to answering the question.

What can be compressed?

Common targets include:

Duplicate chunks
Filler sentences
Low-relevance information
Long-winded explanations
Off-topic sections
Repeated information

Popular compression techniques

LLM Summarization

Summarize each chunk into a smaller representation.

Large chunk
    ↓
1–2 sentence summary

Keyword / Keyphrase Extraction

Keep the most important terms and phrases.

Redundancy Removal

Remove information that appears repeatedly across retrieved documents.

Extractive Compression

Keep only the sentences that directly contribute to answering the query.

Relevance Scoring

Score individual sentences or chunks and keep only high-scoring content.

Example

Suppose retrieval returns 40 chunks.

After compression:

40 chunks
   ↓
8 chunks
   ↓
~75% token reduction
   ↓
Better focused context

The exact improvement depends on the data and compression method, but the goal is to make the context smaller without losing useful information.

Key takeaway

More context is not always better. Relevant context is better.

7. HyDE

Hypothetical Document Embeddings

Think before you search.

HyDE stands for Hypothetical Document Embeddings.

It addresses a common retrieval problem:

The user's query may be too short or vague to produce a strong embedding.

For example:

"message queue retries"

The query contains only a few terms.

A better search signal could be a hypothetical answer generated by an LLM.

How HyDE works

Instead of embedding the original question:

User Question
     ↓
Embedding
     ↓
Vector Search

HyDE introduces an intermediate generation step:

User Question
     ↓
Generate Hypothetical Answer
     ↓
Embed Hypothetical Answer
     ↓
Vector Search
     ↓
Retrieve Documents
     ↓
    LLM

For example, the user asks:

How does a message queue retry failed jobs?

The LLM might generate a hypothetical answer such as:

A message processing system can retry a failed job when the worker encounters a temporary error. Retry policies commonly use a maximum attempt count and exponential backoff before moving permanently failed messages to a dead-letter queue.

The hypothetical answer contains more meaningful domain terms than the original question.

The system embeds that hypothetical answer and uses the embedding to search the knowledge base.

Why it can work

The generated answer may contain:

More domain-specific terminology
More context
Better representation of the user's intent
Terms that are likely to appear in relevant documents

This can improve semantic matching.

HyDE is not random guessing

The hypothetical answer is not used as the final answer.

It is primarily a search representation.

The actual answer still comes from retrieved documents.

Question
   ↓
Hypothetical Answer
   ↓
Embedding
   ↓
Retrieve Real Documents
   ↓
Generate Final Answer

HyDE vs Query Expansion

Query expansion usually creates multiple alternative queries.

HyDE generates a hypothetical document or answer and embeds that representation.

Query Expansion
→ Multiple queries

HyDE
→ One hypothetical answer
→ One embedding

When HyDE is useful

HyDE can help with:

RAG systems
Research assistants
Code search
Legal search
Medical document search
Enterprise knowledge bases
Vague or complex queries

Key takeaway

HyDE turns a weak question into a stronger search signal.

8. Self-RAG

Why search every time? Let the model decide first.

Traditional RAG often retrieves documents for every query.

But not every question needs external retrieval.

For example:

What is the square root of 144?

Retrieving documents from a vector database would be unnecessary.

The problem

Always retrieving causes:

Extra latency
Extra token usage
Additional infrastructure cost
Unnecessary vector database load

Self-RAG introduces a decision step.

      User Question
            ↓
   Should I retrieve?
            ↓
   ┌────────┴────────┐
  NO                YES
   ↓                 ↓
Answer            Retrieve
Directly             ↓
                  Generate

How Self-RAG works

The model first considers:

Do I need external information?
Do I already know the answer?
Is the question domain-specific?
Is the information likely to be recent?
Do I need private or internal documents?

If the answer is NO

The model answers using its internal knowledge.

Example:

What is 15 × 8?

No retrieval is required.

If the answer is YES

The system retrieves relevant documents.

Example:

What changed in our company's API documentation this week?

Retrieval is useful because the information is recent and internal.

When should Self-RAG retrieve?

Typical cases include:

Recent information
Live information
Domain-specific knowledge
Private/internal documents
Complex multi-hop questions

When can it skip retrieval?

Typical cases include:

General knowledge
Simple mathematics
Logic questions
Common facts
Questions where the model is sufficiently confident

Benefits

Self-RAG can:

Reduce unnecessary retrieval
Save tokens
Reduce cost
Reduce vector database load
Improve response latency
Use retrieval when it actually matters

Key takeaway

Traditional RAG retrieves every time. Self-RAG decides whether retrieval is needed before acting.

9. CRAG

Corrective Retrieval-Augmented Generation

Not every retrieved chunk is useful. CRAG checks the quality before trusting it.

A retriever is not perfect.

It can return:

Irrelevant chunks
Outdated information
Misleading information
Incomplete information

If the LLM blindly trusts those chunks, it can produce a confident but incorrect answer.

CRAG introduces a quality-control step.

How CRAG works

      User Question
           ↓
   Retrieve Documents
           ↓
Evaluate Retrieved Documents
           ↓
   ┌───────┴───────┐
 GOOD              BAD
   ↓                ↓
Use Docs     Correct Retrieval
                    ↓
             Refine / Re-query
                    ↓
              Retrieve Again
                    ↓
               Final Context
                    ↓
                   LLM

The retrieved documents are evaluated before they are trusted.

What does the evaluator check?

Potential criteria include:

Relevance
Completeness
Consistency
Whether the documents actually support the question

If the documents are good enough, they can be passed to the LLM.

If they are poor, the system can attempt corrective actions.

Examples include:

Refine the query
Try another search
Expand the query
Rerank the results
Filter noisy chunks
Retrieve from another source

Example

Suppose the user asks:

Which database is a good choice for high-volume event analytics?

The retriever returns:

1. Introduction to relational databases
2. Key-value cache configuration
3. Columnar database architecture for analytics
4. Basic SQL CRUD operations

The evaluator can determine that only some of these documents directly address the question.

The system can then remove weak results and perform additional retrieval if necessary.

The goal is:

Retrieve
   ↓
Check
   ↓
Correct
   ↓
Answer

Benefits

CRAG can:

Reduce confident wrong answers
Improve retrieval quality
Reduce hallucinations
Handle difficult queries
Filter noisy retrieval results
Improve the quality of final context

When CRAG helps most

CRAG is particularly useful for:

Complex multi-hop questions
Ambiguous queries
Long-tail questions
Low-quality retrieval systems
Domain-specific technical search
Enterprise knowledge systems

CRAG vs Normal RAG

Normal RAG:

Retrieve → Answer

CRAG:

Retrieve → Evaluate → Correct → Answer

The fundamental difference is that CRAG does not blindly trust the retriever.

Key takeaway

CRAG verifies the retrieved context before allowing the model to rely on it.

Putting the Techniques Together

These techniques do not need to be used independently.

A production RAG system can combine several of them.

For example:

                    User Query
                        │
                        ▼
                 Self-RAG Decision
                  /            \
                 NO             YES
                 │               │
                 ▼               ▼
             Direct Answer   Multi-Query
                                 │
                                 ▼
                           Hybrid Search
                           Vector + BM25
                                 │
                                 ▼
                             Retrieval
                                 │
                                 ▼
                              Reranking
                                 │
                                 ▼
                          CRAG Evaluation
                          /             \
                       GOOD              BAD
                        │                 │
                        │         Re-query/Correct
                        │                 │
                        └───────┬─────────┘
                                ▼
                      Parent Document Retrieval
                                │
                                ▼
                       Context Compression
                                │
                                ▼
                               LLM
                                │
                                ▼
                           Final Answer

Not every application needs every component.

The correct architecture depends on:

Query complexity
Document structure
Retrieval quality
Latency requirements
Cost constraints
Accuracy requirements
Whether the information changes frequently

A Practical Mental Model

Each technique solves a different failure mode.

Problem	Technique
Correct chunk is retrieved but ranked too low	Reranking
Exact keywords and semantic meaning both matter	Hybrid Search
Documents are difficult to split correctly	Better Chunking
One query misses relevant terminology	Multi-Query Retrieval
Retrieved chunk lacks surrounding context	Parent Document Retrieval
Too many retrieved chunks overwhelm the model	Context Compression
Query is vague or lacks useful search terms	HyDE
Retrieval isn't necessary for every question	Self-RAG
Retriever returns poor or misleading documents	CRAG

A Strong Production RAG Pipeline

A practical system might start with something relatively simple:

Documents
   ↓
Structure-Aware Chunking
   ↓
Embeddings + Keyword Index
   ↓
Hybrid Search
   ↓
Reranking
   ↓
Parent Context
   ↓
Context Compression
   ↓
LLM

Then add more advanced techniques only where measurements show they are needed.

For example:

Self-RAG

can reduce unnecessary retrieval.

Multi-Query Retrieval

can improve recall for difficult questions.

HyDE

can help with vague queries.

CRAG

can add a validation and correction loop.

The Bigger Picture

The biggest mistake when building RAG systems is treating retrieval as a single operation:

Query → Vector DB → LLM

Real-world retrieval is closer to a pipeline of decisions:

Should I retrieve?
        ↓
What should I search for?
        ↓
Where should I search?
        ↓
How should I split the documents?
        ↓
Which results are actually relevant?
        ↓
Which results should be ranked highest?
        ↓
How much context should I provide?
        ↓
Is the retrieved context trustworthy?
        ↓
Can the LLM answer from this context?

The quality of the final answer is often determined before the LLM generates a single token.

Better retrieval → Better context → Better answers.

And the goal isn't to build the most complicated RAG pipeline.

The goal is to build the simplest retrieval architecture that reliably provides the right context for your workload.

Engineering Reliable AI Document Scanning: Prompts and Schemas

Bibek — Sat, 22 Aug 2026 19:32:16 +0000

Managing short-term rentals and homestays usually involves a chaotic mix of spreadsheets, WhatsApp messages, and scattered paper receipts. Propio was built to replace that chaos with a purpose-built financial tracking platform.

One of the most powerful features in Propio is Smart Scan — an AI-powered OCR system that allows property managers to drop a receipt, invoice, or booking confirmation into the app and have all the relevant financial fields extracted and categorized automatically.

But building an AI that reads documents is easy; building one that extracts data reliably enough for financial records is incredibly difficult. If your AI hallucinates a tax amount or miscategorizes an expense, you haven't saved the user time—you've created a data integrity nightmare.

Here is a deep dive into how Propio's document scanning architecture works, focusing on the critical importance of system prompts, output structuring, and fallback mechanisms.

The Asynchronous Pipeline

Document processing is slow. Relying on a synchronous HTTP request to wait for an LLM to parse a multi-page PDF is a recipe for browser timeouts and frozen UIs.

Propio handles this asynchronously:

Stream to Storage: The user uploads a file, which is streamed directly to Cloudflare R2.
Task Creation: An AgentTask is created in MongoDB with a PENDING status, and the Task ID is returned to the client immediately.
Background Processing: The server kicks off the OCR processing in the background (asyncOcrAgentProcess).
Client Polling: The frontend polls the Task ID. The user sees a real-time progress stepper. Once the status hits COMPLETED, the extracted data pre-fills the expense or booking form for a quick human review.

This "fire-and-forget with polling" approach ensures the UI remains snappy regardless of how long the AI takes to "think."

Taming the AI: Schemas Over Free-Text

The biggest mistake when using LLMs for data extraction is asking for free-text or loosely formatted JSON. LLMs are eager to please and will often include conversational filler (e.g., "Here is the extracted data:"), which breaks standard JSON parsers.

Propio enforces strict structured outputs at the API level using the @google/genai SDK's schema definition.

const config = {
    responseMimeType: "application/json",
    responseSchema: {
        type: Type.OBJECT,
        properties: {
            recordDate: {
                type: Type.STRING,
                description: "This is receipt/invoice/billing date",
            },
            category: {
                type: Type.STRING,
                enum: ExpenseCategories, // e.g., ["Electricity", "Water", "Maintenance"...]
            },
            amount: {
                type: Type.NUMBER,
            },
            paymentMode: {
                type: Type.STRING,
                enum: ExpensePaymentOptions,
            },
            vendorName: {
                type: Type.STRING,
            },
            error: {
                type: Type.STRING,
                nullable: true,
            },
        },
    },
    systemInstruction: [{ text: expenseParsingSystemInstruction }],
};

By enforcing responseMimeType: "application/json" and providing a strict OpenAPI-style schema, we guarantee that the output will be parseable JSON matching our exact database requirements. We even pass our application's ENUMs (ExpenseCategories) directly into the schema to ensure the AI categorizes the expense into a bucket our frontend actually supports.

The Art of the System Prompt

Even with a forced JSON schema, the AI needs strict behavioral boundaries. Propio's expenseParsingSystemInstruction acts as a rigid set of rules designed to prevent hallucination and enforce normalization.

1. The "Do Not Guess" Rule

Financial data must be exact. The prompt explicitly states:

"Extract only data that is explicitly visible in the document. Never guess, infer, or fabricate values. If a field is missing or unclear, return null for that field."

2. Normalization Rules

Raw OCR data is messy. Dates come in various formats (MM/DD/YY, DD-MMM-YYYY), and amounts often include currency symbols or commas. We instruct the model to normalize this on the fly:

recordDate → YYYY-MM-DD format.
amount → numeric value only (remove currency symbols, commas, text).

3. Graceful Rejection

What happens if a user uploads a photo of their cat instead of a receipt? The agent needs an escape hatch.

FAILURE CONDITIONS: If the file is corrupted, blank, unsupported, not readable, or not a financial document, return only: { 'error': 'Seems like file is not a valid document' }

Because our schema includes a nullable error string, the AI can legally fulfill the JSON requirement while still rejecting the document.

High Availability: The Multi-Model Cascade

AI APIs go down. They get rate-limited. Models get overloaded. If your feature relies on a single model endpoint, your feature will break.

To ensure near-zero downtime for the Smart Scan feature, Propio implements a multi-model cascade with exponential backoff.

const Models = ["gemma-4-31b-it", "gemini-2.5-flash-lite"];

const generateContent = async (models, config, contents) => {
    const delayMs = 1000 * 2;
    const maxRetryPerModel = 2;

    for (const model of models) {
        for (let attempt = 1; attempt <= maxRetryPerModel; attempt++) {
            try {
                const response = await ai.models.generateContent({
                    model,
                    config,
                    contents,
                });
                if (response.text) return response;
            } catch (error) {
                // If it's a 429 Rate Limit, break and try the next model immediately
                if (error instanceof ApiError && error.code === 429) {
                    break;
                }

                // Otherwise, wait with exponential backoff and retry this model
                if (attempt <= maxRetryPerModel) {
                    const waitTime = delayMs * Math.pow(2, attempt - 1);
                    await sleep(waitTime);
                }
            }
        }
    }
    throw new Error("Model API call error. All models failed.");
};

This wrapper iterates through an array of preferred models. If the primary model fails due to a standard error, it retries with exponential backoff. Crucially, if it receives a 429 Too Many Requests error, it immediately aborts retrying the current model and seamlessly cascades to the next fallback model. The user rarely notices a delay.

Conclusion

Building reliable AI features isn't just about sending a prompt to an endpoint. It requires treating the AI as an unreliable function that needs strict guardrails.

By combining asynchronous processing for UX, strict JSON schemas for structural integrity, rigid system instructions for data accuracy, and multi-model cascading for resilience, Propio turns AI document scanning from a novelty into a dependable tool for property managers.

Building a Multi-Agent AI Pipeline with Mastra and TypeScript

Bibek — Sat, 22 Aug 2026 19:28:33 +0000

Building an AI feature is easy. Building a reliable multi-agent pipeline that coordinates four specialized AI agents, persists intermediate state, skips already-completed work on retries, and keeps the API responsive while the models think — that is the hard part.

This post walks through the architecture behind Clause AI, a platform that analyzes rental and lease agreements. It extracts key terms, flags risky clauses, and lets users chat with their contracts using RAG (Retrieval-Augmented Generation) — all powered by a coordinated pipeline of specialized AI agents.

The Problem with "Just Call an LLM"

The naive approach to building an AI-powered document analysis tool would be a single function that calls an LLM, parses the output, and saves it to a database. It works until it doesn't.

The moment you introduce multiple steps — parsing, summarizing, embedding, risk analysis — things break:

A worker crashes mid-pipeline, and you re-run everything from scratch.
You burn API quota re-processing steps that already succeeded.
Partial writes leave the database in an inconsistent state.
Multiple uploads compete for rate-limited model endpoints.

Clause AI was designed from the start to handle these failure modes, not as an afterthought.

Agent Design: Four Specialists, One Pipeline

Rather than one monolithic prompt that tries to do everything, the system uses four purpose-built agents — each with a focused responsibility, tuned model parameters, and a structured output schema.

Agent	Responsibility	Model Settings
Parser Agent	Extracts entities, dates, parties, payments, and clause-level structure	Low reasoning, temp 0.2
Summary Agent	Converts legal jargon into plain-English bullet points	Low reasoning, temp 0.6
Risk Agent	Flags risky or unfair clauses with severity scoring	Medium reasoning, temp 0.4
Query Agent	Answers user questions via RAG with tool use	Medium reasoning, temp 0.7

Each agent is configured with distinct reasoning levels and temperatures. The Parser Agent runs at a low temperature (0.2) because extraction requires precision — you want deterministic, faithful reproduction of what the document says. The Query Agent runs warmer (0.7) because conversational responses benefit from more natural phrasing.

Structured Output with Zod Schemas

Every agent produces validated, structured output using Zod schemas. The Parser Agent, for example, returns a typed object with nullable fields — if information is missing from the document, the agent returns null rather than hallucinating data.

const ResponseSchema = z.object({
    title: z.string().nullable(),
    type: z.enum(AGREEMENT_TYPES).nullable(),
    metadata: z
        .object({
            effectiveDate: z.string().nullable(),
            expiryDate: z.string().nullable(),
            autoRenewal: z.boolean().nullable(),
            governingLaw: z.string().nullable(),
        })
        .nullable(),
    parties: z
        .array(
            z.object({
                name: z.string(),
                role: z.enum(AGREEMENT_PARTY_ROLES),
                address: z.string().nullable(),
            }),
        )
        .nullable(),
    sections: z
        .array(
            z.object({
                ref: z.string(),
                type: z.enum(SECTION_CLAUSE_TYPES),
                heading: z.string(),
                content: z.string(),
            }),
        )
        .nullable(),
    error: z.string().nullable(),
});

This schema-first approach means downstream agents and database writes can trust the shape of the data they receive. No defensive parsing, no "hope the LLM returned the right format" — it either validates or it fails.

Orchestration with Mastra Workflows

The orchestration layer is where the architecture earns its complexity budget. The project uses Mastra — a TypeScript-native agent orchestration framework — to define workflows as composable, sequential pipelines with branching, iteration, and shared state.

Here is the main workflow definition, stripped to its essence:

export const agentWorkflow = createWorkflow({
    id: "agent-workflow",
    inputSchema: z.any(),
    outputSchema: z.object({ status: z.string() }),
    stateSchema: WorkflowStateSchema,
})
    .then(initiateStateHydration)
    .branch([[async ({ state }) => !state.skipParserAgent, parsingWorkflow]])
    .branch([[async ({ state }) => !state.skipSummaryAgent, summaryWorkflow]])
    .then(embeddingWorkflow)
    .branch([[async ({ state }) => !state.skipRiskAgent, riskWorkflow]])
    .then(finishStep)
    .commit();

The .then() calls chain steps sequentially. The .branch() calls conditionally execute sub-workflows based on runtime state. This is where fault tolerance comes in — but more on that in the next section.

Each sub-workflow itself is a two-step pattern: LLM call → DB persistence.

export const summaryWorkflow = createWorkflow({
    id: "summary-workflow",
    inputSchema: z.any(),
    outputSchema: z.any(),
    stateSchema: WorkflowStateSchema,
})
    .then(summaryAgentStep) // LLM call: generate summary
    .then(storeSummaryStep) // DB call: persist to Postgres
    .commit();

This separation is deliberate. The LLM step writes only to workflow state — an in-memory, transient object. The DB step is a separate, retryable operation. If the DB write fails, the LLM result isn't lost; it lives in state and can be retried without re-running the expensive model call.

State Hydration: The Key to Fault Tolerance

The most critical design pattern in the entire system is state hydration — the first step of every pipeline run.

Before any agent executes, the workflow reads the current state of the agreement from the database. If a previous run already completed the parsing step (title, type, parties, and sections exist in the DB), the hydration step sets skipParserAgent: true in the workflow state. The main workflow's .branch() sees this flag and skips the parsing sub-workflow entirely.

const hydrateWorkflowState = async (agreementId, userId, state) => {
    const agreement = await AgreementsService.fetchAgreement(
        agreementId,
        userId,
    );

    const [dbSections, dbRisks] = await Promise.all([
        AgreementsService.fetchSectionsByAgreement(agreementId, userId),
        AgreementsService.fetchRisksByAgreement(agreementId, userId),
    ]);

    return {
        ...state,
        title: agreement.title,
        sections: dbSections.length > 0 ? dbSections : state.sections,
        risks: dbRisks.length > 0 ? dbRisks : state.risks,
        // Skip flags based on what already exists
        skipParserAgent: Boolean(
            agreement.title &&
            agreement.metadata &&
            agreement.parties &&
            dbSections.length > 0,
        ),
        skipSummaryAgent: Boolean(agreement.summary),
        skipRiskAgent: Boolean(dbRisks.length > 0),
    };
};

This means:

Crash recovery is free. If the worker dies after parsing but before summarization, the retry picks up exactly where it left off.
No wasted API calls. Already-completed LLM steps are not re-run.
Idempotent by design. Running the workflow twice on the same agreement produces the same result without side effects.

There is also a forceRestart flag that bypasses hydration entirely, useful when the user explicitly wants to re-process a document from scratch.

Handling Fan-Out: Embeddings and Risk Analysis

Not every step in the pipeline is a simple A→B chain. The embedding and risk workflows use Mastra's .foreach() primitive to fan out work across multiple items.

Embedding Workflow

After parsing, each section needs a vector embedding for semantic search. The embedding workflow:

Prepares a list of sections that don't yet have embeddings (idempotent — already-embedded sections are skipped).
Fans out with .foreach(), running each section through a per-section sub-workflow.
Each sub-workflow generates the embedding, then persists it to the database.

export const embeddingWorkflow = createWorkflow({
    id: "embedding-workflow",
    inputSchema: z.any(),
    outputSchema: z.any(),
    stateSchema: WorkflowStateSchema,
})
    .then(prepareEmbeddingSectionsStep)
    .foreach(embeddingPerSectionWorkflow)
    .commit();

Risk Workflow

The risk workflow follows a similar fan-out pattern, but with a twist: sections are grouped by clause type before analysis. Instead of analyzing 15+ individual sections, the system groups them into logical categories (Rent, Termination, Maintenance, etc.) and analyzes each group in a single LLM call. This reduces the number of API calls while keeping each prompt focused.

export const riskWorkflow = createWorkflow({
    id: "risk-workflow",
    inputSchema: z.any(),
    outputSchema: z.any(),
    stateSchema: WorkflowStateSchema,
})
    .then(prepareRiskSectionsStep) // Group sections by type
    .foreach(riskAnalyzeStep) // Analyze each group
    .then(storeRiskResultStep) // Persist all results
    .commit();

The risk scoring itself is intentionally conservative. The Risk Agent's system prompt explicitly states that "absence of risk is a valid and expected outcome" and sets a high bar: only flag issues that are "risky enough to mention in a legal memo." Each identified risk gets a numeric score (0–100) that maps to severity levels.

Score Range	Severity
0–40	LOW
41–60	MEDIUM
61–80	HIGH
81–100	CRITICAL

The RAG Q&A Flow: Query Agent with Tool Use

Once the processing pipeline completes, the agreement is ready for interactive Q&A. The Query Agent is architecturally different from the other three — it runs on-demand per user question rather than as part of the batch pipeline, and it uses tool calling to decide what information it needs.

The agent has access to two tools:

fetchSectionsTool — Generates a query embedding, runs vector similarity search against the agreement's sections in pgvector, and returns the most relevant sections within a token budget.
fetchRisksTool — Returns pre-identified risks from the database (no embedding step needed).

The critical design choice here is that the agent decides whether to use tools at all. For simple questions that can be answered from the agreement's metadata (already injected into the system prompt) or from conversation history, no tool call is made. This keeps simple queries fast.

// Token-budgeted retrieval instead of fixed top-K
const selectedSections = [];
for (const s of sections) {
    const tokens = estimateTokens(s.content) + estimateTokens(s.heading);

    if (tokens + usedTokens > maxTokens) break;
    usedTokens += tokens;

    selectedSections.push({
        section: s.ref,
        heading: s.heading,
        content: s.content,
        similarity: s.similarity,
    });
}

The sections tool uses token-budgeted retrieval rather than a fixed top-K count. Since the Query Agent already carries conversation history and agreement metadata in its context window, blindly returning 10 sections could overflow the context and degrade response quality. Instead, sections are added until a token cap is reached, regardless of how many or how few that turns out to be.

Async Processing with Polling

The Q&A flow is fully asynchronous. When a user sends a question:

The message is saved and a query ID is returned immediately.
The Query Agent processes the question in a background worker.
The client polls the query ID until the status changes from Processing to Success or Failed.

This keeps the API responsive even when the model takes several seconds to reason through a complex question.

Decoupling with BullMQ

The entire processing pipeline is decoupled from the API layer through BullMQ (Redis-backed job queues). When a user uploads a document, the API doesn't start AI processing inline — it enqueues a job.

This solves two problems:

Rate limit protection. If multiple agreements are uploaded simultaneously, the queue absorbs the burst and processes jobs sequentially, avoiding concurrent model calls that would hit API rate limits.
Process isolation. A crash in the AI worker doesn't take down the API server. The job stays in the queue and gets retried.

The message worker handles both file processing jobs and email notification jobs, routing based on job name:

if (job.name === PROCESS_FILE_JOB) {
    await WorkflowService.startAgreementProcessing(agreementId, fileId, userId);
} else if (job.name === EMAIL_NOTIFICATION_JOB) {
    await NotificationService.sendEmailNotification(email, type, payload);
}

Model Resilience: Fallback and Rate Limit Handling

Every agent is configured with multiple model fallbacks. If the primary model returns a 429 (rate limited), the system marks it as unavailable for the duration specified in the retry-after header and automatically falls back to the next available model.

const parserAgent = new Agent({
    id: "parser-agent",
    name: "Parser Agent",
    instructions: Instructions,
    model: getAvailableModels().map((model) => ({
        id: model,
        model: model,
        modelSettings: {
            reasoning: "low",
            temperature: 0.2,
        },
    })),
});

This means the pipeline doesn't fail because of a temporary rate limit — it gracefully degrades to a different model and continues processing.

Putting It All Together

Here is the full pipeline from upload to interactive Q&A:

Upload — User uploads a PDF or DOCX lease agreement.
Queue — A BullMQ job is enqueued; the API returns immediately.
Hydration — The worker checks what work has already been done for this agreement.
Parse — The Parser Agent extracts structured data (conditionally skipped).
Summarize — The Summary Agent generates plain-English bullet points (conditionally skipped).
Embed — Each section is converted into a vector embedding (per-section fan-out, skips already-embedded sections).
Risk — The Risk Agent scores and classifies risky clauses (conditionally skipped, fan-out by clause type).
Finish — Status is set to Success; the agreement is ready for Q&A.
Chat — The Query Agent answers questions using tool-based RAG, grounded strictly in the document.

Every step is discrete, retryable, and idempotent. Intermediate state is persisted between steps. The workflow can be interrupted and resumed without losing progress or wasting API calls.

Key Takeaways

Building a multi-agent system isn't about calling multiple LLMs — it's about orchestrating them. The real engineering work is in the scaffolding:

Schema-first agent design ensures downstream consumers can trust the data shape.
State hydration makes crash recovery and retries free.
Separating LLM calls from DB writes means expensive model calls aren't repeated when only the persistence step fails.
Fan-out with .foreach() handles variable-length work (sections, risk groups) without hardcoding batch sizes.
Token-budgeted retrieval adapts to the available context window rather than using arbitrary limits.
Job queues decouple compute-intensive AI work from the request-response cycle.

The multi-agent approach isn't just an architectural choice — it's a reliability strategy. Each agent has a focused responsibility, a clear contract, and a failure boundary that doesn't contaminate the rest of the pipeline.

Simplify Phone Screening with Twilio and AI Automation

Bibek — Sun, 23 Jun 2024 22:52:58 +0000

This is a submission for the Twilio Challenge

What I Built

I explored several ideas for this challenge and did some research. Then, I found a LinkedIn post about how recruiters handle phone interviews for screening and the problems they face, like coordinating schedules between recruiters and candidates. Often, these calls are unplanned for the candidates, causing nervousness and a poor first impression. This inspired me to create a product that automates the process using IVR to conduct phone interviews for screening. The product would evaluate the call recordings and provide a summary of the entire conversation to the recruiter.

Flow of the system:

The recruiter will enter the candidate's details into the system through a form.
The candidate will receive an SMS notification with a link included in the message.
When the candidate clicks the link, the system will automatically dial their phone number.
An IVR call will guide the candidate through the interview and ask the necessary questions.
The candidate's responses will be recorded and transcribed by the system. AI will then use the transcription to provide context for the call recording.

Future Scopes/Improvements:

Develop a comprehensive multi-tenant dashboard for recruiters to manage records efficiently.
Integrate the system with job boards for seamless operation.
Implement an AI model to evaluate candidates' responses and rank them based on job requirements.

Demo

Walkthrough video

Demo application link

Application URL is https://ai-interview-call-8568-dev.twil.io/add-candidate.html
IVR call might not work for you as it is a demo account and only verified phone numbers are allowed.

Github link
https://github.com/bibekkakati/ai-interview-call

Twilio and AI

Let's discuss how I used Twilio and AI in the project.

Twilio Verify is used to validate the candidate's phone number and provide an internationally formatted result.
Twilio Programmable Messaging is used to send an SMS to the candidate with the interview call link.
Twilio Voice is used to make a call to the candidate, gather information, and record the candidate's responses.
Twilio Voice Intelligence is used to transcribe the call recordings.
Gemini AI is used to extract key points from the candidate's responses (transcriptions).
Twilio Serverless functions are used to deploy the functions and assets (a form to capture candidate details).

Additional Prize Categories

My submission qualifies for the following additional prize categories:

Twilio Times Two: Multiple Twilio features are used in the project.
Impactful Innovators: This product will greatly help recruiters and companies manage their time and resources better.

How to Build a Classic Snake Game Using React.js

Bibek — Tue, 04 Jun 2024 10:41:45 +0000

Hello folks! Welcome to this tutorial on developing the classic Snake game using ReactJS.

I've been working with technology for over six years now, but I've never tried building a game that many of us loved during our childhood. So, this weekend, I decided to create this classic Snake game using web technologies, specifically ReactJS.

Before proceeding further, let me clarify what we are building. As we know, there are various versions of the Snake game available on the internet. What we are building is a game board where the snake will move at a constant speed in the user-selected direction. When it consumes a food ball, its length will increase, and a point will be scored. If the snake's head touches the wall boundary or any part of its own body, the game is over.

Github: https://github.com/bibekkakati/snake-game-web

Demo: https://snake-ball.netlify.app

Game Design

Components in the game

Snake
Food Ball
Game Board
Boundary Walls

Approach

The game board is a 2D matrix with multiple rows and columns.
The intersection of rows and columns forms a cell.
A cell can be identified by its row number and column number.
The snake's body parts will be represented by these cell numbers on the board.
When the snake moves, the cell number (i.e., row and column number) will be updated for the body part cell based on the direction. For example, if the snake is moving to the right, the cell's column number will be incremented by 1.
Before rendering the snake's position after each movement, we also need to perform these steps:
- Check if this movement results in any collision with the boundary wall or its own body. If there is a collision, stop the game and show "game over"; otherwise, continue.
- Check if the snake's head cell number is the same as the food ball's cell number. If they match, update the score and place a new food ball on the board.

Implementation

We are writing all the logic and UI code in a single file, App.jsx, and using index.css for the styling. In this implementation, we will not be discussing the styling.

Constants

First, we will declare the constants before the component function definition.

const COLs = 48; // Number of columns on board
const ROWs = 48; // Number of rows on board

// Default length of snake i.e, it will consume 10 cell by default
const DEFAULT_LENGTH = 10;

// Declaring directions as symbol for equality checks
const UP = Symbol("up");
const DOWN = Symbol("down");
const RIGHT = Symbol("right");
const LEFT = Symbol("left");

State and Reference

Declare the reference and state variables.

const timer = useRef(null);
const grid = useRef(Array(ROWs).fill(Array(COLs).fill("")));
const snakeCoordinates = useRef([]);
const direction = useRef(RIGHT);
const snakeCoordinatesMap = useRef(new Set());
const foodCoords = useRef({
    row: -1,
    col: -1,
});
const [points, setPoints] = useState(0);
const [gameOver, setGameOver] = useState(false);
const [isPlaying, setPlaying] = useState(0);

The timer variable stores the instance of setInterval that we use to automate the snake's movement. This instance will be used to clear the interval when the game is over.
The grid variable stores the empty 2D array used to render the game board.
The snakeCoordinates variable stores the indexes of the snake's body parts, i.e., cell numbers. The 0th index value is the snake's tail, and the last value is the snake's head.
- The value of snake coordinates will look like { row: [Number], col: [Number], isHead: [Boolean] }.
The direction variable stores the user-selected direction. This value will be the same as the declared constant direction symbols.
The snakeCoordinatesMap variable stores the set of snake body parts, i.e., cell numbers. This helps in the render method to check which part of the board (grid) we need to render a snake body part on. The variable name includes the word map, but the value is of type Set.
The foodCoords variable stores the position of the food ball's cell number.
The points, gameOver, and isPlaying are state variables used to store the score, game over status, and game play status, respectively.

You might have noticed that isPlaying is a number, not a boolean. This is due to a specific bypass mechanism we will discuss in the coming sections.

Functionality

Let's discuss the implementation of snake's body movement along with collision check and food ball consumption.

We are writing a function moveSnake to handle the snake movement logic.

const moveSnake = () => {
        if (gameOver) return;

        setPlaying((s) => s + 1);

        const coords = snakeCoordinates.current;
        const snakeTail = coords[0];
        const snakeHead = coords.pop();
        const curr_direction = direction.current;

        // Check for food ball consumption
        const foodConsumed =
            snakeHead.row === foodCoords.current.row &&
            snakeHead.col === foodCoords.current.col;

        // Update body coords based on direction and its position
        coords.forEach((_, idx) => {
            // Replace last cell with snake head coords [last is the cell after snake head]
            if (idx === coords.length - 1) {
                coords[idx] = { ...snakeHead };
                coords[idx].isHead = false;
                return;
            }

            // Replace current cell coords with next cell coords
            coords[idx] = coords[idx + 1];
        });

        // Update snake head coords based on direction
        switch (curr_direction) {
            case UP:
                snakeHead.row -= 1;
                break;
            case DOWN:
                snakeHead.row += 1;
                break;
            case RIGHT:
                snakeHead.col += 1;
                break;
            case LEFT:
                snakeHead.col -= 1;
                break;
        }

        // If food ball is consumed, update points and new position of food
        if (foodConsumed) {
            setPoints((points) => points + 10);
            populateFoodBall();
        }

        // If there is no collision for the movement, continue the game
        const collided = collisionCheck(snakeHead);
        if (collided) {
            stopGame();
            return;
        }

        // Create new coords with new snake head
        coords.push(snakeHead);
        snakeCoordinates.current = foodConsumed
            ? [snakeTail, ...coords]
            : coords;
        syncSnakeCoordinatesMap(); // Function to create a set from snake body coordinates
    };

The first check ensures that if the game is over, we don't need to move the snake. It's just an extra precaution.
Next, we derive the current snake coordinates, the snake tail position, and the snake head position.
We then check if the food ball is consumed, meaning the snake head position should match the food ball position.
After that, we iterate over the body parts, excluding the snake head, to determine the new coordinates of the snake body.
- The position of each snake body part depends on the position of the next part, as the snake's body parts move in the same path as the head. So, we replace the current body part coordinates with the next body part's coordinates.
- If the body part is the last one, i.e., the neck, it will take the coordinates of the current snake head.
We then update the new snake head position based on the selected direction.
Finally, we check for food consumption and collisions and update the new snake coordinates if there is no collision.

Let's talk about how we populate the food ball.

    const populateFoodBall = async () => {
        const row = Math.floor(Math.random() * ROWs);
        const col = Math.floor(Math.random() * COLs);

        foodCoords.current = {
            row,
            col,
        };
    };

We generate a random row and column number based on our constants and set them in the reference variable foodCoords.

Now, let's discuss the collision check function.

    const collisionCheck = (snakeHead) => {
        // Check wall collision
        if (
            snakeHead.col >= COLs ||
            snakeHead.row >= ROWs ||
            snakeHead.col < 0 ||
            snakeHead.row < 0
        ) {
            return true;
        }

        // Check body collision
        const coordsKey = `${snakeHead.row}:${snakeHead.col}`;
        if (snakeCoordinatesMap.current.has(coordsKey)) {
            return true;
        }
    };

The function will receive the new snake head coordinates as a parameter.

First, we check for boundary collisions. If the new snake head's coordinates are greater than the respective constants or less than 0, it means the snake head is going out of range, which is a collision.

Next, we check for self-collision, meaning the snake head colliding with its own body. We do this by checking if the snake head coordinates are already present in the snake coordinates map.

Then we have the startGame and stopGame functions to control the gameplay.

    const startGame = async () => {
        const interval = setInterval(() => {
            moveSnake();
        }, 100);

        timer.current = interval;
    };

    const stopGame = async () => {
        setGameOver(true);
        setPlaying(false);
        if (timer.current) {
            clearInterval(timer.current);
        }
    };

startGame triggers a setInterval with a 100ms interval. After each interval, the moveSnake method is called.

stopGame sets the game over state, updates the gameplay status, and clears the interval instance.

Then, we have the render method.

    const getCell = useCallback(
        (row_idx, col_idx) => {
            const coords = `${row_idx}:${col_idx}`;
            const foodPos = `${foodCoords.current.row}:${foodCoords.current.col}`;
            const head =
                snakeCoordinates.current[snakeCoordinates.current.length - 1];
            const headPos = `${head?.row}:${head?.col}`;

            const isFood = coords === foodPos;
            const isSnakeBody = snakeCoordinatesMap.current.has(coords);
            const isHead = headPos === coords;

            let className = "cell";
            if (isFood) {
                className += " food";
            }
            if (isSnakeBody) {
                className += " body";
            }
            if (isHead) {
                className += " head";
            }

            return <div key={col_idx} className={className}></div>;
        },
        [isPlaying]
    );

    return (
        <div className="app-container">
            {gameOver ? (
                <p className="game-over">GAME OVER</p>
            ) : (
                <button onClick={isPlaying ? stopGame : startGame}>
                    {isPlaying ? "STOP" : "START"} GAME
                </button>
            )}
            <div className="board">
                {grid.current?.map((row, row_idx) => (
                    <div key={row_idx} className="row">
                        {row.map((_, col_idx) => getCell(row_idx, col_idx))}
                    </div>
                ))}
            </div>
            <p className="score">SCORE {points}</p>
        </div>
    );

The getCell method checks if the cell is empty, part of the snake's body, or food, and updates the CSS class name accordingly.

We use the useCallback hook in the getCell method, with isPlaying as a dependency. This isPlaying variable is a number that increases by 1 with each snake movement.

Here's why we did this:

Stale State Issue:

* Initially, many variables were state variables.

* The snake movement logic didn't work well because `setInterval` was calling `moveSnake` but the state values inside `moveSnake` weren't updating properly.

Switch to Reference Variables:

* To fix this, we changed those state variables to reference variables.

* This allowed `moveSnake` to access the latest values.

Re-rendering Problem:

* Reference variables don't trigger re-renders when they change.

* To solve this, we used the `isPlaying` state variable which increments by 1 with each snake movement.

* This increment ensures the `getCell` method has access to the updated reference variable and the component re-renders correctly.

Github: https://github.com/bibekkakati/snake-game-web

Demo: https://snake-ball.netlify.app

Works best on desktop web.

I hope this tutorial helps you understand the concept behind implementing a snake game. There are a few alternative approaches as well, but I found this method easier to understand and implement. Please feel free to share your feedback and suggestions.

Thank you for reading 🙏

If you enjoyed this article or found it helpful, give it a thumbs-up 👍

Feel free to connect 👋

Twitter | Instagram | LinkedIn

Navigating React.js SEO Challenges: A Case Study with CoderKit

Bibek — Sun, 19 Nov 2023 16:19:19 +0000

Introduction:

Embarking on the journey of launching CoderKit, a React.js application, brought with it the daunting challenge of Search Engine Optimization (SEO). This blog recounts the SEO hurdles faced and the inventive solutions employed to ensure visibility on Google.

The SEO Conundrum:

Post-launch, the realization struck that the application wasn't making its way to Google search results. Traditional solutions pointed toward static site generators or frameworks like Next.js, but migrating the project wasn't an option. Delving into SEO implementation nuances and website essentials, initial efforts to update meta descriptions in index.html proved futile.

Discovering the Power of Sitemap.xml:

A breakthrough emerged with the revelation of the significance of sitemap.xml. Creating a script to automatically generate this file based on known routes, devoid of dynamic backend-driven URLs, became pivotal. Configuring the Search Console to index these pages marked progress, but a notification soon arrived—indexing failure.

Addressing Redirection Woes:

Upon inspection, the issue lay in redirection. React applications default to landing on index.html, hindering search engines from indexing individual pages. An innovative solution materialized: generating HTML pages for each known route during the pre-build phase. These pages mirrored index.html structure but contained distinct meta tags and content pulled from the route config.

Making Redirection Seamless:

Concerns about server-level configurations were assuaged by platforms like Netlify, which inherently checked for file name matches with requested URLs. If found, they returned the file; otherwise, they defaulted to redirecting requests to index.html. This seamless redirection is crucial for React applications, ensuring that custom error components function effectively.

Testing and Triumph:

With all configurations updated in the Search Console, the real test began. After a day, a notification arrived—success! All pages were now indexed. However, the ranking was modest due to the application's novelty. A search appended with "coderkit" yielded optimal results, but there was room for improvement.

Conclusion:

This SEO journey with CoderKit reflects the iterative and adaptive nature of problem-solving in the tech realm. While the current approach has yielded positive results, the ever-evolving landscape of SEO beckons exploration. Feedback and alternative approaches are welcomed. Check out CoderKit to witness these strategies in action.

Unleash Your Coding Superpowers with CoderKit! 🚀

Bibek — Fri, 03 Nov 2023 19:34:28 +0000

🚀 The Spark of Inspiration

As a developer, I've been there, facing those repetitive coding tasks day in and day out. That's when the spark ignited. I asked myself, "How can we make this easier?"

💡 The Eureka Moment

And just like that, CoderKit was born. I dreamt of a toolbox filled with developer-friendly utilities. A JSON formatter, a text case converter, a code minifier and more – all at your fingertips.

🛠️ Building the Arsenal

The journey was a rollercoaster, crafting tools, and making them work seamlessly. It was just me and my code, hours upon hours. The tools became my coding companions.

👥 Inviting You to the Journey

Today, we're launching CoderKit Beta. It's about time we made your coding life simpler. These tools are designed to make your day-to-day coding tasks a breeze.

🤝 Your Feedback, Our Fuel

CoderKit isn't complete without you. Your feedback, and your insights – they're our guiding stars. This Beta launch is the beginning, and your suggestions will shape the future.

🔮 The Future of Coding

CoderKit is not just about tools; it's about coding with confidence. We're here to empower you – whether you're a pro or just starting.

🌐 Join the Journey

Come, and explore CoderKit Beta with us. Try out the tools, and share your thoughts. Let's make coding a bit more exciting.

🔧 Meet the Tools

JSON Formatter: Tame unruly JSON data with ease, ensuring readability and error-free code.
Text Case Converter: Convert text between various cases (e.g., CamelCase, snake_case) effortlessly.
JavaScript Minifier: Reduce file size and boost website performance by minifying your JavaScript code.
HTML Minifier: Optimize your HTML code for faster loading times and improved user experience.
CSS Minifier: Streamline your stylesheets to enhance website performance.
JavaScript Beautifier: Make your JavaScript code more readable and consistent.
HTML Beautifier: Elevate the aesthetics of your HTML code for better readability.
CSS Beautifier: Improve the structure and presentation of your CSS styles.
Base64 Encoder/Decoder: Encode and decode data with this versatile utility.
JWT Decoder: Decode JSON Web Tokens to inspect and verify their content.
Lorem Ipsum Generator: Generate placeholder text for content drafting and design prototyping.

👉 Get Started

Visit https://coderkit.dev and see how CoderKit can simplify your coding journey. Welcome to a world where coding just got a whole lot easier.

Here's to coding adventures with CoderKit! 🎉

What is Chat GPT

Bibek — Sat, 07 Jan 2023 15:30:09 +0000

GPT, or Generative Pre-training Transformer, is a type of language model developed by OpenAI that has been widely used for various natural language processing tasks. Language models are algorithms that are trained to predict the next word in a sequence of text, based on the words that came before it. GPT takes this a step further by using an attention mechanism, which allows it to consider the entire input context when making predictions.

One of the main use cases for GPT is text generation. Given a prompt, GPT can generate human-like text that is coherent and flows naturally. This has a wide range of applications, including generating news articles, creating social media posts, and even writing code.

Another use case for GPT is language translation. By training GPT on a large dataset of parallel text in two different languages, it can learn the relationship between the languages and generate translations that are accurate and fluent.

GPT can also be used for summarization, by generating a shorter version of a long piece of text that retains the main points and ideas. This can be useful for creating summaries of news articles, research papers, and other lengthy documents.

One of the most notable use cases for GPT is chatbots. By training GPT on a large dataset of conversation transcripts, it can learn how to carry on a conversation with a user naturally and coherently. Chatbots powered by GPT has been used for customer service, providing information and assistance to users, and even for entertainment.

Aside from these specific use cases, GPT has also been used for a wide range of other natural language processing tasks, including question answering, text classification, and even creating music.

Overall, GPT is a powerful and versatile tool for natural language processing, with a wide range of use cases and applications. Its ability to generate human-like text and understand the context of a conversation makes it a valuable asset for a variety of industries and purposes.

Benefits or advantages of using chat GPT:

Efficiency: Chatbots powered by GPT can handle a large volume of conversation without getting tired or needing breaks, which can be useful for customer service or other applications where there is a high demand for conversation.

Personalization: GPT can generate personalized responses based on the input it receives, allowing it to have unique conversations with different users.

Cost-effectiveness: Using chatbots powered by GPT can be more cost-effective than hiring human employees to handle conversation tasks.

24/7 availability: Chatbots powered by GPT can be available to chat with users around the clock, which can be convenient for users who need assistance outside of regular business hours.

Language support: GPT can be trained in multiple languages, allowing it to carry on conversations with users in different languages.

Drawbacks or disadvantages of using chat GPT:

Limited understanding of context: While GPT can generate text that flows naturally and considers the input it receives, it is ultimately limited in its understanding of context and may not be able to fully understand the nuances and subtleties of human conversation.

Lack of empathy: As a machine learning model, GPT cannot feel empathy or understand the emotions of others. This can make it difficult for it to fully engage in empathetic or emotional conversations.

Limited creativity: GPT is limited by the data it was trained on and the algorithms that power it, which means it may not be able to come up with creative or original responses to certain prompts.

Lack of accountability: As a machine, GPT cannot take responsibility for its actions or hold itself accountable in the same way a human would. This can be a concern in certain applications, such as customer service.

Dependence on data quality: The quality of the responses generated by GPT is largely dependent on the quality of the data it was trained on. If the training data is biased or contains errors, the responses generated by GPT may also be biased or inaccurate.

~ This article was written by Chat GPT.

Originally published on bibekkakati.hashnode.dev

Thank you for reading 🙏

If you enjoyed this article or found it helpful, give it a thumbs-up 👍

Feel free to connect 👋

Twitter | Instagram | LinkedIn

If you like my work and want to support it, you can do it here. I will really appreciate it.