DEV Community: Hamid Shoja

Coding agents: A silent hook babysits, a loud hook teaches

Hamid Shoja — Tue, 28 Jul 2026 17:48:00 +0000

Hi friends

Third post in a series about setting up coding agents in a real codebase (part 1: structuring CLAUDE.md, skills and agents, part 2: skill descriptions). This one is about hooks, and the difference between a hook that fixes and a hook that teaches.

Two flavors of hook

A hook is code that runs on the agent's actions - the surface for rules that must never be skipped. Instructions can be rationalized away ("it's just a filename, close enough"); a hook can't.

But hooks come in two flavors:

A silent-fix hook repairs the output automatically. The agent never sees an error, so it keeps generating the wrong pattern forever.
A fail-loudly hook blocks and returns an error. The message lands in the agent's context - one failure, one lesson.

Silent is fine when the fix is mechanical and always correct: we run prettier from a hook after every turn, the agent never learns to format, nobody cares. The interesting case is when the fix needs knowledge the hook doesn't have. Then loud is mandatory.

The Postgres migration hook

Our migrations use Flyway, and the file name IS the API:

V012__Billing_AddInvoiceIndex.sql

Get it wrong and nothing crashes on your machine - Flyway just skips the file or orders it wrong, and you find out in a deploy. It's exactly the kind of rule agents violate: the SQL is perfect, the filename is add_invoice_index.sql.

Could a hook silently rename it? No. A rename needs the next version number, the right schema, a description - knowledge that lives on the agent's side. A silent fix here isn't just pedagogically worse, it's less correct. So the hook's job is to refuse, and say why:

#!/usr/bin/env bash
# PreToolUse hook on Write|Edit: enforce Flyway migration naming.
set -euo pipefail

input=$(cat)
file=$(python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))' <<<"$input")

[[ "$file" != */db/migrations/* ]] && exit 0

name=$(basename -- "$file")
if [[ ! "$name" =~ ^[VB][0-9]{3}__[A-Za-z][A-Za-z0-9]*_[A-Za-z0-9]+\.sql$ ]]; then
  {
    echo "Blocked: '$name' is not a valid Flyway migration name."
    echo "Expected: V<3-digit-version>__<SchemaName>_<Description>.sql"
    echo "Example:  V012__Billing_AddInvoiceIndex.sql"
    echo "(B prefix for baseline migrations. Check existing files for the next version number.)"
  } >&2
  exit 2
fi
exit 0

Wired up in settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/migration-name.sh" }]
      }
    ]
  }
}

What happens next is the whole point: the write is blocked, the agent reads the rule, checks existing files for the next version, renames to V013__..., and names every migration correctly for the rest of the session. The violation taught it.

The fix, precisely

"Fail loudly" is a choice of three patterns, and the decision fits in a table:

Pattern	Mechanics (Claude Code)	Use when
Silent fix	apply fix, `exit 0`	fix is mechanical and always correct (formatting)
Loud fix	apply fix, print what you fixed to stderr, `exit 2` (PostToolUse)	fix is safe to automate but the pattern should stop appearing
Loud reject	no fix, print the rule to stderr, `exit 2` (PreToolUse)	fix needs knowledge the hook doesn't have, or the action is dangerous

Exit codes, because this is where people get it wrong: exit 0 allows, the agent sees nothing. exit 2 feeds stderr back to the agent - on PreToolUse it also cancels the action; on PostToolUse the action already happened, so it just delivers the lesson. Any other exit code shows stderr to the human only: the agent learns nothing, the worst option for rules.

Converting a silent autofix into a loud fix is one extra branch:

# Before - agent never learns, hook mops up forever
eslint --fix "$file" >/dev/null 2>&1
exit 0

# After - same fix, and the agent stops making the mistake
before=$(git hash-object "$file")
eslint --fix "$file" >/dev/null 2>&1
after=$(git hash-object "$file")

if [[ "$before" != "$after" ]]; then
  {
    echo "Auto-fixed import order in $file."
    echo "Rule: external imports first, then common/, then relative, sass last."
    echo "Write it in that order next time."
  } >&2
  exit 2
fi
exit 0

That's the whole solution: detect whether you changed anything, and if you did, say so on stderr and exit 2.

The migration hook above is the loud reject template: match the path, validate, refuse with the rule plus a valid example. Swap the regex and the message and you've got the same enforcement for branch names, commit formats, whatever your team keeps repeating in review.

The error message is a teaching surface

The rejection message is where most hooks fail. It needs four things:

What was blocked - the exact filename, no ambiguity
The rule - the format spec, not just "invalid name"
A valid example - agents pattern-match; one example beats three paragraphs
Where to look next - "check existing files for the next version number"

A hook that just says error: invalid file blocks but teaches nothing - the agent retries variations and burns tokens guessing. Write the stderr like a review comment from a good colleague.

A repeated rejection is a bug report against your docs

Is it OK that this loop repeats every session - violate, reject, correct, forget? No. The lesson dies with the context window, and a rejection that fires session after session means your instruction layer failed: docs and skills are prevention (they load before the action), the hook is the guarantee - and its firings are telemetry on how prevention is doing.

Fires once in a while: backstop doing its job. Fires repeatedly: a failing test against your docs. Three usual causes:

The rule isn't in any surface that loads before the action -> add it to the skill that owns the task (our migration rule belongs in the migrations skill, not just the hook).
The rule exists but the skill never triggers -> a routing bug, fix the skill description (previous post).
The rule is in CLAUDE.md but buried in a wall of text -> promote it, shorten it, or move the noise out.

One line of bash turns the hook into telemetry - log before the exit 2:

echo "$(date +%F) $name" >> "$CLAUDE_PROJECT_DIR/.claude/hook-rejections.log"

The most-fired rules in that file are exactly the docs most worth fixing. So "hook or fix the skill?" is the wrong question - both, in that order of time: hook immediately, then let the repeat-firings tell you which doc fix pays for itself.

Loud or silent - the checklist

Fix is mechanical, always correct, and nobody cares if it repeats (formatting)? Silent fix.
Fix is safe to automate but you're tired of seeing the pattern? Loud fix.
Fix needs knowledge or judgment (naming, versioning, schema)? Loud reject.
Violation is expensive or irreversible downstream (prod deploy, data migration)? Loud reject, always.

One sentence to keep: a silent hook babysits, a loud hook teaches. Babysit the whitespace, teach everything else.

Hope that helped!
Hash

Coding agents: Your skill bodies are fine, your descriptions are broken

Hamid Shoja — Tue, 28 Jul 2026 17:36:00 +0000

Hi friends

This is a follow-up to my post about structuring CLAUDE.md, skills and agents. A comment on that post pointed at a failure layer I had completely skipped, and it deserves its own write-up: your skill bodies can be perfect and the agent still never reads them.

The invisible bottleneck

Skills load lazily, that's the whole point. Until one triggers, the only thing the model can see is the one-line description in the frontmatter. Which means routing accuracy is bounded by how well a single sentence discriminates between neighboring skills.

You can audit every body, verify every code example against the codebase, run retrieval tests on the content... and none of it matters if the model picks the wrong skill, or no skill, or decides the sentence already told it everything it needs.

Two failure modes to check for.

Failure 1: the description that replaces the skill

# BAD - the description IS a procedure
description: Verifies finished work by running tests, checking the diff
  for weakened assertions, and reporting pass/fail

The model reads that sentence, feels it already knows the procedure, and executes a shallow version from memory: run tests, glance at diff, report. It never opens the body, where the actual teeth live ("diff each changed assertion against the base branch; a widened tolerance counts as failure").

The skill "fired", but the one check that mattered didn't happen. And it looks like success in your logs.

# GOOD - trigger only, zero procedure
description: Use when a refactor or bugfix is complete and you are about
  to report it as done. NOT for doc-only changes.

Now the sentence contains nothing executable, so the model has to read the body to know what to do. The description's only job is routing.

Failure 2: skills that shadow each other

# skill A
description: Testing best practices for this repo
# skill B
description: Testing best practices - integration harness, DB fixtures, fake upstreams

Both start with the same phrase. Every testing task matches A first, and the deeper B never loads. Here's the trap: rewriting the bodies changes nothing, the model never gets past the sentence. You can polish skill B forever and it stays invisible.

Fix it at the description level, with discriminating triggers:

# skill A
description: Use when writing or fixing unit tests for components or pure
  functions. NOT for endpoint or database tests.
# skill B
description: Use when testing HTTP endpoints against a real database or
  faked upstream services (integration tests).

Test descriptions like you test docs

In the previous post I ran retrieval tests against doc bodies: give a subagent only the docs, no repo access, make it answer implementation questions, grade against the codebase. The extension: run a second version against the descriptions alone.

Give a subagent just the list of skill descriptions, nothing else, and feed it real task prompts:

"Write an integration test for the orders endpoint."
"A refactor is done, wrap it up."
"Fix this flaky unit test."

Ask one question: which skill would you load, and why? Grade the routing. If the wrong skill wins, or none triggers, or the model says "no need to load anything, the description tells me what to do" - your descriptions failed the test. Fix the sentences, not the bodies.

The rule of thumb

The description answers "should I load this skill right now?", never "what will it do once loaded?"

If you can execute the description, it's carrying content that belongs in the body. A quick checklist for each skill:

starts with "Use when ..." (a trigger, not a capability)
says what it's NOT for, if a neighboring skill is close
contains no procedure verbs (run, check, verify, generate)
no two skills in the folder could match the same task prompt

One sentence of frontmatter is doing the routing for everything underneath it. Test it like it matters, because it does.

Hope that helped!
Hash

How to structure CLAUDE.md, Skills and Agents

Hamid Shoja — Sat, 25 Jul 2026 09:00:00 +0000

Hi friends

Here's a tip for when you're setting up Claude Code (or any coding agent) in a real codebase, this came in clutch for me when I discovered our agent docs were actively generating broken code.

The problem

Most projects end up with four kinds of instruction files:

CLAUDE.md / AGENTS.md files
skills (.claude/skills/...)
agent definitions (.claude/agents/...)
big reference docs (UI library API, internal tooling, etc.)

And the same knowledge gets copy-pasted into all of them. Each copy drifts separately. When I finally audited every claim in ours against the actual code, it was worse than I thought:

The styling docs showed a CSS-modules pattern that produces class names that never match the build config. Any agent following it ships broken styles.
The canonical test template set up mocks in beforeAll, but the test setup file restores all mocks after every test. So the mock silently dies after test one.
The same template rendered a data-fetching component without its required provider. Instant crash on render.
The "recommended" test helper was used by exactly 1 of 50 real test files.

The docs looked complete. They were confidently wrong. And every wrong doc costs you a multi-thousand-token debug loop when the agent hits it.

The rule of thumb

It's all about when it loads and who needs it:

Surface	Loads	Should own
CLAUDE.md / AGENTS.md	always, every session	rules true for every edit
Skill	on demand, per task type	deep how-to knowledge
Agent	when delegated	workflow and gates, not knowledge
Hook	enforced by code	rules that must never be skipped

Four questions to route any piece of content:

Applies to every change in the folder? Then CLAUDE.md: import style, naming, commands, project structure. Keep it small, it pays token rent every single session.
Only needed for one kind of task, but deep? Then a skill: styling mechanics, data-fetching patterns, testing recipes. Costs nothing while idle, only the description loads until it triggers.
Is it a role or a process rather than knowledge? Then an agent: the workflow order, the definition of done, which skill to load. Keep agents thin, knowledge buried in an agent file is invisible to everyone else.
Not acceptable to ever skip? Then a hook. Instructions can be rationalized away, code can't. Run your formatter from a hook, not from a sentence asking nicely.

The one rule that stops the rot

Every fact lives in exactly one file. Everything else links to it.

Our drift existed precisely because one test template was pasted into three places and evolved independently. After the cleanup:

CLAUDE.md / AGENTS.md  -> rules in 3 lines max + link to the skill
skill                  -> the deep patterns, citing real source files
agent                  -> workflow + "run the check command and observe it pass"
reference doc          -> single home for the heavy API reference

So we can define the boundary in one sentence: if a pattern needs more than a few lines, it goes in the skill and CLAUDE.md gets a link.

Verify your docs like you verify code

This was the fun part. Docs claims are testable, so test them:

First, grep before you trust. Every example in your docs should exist in the codebase. Ours didn't:

# "best practice" from our docs vs reality
grep -rl "prefetchQuery" src/ | wc -l      # 0 uses
grep -rl "recommendedHelper" src/ | wc -l  # 1 of 50 test files

Then run a retrieval test with a subagent. Give it ONLY the doc files, no repo access, and make it answer real implementation questions:

"Write a test for a component that fetches data."
"Which package does this component come from?"
"Where do global stores live?"

Grade the answers against the codebase. If the agent following your docs writes code that would fail, your docs failed the test, fix them before merging. We caught every regression this way, before it cost anyone a debug session.

What it achieved

~11% smaller context per typical feature task, leaner always-on footprint
a convention change now touches 1 file instead of 3
and the big one: the docs no longer generate broken styles and failing tests, each of those was a few thousand tokens of debugging every time an agent stepped on it

this example demonstrates that agent docs are a system with loading semantics, not a wiki: put each fact where its loading model matches, keep one home per fact, and test docs like code.

Hope that helped!
Hash

Why Sequential Reads Beat Random Reads in Postgres at Scale

Hamid Shoja — Fri, 24 Jul 2026 17:16:00 +0000

We had a large table - hundreds of gigabytes - that needed to be fully exported and processed in batches. The pipeline fetched rows from Postgres in batches of 2000, processed them, and pushed results downstream.

It was slow. Much slower than expected. The bottleneck wasn't the processing. It was Postgres. Specifically, how we were reading from it.

How Postgres Stores Data

Before getting to the fix, you need to understand three things: pages, slots, and sequence columns.

Pages are fixed 8KB chunks on disk. Everything Postgres stores lives inside pages.

disk: [page 0][page 1][page 2][page 3]...
       8KB     8KB     8KB     8KB

Slots are positions of rows within a page. Each page holds however many rows fit in 8KB - typically 10-20 rows depending on row size.

page 1 (8KB):
  slot 1: [row data - ~500B]
  slot 2: [row data - ~500B]
  slot 3: [row data - ~500B]
  ...

A row's physical address is (page, slot). Postgres calls this a ctid.

A sequence column (like an id or created_at) is just a business column in your table - a regular value like any other field. It has no relationship to where the row lives on disk.

page 1:
  slot 1: { id: 892, name: "foo", status: "active" }
  slot 2: { id: 3,   name: "bar", status: "pending" }
  slot 3: { id: 445, name: "baz", status: "active" }

Rows are written to the heap in insert order, not id order. Deletes, updates, and bulk loads all shift things around. So id 1, 2, 3 can be on completely different pages scattered across the table.

The Index Makes It Worse at Scale

Postgres builds a B-tree index on id that maps each value to a ctid:

Index (B-tree on id):            Heap (actual rows on disk):

id → (page, slot)                page 0: [id=892][id=3  ][id=445]
  1 → (5, 2)                     page 1: [id=7  ][id=1  ][id=22 ]
  2 → (2, 3)                     page 2: [id=2  ][id=567][id=88 ]
  3 → (0, 2)                     ...

When you run WHERE id > X LIMIT 2000:

Postgres walks the B-tree to find matching ids in order
For each one, jumps to a random heap page to fetch the row
2000 rows = up to 2000 random page reads, each potentially on a different part of disk

At small scale this is fine. At hundreds of gigabytes it kills you - the disk head is constantly seeking to new locations.

The Sequential Scan Fix

A cursor tells Postgres to scan the heap directly, page by page, from start to finish:

BEGIN;

DECLARE rows_cursor CURSOR FOR
  SELECT * FROM events
  WHERE id > 0
  ORDER BY id;

FETCH 2000 FROM rows_cursor;  -- reads ~130 pages sequentially
FETCH 2000 FROM rows_cursor;  -- continues from where it left off
FETCH 2000 FROM rows_cursor;  -- no seeking, no index lookups
-- ...

COMMIT;

FETCH 2000 doesn't mean "read 2000 pages". Each page holds N (e.g. 16) rows, so fetching 2000 rows reads ~130 pages. The cursor remembers where it stopped and the next fetch continues from there.

Across the entire export, every 8KB page is read exactly once. No page is visited twice. No index lookups. The OS can prefetch pages ahead because the read pattern is completely predictable.

Sequential vs Random - Side by Side

Random reads (index scan):
  query 1 → index lookup → jump to page 450 → read 16 rows
  query 2 → index lookup → jump to page 23  → read 16 rows
  query 3 → index lookup → jump to page 891 → read 16 rows
  disk head: seeks constantly

Sequential scan (cursor):
  fetch 1 → page 0  → read 16 rows
  fetch 2 → page 1  → read 16 rows
  fetch 3 → page 2  → read 16 rows
  disk head: moves forward, never back

Same data. Same Postgres. Just read in a straight line instead of jumping around.

The Trade-off

The cursor holds an open transaction for the duration of the scan. For a large table that takes hours or days to process, this blocks vacuum, bloats pg_wal, and holds locks.

In practice, keyset pagination gets most of the benefit without a long-lived transaction:

-- track last seen id, restart cleanly if interrupted
SELECT * FROM events
WHERE id > :last_seen_id
ORDER BY id
LIMIT 2000;

-- update :last_seen_id after each batch and repeat

This isn't a pure sequential scan but it's close enough - as long as id correlates with physical insert order, most reads will be forward-moving on disk.

Result

When a full table export is slow, the first thing to check isn't hardware or downstream processing. It's whether you're doing thousands of random index lookups when you could be reading the table in a straight line.

The index is great for finding a few rows. For reading everything, it's just overhead.

5- AWS Serverless:: Caching and Event-Driven Design

Hamid Shoja — Tue, 16 Jun 2026 20:56:00 +0000

When building high-scale, resilient systems on AWS, performance isn't just about writing fast code, it’s about avoiding unnecessary work. A Engineer’s philosophy often boils down to a simple truth: The fastest code is the code that never executes, and the fastest database query is the one you never have to make.

Let’s unpack caching in AWS piece by piece with a few real-world examples.

Layer 1: Edge Caching (AWS CloudFront)

AWS CloudFront is a Content Delivery Network (CDN). Instead of forcing every user around the world to request data from your main servers (say, located in Virginia), CloudFront replicates data across hundreds of data centers globally, called Edge Locations. If a user in London requests an asset, CloudFront serves it from a London edge server.

There are two types of data cached here:

Static assets: Images, CSS, JavaScript files.
Cacheable API responses: Data from your backend that doesn't change frequently (e.g., a product catalog list).

This is controlled using standard web instructions called Cache-Control HTTP headers sent by your application (e.g., Cache-Control: public, max-age=3600 tells CloudFront to hold onto this data for one hour).

Simple Example:

Imagine an e-commerce store. The logo image (logo.png) and the list of product categories (Shoes, Hats, Shirts) rarely change.

The Flow: When User A requests the category list, CloudFront fetches it from your database once, saves a copy at the Edge, and delivers it. When Users B through Z request the same list, your database is never touched; CloudFront handles it entirely at the edge.
Pipeline Invalidation: When the developers deploy a new version of the website code with a new logo, the deployment pipeline automatically runs a command (aws cloudfront create-invalidation) to forcefully wipe the old logo out of CloudFront's memory globally so users immediately see the new one.

Layer 2: Application Layer Caching (Amazon ElastiCache Redis)

When a request gets past CloudFront and hits your backend compute (AWS Lambda), you don't want the application to immediately hit the primary database if it doesn't have to. we can place Amazon ElastiCache Redis here. Redis is an ultra-fast, in-memory data store.

There are a few specific choices here:

Inside the same VPC: A Virtual Private Cloud (VPC) is your private, isolated network in AWS. Putting Lambda and Redis in the same VPC ensures they can talk to each other securely and with incredibly low latency.
Redis over Memcached: Memcached is a simple key-value cache (e.g., store a string, get a string). Redis is much more powerful. It supports richer data structures (like sorted sets, hashes, and lists) and Pub/Sub (Publish/Subscribe), which allows different parts of your application to broadcast events to each other in real-time.

Simple Example:

Think of a gaming leaderboard or a user's active shopping cart session.
Instead of querying a slow disk-based database every time a player scores a point, you use a Redis Sorted Set. Redis handles the math and sorting instantly in memory. If you want to notify other services that a score changed, you use Redis Pub/Sub to broadcast a message: "Player1 just scored!"

Layer 3: Database Caching (Amazon DAX)

Amazon DynamoDB is a NoSQL database that natively delivers single-digit millisecond latency. For 99% of applications, that is incredibly fast. However, for extreme scale, milliseconds aren't fast enough.

DAX (DynamoDB Accelerator) is a specialized, fully managed write-through cache designed exclusively for DynamoDB. It sits directly in front of your DynamoDB tables. While DynamoDB responds in milliseconds (1/1000th of a second), DAX responds in microseconds (1/1,000,000th of a second). Because it is a "write-through" cache, when you write data to DAX, it automatically saves it to DynamoDB for you, ensuring the cache is always up to date.

Compute Optimization: Lambda Execution Context Reuse

AWS Lambda is serverless. When a request comes in, AWS spins up a tiny container (an invocation), runs your code, and then pauses it.

If a Lambda container is spun up from scratch, it's called a Cold Start.
If a container is reused for a subsequent request, it's called a Warm Start.

If you initialize your database or Redis connection inside the main function handler, your code will open and close a new connection on every single request. This destroys performance. By declaring the Redis client outside the handler function (module scope), AWS keeps that connection alive in memory. When a "warm" invocation happens, the Lambda instantly reuses the existing connection.

Simple Example (Code Context):

Instead of doing this (Bad):

exports.handler = async (event) => {
    const redisClient = connectToRedis(); // Opens a connection EVERY time the function runs
    return await redisClient.get("key");
};

Do this (Good):

const redisClient = connectToRedis(); // Module Scope: Runs ONCE during cold start

exports.handler = async (event) => {
    // Reuses the established connection on all warm starts!
    return await redisClient.get("key");
};

Event-Driven Cache Invalidation

Caching has a legendary problem: How do you know when cached data is old (stale) and needs to be deleted? The engineer uses two strategies to solve this:

TTL-based (Time-to-Live): You set an expiration date on data. For example, "Keep this in Redis for 5 minutes, then delete it automatically."
Event-Driven Invalidation: This is where Event-Driven Design shines. Instead of waiting for a timer to run out, your system reacts to data changes (mutations) in real-time. When a user updates their data, an "event" is triggered. A Lambda function listens to this event and immediately deletes ("invalidates") the old cache key.

Simple Example:

Let's look at a profile update feature:

A user updates their profile bio from "Software Engineer" to "Principal Engineer."
The change is saved to the primary database (DynamoDB).
The Event: DynamoDB emits an event via a feature called DynamoDB Streams saying: "Hey, User 123 just changed their bio!"
The React: An isolated Lambda function wakes up automatically because of that event. It doesn't handle the user's web request; its only job is cache maintenance.
The Lambda runs a command to delete the old cache key for User 123 in Redis (redis.del("user:123")).
The next time anyone views User 123's profile, the application sees the cache is empty, fetches the brand-new data from the database, and repopulates the cache.

Summary

By combining these layers, we can build a system that is incredibly cost-efficient, lightning-fast, and decoupled

I hope you find it helpful
Hash

4- AWS Serverless: Event-Driven Design: SQS, SNS, and EventBridge

Hamid Shoja — Mon, 15 Jun 2026 20:02:00 +0000

When designing modern cloud architectures, Event-Driven Architecture (EDA) is the gold standard for creating decoupled, scalable, and resilient systems. However, choosing the right AWS service for passing messages around can be daunting.

Let’s break down exactly what this means, how each part works, and look at simple real-world examples for each.

Part 1: AWS SQS (Simple Queue Service)

"For resilient pull-based processing with FIFO for ordering guarantees"

What it means

Pull-Based Processing: Instead of pushing an event directly onto a consumer (which might overwhelm it), messages sit safely in a storage queue. The consumer "pulls" (polls) messages from the queue only when it has the capacity to process them.
Resilient: If your consumer service crashes or experiences a sudden traffic spike, the messages aren’t lost. They wait in the queue until the service recovers.
FIFO (First-In, First-Out): Standard queues process messages roughly in order, but sometimes duplicate or out-of-order messages happen. A FIFO queue guarantees strict ordering (Message A will always be processed before Message B if A arrived first) and exactly-once processing.

Simple Example: The Coffee Shop

Imagine a busy coffee shop. Customers place orders, and instead of shouting them directly at one overworked barista (push-based), the orders are printed on paper tickets and lined up on a rail (the queue).

The barista pulls the next ticket from the rail only when they finish the current drink (pull-based processing). If the barista steps away for a moment, the tickets don't vanish; they just wait on the rail (resilient).

Why FIFO matters here: If Customer A orders a Latte and Customer B orders an Espresso immediately after, the barista must make the Latte first to ensure fairness and prevent Customer A from waiting forever.

Part 2: AWS SNS (Simple Notification Service)

"For fan-out to multiple consumers simultaneously"

What it means

Fan-Out Pattern: This is a "push-based" publish/subscribe (Pub/Sub) pattern. A publisher sends a message once to an SNS "Topic," and SNS instantly clones and broadcast-pushes that message to multiple subscribers (consumers) simultaneously.
Decoupling: The service sending the message doesn't know (or care) who is listening. It just drops the message in the bucket, and SNS handles the distribution.

Simple Example: The New Author Announcement

Imagine an author finishes a new book. Instead of emailing every single fan individually, they post an update to a subscription newsletter service (the SNS Topic).

Instantly, that single update is broadcasted ("fanned out") to thousands of subscribers via different channels: some get an email, some get an SMS text, and another system automatically updates the bookstore website inventory.

In a software example: When a user buys a product on an e-commerce site, the OrderPlaced event is sent to SNS. SNS instantly "fans out" this event to three different systems at the exact same time:
The Shipping Service queue to pack the item.
The Invoicing Service queue to charge the card.
The Analytics Service to update marketing dashboards.

Part 3: AWS EventBridge

"For complex routing with pattern-based rules... my default for internal domain events"

What it means

Complex Routing & Pattern-Based Rules: EventBridge is a serverless event bus. Unlike SNS, which blasts messages to everyone subscribed, EventBridge inspects the contents of the event payload. You can write specific rules like: "Only forward this event if status is 'FAILED' and location is 'US'."
Internal Domain Events: A "domain event" is something meaningful that happened in your business logic (e.g., UserUpgradedToPremium). EventBridge is built to be the central nervous system connecting all your microservices.
Schema Registry & TypeScript Auto-Generation: As your team grows, keeping track of what an event looks like (its schema) becomes difficult. EventBridge’s Schema Registry automatically detects the structure of your events. It can then generate code bindings (like TypeScript types). This means developers get auto-complete in their code editors for events happening across the entire company!

Simple Example: The Airport Sorting System

Think of EventBridge like an automated airport baggage handling system. Every bag (event) has a tag indicating its destination, weight, and airline.

The main conveyor belt (the Event Bus) scans the tag of every bag and uses rules to route it:

If the destination is "London," send it to Gate 4.
If the bag is flagged as "Oversized," route it to the special handling team.
If it belongs to a third-party partner airline, route it to their terminal.

Furthermore, the airport maintains a central database of exactly what a valid baggage tag looks like (Schema Registry), so every airline's computer system knows precisely how to print a compatible tag without manual coordination.

When to use which?

Use SQS when your primary goal is load-smoothing and safety. You want to make sure your database or microservice doesn't break under high traffic, and you need to process items sequentially.
Use SNS when you want to broadcast a single event to multiple distinct systems instantly, and you want a simple "fire-and-forget" mechanism.
Use EventBridge when you are building an enterprise microservice mesh. It is the ideal choice when you need to route events based on what is inside them, integrate with SaaS apps (like Zendesk or Stripe), or want strict code-level governance over your event data structures.

hope you find it helpful
Hash

3- AWS Serverless: REST API vs. HTTP API

Hamid Shoja — Sun, 14 Jun 2026 18:42:00 +0000

There is common point of confusion. what's the different between REST API vs. HTTP API in AWS and what's the different between them and a traditional Rest API you write with e.g express in node

in the broader software world, a "REST API" is just an architectural pattern built on top of HTTP requests.

The confusion comes entirely from AWS-specific marketing terminology.

When you are inside the AWS ecosystem, Amazon API Gateway is a specific managed service, and AWS chose to split that service into two different flavors (or software products): one called "REST API" and one called "HTTP API."

Here is exactly how they work under the hood, how they differ internally, and how it compares to traditional servers.

1. How It Works: REST API vs. HTTP API (AWS Architecture)

Think of Amazon API Gateway as a reverse proxy or a "front door" that sits in front of your Lambda functions.

AWS REST API (The Heavyweight)

When a request hits an AWS REST API, AWS passes that request through a massive feature pipeline before it ever touches your Lambda code.

[Client Request] ──> [Authentication (Cognito/IAM)] ──> [Request Validation] ──> [Data Transformation (VTL)] ──> [Your Lambda]

What happens: AWS decrypts the request, validates the JSON schema, checks API keys, runs any custom request transformations using a complex mapping language called VTL, and then invokes your Lambda function.
Why it costs more: You are paying AWS for all that computing power happening inside the API Gateway layer itself.

AWS HTTP API (The Express Lane)

When a request hits an AWS HTTP API, AWS strips out almost the entire middle pipeline.

[Client Request] ──> [JWT/OAuth2 Authorization Only] ──> [Your Lambda]

What happens: The HTTP API acts as a lightning-fast router. It optionally checks a standard JWT token, converts the incoming HTTP request directly into a clean JSON object, and throws it straight into your Lambda function.
Why it costs less: Because AWS is doing almost zero processing or data manipulation. Your TypeScript Lambda function handles the validation and logic instead.

2. The Traditional Service Comparison (Express.js / NestJS)

In a traditional application (like a Node.js/Express app running on a virtual server or Docker container), you don't have this artificial split. You just write a "REST API."

Here is how the architecture looks side-by-side:

Traditional Server (Express.js on EC2/Docker)

In a traditional setup, one single server handles everything.

The server listens for an HTTP request.
Your Express middleware handles routing (app.get('/hello')).
Your Express middleware handles authorization and data validation.
Your controller executes the business logic.

AWS Serverless (HTTP API + Lambda)

In AWS Serverless, the responsibilities are decoupled into completely separate services:

AWS HTTP API handles the networking, SSL certificates, and basic routing (GET /hello).
AWS Lambda acts as the isolated execution container that runs your TypeScript code to handle the business logic.

Summary: Unmixing the Terms

In the Real World: A REST API is a conceptual design pattern. An HTTP request is the underlying protocol. A traditional Node.js backend handles both of these inside the application code.
In AWS Language: "REST API" and "HTTP API" are just two different pricing and feature tiers of the Amazon API Gateway service.

If you don't need AWS to do complex request manipulation before your code runs, you choose the HTTP API tier to save 70% on your infrastructure bill and let your TypeScript code do the heavy lifting!

I hope you find it useful
HASH

2- AWS Serverless: Testing (typescript)

Hamid Shoja — Fri, 12 Jun 2026 09:31:00 +0000

Shifting from traditional application testing to serverless TypeScript engineering is all about shifting your perspective: you stop testing a running server, and you start testing how your function responds to events and SDK states. Here is a simple, practical example for each testing, using modern AWS SDK v3 syntax.

1. Unit Testing: Jest + Mock Payloads & SDK Client Mocking

In unit tests, you don't call real AWS services. You pass a simulated API Gateway event to your handler, and you mock the AWS SDK so it returns predictable data instead of hitting live infrastructure.

The Code Under Test (`src/handler.ts`)

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';

const ddbClient = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(ddbClient);

export const handler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
  const userId = event.pathParameters?.id;

  if (!userId) {
    return { statusCode: 400, body: JSON.stringify({ message: 'Missing ID' }) };
  }

  // Fetch from DynamoDB
  const result = await docClient.send(new GetCommand({
    TableName: process.env.USERS_TABLE,
    Key: { id: userId }
  }));

  if (!result.Item) {
    return { statusCode: 404, body: JSON.stringify({ message: 'User not found' }) };
  }

  return {
    statusCode: 200,
    body: JSON.stringify(result.Item),
  };
};

The Jest Unit Test (`tests/unit.test.ts`)

Instead of the legacy aws-sdk-mock, the modern standard for AWS SDK v3 is aws-sdk-client-mock.

import { handler } from '../src/handler';
import { APIGatewayProxyEvent } from 'aws-lambda';
import { mockClient } from 'aws-sdk-client-mock';
import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';

const ddbMock = mockClient(DynamoDBDocumentClient);

describe('Lambda Handler Unit Test', () => {
  beforeEach(() => {
    ddbMock.reset();
    process.env.USERS_TABLE = 'TestTable';
  });

  it('should return 200 and user data when user exists', async () => {
    // 1. Mock the AWS SDK Behavior
    ddbMock.on(GetCommand).resolves({
      Item: { id: 'user-123', name: 'Alice' }
    });

    // 2. Shape the Mocked APIGatewayProxyEvent Payload
    const mockEvent = {
      pathParameters: { id: 'user-123' }
    } as unknown as APIGatewayProxyEvent;

    // 3. Execute handler directly
    const response = await handler(mockEvent);

    expect(response.statusCode).toBe(200);
    expect(JSON.parse(response.body)).toEqual({ id: 'user-123', name: 'Alice' });
  });
});

2. Integration Testing: LocalStack

Integration tests verify that your code accurately interacts with auxiliary services, without relying on real AWS. LocalStack spins up containerized versions of AWS services inside your CI/CD pipeline or local environment.

To test against LocalStack, your application code just needs to point its AWS Clients to the local Docker container URL (usually http://localhost:4566).

The Integration Test Configuration (`tests/integration.test.ts`)

import { DynamoDBClient, CreateTableCommand } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
import { handler } from '../src/handler';
import { APIGatewayProxyEvent } from 'aws-lambda';

// Point the client to LocalStack instead of real AWS
const localStackConfig = {
  endpoint: 'http://localhost:4566',
  region: 'us-east-1',
  credentials: { accessKeyId: 'test', secretAccessKey: 'test' }
};

const ddbClient = new DynamoDBClient(localStackConfig);
const docClient = DynamoDBDocumentClient.from(ddbClient);

describe('DynamoDB Integration via LocalStack', () => {
  beforeAll(async () => {
    // Setup: Create the table in LocalStack before tests run
    await ddbClient.send(new CreateTableCommand({
      TableName: 'LocalUsersTable',
      AttributeDefinitions: [{ AttributeName: 'id', AttributeType: 'S' }],
      KeySchema: [{ AttributeName: 'id', KeyType: 'HASH' }],
      BillingMode: 'PAY_PER_REQUEST'
    }));

    process.env.USERS_TABLE = 'LocalUsersTable';
  });

  it('should successfully read data actually written to LocalStack', async () => {
    // Seed real data into the LocalStack DynamoDB container
    await docClient.send(new PutCommand({
      TableName: 'LocalUsersTable',
      Item: { id: 'user-456', name: 'Bob' }
    }));

    const mockEvent = { pathParameters: { id: 'user-456' } } as unknown as APIGatewayProxyEvent;

    // Run the handler — it will communicate directly with LocalStack
    const response = await handler(mockEvent);

    expect(response.statusCode).toBe(200);
    expect(JSON.parse(response.body).name).toBe('Bob');
  });
});

3. End-to-End (E2E) Testing: Newman

In E2E testing, your application is fully deployed to a staging environment. You treat it entirely as a black box—sending actual HTTP requests to the live API Gateway URL. Newman allows you to run Postman collections natively via the CLI.

The Testing Workflow

You export a Postman collection containing your test assertions (my-api-tests.json).
You execute it via your terminal or CI environment against the live URL.

# Execute your Postman test collection against your deployed AWS Staging endpoint
newman run ./tests/my-api-tests.json --env-var "baseUrl=https://xyz123.execute-api.us-east-1.amazonaws.com/staging"

4. Local Execution: AWS SAM Local

Before deploying to staging, you want to see how your Lambda executes inside an isolated Docker container mimicking the real AWS Lambda runtime environment. AWS SAM achieves this.

Step A: Define your event payload (`events/mock-request.json`)

{
  "pathParameters": {
    "id": "user-789"
  }
}

Step B: Invoke the function via CLI

Run the SAM build command to compile your TypeScript down to JavaScript, then use sam local invoke to execute the function with your mock event.

# 1. Compile TypeScript and build resources
sam build

# 2. Locally invoke the function using the mock event
sam local invoke UserHandlerFunction --event events/mock-request.json

Hope youe find it helpful
Hash

1- AWS Serverless: Designing a serverless API: Order Processing API (E-commerce)

Hamid Shoja — Thu, 11 Jun 2026 15:40:00 +0000

Modern enterprise order processing architectures must decouple synchronous client demands from asynchronous backend dependencies. Here I'll detail a highly scalable, fault-tolerant design built on AWS. By utilizing an automated API Gateway entry point, specialized Amazon Cognito authentication, optimized AWS Lambda logic blocks, an engineered RDS Proxy connection layer, and an event-driven SQS/EventBridge core, the design guarantees isolation, cost efficiency, and sub-millisecond structural routing.

The Scenario

User places an order → payment is processed → inventory updated → confirmation email sent

Client → API Gateway (Cognito auth + validation)
       → Order Lambda (business logic + DynamoDB write)
       → SQS (payment queue)
       → Payment Lambda → EventBridge
                        → Inventory Lambda
                        → Notification Lambda (SES)

1- Entry Point — API Gateway

REST endpoint: POST /orders

Request validation via API Gateway models (reject malformed payloads instantly, no Lambda invoked)

Auth via Cognito User Pool Authorizer — validates JWT token on every request

How It Works

The Request Hits: A client sends a POST /orders request with a JWT token in the header.
Auth Check: API Gateway automatically intercepts the request and validates the JWT against the Cognito User Pool. If expired or spoofed, it returns 410 Gone / 401 Unauthorized right there.
Payload Check: Next, it compares the body against your JSON Schema Model. If a required field like customer_id is missing, API Gateway instantly drops it with a 400 Bad Request.
The Win: Your downstream services (like Lambda) are never invoked for bad/unauthorized requests, saving compute costs and protecting against basic DDoS or bad actor spam.

Gotchas

Cognito Latency: While Cognito authorizers are native, they can add a slight latency overhead to your API's P99 metrics during peak traffic. For massive global scale, some enterprises migrate to custom Lambda Authorizers that cache tokens in ElastiCache (Redis).
Model Validation Limits: API Gateway's built-in validator is great for structural checks (e.g., "is this an integer?"), but it cannot do business logic validation (e.g., "is this item SKU actually in our database?"). You still need lightweight validation downstream.
Throttling: Always configure Usage Plans and Rate Limiting at this layer. Without it, a rogue client could overwhelm your backend before your auto-scaling kicks in.

2. Business Logic — Lambda (TypeScript)

Bundled with esbuild — tiny bundle, fast cold start

Uses aws-lambda-powertools for structured logging + correlation IDs + tracing

How It Works

Bundling (esbuild): Strips unused node modules, removes comments, tree-shakes dead code, and transpiles TypeScript down to a single, lightweight JavaScript file. Less code means the internal Lambda service downloads and instantiates your code container incredibly quickly.

The Execution Lifecycle: * Initialization (Cold Start): Lambda boots the container and runs code outside the handler function. By not putting heavy SDK packages here, initialization remains ultra-fast.

Invocation (Warm Start): The handler executes. Because DynamoDBClient was stored in a global variable during the first run, subsequent warm invocations bypass the heavy initialization and dynamic import() statement entirely.

Powertools Observability: Rather than using console.log, Powertools outputs structured JSON logs. If a customer has an issue, you can trace that specific correlationId seamlessly across your logs, metrics, and X-Ray traces.

Gotchas

The Memory vs. CPU Trap: Developers often assign Lambda the minimum memory (128MB) to "save money". The catch: AWS scales CPU and network performance proportionally with memory. Upgrading to 1024MB or 1536MB often speeds up cold starts and execution times so drastically that the execution costs remain identical or cheaper while delivering a superior P99 response time.
VPC Cold Starts: If your business logic needs to query an RDS database inside a private VPC, Lambda must attach an Elastic Network Interface (ENI). While AWS optimized this significantly using Hyperplane, it can still add a predictable overhead to cold starts compared to a Lambda running outside a VPC.
Global State Pollution: Global variables (like DynamoDBClient above) persist across warm starts. If you modify a global variable inside a handler (e.g., global error arrays or temporary user arrays), it will bleed into the next customer's request. Always reset request-specific states inside the handler.

Conceptual Application Code (TypeScript)

// 1. GLOBAL SCOPE: Warm start re-use (No heavy SDKs imported here)
import { Logger } from '@aws-lambda-powertools/logger';
import { Tracer } from '@aws-lambda-powertools/tracer';

const logger = new Logger();
const tracer = new Tracer();

// 2. LAZY LOADING: Dynamically imported only when needed inside handler
let DynamoDBClient: any = null; 

export const handler = async (event: any, context: any) => {
  // Clear state/set correlation context
  logger.addContext(context);
  const correlationId = event.headers['X-Correlation-Id'] || context.awsRequestId;
  logger.appendKeys({ correlationId });

  try {
    const body = JSON.parse(event.body);

    // Business Logic Validation (Stock/Price Check)
    const isStockAvailable = await checkStock(body.items);
    if (!isStockAvailable) {
      return { statusCode: 422, body: JSON.stringify({ message: "Out of stock" }) };
    }

    // Lazy load the heavy SDK right before database write
    if (!DynamoDBClient) {
      const { DynamoDBClient: DB } = await import('@aws-sdk/client-dynamodb');
      DynamoDBClient = new DB({});
    }

    // Proceed with processing...
    return { statusCode: 201, body: JSON.stringify({ orderId: "12345" }) };

  } catch (error) {
    logger.error("Order processing failed", error as Error);
    return { statusCode: 500, body: JSON.stringify({ message: "Internal Error" }) };
  }
};

3. Database — RDS

table design — orders, users, inventory

RDS proxy

How It Works

The Serverless Connection Problem: Relational databases assign memory to every single open connection. If your API gets a spike in traffic and Lambda scales up to 2,000 concurrent containers, they will try to open 2,000 direct database connections, instantly crashing RDS with an "out of memory" error.
Enter RDS Proxy: Lambda functions point to the RDS Proxy endpoint instead of the database. The proxy keeps a continuous, optimized pool of connections open to RDS.
Multiplexing: When a Lambda function finishes executing an order (takes 50ms), RDS Proxy immediately claims that connection back and hands it to a different Lambda instance. Your DB only ever sees a stable, flatlined connection count.

Gotchas

Session Pinning: RDS Proxy's primary job is to multiplex connections. However, if your Lambda executes certain commands—like preparing a dynamic SQL statement, changing session variables, or utilizing temporary tables—RDS Proxy gets confused and performs

-Session Pinning. This ties that specific Lambda instance to that specific database connection until the Lambda dies, completely destroying the benefits of the proxy pool. Keep queries standard and stateless.

The IAM Secret Storage Lag: RDS Proxy reads the DB password directly from AWS Secrets Manager. If you rotate your database password in an emergency, there can be a tiny window (seconds) of cached credential lag where the proxy might drop connection handshakes.
DynamoDB vs. RDS: If you genuinely want a Partition Key (userId) and Sort Key (orderId), you should drop RDS and switch to Amazon DynamoDB. In an enterprise context, DynamoDB handles high-scale transactional orders infinitely better without needing an RDS Proxy, VPC configurations, or connection pools, though you sacrifice the ability to run complex SQL JOIN statements across your tables.

High-Level Relational Database Design (DDL)

-- 1. Users Table
CREATE TABLE users (
    user_id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 2. Orders Table (Composite Index handles the lookups)
CREATE TABLE orders (
    order_id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(user_id) NOT NULL,
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(50) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Accelerates "Get all orders for a specific User ordered by date"
CREATE INDEX idx_user_orders ON orders(user_id, created_at DESC);

-- 3. Inventory Table
CREATE TABLE inventory (
    item_id UUID PRIMARY KEY,
    sku VARCHAR(100) UNIQUE NOT NULL,
    stock_quantity INT NOT NULL CHECK (stock_quantity >= 0),
    price DECIMAL(10, 2) NOT NULL
);

4. Async Flow — SQS + EventBridge

After order saved → Lambda drops message to SQS (payment queue)
Payment Lambda picks it up, processes payment
On success → publishes event to EventBridge
EventBridge fans out to:Inventory Lambda (update stock)
Notification Lambda (send email via SES)

How It Works

The Hand-off: Once the Business Logic Lambda from Part 2 saves the order as PENDING, it drops a lightweight message (e.g., { "orderId": "abc-123", "amount": 99.00 }) directly into SQS. The API Gateway can instantly return a 202 Accepted response to the client. The user isn't left waiting on a spinner while the payment processes.
The Consumer: The Payment Lambda continuously polls SQS. It talks to your third-party payment gateway (like Stripe).
The Broadcast: On successful payment, the Payment Lambda fires a single structured JSON event into EventBridge. It doesn't know—or care—who needs this information.
The Fan-Out: EventBridge evaluates the incoming event pattern. Because it matches a Payment.Success type, it acts as a traffic cop and duplicates the event, executing both the Inventory Lambda and the Notification Lambda concurrently.

Gotchas

The Visibility Timeout Trap: Your SQS visibility_timeout_seconds configuration is hyper-critical. When a Lambda instance reads a message, that message is hidden from other instances for X seconds. If your Payment Lambda hits an API lag with Stripe and takes 31 seconds to complete, but your visibility timeout is set to 30 seconds, SQS will make that message visible again. A second Lambda will pick it up and process the payment a second time. Rule of thumb: Visibility timeout must always be > 6 times your Lambda function timeout.
Idempotency is Non-Negotiable: Because SQS guarantees at-least-once delivery (network hiccups can cause duplicate messages), your consumers must be idempotent. The Payment Lambda must verify with your DB or payment processor if orderId: abc-123 has already been charged before processing it.
EventBridge Latency vs. Throughput: EventBridge is built for massive, complex filtering and cross-microservice routing, but it has a slightly higher delivery latency (typically 20–50ms) compared to Amazon SNS (Simple Notification Service). If you require near-instant sub-millisecond fan-out and don't need advanced JSON schema filtering, an SNS Topic might be a faster alternative, though it lacks EventBridge's robust schema registry capabilities.

Conclusion

Building a enterprise-scale order processing engine on AWS requires balancing system decoupled isolation with a smooth user experience.

I hope you liked the article and you found it helpful.

Have questions about this high-level design, or want to discuss alternatives like DynamoDB single-table design? Let me know in the comments below!

Reclaim Your Mac Disk Space

Hamid Shoja — Fri, 22 May 2026 11:01:52 +0000

Your Mac is nearly full. That 98% capacity warning is real, and it will start causing build failures, crashes, and slowdowns if you ignore it.

This guide walks through what's eating your disk and exactly how to clean it — fast.

Step 1: Diagnose First

Always start with a full picture before deleting anything.

df -h

Look at the Avail column on /dev/diskXXX. If you see less than 1GB, you're in trouble.

Note: I also added a skill which you're LLM gives a Full macOS disk audit, it scans all major dirs including hidden dot dirs, outputs prioritized cleanup table with exact commands.

Then find the biggest offenders in your home folder:

du -sh ~/Library/Caches/* 2>/dev/null | sort -rh | head -20
du -sh ~/Library/Application\ Support/* 2>/dev/null | sort -rh | head -20

Step 2: Clear the Caches (Safe, ~N GB+)

~/Library/Caches is safe to delete. Every app rebuilds its cache on next launch but you can pick some specific ones too

Step 3: Tame Application Support

This is where the real weight lives. Unlike Caches, be selective here — some folders contain important app data.

du -sh ~/Library/Application\ Support/* 2>/dev/null | sort -rh | head -25

For may Docker Desktop or Rancher Desktop stores its entire Linux VM + all container images.

If you no longer use Docker just remove it entirly

Step 4: Clean Docker Images

Old branch images from months ago are dead weight. Check what you have:

docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}"

See how much a full prune would recover:

docker system df

Remove everything not currently running:

docker system prune -a

Or, conservative — only dangling (<none>) images:

docker image prune

Step 5: Verify You Recovered Space

df -h

Check the Avail column again. You should be back to several GBs of free space.

The Developer's Mindset on Disk Hygiene

Disk bloat is gradual. You don't notice until you're at 100% and your docker build silently fails.

A few habits prevent this:

Run docker system prune after finishing a feature branch
Clear ~/Library/Caches monthly — it's always safe
Keep an eye on ~/Library/Application Support/rancher-desktop if you use container runtimes
Old branch images in Docker are never coming back — prune them freely

I hope you found it helpful

A tip from a senior engineer

Hamid Shoja — Mon, 19 Jan 2026 18:12:06 +0000

The Trade-off: Clean Testing vs. Code Brevity in Modern JS

Hamid Shoja ・ Jan 19

#javascript #frontend #node #backend

Uvicorn in Modern Python APIs

Hamid Shoja — Mon, 19 Jan 2026 18:10:24 +0000

A quick guide to why Uvicorn is essential for Python developers in 2026, how to use it, and how it stacks up against other languages.

What is Uvicorn?

Uvicorn is a high-speed ASGI (Asynchronous Server Gateway Interface) server. While frameworks like FastAPI or Starlette help you write your code, Uvicorn is the "engine" that actually runs the code and handles web requests from users.

Why do we use it?

In the past, Python servers (WSGI) could only handle one request at a time per process. Uvicorn uses an asynchronous event loop, allowing it to handle thousands of concurrent connections (like WebSockets or long-polling) without waiting for one to finish before starting the next.

Quick Start Example

Install:

pip install uvicorn

Code (main.py):

async def app(scope, receive, send):
    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [[b'content-type', b'text/plain']],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello, Dev.to!',
    })

Run:

uvicorn main:app --reload

Alternatives to Consider

Hypercorn: Great if you need HTTP/3 support.
Daphne: The go-to for Django Channels.
Granian: A Rust-based runner for those who need even more speed.

Architecture Comparison (Python vs. The World)

How does Uvicorn's "Event Loop" compare to other languages in 2026?

Perfomance

Unicorn: ~150k requests/sec; excellent for I/O but limited by the Global Interpreter Lock (GIL).

Nodejs: ~600k requests/sec; highly optimized for I/O-bound web traffic.
Go (Goroutines): >1M requests/sec; built-in concurrency makes it a "workhorse" for microservices.
Rust (Tokio/Axum): >1M requests/sec; the fastest model due to lack of garbage collection and zero-cost abstractions.

Cpu-intensive tasks

In a single-threaded async loop, one heavy CPU calculation can freeze the entire server. We should offload blocking tasks to a thread pool or a separate worker (like Celery/Arq) to keep the Uvicorn loop responsive.

Example: Use run_in_executor for blocking code.

import asyncio

@app.get("/heavy-task")
async def heavy_task():
    # Don't run blocking code directly; offload it to keep the loop free
    loop = asyncio.get_running_loop()
    result = await loop.run_in_executor(None, some_blocking_heavy_math)
    return result

Summary

If you are building a modern Python web app, Uvicorn is the standard choice. It balances the ease of Python with the speed required for modern, real-time web applications.

Follow for more bite-sized dev tutorials! 🚀
HASH

refs:
https://medium.com/@yogeshkrishnanseeniraj/scaling-django-async-workers-uvicorn-gunicorn-celery-and-redis-full-benchmarking-guide-fef057069e96#:~:text=Uvicorn%20alone%20provides%20excellent%20async,with%20low%20to%20moderate%20traffic.
https://stackoverflow.com/questions/21485920/single-threaded-event-loop-vs-multi-threaded-non-blocking-worker-in-node-js#:~:text=As%20a%20minor%20addendum%20I,57.8k10%2093%20131
https://www.youtube.com/watch?v=n0KETvEqiCk&t=57

DEV Community: Hamid Shoja

Coding agents: A silent hook babysits, a loud hook teaches

Two flavors of hook

The Postgres migration hook

The fix, precisely

The error message is a teaching surface

A repeated rejection is a bug report against your docs

Loud or silent - the checklist

Coding agents: Your skill bodies are fine, your descriptions are broken

The invisible bottleneck

Failure 1: the description that replaces the skill

Failure 2: skills that shadow each other

Test descriptions like you test docs

The rule of thumb

How to structure CLAUDE.md, Skills and Agents

The problem

The rule of thumb

The one rule that stops the rot

Verify your docs like you verify code

What it achieved

Why Sequential Reads Beat Random Reads in Postgres at Scale

How Postgres Stores Data

The Index Makes It Worse at Scale

The Sequential Scan Fix

Sequential vs Random - Side by Side

The Trade-off

Result

5- AWS Serverless:: Caching and Event-Driven Design

Layer 1: Edge Caching (AWS CloudFront)

Simple Example:

Layer 2: Application Layer Caching (Amazon ElastiCache Redis)

Simple Example:

Layer 3: Database Caching (Amazon DAX)

Compute Optimization: Lambda Execution Context Reuse

Simple Example (Code Context):

Event-Driven Cache Invalidation

Simple Example:

Summary

4- AWS Serverless: Event-Driven Design: SQS, SNS, and EventBridge

Part 1: AWS SQS (Simple Queue Service)

"For resilient pull-based processing with FIFO for ordering guarantees"

What it means

Simple Example: The Coffee Shop

Part 2: AWS SNS (Simple Notification Service)

"For fan-out to multiple consumers simultaneously"

What it means

Simple Example: The New Author Announcement

Part 3: AWS EventBridge

"For complex routing with pattern-based rules... my default for internal domain events"

What it means

Simple Example: The Airport Sorting System

When to use which?

3- AWS Serverless: REST API vs. HTTP API

1. How It Works: REST API vs. HTTP API (AWS Architecture)

AWS REST API (The Heavyweight)

AWS HTTP API (The Express Lane)

2. The Traditional Service Comparison (Express.js / NestJS)

Traditional Server (Express.js on EC2/Docker)

AWS Serverless (HTTP API + Lambda)

Summary: Unmixing the Terms

2- AWS Serverless: Testing (typescript)

1. Unit Testing: Jest + Mock Payloads & SDK Client Mocking

The Code Under Test (src/handler.ts)

The Jest Unit Test (tests/unit.test.ts)

2. Integration Testing: LocalStack

The Integration Test Configuration (tests/integration.test.ts)

3. End-to-End (E2E) Testing: Newman

The Testing Workflow

4. Local Execution: AWS SAM Local

Step A: Define your event payload (events/mock-request.json)

Step B: Invoke the function via CLI

1- AWS Serverless: Designing a serverless API: Order Processing API (E-commerce)

The Scenario

1- Entry Point — API Gateway

How It Works

Gotchas

2. Business Logic — Lambda (TypeScript)

How It Works

Gotchas

Conceptual Application Code (TypeScript)

The Code Under Test (`src/handler.ts`)

The Jest Unit Test (`tests/unit.test.ts`)

The Integration Test Configuration (`tests/integration.test.ts`)

Step A: Define your event payload (`events/mock-request.json`)