DEV Community: amananandrai

Avengers: Doomsday is 5 weeks away, so I built hexagon README badges. What are you building?

amananandrai — Sat, 14 Nov 2026 17:14:52 +0000

Avengers: Doomsday hits theaters on December 18, 2026. That's about five weeks from now, and I figured the best use of the wait was to build something Marvel-flavored instead of just rewatching trailers.

So I made hex-badges: hexagon README badges with 10 Avengers-inspired color themes, a glow effect, and live GitHub stats. Yes, one of the themes is a green-and-silver Latveria badge. Doom deserves a README badge.

Before the technical stuff, I have a question for the Marvel fans on DEV: what are you building (or have you built) with the Doomsday hype? A themed portfolio, a countdown widget, a Discord bot, a game, a dumb little CLI? Drop it in the comments. I would love to see them. More on that at the end.

Live demo and badge builder: https://hex-badges.vercel.app
Source: https://github.com/amananandrai/hex-badges

What you get

Two badge styles, 10 themes, and every badge is a plain SVG served from a URL:

![stars](https://hex-badges.vercel.app/github/stars/facebook/react?theme=stark-forge)
![license](https://hex-badges.vercel.app/github/license/facebook/react?theme=asgard&style=wide)

Single hexagon: label over value, with a glow and a themed pattern.
Elongated: a two-part badge with a pointed hexagon outline, closer to a classic badge.

GitHub metrics: stars, forks, watchers, open issues, open PRs, latest release, latest tag, last commit, license, contributors, language and repo size. There is also a custom endpoint, /api/badge?label=build&message=passing, for anything else.

How it works

The whole thing is three small pieces, and none of them needs a dependency.

1. An SVG renderer. A badge is just a string. For the single hexagon, the six corner points come from a bit of trigonometry:

const ring = (rad) => [0, 1, 2, 3, 4, 5].map((k) => {
  const a = ((-90 + 60 * k) * Math.PI) / 180;
  return `${cx + rad * Math.cos(a)},${cy + rad * Math.sin(a)}`;
}).join(' ');
// <polygon points="${ring(r)}" .../>

The tricky part of any badge generator is text width. Real services measure font metrics. I estimate it from character count, which is good enough for a short label:

const textWidth = (s, size) => Math.ceil(String(s).length * size * 0.62);

For long values the hexagon is capped at a maximum size and the font shrinks to fit.

2. Serverless functions on Vercel. Each endpoint reads query params and returns SVG with caching headers:

res.setHeader('Content-Type', 'image/svg+xml; charset=utf-8');
res.setHeader('Cache-Control', 'public, max-age=300, s-maxage=300');
res.status(200).send(svg);

A vercel.json rewrite turns /github/stars/owner/repo into a function call, so the URLs stay short.

3. GitHub data. Each metric is a small function that calls the GitHub REST API and returns a message. Counts are shortened (12,437 becomes 12.4k), and errors become badges too, such as "not found" or "rate limited", instead of a broken image.

Making the themes feel right

Each theme is a handful of values: two gradient pairs, text colors, an outline color and a glow color. Gradients give the badges a metallic look, so "silver" and "gold" actually read as metal.

The glow is the fun part. SVG has no simple glow property, so it is a filter that floods the shape's outline with a color, blurs it, and merges it under the original:

<filter id="glow" x="-40%" y="-40%" width="180%" height="180%">
  <feFlood flood-color="#37ff86" result="f"/>
  <feComposite in="f" in2="SourceAlpha" operator="in" result="c"/>
  <feGaussianBlur in="c" stdDeviation="4" result="b"/>
  <feMerge>
    <feMergeNode in="b"/><feMergeNode in="b"/>
    <feMergeNode in="SourceGraphic"/>
  </feMerge>
</filter>

On top of that, each single hexagon gets a pattern clipped to its shape with a clipPath: arc-reactor rings, armor plates and rivets, lightning, a woven lattice, stars and stripes, cracks, a targeting reticle, a spider web, a sling-ring mandala, and cosmic dust with six colored stones. I kept patterns away from the text area so values stay readable.

One deliberate choice: I used generic motifs and my own theme names, not logos or official symbols. These badges are inspired by the colors, and they are not affiliated with Marvel or Disney.

Lessons learned

Escape everything. Labels come from the URL and go into an SVG, so any user-supplied text is escaped before it is inserted. Otherwise a crafted URL can inject markup.
Validate the repo param. My first regex accepted ../evil as an owner/repo, which would have sent a path-traversal-style request to the GitHub API. A test caught it. Now . and .. segments are rejected.
Cache hard. Badges get requested constantly. CDN cache headers keep latency low and API usage small.
Plan for rate limits. GitHub allows only 60 unauthenticated requests per hour per IP, and serverless platforms share IPs. A read-only token with no scopes raises that to 5,000 per hour. Issue and PR counts use the search API, which has its own tighter limit, so caching matters even more there.
Glow needs a dark background. On GitHub's dark theme the glow looks great. On white it fades to a soft halo, which still looks fine but is more subtle.

Deploy your own

Fork the repo and import it into Vercel. There is no build step.
Create a fine-grained GitHub token with public repositories, read-only access and no permissions.
Add it in Vercel as the GITHUB_TOKEN environment variable and redeploy.

That's it. The landing page at / has a builder where you pick a theme and copy the Markdown.

What's next

More metrics (npm versions and downloads are next on my list), more themes, and a light-background glow variant. Theme requests are open, and that's where I need you.

Your turn: let's make this a Doomsday watercooler

Pick any of these and answer in the comments. One line is plenty.

Show me your Marvel (or Doomsday) project. Link the repo, the site, or just describe it, however rough or silly. Hype projects count.
Which theme is your favorite? Stark Forge, Latveria, Asgard, Wakanda, Star Shield, Gamma Smash, Red Room, Web Slinger, Mystic Arts or Infinity.
Which theme should I add next? X-Men, Fantastic Four, Loki, Scarlet Witch, something from the DC side? Give me a color combo and a pattern idea and I'll try to build it.
Are you Team Avengers or Team Doom? Defend your answer. Bonus points if you argue it using only README badges.
Post your README. Add a badge to one of your repos and share a screenshot. I'll reply to as many as I can.

And if you are not a Marvel person, tell me about the side project you are most excited about right now. This is a watercooler post, so all fun projects are welcome.

Disclaimer: this is a fan project and is not affiliated with or endorsed by Marvel or Disney. Theme names are my own, and the patterns are generic motifs, not official logos.

How Open-Source LLMs Differ: Comparing 130+ Model Architectures

amananandrai — Fri, 13 Nov 2026 10:38:47 +0000

A few weeks ago I wrote about LLM Explained, a free, open-source course of 43 interactive pages that takes you from tokens to AI agents. Each page has a scroll-driven animation, an Intuition / Mechanics / Maths depth switch, runnable Python and a short quiz.

The most common question I got afterwards was some version of:

"OK, I understand attention. But what is actually different between Llama, DeepSeek, Qwen and Gemma?"

So I built the answer into the site: an Architecture Atlas.

👉 Live: https://llm-explained-lovat.vercel.app/#arch
⭐ Repo: https://github.com/amananandrai/llm-explained

The one idea behind the atlas

Every large language model you can download today is the same machine: a stack of identical blocks, each with an attention layer and a feed-forward layer, joined by a residual stream.

The models differ in a short list of part choices:

Which normalisation (LayerNorm, RMSNorm, pre- or post-norm)?
How is position encoded (sinusoids, learned, RoPE, none)?
How many key/value heads (MHA, GQA, MLA)?
Is attention full, windowed, sparse or linear?
Is the MLP dense, gated (SwiGLU / GeGLU) or a mixture of experts?

Once you see the machine, every new model release becomes a diff instead of a mystery. The atlas is built around that idea, in four sections.

1. The transformer, drawn in three eras

The first widget redraws the classic transformer three times, so you can watch the design evolve:

2017: the original encoder–decoder from Attention Is All You Need. Two towers, post-norm, sinusoidal positions, and cross-attention as the bridge between them.

2019: the GPT-style decoder. The encoder and cross-attention disappear. The prompt and the answer become one sequence, and the norm moves before each sub-layer.

2023 onwards: the modern open-model block. It's the same skeleton with four part swaps: RMSNorm, rotary positions inside attention, grouped-query attention with a KV cache, and a SwiGLU MLP (or a mixture of experts).

You can click any block to see what it does, its tensor shapes in the Mechanics view, and links to the modules that teach it. The diagram is a doorway into the course, not a dead end.

2. Open-weight models, generated from their configs

The second widget is my favourite. Pick a family (Llama, Mistral, Qwen, DeepSeek, Kimi, Gemma, Phi, gpt-oss) and the whole diagram is generated from that model's configuration. The block labels, the expert grid, the KV-cache inset, the layer strip and every number are computed, not drawn by hand.

Here's DeepSeek-V3. You can see multi-head latent attention caching one 576-number latent per token instead of 128 heads of K and V (57× smaller), and 256 routed experts with 8 active per token plus one shared expert:

Switch to Gemma 3 and the picture changes: interleaved local/global attention, norms before and after each sub-layer, tied embeddings and image input:

Can you trust the numbers? Each model is marked either as checked against the vendor's config or model card, or as confirmed by reproducing the published parameter count. All 14 configs reproduce their published size to within 0.3% (except Kimi K2, which is published as a rounded "1T"). Adding a new model takes one config entry, and the diagram, spec card, diff and matrix all pick it up.

Under every diagram, a row of concept chips (RoPE · M5, MLA · M10, KV cache · M11, MoE · M12…) links each idea inside the model to the module that teaches it.

3. The comparison: concept by model

Diagrams are great for one model at a time. For comparisons you want a table, so the third section is a concept-by-model matrix:

Read down a column for one model's recipe, or across a row to see how far an idea has spread. A few things jump out straight away:

Observation	What the matrix shows
Everyone agrees on the basics	Decoder-only, pre-norm RMSNorm, RoPE and a gated MLP appear in every column
GQA is the default for KV heads	32:8 for Llama/Mistral/Qwen, 64:4 for Qwen3-235B, 40:10 for Phi-4
MLA is the alternative	DeepSeek-V3 and Kimi K2 use a 512-dim latent instead
MoE is how models scale cheaply	Mixtral 2/8, Qwen3 8/128, DeepSeek 8/256, Kimi K2 8/384, gpt-oss 4/32
KV cache size varies 8×	From 48 KB/token (gpt-oss-20b) to 384 KB/token (Gemma 3 12B)

The sizes table underneath (total params, active per token, layers × width, KV cache per token) is computed from the same configs. It shows why "671B parameters" (DeepSeek-V3) can still mean only ~37B active per token.

4. The gallery: 120 more architectures

Fourteen hand-checked models are not enough to keep up with how fast new models are released. So the atlas ends with a searchable gallery of 120 open-weight architectures, from GPT-2 to this month's releases:

Each card has a layer strip: one cell per layer, coloured by what that layer is (full attention, sliding-window, latent/sparse, linear attention, state-space/convolution…). You can tell a hybrid model from a pure-attention one at a glance, without reading a paper.

You can:

🔎 Search by model, company or attention type
🧩 Filter by Dense / MoE / Hybrid or by sequence mixer
↕️ Sort newest or oldest first
📂 Open a card for a block schematic, the full layer-by-layer strip, a facts table (size, context, vocab, KV cache, licence) and "ideas used" chips that link back to the course

Some numbers from the snapshot: 57 sparse MoE, 29 dense and 29 hybrid models (plus a few omnimodal, encoder–decoder and recurrent ones). RoPE appears in 104 of them, GQA in 73 and MLA in 30. Sliding-window attention, gated attention and Gated DeltaNet are the ideas spreading fastest.

Credit where it's due: the gallery data comes from the public snapshot of Sebastian Raschka's excellent LLM Architecture Gallery (repo, Apache 2.0). A script (scripts/build_gallery.py) turns it into a small data file. Only descriptive fields are kept (no images or benchmark scores), and the strips and schematics are drawn by the site.

How it's built

No frameworks and no build step, just like the rest of the course:

assets/arch.js      model configs (MODELS), parameter + KV-cache counters,
                    SVG stack renderer, transformerDiagram / modelDiagram /
                    conceptMatrix, and the atlas page
assets/gallery.js   generated by scripts/build_gallery.py, lazy-loaded
                    only when you open the atlas

One source of truth per model. A config object (layers, d_model, heads, KV heads, experts, window pattern, vocab…) drives the diagram, the counters, the matrix row and the spec card.
Counters as validation. Parameter and KV-cache counts are computed from the config and compared with the published number. If they don't match, the config is wrong.
Lazy loading. The 86 KB gallery file only downloads when you open the atlas.
The same widgets are reused inside Module 6 (encoder vs decoder) and Module 16 (spec cards, parameter counter, architecture diff).

Why this helps you actually understand LLMs

I've read a lot of architecture explainers. The ones that stuck had three things in common, and I tried to build all three in:

One mental model, many instances. Seeing Llama, DeepSeek and Gemma drawn on the same skeleton turns ten "new" architectures into a handful of choices. You stop memorising models and start recognising patterns.
Every part links to its explanation. If you don't know what MLA is, it's one click away, in a module with an animation, a widget and runnable Python:

Numbers you can trace. "57× smaller KV cache" or "3.5% of MLP weights active per token" aren't marketing claims here. They're computed from the config in front of you, so you can check them yourself.

It also works as a quick reference. When a new model drops, open the gallery, look at its layer strip, and you'll know within ten seconds whether it's a standard GQA + MoE stack or something new.

And if you're starting from zero, the curriculum takes you there in order:

⭐ If this helped, please star the repo

LLM Explained is free, open source and has no sign-up. Stars are how other learners find it, so if the atlas helped you understand even one architecture, a star would mean a lot:

👉 github.com/amananandrai/llm-explained ⭐

💬 I'd love your suggestions

I'm planning the next round of updates and would like to hear from you in the comments:

Which model should get a full config-generated diagram next? (Currently Llama, Mistral, Mixtral, Qwen3, DeepSeek-V3, Kimi K2, Gemma 3, Phi-4 and gpt-oss.)
Which architecture idea is still confusing after reading the atlas? MLA, sliding windows, linear attention, hybrids?
What would make the comparison more useful? A side-by-side diff of any two models? Memory estimates for your GPU?
Found a wrong number? Please open an issue. Every config is meant to be checkable.

Pull requests are welcome too: adding a model is a single config entry.

Thanks for reading, and happy learning! 🚀

Explore the atlas → https://llm-explained-lovat.vercel.app/#arch

I turned my GitHub profile into a Doctor Doom vs Avengers fight

amananandrai — Thu, 12 Nov 2026 19:12:11 +0000

My GitHub profile used to look like every other profile on the internet. My name in giant bold letters, a one-line bio, a row of generic shields, and an emoji slapped onto every section header like a kindergarten gold star. Functional. Polite. Completely invisible.

Now it opens with a lethal green energy beam and five GitHub cats in full Marvel cosplay.

You can see the crime scene live at github.com/amananandrai. Since #watercooler is for the fun stuff we do instead of actual work, here is the story of how a "quick five-minute profile update" turned into two pull requests merged in the same evening: the hero GIF and the rest of the theme.

The still (or: Marvel's lawyers, please don't read this)

I didn’t want a clean, minimalist developer logo. I wanted a movie poster.

On the left: Doctor Doom in a green hood, firing a massive beam of cosmic energy. On the right: Captain America, Iron Man, Black Panther, and Thor ready to throw down. The twist? Every single one of them is an Octocat. Cap has his shield, Iron Man has a palm repulsor, Black Panther is crouched in the rubble, and Thor is summoning lightning. The GitHub mark sits right inside the moon behind them, because if anthropomorphic feline superheroes are going to have a turf war, the moon should at least be in on the joke.

That single image dictated everything else. The GIF is the poster moving. The banner steals its color palette. The section dividers are just Doom's energy beam stretched thin enough to act as polite interior decorating.

I did set one ground rule: this stays strictly on my personal profile. The Octocat belongs to GitHub, the costumes belong to Disney's legal team, and I would prefer to keep my organs. It lives on a README with my name on it—not on a SaaS landing page, not on a sticker sheet, and definitely not on a client repo.

A GIF, because a static image lacks drama

GitHub READMEs are allergic to JavaScript. Everything is rendered through a strict sanitizer, which means your big, flashy centerpiece has to be an <img> tag that the browser already knows how to loop without throwing a security tantrum.

Pull request 13 drops assets/hero.gif right under the banner. The beam pulses, the lightning flickers, embers drift, and the camera pushes in slowly. It weighs in at 3.7 MB and renders at 720 pixels wide.

<img
  src="assets/hero.gif"
  alt="GitHub cats as Doctor Doom, Captain America, Iron Man, Black Panther and Thor in a battle"
  width="720"
/>

3.7 MB sits comfortably under the wall people usually slam into with README animations—though I would still happily chop a few frames before letting this file get any heavier. Nobody wants to wait on a loading spinner just to read my bio.

SVG, because if the cats move, the dividers have to move too

Making a GIF for every single horizontal divider would have been a crime against bandwidth. Instead, I built the header typography, the section rules, and the footer as SVGs, sneaking the animation inside the files using SMIL.

GitHub strips <style> tags out of Markdown like contraband, and an <img> tag can't load a Google Font or run a script. You have to play inside a very tight sandbox: no JS, no external stylesheets, and no web fonts. I decided to ignore light-mode users entirely and designed strictly for the dark side. The page background is still GitHub's; the theme lives inside the images.

The banner (assets/banner.svg) sets my name in Orbitron and the tagline in JetBrains Mono. To stop GitHub from falling back to Arial and ruining the whole aesthetic, I base64-encoded both fonts and stuffed them directly into the SVG as woff2 data URIs. That is why a text banner weighs 49 KB. Around the text, there’s a scanline, a green and purple wash, a pulsing beam, a lightning bolt, and rising embers.

The beam itself is just a tiny rectangle doing cardio:

<rect x="0" y="-3" width="700" height="6" rx="3" fill="url(#bm)" filter="url(#glow)">
  <animate attributeName="height" values="5;9;5" dur="1.2s" repeatCount="indefinite"/>
  <animate attributeName="y" values="-2.5;-4.5;-2.5" dur="1.2s" repeatCount="indefinite"/>
</rect>

For the horizontal rules, I built assets/pulse.svg—a featherweight 1.1 KB file that transitions from Doom green to Cap blue to Iron Man red, complete with a little white spark that sprints across the screen every three seconds.

The footer wraps things up in the same night gradient with a polite sign-off: THANKS FOR VISITING / LET'S BUILD SOMETHING.

Honestly, I half-expected GitHub's image proxy (camo.githubusercontent.com) to flatten the SVGs and kill the <animate> tags. Watching the live scroll proved it actually worked—every time a divider came back into view, the little white spark was somewhere else on the track. It wasn't just working on localhost.

Logos, badges, and the stubborn cards that refused to cooperate

Pull request 14 was the full wardrobe change. I kept the palette tight:

Role	Hex
Doom green	`#4cff2a`
Cap blue	`#5aa0ff`
Night text	`#cfe3ff`
Iron Man red	`#d3202f`
Gold	`#f2b632`
Ember	`#ff9a3c`
Night	`#0b1020`
Purple edge	`#2a1250`

Shields.io happily took the new hex codes as URL parameters—followers in Doom green, DEV in Cap blue, LeetCode in Iron Man red, and email in gold. Same links, fresh paint.

The standard section emojis got retired and replaced with eight custom neon SVG tiles (about, tech, projects, writing, stats, coding, community, badges) sitting inline next to the headings:

## <img src="assets/sections/about.svg" width="32" height="32" align="absmiddle" alt="" /> About me

For the tech stack, I took fifteen familiar logos, recolored them to match the theme, and hosted them locally in assets/tech/ so an external badge CDN couldn't revert them back to their factory defaults. Each category (languages, ML, web, databases, tools) gets its own border color, and Python's tile gently breathes on a 2.4-second opacity loop because why not.

The GitHub stats cards accepted the exact same hex values via query parameters. Green titles, gold icons, dark night panel, purple border. I left a note in the PR to fall back to the built-in radical theme if the stats service ever choked on the custom colors, though so far it has behaved.

Then there were the two holdouts. The LeetCode card is still wearing its nord theme, and the HackerRank card doesn't accept color parameters at all. A broken image link looks way worse than a slightly off-brand color scheme, so I let them keep their clothes. At least Stack Exchange let me swap in the ember orange.

It is the classic developer trap: a plain profile, a "quick fifteen-minute tweak," and suddenly you are three hours deep into hand-coding SVG filters. None of it is actually necessary. The code and the articles were already on the page—the superhero cats are just there to get people through the front door.

If you've looked at your own GitHub profile lately, what's the weirdest thing on it that isn't a stats card?

Monuments of India, Part 2: Domes, Arches, Realistic Stone and Finer Details in three.js

amananandrai — Thu, 12 Nov 2026 04:12:29 +0000

Last time, I proudly showed you 101 Indian monuments built entirely from code. This time I have to confess something: some of them were, let's say, enthusiastic approximations. That story is in I Built 101 Indian Monuments in the Browser Using Only Code.

Qutub Minar was wearing a cupola it never owned. The Taj Mahal had a lovely tomb but no actual garden. Dilwara had one temple where there should have been five. And a few of my buildings had a gorgeous front and, behind it, a back that looked like I'd lost interest halfway.

So I went on a fixing spree. Real doorways and guard niches on the forts. A proper charbagh for the Taj. Backs, sides and windows for the palaces. Towns that crowd around the temples like they've been there for centuries. Stone that catches the light, with veining, weathering and pietra dura. And yes, trees: the right trees. No more mango trees in the Thar Desert. Khejri and babul have been called in.

It is still 101 monuments in three.js, still pure code, and still not a single 3D model file downloaded. Come see what got more real, and help me spot what still looks like it's fibbing about its age.

Live: monuments-of-india-nu.vercel.app ·

Code: github.com/amananandrai/monuments-of-india

If the models or the code are useful to you, or you just like them, please give a star to the GitHub repo and help other people find the project.

TL;DR

The masses were already right. The joinery was not. Domes, screens, doors, backs of buildings and the ground around them got a second pass, monument by monument.
Shared parts for the family, detail files for the building. One dome, one jali, one gopuram for everyone, plus a file per monument for what only that monument has.
Everything is still code. Plain files and three.js, no build step, no model files, 650,000 triangles at most on a desktop and 300,000 on a phone.

In this post

What changed since part 1
How a part gets into a building
Domes · Kiosks and turrets · Pillars and columns
Arches, doors and windows · Eaves, battlements and bands
Temple towers · Forts and monasteries
When the shared kit is not the building
What stands around the building
Stone that catches the light
How I checked the work, and what went wrong
What I would still not claim · Add your own monument

What changed since part 1

This is the second pass, with the pictures from the component guides. The masses were already right. Up close, a dome was still a bare bulb, a screen was still a square grid, and the ground around a building was often the wrong trees or the wrong water. The work since then fills in the joinery, gives a few monuments pieces that only they have, and plants each site with what actually stands there.

Here is the short version, in the order I did it:

Real entrances. Forts got passages, guard niches and doors spiked against elephants. Temples got stepped doorways and porches. Mughal tombs got iwans and arcades.
A detail file for every monument, so a building has its own finer architecture and its own setting, not just a generic kit.
Photograph reviews. I compared the models with photographs in batches and fixed what disagreed: the Taj, Charminar, the Lotus Temple, the Hawa Mahal and many more.
Corrections. Qutub Minar lost the cupola it never had and gained Smith's Folly. The Taj Mahal got its full four-quarter charbagh. Dilwara got its other four temples.
Backs, sides and windows for palaces, mosques and tombs, so you can orbit them without finding a blank wall.
Towns and water around the temples at Kedarnath, Tirumala, Trimbak, Varanasi and Ujjain, plus the Old City round Charminar.
The right trees and the right water, per site.
Surfaces: photo textures with normal and roughness maps, calligraphy, pietra dura, carved reliefs and banded masonry.
Performance: monuments load when you open them, shadows follow the view, and phones get a lighter build.

Before and after

Same monument, same site, rendered by the same code: the left side is the repository before the second pass began, the right side is today.

Qutub Minar. The old tower wore a cupola it never owned. Now it tapers to its real top, and Smith's Folly, the Alai Darwaza, the cloister and Iltutmish's tomb stand around it, on grass with a path and trees.

Taj Mahal. The old tomb stood alone on a red plinth. Now it has its pishtaqs, calligraphy, chhatris and a charbagh garden to walk down.

Dilwara. One temple became the whole group of five, each in its own walled court, among trees.

Jaisalmer. A smooth sandstone mound with a ring wall became a fort at its real size on its Trikuta hill, with bastions, the road up to the gate and a town inside the walls.

Hawa Mahal. A flat stepped front with no depth became a screen of carved jharokhas, with the court and ranges behind it, the street in front and the building's sides finished.

The pictures below are the ones in components.md. node tools/shoot-components.mjs draws each shared part alone, in plain light. On the site the same part carries shadows, a photo texture and weathering. What each function takes, and which file it lives in, is in architecture.md and realism.md.

The site is still plain files and three.js, with no build step.

How a part gets into a building

Each monument has two files.

js/monuments/<name>.js builds the masses: plinth, walls, towers, roofs.
js/details/<name>.js adds the finer architecture and the setting, from addDetails(f, g).

f is the group the home view frames. g is the whole site, so a river or a town can sit outside the frame and not pull the camera back.

A few rules hold for every part:

Metres, y up. A part stands on y = 0 and faces +z unless its comment says otherwise.
The stone is passed in. M.marble, M.red, M.granite and the rest live in js/helpers.js. A one-off stone is mat('#hex', roughness).
Merge when the part is done. mergeByMaterial(group) leaves one mesh per material, so a facade of hundreds of small pieces is a handful of draw calls.
Two faces never share a plane. An overlay sits 2 to 5 cm off its wall. node check-flicker.mjs <id> from tools/ finds the ones that do not.

Placing a row of windows is a loop around the four faces:

// A window on each face, 11 m out from the centre, the sill 13.6 m up.
for (const a of FACES) {
  d.add(onFace(at(windowFrame(2, 4.2, M.cream, { shape: 'flat' }), 0, 13.6, 0), a, 11.01));
}

at moves a part. onFace turns that move onto a wall: angle 0 is the +z face, the next number is how far out, and a third number walks along the face. aroundCircle and alongFace do the same for a ring of brackets or a cornice. Hundreds of identical merlons or columns go through inst(), one geometry drawn many times.

Domes

A dome is rarely just a dome. The bulb springs from a drum through a moulded neck, and the finial that crowns it tells you the tradition: a Mughal spike, a temple pot, a crescent.


Onion dome: neck, lotus crown, finial	Lotus dome: ribs, a cup of petals, a crescent

onionDome(r, m) is a lathe of the shared onion profile. From 1.5 m radius upward (4 m on a phone) it adds two more lathes that ride on the same group, so moving, scaling or ribbing the dome carries them along:

export function onionDome(r, m, {
  crown = r >= (detail.low ? 4 : 1.5),
  neck = r >= (detail.low ? 4 : 1.5),
} = {}) {
  const o = lathe(ONION.map(([a, b]) => [a * r, b * r]), m, 48);
  if (neck) o.add(lathe(DOME_NECK.map(([a, b]) => [a * r, b * r]), m, 32));
  if (crown) o.add(ribbed(lathe(DOME_CROWN.map(([a, b]) => [a * r, b * r]), m, 32), 16, 0.1));
  return o;
}

The neck is the moulding where the bulb springs from the drum. The crown is the inverted lotus, sixteen ribs pressed in by ribbed(), which is the mahapadma the finial rises from. { crown: false } or { neck: false } leaves one off where a monument models its own. The Taj does.

Around that sit the other turned shapes: hemi for a plain hemisphere, persianDome for a pointed double curve, lotusDome for an onion with shallow ribs sitting in a cup of petals, petalRing for the petals themselves, and finial, kalash and crescentFinial for whatever crowns it. A temple pot, a Mughal spike and a crescent are three different functions, because they are three different objects.

Kiosks and turrets

The chhatri, a small domed kiosk on columns, is the silhouette of Rajput and Mughal skylines. Take them off a roofline and it stops looking like India.


Chhatri	Mughal chhatri	Guldastas

Minaret	Jharokha

chhatri(r, h, m, domeM) is the domed kiosk on eight columns that stands on Mughal and Rajput roofs. At full detail each column gets a moulded base and a spreading capital, the eave gets a drip edge, and the dome sits on a low drum. mughalChhatri is the richer one: arches between the columns, a sloping eave, a ribbed lotus dome, and an optional crescent.

guldasta is the Lucknow roof turret, a thin shaft under a tiny onion and a spike. minaret tapers, takes a list of balconies, and is capped by a chhatri. jharokha is the oriel on brackets, screened on three sides, under a roof that can be curved Bengal ('bangla'), domed, or flat. banglaRoof is that curve on its own, for pavilions as well as windows.

Pillars and columns


Classical, plain and Corinthian	Carved temple pillar	Cluster pillar

Yali pillar	Column trim on bare shafts

These are different orders, so they are different functions.

column(r, h, m, { order }) in js/details/colonial.js is a classical column: plinth, base, tapering shaft, capital. order: 'corinthian' adds flutes and acanthus. entablature and corinthianCapital are what a colonnade carries above it.
carvedPillar is a temple pillar: square base, octagonal shaft with two carved bands, a cushion and a capital.
clusterPillar is the Vijayanagara pillar, a shaft ringed by slender colonnettes. yaliPillar carries a rearing yali and its rider. Both are sculpted rather than stacked from boxes.
columnTrim(list, m, { capM }) dresses a colonnade that was built as bare instanced shafts: a plinth and moulding under each, a necking ring and an abacus at the head. It is on Agra Fort's Diwan-i-Am, the Padmanabhaswamy corridor, Mahakaleshwar's colonnade and the Secretariat loggias at Rashtrapati Bhavan.
pilasters are the flat ones, proud of a wall by a few centimetres.

The trim matters because the cheap way to draw forty columns is one instanced cylinder. That reads as a row of poles. Bases and capitals are a second instanced pass, so the shafts stay cheap and the order comes back.

Arches, doors and windows


Arch and its ring	Iwan	Niche

Window with a jali	Classical door	Gothic window

Temple doorway

archWall cuts an opening through a wall. archRing is the moulded band around it. niche is a blind arch with a half-dome hood, deep enough to read as a recess. iwan, in js/details/mughal.js, is the great recessed arch of a gate or a tomb front, with its door. arcadeSkin cuts a wall into a row of arched cells, each a door, a screen or a room. mughalDoorway is the smaller pointed door onto a dim interior.

The traditions that are not Mughal have their own doors, because a fanlight is not a torana.

templeDoorway is a stepped frame, a hood, timber leaves standing open, a lamp in the sanctum, and guardians. doorLeaves can take spikes, the iron points set against war elephants. doorFrame is the nested carved bands of a post-and-lintel door. interior is the dim room seen through it. templePorch is the small open porch in front.
classicalDoor, porch and pediment are the colonial and Indo-Saracenic set. gothicDoor, gothicWindow and oculus are the pointed portal, the two-light window and the round window.
windowFrame(w, h, m, { shape, screen }) is a window in a stone surround. screen: jali(m) fills it.

The jali, from a grid to a lattice

A jali is a pierced stone screen. It lets air and light through while keeping a room private, and it is one of the most recognisable things in Mughal and Rajput architecture. It is also the part that used to be a square grid. It is now the octagon-and-diamond lattice of Mughal and Rajput screens, one function for the cut and the shading so they cannot drift apart. A 22 cm grid:

float sJaliHole(vec2 uv) {
  vec2 p = abs(fract(uv / 0.22) - 0.5);
  float oct = step(max(p.x, p.y), 0.34) * step(p.x + p.y, 0.47);
  float dia = step(1.0 - p.x - p.y, 0.13);
  return max(oct, dia);
}

Up close, when the holes are large enough on screen not to shimmer, the shader discards the opening. The stone around it still casts the shadow. Far away the lattice stays a shading pattern. Modelling every hole on 101 buildings was never going to fit the triangle budget: 650,000 on a desktop, 300,000 on a phone.

The same trick covers the ornament that should stay cheap: frieze for a band of rosettes, carved(m, kind) for 'script', 'calligraphy', 'pietra', 'reliefs' and 'tiles', plus rosette, medallion, sunburst and lettering for the roundels and the raised names. The pattern lives in the shader. The mesh stays a wall.

Eaves, battlements and bands


Chhajja on brackets	Merlons	Railing

chhajja is the deep sloping eave. chhajjaRing is the round version. bracketGeo is the corbel that carries an eave or a balcony, and placeAll drops one copy at every point in a list. merlons is a row of pointed battlements. On a fort, rampart and bastionCrowns add the parapet, a string course and arrow slits, for a long curtain wall and for round bastions.

railing and railingRing are posts with pierced screens between them. balustrade is the classical version. beltCourse runs a band around a rectangular building, mouldings stacks courses into a plinth or a cornice, dentils is the row of small blocks under that cornice, and panel is a sunk field that can be carved or inlaid. wallWithGaps is a compound wall with openings left for its gates.

Temple towers


Shikhara	Nagara temple	Dravida vimana

Gopuram	Mandap	Temple niche

nagaraTemple({ w, h, m, halls, … }) builds a North Indian temple in one call: sanctum, curved spire, and halls stepping out in front. That is why Somnath, in the first article, fits under 1 KB. shikhara is the spire alone, with nagaraProfile and kalingaProfile as two tapers. bhumijaRows sets miniature spires between the bands of a Bhumija tower.

dravidaVimana is the stepped tower over a South Indian sanctum. Each storey's edge carries miniature shrines: kuta at the corners, shala along the sides, laid out by haraRow. gopuram(w, d, h, tiers, seed) is the gate tower, tier on tier of painted stucco figures. The seed is why Meenakshi's towers are not copies of each other. mandap is a pillared hall under a stepped roof. storeyedHall stacks galleries. pidaRoof is the stepped pyramid of slabs on its own.

templeNiche(w, h, m, { figure }) puts an image in a niche. For a long row, idol is the cheap standing figure in relief. trabeateGate is a post-and-lintel gatehouse, with guardians or carved beasts. dwajasthambha is the gold flagstaff in front of the sanctum. grandStair is the broad flight between side walls, with a landing and guardians.


Grand stair	Figure frieze	Statue, urn, pinnacle

figure, guardian, statue and figureFrieze are the sculpted ones. The great statues, Patel, Bahubali, Thiruvalluvar and the Nageshwar Shiva, are each one continuous skin, grown from a signed distance field in js/sdf.js and meshed in the browser, so a limb grows out of a body the way it does in a carving.

The temples got the biggest structural rethink in this pass. Ram Mandir now has three storeys with cusped arches and a 32-step stair. Somnath's spire rises in seven storeys over a three-tier plinth and a broad stair. Mahakaleshwar has three storeys of shrines under its spire. The shared parts that made this cheap, grandStair, storeyedHall and the cusped arch, are now available to every temple.

Forts and monasteries


Fort gate	Rampart and bastion	Monks' houses

Dharma wheel and victory banner

fortGate is a gatehouse with a real passage, guard niches, and leaves spiked against elephants. towerDetail adds string courses and arrow slits to a round tower. slitRow is a row of slits along a wall.

A gate that is only an arch painted on a wall reads as scenery. A passage you could walk reads as a fort.

For the Himalayan monasteries, tibetanBlock is the whitewashed mass with dark windows under a maroon band. quarters dresses a list of those blocks as monks' houses: windows in black surrounds, doors, beam ends, earth roofs, prayer-flag poles. dharmaWheel is the gilded wheel between two deer over an assembly hall. gyaltsen is the victory banner at a roof corner, shabkhep the pleated awning over a window, parapetDiscs the gilded discs along a parapet. tibetanDoor and tibetanPortico are the painted door and the pillared porch.

The ground under a hill monastery comes from js/details/terrain.js: heightField shapes a surface from a height function, rock where it is steep, scrub or grass where it is not, and mountainRing sets a ring of mountains around a valley. That is how Tawang sits on its spur, Kailasa is cut out of a basalt escarpment, Ajanta sits in its horseshoe gorge, and Amber stands on its ridge with Jaigarh's wall above.

When the shared kit is not the building

Shared parts get a monument into the right family. They do not make the Taj the Taj. The detail file is where a photograph would disagree with a generic kit.

The Taj Mahal. Each face is a pishtaq: a deep pointed arch in a rectangular frame, roofed by a half-dome, with calligraphy in black marble and inlaid flowers in the spandrels. Smaller arched alcoves with pierced screens sit either side. The parapet carries leaf-shaped merlons, the drum a blind arcade, and the four roof chhatris have arches, an eave and a lotus cap. The minarets take three bracketed balconies. The dome's own lotus is modelled here, so the shared crown stays off. And around it all lies the charbagh, the four-quarter garden that the first version forgot.

Konark. The Sun Temple is a stone chariot, so the plinth is wrapped in friezes of elephants and daily life, above and below the wheels. The Jagamohana stands on carved mouldings, with an image in a niche either side of each doorway. At the steps of the Natamandira, lions rear over elephants. The horses are sculpted.

Hawa Mahal. Each jharokha of the screen projects on a pair of small carved brackets under the sill. The white lime bands along the storeys are carved. A lotus crowns each domed kiosk. Flowering bougainvillea sits at either end of the pavement. The lattice holes stay in the shader, so the stone is still solid and the screens still cast shadows. Behind the screen there is now a court, with ranges and ramps, so the building is no longer a facade with nothing behind it.

India Gate, Charminar, the Taj, the Gateway of India and the Old Parliament House carry the most of this layer: roundels, lettering, nested arches, bracketed balconies, jalis, eaves, merlons, lotus domes. The others take the carving of their own tradition. Base mouldings and image niches on the temples. Banded bastions and jharokhas on the forts. Stacked iwans and inlaid stars on the Mughal tombs. Capitals, balustrades and eaves on the colonial buildings.

What stands around the building

Everything that is not the monument comes from js/details/realism.js, with the animals in js/details/animals.js. A part takes a list of spots, [x, z] in metres. Variation comes from a seed, so a visit looks the same as the last one. copies() instances the shape and marks it as dressing, which the home view ignores when it frames the building. Fifty trees are a few draw calls.

Twenty-one kinds of tree, one planter


Broadleaf	Wide	Dry

Columns and conifers	Palms	Shrubs

trees(spots, { kind, seed, y, h }) plants every kind. One table, KINDS, holds the default height, the plain crown, the full crown, the leaf and the bark. An unknown kind throws, naming itself. Only the banyan drops aerial roots. Six silhouettes cover the twenty-one: a broadleaf, a wide broadleaf, a dry umbrella, a column, a tiered conifer, and the palm.

Where	What stands there
Delhi's avenues	Jamun
Bodh Gaya and Sarnath	Peepal, the bodhi tree
Kashmir	Chinar, pale, on a thick trunk
Ladakh, by the Indus	Poplar and willow
Tawang and Rumtek	Fir
Ajanta, and the forests	Teak and sal
The south	Tamarind
Konark and the Shore Temple	Casuarina behind the palms
Jaisalmer, Chittorgarh, the dry ridges	Khejri, dhok, babul, ber

// Twelve jamun down each side of a path. The seed keeps this avenue the same on every visit.
g.add(trees(
  [...along(12, [-58, 14], [-58, 185]), ...along(12, [58, 14], [58, 185])],
  { kind: 'jamun', seed: 6 }
));

along is an avenue. scatter fills a rectangle and stays out of the building. around is a ring.

Every tree starts as a trunk and one crown. That is all a phone keeps. On a desktop, upgradeTrees() replants that monument's trees with a leaning trunk, limbs, and separate leaf clumps, smallest planting first, for as long as the model stays inside its triangle budget. Palms grow fronds with leaflets. Deodars grow drooping tiers. Six specimen trees become full trees. A forest of 160 usually stays plain. Each tree also takes one of three forms of its kind, so a row is not a row of clones.

shrubs has three readings. Plain is a clipped green bush. dry: true is the grey-green scrub of a dry hill. flowers: '#d0306f' is a dark bush with a smaller muted cap, bougainvillea or marigold, deliberately not a bush made entirely of bloom.

Lamps, flags, boats, towns


Lamps, bench, bollards	ASI board	Fountains

Prayer flags	Tricolour and pennant	Marigold garlands

lampPosts are fluted iron posts with a scrolled arm and a glass lantern, lit at night. asiBoard is the blue board on two posts. fountains rise and fall into a ring of foam. umbrellas are the cane and cloth shades on bamboo poles. prayerFlags run from point to point in the five colours. garland hangs marigold strands, orange and yellow. flag is a rippling pennant, saffron or the Nishan Sahib. tricolour is the national flag with the Ashoka Chakra.


Country boats	Ferry launches	Cargo ship

Houseboats	Stalls	Town houses

boats, launches, ships and houseboats take a water height, so a boat floats on its lake. stalls stand outside temple gates and in Laad Bazaar at Charminar. townHouses builds two to five storeys with windows, doors and shop signs. tanks is the share of flat roofs that carry a black water tank, 0.7 by default and 0.15 in the fort town at Jaisalmer. cityAround lines streets on every side of a rectangle and leaves the roads in keep open. At Puri, two rows of houses stand outside Jagannath's outer wall, and the Grand Road stays clear.

Towns are the change I like most. Kedarnath has its pilgrim town along the stone path. Tirumala has the temple town round its Mada streets. Varanasi's old city wraps the Kashi Vishwanath corridor, and Ujjain's old town sits beyond Mahakaleshwar. The Gateway of India has Elephanta ferry launches and ships at anchor.


Traffic on the two bridges that have it

traffic runs only on the Howrah Bridge and the Bandra–Worli Sea Link. There are no motor vehicles anywhere else, and no people at all, so the monument stays the subject.

Animals


Nandi	Elephants	Horse and lion

Deer	Yaks and camels

nandi sits before a Shiva temple. elephant can be stone or bronze. rideElephant adds cloth and a howdah. lion is a gate guardian, and the Lion Capital. deer stand at Sarnath and Sikandra. yaks are in the mountains. camels wear saddle cloths in the Thar. horse, scaled down, is the ponies at Kedarnath. The larger animals are one continuous skin, heavier than the rest of the kit, and the slowest of them are meshed while the map sits idle.

Ground, water, and the shade at a wall's foot

The first scenery was generous, and often invented. Mango and coconut stood in the desert. Pools sat where the ground is grass. A lawn ended like a tile.

Water was put back where the site has it, and taken out where it had been added. The Tungabhadra runs north of Hampi's Vittala compound, palms on its bank. A stone-rimmed lotus pond lies south of the Mahabodhi railing. The Shahi Baoli stands east of the Bara Imambara, a walled stepwell through an arched gate. Ramappa's lake lies beyond the temple garden. India Gate lost the canals at its piers. Jallianwala Bagh's flame stands on the grass. Rameswaram's sea sits east of the temple, in the town. Maota Lake at Amber mirrors the fort.

Paths are flagstones. Courses are 70 cm deep, stones are 1.1 m long, every third course is half-length, and the courses shift so no joint runs straight through. Each stone has its own tone. Far off, the joints drop away and the floor stays slightly mottled.

float row = floor(uv.y / 0.7);
float wdt = mod(row, 3.0) < 0.5 ? 0.55 : 1.1;
float xo = uv.x + row * 0.37;

A wall meets the grass in shade, not in a hard line. When a monument is shown, it is drawn once from straight above into a 512×512 height map (groundShade in js/surface.js). Upward faces darken where that blur stands well above them. Trees are left out of the pass, because they already cast shadows. It runs on phones too.

Ceremonial lawns stay mown: India Gate, the Taj, Victoria, the National War Memorial, both Parliaments. Elsewhere, desktops get grass tufts under about 0.35 m, kept 4 m clear of the monument and off any path.

Close to a building, the camera casts a ray toward its target. If it has entered a solid it steps back out, and it keeps about 1.5 m off a wall in front of it. The home view frames the monument, not the lawns around it, and fifteen monuments open on the view of their best-known photograph: the Taj down its garden, the Red Fort's Lahori Gate, Meenakshi's south gopuram, Hawa Mahal's street front.

At night, floodlights and festival lights come on and stars fill the sky. Press the Night button on any monument to see it.

Stone that catches the light

The shader still paints joints, veins, brick courses, weathering and a slight tint per piece, from world position, so nothing has to be unwrapped. A one-metre block is the same size on the Qutub Minar as on the walls of Agra Fort. Over that, most stones carry a CC0 photograph from Poly Haven: marble, red and cream sandstone, granite, laterite, dark coursed blocks, fort rubble, plaster, lime, khondalite, concrete and weathered planks.


Marble	Red sandstone	Granite

Each set has a normal map and a roughness map beside the colour, packed by tools/pack-textures.py. On a desktop the shader projects them the same way as the colour, so the stone catches the light as a rough surface. Phones keep the colour map. A set is fetched the first time a monument that uses it is opened, not all of them at startup.

On top of the stone comes the ornament. The Taj gets black calligraphy bands round its pishtaqs. Itmad-ud-Daulah gets pietra dura over its walls, towers and pavilion. CSMT gets buff stone coursed with blue-grey basalt. Rani ki Vav gets sculpted panels on its side walls. All of it lives in the shader, so the mesh stays a wall.

Shadows follow the view. The shadow map used to cover a fixed box around the whole monument, so on a large site one texel was most of a metre. It now stays about three-quarters of the camera's distance from its target, changes in steps so the shadows do not crawl, and is redrawn only when a step is crossed. Desktops start at full sharpness and step down for that visit if the frame rate cannot hold.

On a phone, below 760 px wide, ambient occlusion and reflections are skipped. Trees stay plain, the ground has no tufts, towns and traffic are thinned, and the heavier carving waits. ?detail=high or ?detail=low on the address chooses.

How I checked the work, and what went wrong

Procedural models fail in a particular way: they look fine from the home view and wrong from two metres away. So most of the second pass was checking.

Photograph reviews. I went through the monuments in batches and compared each model with photographs of the real building. That is how the Taj, Charminar, the Lotus Temple, Mahabodhi and the Hawa Mahal got their fixes, and how a handful of near-misses were found and closed.
Full audits. After the photo reviews I went round the whole set again, in groups: views and land forms, mountains and towns, then framing, missing pieces and flicker.
Headless checks. The scripts in tools/ run in Node and Playwright and check triangle budgets, heights, filters, flicker and detail counts. They stop a regression from hiding in monument number 87.

Things that went wrong along the way, as I found them:

Flicker. Two faces on the same plane fight over the pixel. Windows, glazing and sea were all guilty. check-flicker.mjs finds them, and the rule is now that an overlay sits 2 to 5 cm off its wall.
A dark seam at the foot of sculpted hills, where the land met the ground.
A black reflection pixel on the Bandra–Worli Sea Link.
Eleven models that were too tall for their real heights, brought back within them.
Water and trees that were simply invented. The first scenery was generous. The mango orchard in the desert was the most photogenic of the lot.

I also made some deliberate cuts. The jali holes are not modelled, because 101 buildings of them would never fit the triangle budget. People are not in the scenes, and motor vehicles appear only on the two bridges that have traffic, so the monument stays the subject.

What I would still not claim

These are interpretations, not survey records. The goal is that someone who knows the building can see its plan, its material and its setting, and that someone who does not can tell a gopuram from a shikhara, and Konark from a generic temple.

The rule from the second pass is small. Repeated joinery lives in one shared part, which is why the pictures above are a catalogue and not 101 separate models. The thing that makes a monument itself lives in that monument's file. The tree and the water are the ones the site's own notes name. A new dome profile does not need a new texture unwrap. A new tree is one row in KINDS.

If you know a building well and see something wrong, I would like to hear it. Open an issue with a photograph or a source, and it becomes the next fix.

Add your own monument

Adding another monument is still one module and one card in js/data.js.

Create js/monuments/<name>.js with the masses: plinth, walls, towers, roofs.
Add its card to js/data.js: name, place, dates, style, material and a few facts.
Optionally add js/details/<name>.js with addDetails(f, g) for the finer architecture and the setting. Reuse the shared parts first.
Run the checks in tools/ (budgets, heights, flicker). See tools/README.md.

The code is MIT licensed, so you are free to use it, learn from it and build on it.

Try it

Explore: monuments-of-india-nu.vercel.app. Open #taj-mahal, then #konark-sun-temple, #hawa-mahal and #jaisalmer-fort.
The guides, with every part: components, architecture, the setting, how it is drawn.
If you found this helpful, or you like the project, star the repo on GitHub.

Which building still looks least like itself? Tell me in the comments. That is the next detail file.

The component pictures are rendered from the repo by tools/shoot-components.mjs. The project's code is MIT licensed, and so is three.js. Photo textures are CC0 from Poly Haven. Map data is public domain from Natural Earth.

LLMs Aren’t the Only Game in Town: A Beginner’s Guide to JEPA, Concept Models and Decision Models

amananandrai — Tue, 10 Nov 2026 18:52:51 +0000

Last week I asked a teammate, "Is the build green?"

He replied with four paragraphs. There was context. There was a history of the CI pipeline. There was a philosophical aside about flaky tests. Somewhere in paragraph three was the word "yes".

That, in one office anecdote, is how we use large language models today. We have a machine that is wonderful at writing, and we keep asking it questions whose answer is one word.

This post is a tour of the models that do something other than write one token after another: concept models, JEPA, diffusion language models and decision models. No maths degree required. Bring chai.

First, what is "next-token prediction"?

Your phone keyboard suggests the next word as you type. An LLM is that idea with a gym membership and a few billion parameters.

It reads everything so far, guesses the most likely next token (a word or a piece of one), adds it to the text, and then does the whole thing again. And again. A 500-word answer is roughly 700 tiny guesses in a row.

This works absurdly well. It gave us chatbots, coding assistants and an entire genre of LinkedIn posts. But it has three built-in quirks:

It is slow by design. One token per trip through the network. A long answer is a long queue.
It thinks at the smallest unit. Imagine planning a holiday letter by letter. "G... o... a..." You would never get to the beach.
It always writes. Even when your code only wanted true or false, you get prose, and then you write a parser to dig the answer back out.

Each alternative below attacks one of these quirks.

1. Large Concept Models: think in sentences

The story. My grandmother does not cook letter by letter. Her recipe in her head is "make the tadka, add the dal, simmer". Each step is a whole idea. The exact words come later, and she can say them in three languages depending on who is in the kitchen.

The idea. In December 2024, Meta published Large Concept Models. Instead of predicting the next token, the model predicts the next concept, where a concept is roughly one sentence squeezed into a single vector.

It works in three steps:

An encoder called SONAR turns each sentence into a vector.
The concept model looks at the vectors so far and predicts the next vector.
A decoder turns that vector back into words.

The neat part is that the vector does not belong to any language. SONAR covers about 200 languages for text, so the same predicted idea can be decoded into English, Spanish or Japanese without running the model again.

Benefits

Plans at the level of ideas, which is closer to how people outline before they write.
Language-agnostic by construction. Low-resource languages get a ride for free.
Long documents become short sequences, since one sentence is one step.

The catch. This is research, not a product you can call from your app. The paper itself notes that sentence vectors can be fragile (a tiny nudge can decode into a different sentence), and for very short sentences an ordinary LLM is actually cheaper.

2. JEPA: predict the meaning, not the pixels

The story. You are crossing a busy road. An auto-rickshaw is approaching. Your brain predicts "that thing will be here in two seconds". It does not predict the exact pattern of dust on its windshield or which way each leaf on the roadside tree will flutter. If it tried, you would still be standing on the kerb next Tuesday.

The idea. JEPA stands for Joint-Embedding Predictive Architecture, a line of work Yann LeCun proposed in 2022. The pitch is simple: do not make a model reconstruct raw data. Make it predict the representation of the missing part.

Hide a patch of an image. A generative model is graded on repainting every pixel. A JEPA model is graded on whether its summary of the hidden patch matches the real summary. Unpredictable details simply stop mattering.

The family so far:

I-JEPA (2023): images.
V-JEPA (2024): video.
V-JEPA 2 (June 2025): a 1.2-billion-parameter model trained on more than a million hours of video. After just 62 hours of robot footage, it could plan pick-and-place moves for a robot arm on objects it had never seen.
LLM-JEPA (September 2025): brings the trick to language. It keeps normal next-token training and adds a JEPA term. For example, a bug description and the code that fixes it are two views of the same thing, so their representations should be predictable from each other. The extra work happens only during training; the finished model runs at the usual speed.

The "world model" argument. LeCun's long-running claim is that a system which only predicts the next word never has to learn how the world behaves. A toddler knows a dropped spoon falls long before she can say "gravity". A world model learns that kind of physics by watching, then uses it to imagine "if I do this, that happens" before acting. That is planning.

Benefits

Learns the gist and ignores noise, so it needs less hand-labelled data.
A natural fit for robots and anything that must predict consequences.
LLM-JEPA shows the idea can improve ordinary LLMs without slowing them down at run time.

The catch. You cannot chat with V-JEPA. It does not produce text. Today it is a research direction for long-horizon planning, not a drop-in API.

3. Diffusion language models: develop the whole photo

The story. Remember Polaroid photos? The picture does not print from left to right. The whole thing appears as a grey blur and sharpens everywhere at once.

The idea. A diffusion language model starts with a full-length answer made of noise and cleans up the entire sequence over a handful of passes. Many tokens are fixed in parallel rather than one after another.

This is the same family of technique behind image generators, pointed at text. Inception Labs shipped the first commercial one, Mercury, in early 2025, and Google showed an experimental Gemini Diffusion that May. In February 2026 Inception released Mercury 2, claiming about 1,000 tokens per second.

Benefits

Speed. Parallel refinement is the whole point.
It can revise the middle of a text, not only append to the end. Handy for editing and code infill.
Still a real language model: you get normal text out.

The catch. Speed numbers come from the vendors, and a "tokens per second" figure means little without the test conditions. One independent test measured Mercury 2 at a median of 324 tokens per second, well under the headline. Tooling around diffusion models is also younger.

4. Decision models: just give me the verdict

The story. In cricket, when a run-out goes upstairs, the third umpire watches the replay and the big screen shows two words: OUT or NOT OUT. Nobody in the stadium wants an essay. Forty thousand people want a decision, quickly, and ideally a correct one.

Psychologist Daniel Kahneman called this fast, intuitive mode of thought System 1, as opposed to slow, deliberate System 2. Catching a ball is System 1. Filing taxes is System 2.

The idea. On 15 September 2026, TypeSafe AI released Jev and described it as a "System One" model. It does not generate text at all. You send it:

a state (some text or JSON), and
one or more typed questions defined in code.

It returns typed answers with probabilities, in a single pass. All the questions are answered in parallel.

The docs list a few question types: Choice (pick one option from a set), Score (a number on a scale) and Noul (their name for a yes/no answer expressed as a probability between 0 and 1). In spirit, your code ends up looking like this:

# Sketch of the idea, not the real SDK. See TypeSafe's quick start for actual syntax.
answer = decide(
    state={"ticket": "I was charged twice and nobody is replying!!"},
    questions={
        "team": Choice(["billing", "bugs", "sales", "other"]),
        "urgency": Score(1, 5),
        "angry": Noul(),
    },
)

if answer.team.choice == "billing" and answer.angry > 0.9:
    page_a_human()

No prompt engineering, no "respond ONLY in JSON, I am begging you", no regex.

Where people use it

Routing between LLMs. Is this request easy enough for the cheap model, or does it need the expensive one?
Checking an agent's next action. Before the agent runs DROP TABLE users, ask a fast model: is this safe?
Classification inside software. Spam or not, which queue, how severe.

A fun detail. The name comes from the economist William Stanley Jevons. His paradox: when steam engines got more efficient, Britain burned more coal, not less, because coal power became worth using everywhere. TypeSafe's bet is the same for decisions. Make one cheap enough and software will make a lot more of them.

Benefits

Fast: TypeSafe reports 70 to 500 milliseconds per call.
Output your code can branch on directly, with a probability attached so you can set thresholds.
Cheap at high volume.

The catch. It only works when you can list the possible answers in advance. It cannot explain itself, write, or reason through a brand-new problem. The headline comparisons are also TypeSafe's own, and the company itself flags limits in its benchmark, such as building the test workflows in-house. Treat it as early access, because it is.

The timeline: how we got here

Read it as a story in three acts:

2017 to 2022: one unit to rule them all. The Transformer arrives, and predicting the next token turns out to scale further than anyone expected.
2022 to 2025: "should we predict something else?" LeCun argues for predicting representations. JEPA moves from images to video to robots. Meta tries sentences as the unit. Inception tries the whole sequence at once.
2025 to 2026: mix and match. LLM-JEPA blends two training goals in one model. Decision models drop text entirely for the jobs that never needed it.

Notice that nobody on this timeline killed the Transformer. Most of these models still use it inside. What changed is the question we ask it.

Cheat sheet: what each approach buys you

Approach	Predicts	Main benefit	Main catch	Status in 2026
Next-token LLM	The next token	Writes and reasons about almost anything	Slow, wordy, costly for tiny jobs	Everywhere
Large Concept Model	The next sentence-sized idea	Plans in ideas, works across languages	Fragile vectors, research code	Research
JEPA / world model	The representation of what is missing or next	Learns the gist, enables planning	No text output	Research, early robotics
LLM-JEPA	Tokens, plus a representation term in training	Better representations at no run-time cost	Extra training cost	Research
Diffusion LM	The whole sequence, refined in passes	Very fast generation, easy mid-text edits	Younger tooling, vendor-reported speeds	Commercial
Decision model	A typed answer with probabilities	Milliseconds, cheap, no parsing	Only for answers you can enumerate	Early access

Pick the right model for the job

Twelve everyday tasks. Before the animation sorts them, try guessing where each one goes.

Answer key (static version)

The rule of thumb that falls out of this:

Can you list every possible answer in advance? Use a decision model or a small classifier.
Do you need real text, right now? Look at a diffusion LM.
Is the answer open-ended or does it need actual thinking? That is still an LLM.
Does it need planning many steps ahead in the physical world? That is where concept and world models are heading, and it is still research.

In practice these team up. A decision model at the front door routes each request, an LLM writes the hard answers, and another quick decision checks the result before it ships. System 1 and System 2, sharing a desk.

The numbers: latency and cost

Two charts, both built only from figures the vendors or their cited benchmarks have published. Dates are on the charts because these numbers age like milk.

Please read these with one eyebrow raised:

They are not the same test. Jev's figure is for returning a decision. The LLM figures are for generating a full answer. Comparing them is like timing a nod against a speech, which is rather the point, but it is not a benchmark.
They are vendor-reported. Mercury 2's comparison numbers come from Inception. The 3-to-329-second range comes from a benchmark TypeSafe cites.
Prices change. Check the pricing pages before you put anything in a spreadsheet.

The honest takeaway is about orders of magnitude: a bounded decision can come back in a fraction of a second, fast generation in a second or two, and a reasoning answer in many seconds.

So, is the LLM dead?

No. Put the pitchfork down.

LLMs remain the best tool we have for open-ended writing and reasoning. What is ending is the habit of using them for everything. We do not hire a novelist to operate a light switch.

The mental model I would keep:

Words needed? LLM, or a diffusion LM if speed matters most.
A verdict needed? Decision model.
A plan needed? Watch the concept and world model research. It is not ready for your sprint, but it is where the interesting papers are.

And the next time someone asks whether the build is green, consider answering like a decision model: "Yes. 0.97."

Sources and further reading

Large Concept Models: Language Modeling in a Sentence Representation Space (Meta, December 2024)
InfoQ on Large Concept Models (January 2025)
V-JEPA 2 (Meta, June 2025)
LLM-JEPA: Large Language Models Meet Joint Embedding Predictive Architectures (Huang, LeCun, Balestriero, September 2025)
Mercury 2 launch coverage (The Decoder, February 2026)
Mercury 2.5 and the caveats on speed claims (Runtime Wire, 2026)
TypeSafe AI and the Jev documentation
What is Jev? (DigitalOcean, 2026) and TrueFoundry's analysis for latency, pricing and benchmark caveats

Which of these would you actually put in production first? Tell me in the comments. One-word answers are welcome.

From Attention to 3-Bit Caches: How LLMs Learned to Remember Less (MHA, GQA, MLA, MoE, Quantisation Explained)

amananandrai — Tue, 10 Nov 2026 18:42:22 +0000

In 2017, eight researchers published a paper with the cockiest title in computer science: Attention Is All You Need. They were right, with one small footnote that took the rest of the industry nine years to work through:

Attention is all you need. Also 16 GB of memory per conversation, a warehouse of GPUs, and a power plant.

This post is the story of that footnote. We'll start from zero (what attention even is), then follow the trail of clever hacks that turned a research toy into the chatbots you use every day: KV caches, grouped and latent attention, FlashAttention, mixture of experts, ZeRO, distillation and quantisation.

No PhD needed. If you can follow a restaurant analogy, you can follow this. There is a little maths, clearly marked, and you can skip every formula without losing the plot.

What's inside

Attention in five minutes
The KV cache: a waiter's notepad that ate the restaurant
The evolution of attention: MHA → MQA → GQA → MLA → LRKV
Taming the KV cache: three families of tricks
Mixture of experts: stop asking the dentist about your taxes
Scaling training: parallelism, ZeRO and FSDP
Distillation: a small model that copied the topper's notes
Quantisation: FP8, FP4 and TurboQuant
So how did all this make GPT-style models better?
The timeline

1. Attention in five minutes

The cocktail party

You're at a noisy party. Twenty conversations are happening at once, and yet when someone across the room says your name, your brain snaps to it. You didn't listen to everyone equally. You gave most of your attention to the few voices that mattered.

That is the whole idea. When a language model reads a sentence, every word looks at every other word and decides how much each one matters to it.

Take the sentence: "The cat sat on the mat because it was tired."

What does "it" mean? You know it's the cat (mats rarely get tired). A model works this out by letting "it" pay most of its attention to "cat".

Query, Key, Value: attention as a search engine

How does a word decide who matters? Each word carries three little vectors (lists of numbers):

Query: "here's what I'm looking for"
Key: "here's what I am"
Value: "here's what I'll tell you if you pick me"

Think of a library. Your query is the question in your head. Every book has a key (the label on the spine) and a value (the contents). You compare your question with every spine, then read mostly from the books that match best.

Remember keys and values. They are the main characters of the next three sections, and also the reason your GPU is sweating.

Multi-head attention: a panel of specialists

One round of attention only catches one kind of relationship. So transformers run many in parallel, called heads. One head might track grammar, another tracks who "it" refers to, another notices that we're inside a quotation. Each head has its own queries, keys and values. That's multi-head attention (MHA).

It's a panel interview: one interviewer checks your coding, one checks your communication, one just stares at you to see if you blink.

The transformer in one picture

Stack attention with a small "thinking" network (the feed-forward layer), repeat the pair dozens of times, and you have a transformer.

GPT-style models do one job: guess the next token. Then they add that token to the text and guess again. And again. "The" → "The cat" → "The cat sat". Everything a chatbot writes is produced one token at a time by this loop.

That loop is where the trouble starts.

2. The KV cache: a waiter's notepad that ate the restaurant

Imagine a waiter with no notepad. Every time your table adds a dish, he walks back and asks everyone to repeat the entire order from the beginning. By dessert he has heard "one butter chicken" eleven times.

A transformer without a cache behaves exactly like that. To generate token 1,000, it would recompute the keys and values for the previous 999 tokens, even though they haven't changed.

The fix is obvious: write it down. The KV cache stores the keys and values of every token already processed, in every layer. A new token only computes its own K and V, then looks up everyone else's.

Wonderful. Except the notepad keeps growing:

KV bytes = 2 \times layers \times KV heads \times d_{h e a d} \times tokens \times batch \times bytes per value

Plug in a medium-sized example: 32 layers, 32 heads, 128 numbers per head, 16-bit values and a 32,000-token chat. You get 16 GB for a single conversation. Now serve a thousand users.

This is the plot twist of modern LLMs: for long contexts, the limit is not how fast the GPU can multiply (FLOPs). It's how much the GPU can remember. Almost every trick in the rest of this post is a way to shrink, share or sidestep that notepad.

3. The evolution of attention: MHA → MQA → GQA → MLA → LRKV

Here is the whole family in one animation. Watch the memory meter on the right.

Let's meet them using one running analogy: a class of 32 students (heads) taking notes (keys and values) in a lecture.

MHA: everyone writes their own notes

Every student writes complete notes. Great diversity of thought, 32 notebooks to store. This is the original 2017 design, used by GPT-2 and GPT-3.

MQA (2019): one notebook, photocopied

Noam Shazeer (one of the original eight) asked: what if all heads shared a single set of keys and values, and only the queries stayed separate? The cache shrinks by 32×. The catch: with one notebook, the students start thinking alike, and quality dips.

GQA (2023): study groups

The compromise that won. Split the heads into a few groups; each group shares one notebook. With 8 groups instead of 32 notebooks you save 4× memory and lose almost nothing. Llama 2 (70B), Llama 3 and Mistral all use it. If you've run an open model on your laptop, you've used GQA.

MLA (2024): flat-pack furniture

DeepSeek-V2 took a different road. Instead of sharing notebooks, compress them. Store one small "latent" vector per token, and rebuild the full keys and values only when needed. It's IKEA logic: ship the wardrobe flat, assemble at home.

In the DeepSeek-V2 setup, that's 576 numbers per token per layer. The paper notes this is as small as GQA with only about 2.25 groups, while keeping quality on par with full MHA.

The RoPE headache (and the fix)

There's a neat trick hiding in MLA. At inference time you don't even have to rebuild the keys: the "expand" matrix can be folded into the query side once, like pre-multiplying a recipe. Keys stay compressed forever.

Then RoPE walks in. RoPE (rotary position embedding) is how most modern models know word order: it rotates each key by an angle that depends on the token's position. Token 5 gets one rotation, token 500 another.

And a position-dependent rotation can't be folded into one fixed matrix. It's like trying to pre-print a single shipping label for parcels going to different cities.

DeepSeek's fix is decoupled RoPE: split the key into two parts. A big content part with no position in it (still foldable), and a small separate part that carries the rotation and is cached next to the latent.

For the formula fans:

c^{K V} t = W^{DK V} h_{t}, k^{C} t = W^{U K} c^{K V} t, v^{C} t = W^{U V} c^{K V} t, k_{t R} = RoPE (W^{K R} h_{t}), k t, i = [k_{t, i C}; k_{t R}]

In words: squeeze, cache, expand; and keep position in its own small pocket.

LRKV (2026): one textbook, personal sticky notes

The newest idea, Low-Rank Key-Value attention, comes from a team at Intercom. Their observation: heads are mostly redundant, but not entirely. So give the whole class one shared full-quality textbook, and let each student add a thin stack of personal sticky notes (a low-rank residual).

Turn the sticky-note thickness (the rank, r) down to zero and you get MQA. Turn it all the way up and you're back at MHA. The authors report that a 2.5-billion-parameter model beat standard attention while using roughly half the KV cache.

The scoreboard

Method	Cached per token, per layer	Trade-off
MHA	2 × H × d_head	Full head diversity, largest cache
MQA	2 × d_head	Smallest simple cache, heads lose diversity
GQA	2 × G × d_head (G groups)	The common middle ground
MLA	d_latent + d_rope	Very small cache, extra up-projection maths
LRKV	about 2 × (d_head + H × r)	Shared base plus per-head low-rank detail

And with real numbers for our example model:

Notice the meter doesn't only go down. MQA is the smallest, yet nobody stopped there, because the goal was never "smallest cache". It was "smallest cache that still thinks well". Everything after MQA is about buying quality back cheaply.

Meanwhile, three side quests

FlashAttention (2022): eat the pizza slice by slice. Attention compares every token with every token, giving an N × N grid of scores. For 32,000 tokens, that's a billion numbers the GPU has to shuffle in and out of its slow main memory. FlashAttention computes the grid in small tiles that fit in the GPU's tiny, fast on-chip memory, keeps a running total (the "online softmax") and throws each tile away. During training it recomputes tiles when needed instead of storing them. Same exact answer, far less memory traffic, much faster.

Sliding-window attention and attention sinks. Do you remember every word of this article so far? No, you remember the last few paragraphs and the gist. Sliding-window attention lets each token look only at the last few thousand tokens (early Mistral 7B did this). Researchers then found a quirk: models dump a surprising amount of attention on the very first tokens, using them as a sort of "parking spot". Evict those and the model falls apart. Keep a handful of these attention sinks forever and you can stream text endlessly.

Context extension (RoPE scaling, YaRN). A model trained on 4k tokens panics at token 4,001, a bit like a ruler that only goes to 30 cm. Because RoPE encodes position as rotation, you can re-scale the rotation speeds, effectively stretching the ruler. YaRN does this carefully, frequency by frequency, and lets a model handle much longer text with only a little fine-tuning.

4. Taming the KV cache: three families of tricks

Shrinking the notepad through architecture is one option. There are two more, and real systems stack all three.

Spell 1: architectural magic (make less cache)

Everything from section 3: GQA, MLA, LRKV. You choose this when the model is designed; you can't bolt it on later.

Spell 2: shrinking spells (fewer bits per number)

Each cached number is normally stored in 16 bits. Do we need all 16?

FP8 and FP4 caches: store each value in 8 or 4 bits. Half or a quarter of the memory, for a small accuracy cost.
KIVI (2024): noticed that keys and values have different personalities. Keys have a few loud channels, so quantise keys per channel and values per token. Works down to about 2 bits with no retraining.
TurboQuant (Google Research, ICLR 2026): about 3 bits per value, no retraining, no calibration data. It first rotates vectors so they become predictable (PolarQuant), then adds a tiny 1-bit correction for whatever error is left (QJL). Think of it as packing a suitcase really well, then sitting on it.

More on how quantisation works in section 8.

Spell 3: system tricks (waste less)

PagedAttention (vLLM, 2023). Early servers reserved one huge continuous slab of memory per chat, sized for the longest possible reply. Most chats are short, so most of that memory sat empty, like booking a 12-seat table for two. PagedAttention borrows an idea from 1960s operating systems: cut the cache into small fixed-size blocks, park them anywhere, and keep a lookup table.

Prefix caching. Every user of a chatbot gets the same long system prompt. Why compute and store its keys and values a million times? Compute once, share the blocks. This is what's behind the "cached input tokens" discount on API pricing pages.

Continuous batching. Old approach: a bus that waits until it's full, then leaves, and nobody new boards until the last passenger gets off. Continuous batching is a shared auto-rickshaw: the moment one passenger hops out, another hops in. GPUs stay full.

Chunked prefill. One user pastes a 100-page PDF, and everybody else's chat freezes while the model reads it. Chunked prefill breaks the reading into pieces and interleaves other users' tokens between them. It's the "I'll just let you go ahead, you only have two items" of GPU scheduling.

Speculative decoding. A small, fast model drafts the next few tokens; the big model checks them all in one pass and keeps the ones it agrees with. The intern drafts the email, the boss skims and approves. The output is exactly what the big model would have written anyway, just faster, as long as the intern is usually right.

If the big model accepts each guessed token with probability α, guesses γ tokens ahead, and the draft model costs a fraction c of the big one:

speed-up = \frac{1 - α ^{γ + 1}}{( 1 - α ) ( γ c + 1 )}

Cache offloading and eviction. When a user wanders off to make chai, move their cache to cheaper memory (CPU RAM or disk), or delete it and rebuild later. Hot conversations stay on the GPU; cold ones go to the attic.

5. Mixture of experts: stop asking the dentist about your taxes

So far we've optimised attention. The other half of every layer is the feed-forward network, and it's where most of the parameters live.

In a normal ("dense") model, every token passes through all of those parameters. That's a hospital where every patient, including the one with a paper cut, must see every specialist in the building.

A mixture of experts (MoE) adds a receptionist. A tiny router looks at each token and sends it to just a few specialists, say the top 2 out of 8.

The maths is short. The router scores every expert, keeps the top k, and blends their answers:

y = i \in TopK (g (x), k) \sum g_{i} (x) E_{i} (x), g (x) = softmax (W_{r} x)

Total vs active parameters

This gives MoE models two sizes. Mixtral 8x7B has about 47 billion parameters in total but uses only about 13 billion for any given token. DeepSeek-V3 has 671 billion in total and roughly 37 billion active. You get the knowledge of a giant model at the per-token cost of a mid-sized one.

The lazy-router problem

Left alone, routers play favourites. One expert gets picked a bit more, so it learns a bit more, so it gets picked even more. Soon you have one exhausted expert and seven on a tea break (the second half of the animation above).

Fixes:

Load-balancing loss: a small penalty, α · N · Σ fᵢ · Pᵢ, that is lowest when work is spread evenly (fᵢ is the share of tokens expert i received, Pᵢ the share of router probability).
Auxiliary-loss-free balancing (DeepSeek-V3): instead of a penalty, quietly nudge each expert's score up or down depending on how busy it has been. Like a restaurant host steering guests to the empty section.
Capacity factor: each expert has a fixed number of seats per batch. Overflow tokens get dropped: they skip the expert layer entirely.
Shared and fine-grained experts: a couple of always-on generalists handle common knowledge, plus many small specialists instead of a few big ones.

The fine print

Experts usually live on different GPUs (expert parallelism), so tokens must be shipped to their expert and back. Every GPU talks to every other GPU, a traffic pattern called all-to-all.

And the big caveat: MoE saves compute, not memory. All the experts must sit loaded in memory, because you can't know which ones the next token will need. All the doctors are on salary even if you only see two.

6. Scaling training: parallelism, ZeRO and FSDP

Running a model is hard. Training one is harder, because training hoards memory.

Where the memory goes

For every parameter, training keeps roughly:

2 bytes for the weight itself (16-bit)
2 bytes for its gradient (which way to nudge it)
12 bytes for the Adam optimiser's bookkeeping (a full-precision copy, plus momentum, plus variance)

That's about 16 bytes per parameter before counting activations. A 7.5-billion-parameter model needs 120 GB. No single GPU has that. So we split the work.

Three ways to slice a model

It's a group project, and there are three ways to divide it.

Data parallelism: everyone gets a full copy of the assignment and a different chapter to work on, then you average the results. Simple, but every GPU needs the whole model.
Tensor parallelism: split each big matrix across GPUs. Everyone works on the same sentence at the same time, so it needs very fast connections.
Pipeline parallelism: GPU 1 holds layers 1 to 8, GPU 2 holds 9 to 16, and so on. A relay race.

GPUs coordinate with a small vocabulary of group chats, called collective operations: all-reduce (everyone sums up and gets the total), all-gather (everyone gets everyone's piece), reduce-scatter (sum, then each keeps a slice), and all-to-all (the MoE one from earlier).

ZeRO: stop making everyone carry everything

Plain data parallelism is wasteful. All 64 GPUs hold identical copies of the optimiser states, like 64 flatmates each buying their own washing machine.

ZeRO (Zero Redundancy Optimizer) shards things so each GPU keeps only its slice:

Stage 1: shard the optimiser states
Stage 2: also shard the gradients
Stage 3: also shard the weights themselves, fetching them when needed

FSDP is PyTorch's implementation of the stage 3 idea. ZeRO-Offload goes further and pushes the optimiser's work to CPU memory.

With Ψ parameters and N GPUs:

M_{ZeRO-1} = 4Ψ + \frac{12Ψ}{N _{d}}, M_{ZeRO-2} = 2Ψ + \frac{14Ψ}{N _{d}}, M_{ZeRO-3} = \frac{16Ψ}{N _{d}} bytes

From 120 GB to under 2 GB per GPU. The price is more chatter between GPUs, which is why the fast interconnect matters as much as the GPUs.

The pipeline bubble

The relay race has a flaw. While runner 1 is running, runners 2, 3 and 4 stand around. That idle time is the pipeline bubble.

The fix is to cut each batch into many micro-batches, so GPU 1 can hand off the first one and start the next immediately:

bubble = \frac{p - 1}{m + p - 1}

With 4 stages and 4 micro-batches, GPUs idle 43% of the time. With 32 micro-batches, under 9%. A smarter ordering called 1F1B (one forward, one backward) keeps the same bubble but stops activations piling up in memory.

The rest of the toolbox, quickly

Sequence / context parallelism: split one very long sequence across GPUs; ring attention passes keys and values around in a circle.
Expert parallelism: different MoE experts on different GPUs.
3-D / 4-D parallelism: real training runs combine data + tensor + pipeline (+ sequence or expert) at once.
Activation checkpointing: don't store every intermediate result for the backward pass; save a few and recompute the rest. Trades time for memory.
FP8 training: do much of the arithmetic in 8-bit floats (DeepSeek-V3 trained this way).
FlashAttention helps here too: its recomputation trick is what keeps training memory linear in sequence length.
Overlapping communication with compute: send data while the GPU is busy calculating, so nobody waits on the network.
MFU (model FLOPs utilisation): the fraction of the hardware's theoretical peak that actually goes into your model's maths. It's the fuel-efficiency number of training; around half is considered good.

7. Distillation: a small model that copied the topper's notes

You've trained a brilliant, enormous model. It's also slow and expensive. Can a small model learn to behave like it?

Dark knowledge

Show a great teacher model a photo of a husky. A plain label says: "husky". End of lesson.

But the teacher's full answer is richer: "88% husky, 7% wolf, 4% malamute, basically 0% pizza." That tells the student something a textbook label never could: huskies look like wolves and not like pizza. Geoffrey Hinton called this dark knowledge. It lives in the wrong answers.

At normal settings those small percentages are too faint to learn from. So we raise the temperature, which softens the teacher's confidence and makes the "nearly right" answers visible:

The student is trained on a blend of the true labels and the teacher's softened opinion:

L = α CE (y, p_{s}) + (1 - α) T^{2} KL (p_{t (T)} ∣ p_{s (T)}), p^{(T)} = softmax (z / T)

It's the difference between an answer key and a teacher who explains why option B was tempting.

Flavours of distillation

Logit distillation: copy the teacher's output probabilities (above).
Hidden-state (feature) distillation: also copy what the teacher is "thinking" in its middle layers.
Sequence-level distillation: just train the student on text the teacher wrote. Simple, and it works even when you can only see the teacher's outputs.
On-policy distillation: the student writes, the teacher marks. This matters more than it sounds.

Mean-seeking vs mode-seeking

Suppose a question has two good answers, and the student is too small to hold both. It has two ways to fail:

Classic distillation minimises forward KL: the student tries to cover everything the teacher might say, and ends up blurring between the two answers, sometimes producing a mushy mix the teacher would never say. Ask two friends for directions, average "turn left" and "turn right", and drive into a wall.

On-policy distillation minimises reverse KL: the student is only judged on what it actually says, so it learns to pick one good answer and commit. For generating text, committing is usually what you want.

Where it shows up

DistilBERT (2019): 40% smaller than BERT, nearly as good. The proof that this works for language.
Reasoning-trace distillation (2025): DeepSeek-R1's step-by-step reasoning was distilled into small open models, giving laptop-sized models that "think out loud".
Distillation + pruning: cut parts out of the big model, then use distillation to help what's left recover.

8. Quantisation: FP8, FP4 and TurboQuant

Last stop. Distillation makes the model smaller by having fewer numbers. Quantisation keeps the same count of numbers and makes each one cheaper.

Think of prices. ₹499.99 and ₹500 are the same to your wallet. A model's weights are stored with far more decimal places than they need.

Where the bits go

FP32 / FP16 / BF16: the standard floating-point formats. BF16 keeps FP32's huge range but with fewer digits, which training likes.
FP8: comes in two flavours. E4M3 (more precision) and E5M2 (more range).
INT8 / INT4: plain evenly spaced steps: 256 or 16 of them.
NF4: 4 bits, but the 16 levels are placed where weights actually cluster (a bell curve), not evenly.
FP4 (MXFP4, NVFP4): tiny 4-bit floats where a block of values shares one scale factor.

How rounding works

To quantise, pick a ruler: a step size s and an offset z. Then snap every value to the nearest mark.

q = clamp! (round (\frac{x}{s}) + z, 0, 2^{b} - 1), x^= s (q - z), s = \frac{x _{m a x} - x _{m i n}}{2 ^{b} - 1}

Absmax quantisation centres the ruler on zero. Zero-point (affine) quantisation slides the ruler to wherever the data sits.
The rounding error is never more than half a step (s/2).
Weight memory ≈ parameters × bits ÷ 8. A 70-billion-parameter model is 140 GB at 16 bits and 35 GB at 4 bits. That's the difference between "data centre" and "one very nice workstation".

The outlier problem

Ten people are in a bar. Bill Gates walks in. On average, everyone is now a billionaire.

The same thing wrecks naive quantisation. The step size depends on the largest value, so one giant outlier stretches the ruler until all the normal weights are crushed onto two or three marks (the last frame above: one outlier makes 4-bit error about five times worse). LLMs are full of such outliers, which is why "just round everything" doesn't work.

You can soften this with granularity: one ruler for the whole tensor (crude), one per channel (better), or one per small group of values (best, slightly more overhead).

The methods you'll see on model cards

Post-training quantisation (PTQ) vs quantisation-aware training (QAT): round after training (cheap) or teach the model to live with rounding during training (better, costly).
LLM.int8(): keep the few outlier dimensions in 16-bit, squash everything else to 8-bit.
SmoothQuant: move the "spikiness" from activations into weights, where it's easier to handle.
GPTQ: quantise one weight at a time and adjust the remaining ones to cancel out the error. Like fixing a wobbly table by trimming the other legs.
AWQ: look at real activations to find the small fraction of weights that matter most, and protect them.
GGUF k-quants: those Q4_K_M files you download for llama.cpp. Different layers get different bit-widths depending on how sensitive they are.
QLoRA: freeze a 4-bit (NF4) model and train small adapter layers on top. This made fine-tuning big models possible on a single consumer GPU.

Back to the KV cache

And so we return to our villain. Weights are quantised once, offline. The KV cache is created live, per user, per token, so its quantiser must be fast and must work without seeing data in advance.

That's the significance of TurboQuant: about 3 bits per cached value, with no retraining and no calibration. Compared with 16 bits, that's a cut of more than 5× applied to the largest moving part of long-context inference. The rotation step (PolarQuant) deals with the Bill Gates problem by spreading every vector's energy evenly, and the 1-bit correction (QJL) fixes the small bias that's left in attention scores.

9. So how did all this make GPT-style models better?

None of these ideas made models smarter directly. They made bigger, longer, cheaper possible, and that's what made models smarter. (OpenAI doesn't publish GPT-4-era internals, so the examples below come from open models and papers.)

The wall we hit	The idea that broke it	Where you can see it
Recomputing everything per token	KV cache	Every LLM in production
Cache too big for long chats	GQA, MLA, LRKV	Llama 2/3, Mistral (GQA); DeepSeek-V2/V3 (MLA)
Attention too slow and memory-hungry	FlashAttention	Built into PyTorch and most training stacks
Context windows stuck at a few thousand tokens	RoPE, YaRN, sliding windows, attention sinks	4k contexts became 100k+
GPUs sitting half-empty when serving	PagedAttention, continuous batching, prefix caching	vLLM and friends; "cached token" pricing on APIs
Replies too slow	Speculative decoding	Faster responses, same output
Bigger models cost more per token	Mixture of experts	Mixtral, DeepSeek-V3
Model doesn't fit on any GPU for training	ZeRO/FSDP, tensor and pipeline parallelism	Every 100B+ training run
Great model, too expensive to deploy	Distillation	DistilBERT, small "distilled" reasoning models
Model doesn't fit on your GPU	Quantisation	GGUF files, QLoRA fine-tunes, FP8 serving

Put together: GPT-2 in 2019 handled 1,024 tokens. Today's models read entire codebases in one go and answer in seconds, on hardware that isn't a thousand times bigger. The gap was closed by the tricks in this post.

10. The timeline

Year	What happened	Why it mattered
1991	Mixture of experts proposed	The "router + specialists" idea, decades early
2014	Attention for translation (Bahdanau et al.)	Models learn to focus
2015	Knowledge distillation (Hinton et al.)	Small models learn from big ones
2017	Transformer; sparsely-gated MoE	Attention becomes the whole architecture
2018–2020	GPT-1, GPT-2, GPT-3	Scale works; costs explode
2019	MQA, DistilBERT, ZeRO, Megatron	First serious efficiency push
2021	RoPE, Switch Transformer	Better positions; MoE meets transformers
2022	FlashAttention, GPTQ, LLM.int8(), SmoothQuant, speculative decoding	Speed and compression go mainstream
2023	GQA, PagedAttention (vLLM), QLoRA, AWQ, YaRN, attention sinks, Mixtral	Open models become practical to run
2024	MLA (DeepSeek-V2), KIVI, DeepSeek-V3	The KV cache becomes the main target
2025	Reasoning distilled into small open models	"Thinking" models on laptops
2026	LRKV, TurboQuant	Smaller caches without losing head diversity; ~3-bit caches

The 30-second version

Attention = every token decides which other tokens matter, using queries, keys and values.
KV cache = remember keys and values so you never recompute them. It's fast, and it eats memory.
MHA → MQA → GQA → MLA → LRKV = five answers to "how little can each token remember and still think well?"
Three spells for the cache: better architecture, fewer bits, smarter memory management.
MoE = use a few specialists per token. Saves compute, not memory.
ZeRO and parallelism = split training across GPUs without everyone carrying everything.
Distillation = a small model learns from a big one's full opinions, not just its final answers.
Quantisation = store each number with fewer bits; watch out for outliers.

The original paper said attention is all you need. Nine years of engineering later, the fuller version is: attention, plus a very good memory for what not to remember.

If this helped, tell me which section you'd like expanded into its own post. And if you spot a mistake, call it out in the comments; I'd rather be corrected than confidently wrong.

I Built LLM Explained: 43 Interactive Pages That Take You From Tokens to AI Agents

amananandrai — Mon, 02 Nov 2026 21:03:27 +0000

I kept running into the same problem while learning about large language models.

I'd read a blog post about attention, nod along, and two days later I couldn't tell you why we divide by √d_k. I'd see "GQA", "MLA", "MoE", "LoRA", "HNSW" or "context rot" in a paper or a tweet, open five tabs, and close them all with the uneasy feeling that I sort of got it. And the field keeps moving, so there's always a new term on top of the ones I hadn't really nailed down.

So I built the resource I wished I had: LLM Explained. It's a free, interactive course that goes from "why did RNNs hit a wall?" all the way to "how does a production agent retrieve, reason, act and get evaluated?"

I built it to learn, and writing each page forced me to understand things properly. I'm sharing it because I think it can help other people too.

🔗 Live site: https://llm-explained-lovat.vercel.app/
💻 Source code: https://github.com/amananandrai/llm-explained

💌 This is a work in progress and I'd love your help. Suggestions are always welcome. If you find it useful, please ⭐ star the repo on GitHub. Spotted a mistake or have an idea? Open an issue. Want to fix or add something yourself? Pull requests are very welcome!

What is LLM Explained?

It's 42 modules in seven parts plus a capstone (43 interactive pages if you count the KL divergence sub-page). Every concept appears as a picture you can play with before you see its equation.

A few principles shaped every page:

Picture first, symbol second. Each equation sits next to the animation that computes it, and they use the same colours. If the query is blue in the diagram, it's blue in the formula.
One idea per scroll step. Animations move forward as you scroll and never run on without you.
Real numbers at toy scale. 4-dimensional embeddings and 3–5 token sentences, so every value fits on screen and you can check it.
Touch the knob. Every module has at least one widget you control.
Run it yourself. Optional in-browser Python (NumPy) cells reproduce the figures.
Honest limits. Every module ends with a "what this picture leaves out" box, because simplified diagrams can mislead you if you don't know what they skip.

Also, every number on screen is computed in your browser. When something is a simulation or an illustrative figure, the page says so.

How to use the site

1. Start with the curriculum map

The Curriculum link in the top navigation shows the whole course. Parts 1 and 2 are meant to be read in order, and everything after them builds on the attention module. Beyond that you can jump around:

Parts 3, 4 and 7 can be read in any order within each part.
Part 5 (RAG) follows the order of a retrieval pipeline.
Part 6 (Agents) starts from the agents and ReAct module.

If you already know the transformer well, skip to whatever you're curious about. If you're new, start at Module 1 (or the optional maths primer, Module 0).

2. Pick your depth: Intuition, Mechanics or Maths

This is my favourite feature. Every page has a depth switch with three levels:

Depth	What you get	Good for
Intuition	Pictures and plain language, no symbols	A first read, or a quick refresher
Mechanics	Tensor shapes and step-by-step operations	Engineers who want to implement it
Maths	Full derivations, colour-linked KaTeX equations	Going deep, or interview prep

You can read a page at Intuition level, come back a week later and flip to Mechanics. The page grows with you.

And here's what the Maths depth looks like. Notice that Q, K and V keep the same blue, orange and green as in the animations:

3. Scroll, step and scrub the animations

Each page has a hero animation driven by your scroll position. There are also play, pause, step back, step forward and a scrubber, so you can pause on exactly the frame that confuses you.

For example, in the attention module a 5-token attention matrix fills in cell by cell, the heads split into colours, and you see each output vector built up as a weighted sum of value vectors.

Every animation also has a text transcript, and if your system has reduced motion turned on, animations turn into numbered static frames.

4. Play with the widgets

This is where things click. Some examples:

A "remove √d_k" toggle that shows softmax saturating when you drop the scaling factor. You can see why the scale is there.

A parameter counter that checks the 12·d² rule against GPT-2 and GPT-3.

A real byte-level BPE tokeniser running in the browser. Try the Hindi example and watch the token bill go up.

A numerical KL divergence explorer and the closed-form RLHF optimum.

5. Run the Python yourself

Most modules include a "Run it yourself" cell: editable Python running in your browser through Pyodide with NumPy. Change a number, hit Run, and watch the result update. You don't need to install anything. (Pyodide downloads on your first run, so give it a moment.)

6. Check yourself with the quiz

Each page ends with a "what this picture leaves out" box, a 3-question quiz and a further reading list linking the primary papers. Every module cites its sources, from Attention Is All You Need to LoRA, DPO and PagedAttention.

What's covered

Here's the full curriculum. I tried to cover both the core fundamentals and the newer ideas that keep showing up in papers and on Twitter/X.

Part 1 · Foundations: how text becomes numbers

M0 Maths primer (optional), plus a dedicated KL divergence page
M1 How models learn: training terms
M2 Why transformers were needed
M3 Tokenisation
M4 Embeddings

Part 2 · The Transformer and GPTs

M5 Attention and the transformer block
M6 Encoder, decoder and encoder–decoder
M7 GPTs: from pretraining to generation
M8 Post-training: SFT, RLHF, DPO and reasoning
M9 Prompt engineering: zero-shot, few-shot and beyond

Part 3 · Faster, bigger, smaller

M10 Evolution of attention: MHA vs GQA vs MLA (and LRKV)
M11 Taming the KV cache
M12 Mixture of experts
M13 Scaling training: parallelism, ZeRO and FSDP
M14 Distillation
M15 Quantisation: FP8, FP4 and TurboQuant

Part 4 · Real models, new ideas and adapting them

M16 Open-source LLM architectures compared
M17 New block designs: Attention Residuals and beyond
M18 Beyond next-token LLMs: concept models, JEPA and decision models
M19 Multimodality
M20 Fine-tuning: full, LoRA and QLoRA

Part 5 · Retrieval and RAG

M21 Embedding models in depth
M22 Vector search and HNSW
M23 Chunking strategies
M24 Re-ranking with cross-encoders
M25 The seven types of RAG
M26 Graph RAG, open knowledge graphs and vectorless RAG

Part 6 · Agents and harnesses

M27 Agents, tool use and the ReAct framework
M28 Context engineering and context rot
M29 Types of memory
M30 Harness engineering: building the harness
M31 Loop engineering and the Ralph Wiggum loop
M32 MCP: the Model Context Protocol
M33 Skills and plugins
M34 Agent orchestration and subagents
M35 Agent-to-agent communication
M36 Agentic engineering

Part 7 · Production and safety

M37 Benchmarking and evaluation
M38 LLMOps
M39 Safety, alignment and interpretability
M40 Model governance

Capstone

M41 Follow one request end to end. One prompt's whole journey: text → tokens → embeddings with RoPE → transformer blocks (GQA attention with a KV cache, MoE feed-forward) → logits → sampling → text. Then the same request inside an agent harness that chunks, retrieves and re-ranks context, calls a tool, writes to memory, and is traced and evaluated. A tiny real transformer block runs in your browser, and you can inspect every intermediate tensor.

One visual language across every page

Something I cared about a lot: colours mean the same thing everywhere. The blue you learn as "query" in Module 5 is still "query" in the capstone.

Element	Colour
Query (Q)	Blue
Key (K)	Orange
Value (V)	Green
Residual stream	Neutral grey
Router and experts (MoE)	Purple
Frozen weights vs trainable adapters (LoRA)	Grey vs bright pink
Retrieved passages (RAG)	Filled teal
Pass / fail / needs review (evals)	Green / red / amber, always with an icon
Untrusted or injected content	Red hatching

Once you learn the colours, later diagrams are much easier to read, because half the explanation is already done for you.

Colour never carries meaning on its own, though. There are icons, labels and transcripts too, and both light and dark themes aim for WCAG AA contrast.

Who is this for?

Software engineers and students who know some Python and school-level maths and want to really understand what's going on inside an LLM.
ML practitioners who want the maths and architecture details collected in one place.
Anyone building with LLMs (RAG apps, agents, MCP servers) who wants a mental model of the stack underneath.

Two goals I used to test the site:

After Module 7, you should be able to sketch a decoder block and estimate its parameter count to within 10%.

After Module 36, you should be able to sketch a RAG agent's harness and name where it can fail.

Under the hood (for the curious)

I deliberately kept the tech simple:

Plain JavaScript and static files, no build step. index.html is the shell, and each module is its own file (assets/m/m<id>.js) that loads lazily when you navigate to it.
A small reusable component library (core.js, kit.js): router, depth switch, ScrollyStage (sticky visual next to scrolling text), sliders, probability bars, matrix grids, line charts, quizzes, colour-linked math blocks, pipeline diagrams and agent traces.
KaTeX for the maths and Pyodide + NumPy for the runnable Python cells.
Plan-driven content. The whole course is written as a single build plan in Markdown. A Python script (scripts/build_data.py) parses it into the curriculum, tables and reading lists. If a module script fails to load, the page falls back to an outline generated from the plan.
Deployed on Vercel as a static site.

To run it locally:

git clone https://github.com/amananandrai/llm-explained
cd llm-explained
./scripts/dev.sh                    # wraps index.html into dev.html
python3 -m http.server 8765         # open http://localhost:8765/dev.html

Honest limits

In the same spirit as the "what this picture leaves out" boxes, here's what the site doesn't do yet:

It doesn't use real production tokenisers, recorded agent traces or live LLM calls. Widgets that would need those use in-browser computation (byte-level BPE, a real HNSW, numerical KL, a tiny real transformer block) or written examples with illustrative numbers, and the page labels them.
The model spec cards in Module 16 are transcribed from published configs. If you spot an error, please tell me!

Why I built it, and why I'm sharing it

Building this was the best way I've found to learn. You can't animate attention cell by cell, or write a widget that shows a KV cache growing, without understanding exactly what's happening. Every page exposed a gap in my own understanding that I then had to fill.

I'm sharing it because if it helped me, it may help you too. And sharing it means people will find my mistakes, which is how I keep learning.

🤝 Help make it better

This project gets better with every pair of eyes on it. Suggestions are always welcome, big or small. Here's how you can help:

⭐ Star the repo on GitHub. It helps more learners find it, and it makes my day.
🐛 Raise an issue for anything wrong, confusing or broken: open an issue.
🔧 Raise a PR to fix a typo, improve an explanation, add a widget or even a whole module: pull requests are welcome.
💡 Suggest a topic you want explained, right here in the comments.
🔁 Share it with a friend, classmate or teammate who's learning about LLMs.

Pick a module, flip the depth switch, play with a knob, and tell me which concept finally clicked for you. 👇

👉 llm-explained-lovat.vercel.app

I Built a Visual System Design Reference — Switch Any Architecture Between AWS, Azure, GCP & Open Source

amananandrai — Mon, 02 Nov 2026 20:40:43 +0000

I Built a Visual System Design Reference — Switch Any Architecture Between AWS, Azure, GCP & Open Source

🔗 Live site: system-design-explainer.vercel.app
⭐ GitHub: amananandrai/system-design-explainer

🧠 Why I Built This

Like a lot of developers, I've spent hours reading system design articles, watching interview prep videos, and staring at static diagrams trying to understand how YouTube actually handles an upload or how Uber matches a rider to a driver in real time.

The problem I kept running into:

Diagrams were static — you could see the boxes, but not how a request actually flows through them.
Every diagram was tied to one vendor's vocabulary. An AWS diagram says "S3, SQS, DynamoDB", a GCP one says "Cloud Storage, Pub/Sub, Bigtable" — and translating between them in your head is tiring.
My notes were scattered across bookmarks, Notion pages, and screenshots.

So I decided to build the reference I wished I had.

This started as a personal project to learn and grow. Building it forced me to actually understand each architecture well enough to draw it, break it into steps, and map every component across clouds. Somewhere along the way, I realised it could be just as useful for others preparing for interviews, designing real systems, or simply curious about how the apps they use every day work under the hood.

🚀 What Is System Design Explainer?

System Design Explainer is an interactive system design reference site where you can visualise architectures of real-world systems and view the same architecture through different tool lenses — a generic view, AWS, Google Cloud, Azure, or open-source tooling.

Every system page covers the requirements, APIs, capacity estimates, data model, request-flow walkthroughs, bottlenecks, scaling and extensions — all next to an auto-laid-out architecture diagram.

At the time of writing it has:

📦 36 systems
🧩 36 components
📚 27 concepts

✨ Key Features

☁️ 1. Switch Clouds in One Click

This is the feature I'm most excited about. Every architecture can be relabelled for:

Generic (vendor-neutral building blocks)
AWS
Google Cloud
Azure
Open source

So the same "object storage → queue → worker → CDN" flow instantly becomes the matching services for whichever stack you work with. Here's the YouTube design switching between all five:

Object storage becomes Amazon S3, Cloud Storage, Azure Blob Storage or MinIO; the event stream becomes Amazon MSK, Pub/Sub, Azure Event Hubs or Apache Kafka — same boxes, same arrows, different names. Great for interviews (where you're often asked to stay generic) and for real-world work (where you're usually tied to a specific cloud).

▶️ 2. Play Hop-by-Hop Walkthroughs

Instead of just looking at a diagram, you can follow a request step by step — upload a video, book a seat, pay a merchant, create a short link. Each step highlights what's happening and which component is responsible, so you build intuition for the flow, not just the layout.

Here's what uploading a video to YouTube looks like:

And booking movie seats on BookMyShow (watch the seat hold and the idempotency key do their thing):

Walkthroughs work on every cloud too, so you can follow the exact same request through AWS, GCP or Azure services.

🎬 More walkthroughs (click to expand)

Create a short link (URL shortener):

Charge a card (payment gateway):

Request a ride (Uber, on AWS):

Message an online friend (WhatsApp, on GCP):

Payment declined → saga compensation (Amazon, on Azure):

🔍 3. Inspect Components

Every building block (load balancers, caches, queues, databases, CDNs, etc.) has its own page covering:

The options available per provider
Common pitfalls
Which systems on the site use it

📖 4. Learn the Patterns

Core concepts like caching, sharding, fan-out, sagas, idempotency, consistent hashing, rate limiting, geospatial indexing, WebSockets, change data capture and more are explained on their own — and linked back to the real designs where they're applied. Many concept pages even come with a small diagram you can step through.

🔎 Bonus: Search & Dark Mode

Hit Ctrl K to jump to any system, component or concept, and switch to dark mode for late-night interview prep.

🗺️ Learning Paths

If you're not sure where to start, there are guided learning paths where each one builds on the patterns from the previous one. Your progress is saved in your browser.

Level	Path	Systems
🟢 Start here	Foundations	URL shortener → Pastebin → API rate limiter → Search autocomplete
🟡 Intermediate	Real-time systems	WhatsApp → WebSockets at scale → Live sports scores → Uber
🔴 Advanced	Media at scale	Instagram → Twitter / X → YouTube → Netflix
🔴 Advanced	Money & bookings	BookMyShow → Amazon → Payment gateway → Buy now, pay later

🏗️ Systems Covered

The catalogue is filterable by category, difficulty, and concept. Here's a snapshot:

Media & Social: YouTube, Netflix, Instagram, Twitter / X, WhatsApp, Quora, LinkedIn, Live sports scores
Mobility & Logistics: Uber, Google Maps, Zomato / food delivery, Porter, Car rental, Driver booking & fleet management
Commerce & Fintech: Amazon, Payment gateway, Buy now pay later, Stock brokerage
Bookings & Marketplaces: BookMyShow, MakeMyTrip, Airbnb, Airline reservations, NoBroker, Urban Company, Practo, AstroTalk, Meeting scheduler
Building Blocks: URL shortener, Pastebin, API rate limiter, Search autocomplete, Web crawler, Dropbox, WebSockets at scale, Video calling (WebRTC), Redis Cluster

I deliberately included a mix of global giants and systems that are popular in India (BookMyShow, Zomato, NoBroker, Practo, Urban Company…) because those come up a lot in interviews here and are rarely covered elsewhere.

🎯 Who Is This For?

👩‍💻 Interview preppers — practise explaining designs end-to-end and see how patterns repeat across systems.
🏢 Working engineers — map a design you know in one cloud to another cloud's services.
🎓 Students & beginners — start with the Foundations path and build up gradually.
🤔 The curious — ever wondered what happens when you hit "Book" on a movie seat? Now you can watch it happen.

🛠️ How It's Built

Next.js (static export) — the whole site is plain static files, deployed on Vercel
React Flow + ELK — auto-laid-out, zoomable architecture diagrams
Tailwind CSS — styling, including dark mode
Zod — every system is a typed content file validated against a schema, so adding a new design is mostly writing data, not UI code

📈 What I Learned Building It

Building this taught me far more than reading ever did:

You only really understand a system when you have to draw every hop. Gaps in my knowledge showed up immediately when I tried to write a walkthrough.
Clouds are more similar than they look. Once you map components across AWS, GCP, Azure and open source, the underlying patterns become obvious — the names are just different.
Patterns repeat everywhere. Idempotency shows up in payments, bookings, and ride matching. Fan-out shows up in Twitter, Instagram, and LinkedIn. Seeing this visually made it click.

This project is very much still growing — and so am I.

🤝 Get Involved

This is a learning project, and I'd love for it to become a community resource. If you found it useful:

⭐ Star the repo on GitHub — it really helps more people discover it: github.com/amananandrai/system-design-explainer
💡 Share suggestions — which system should I add next? Drop it in the comments!
🐛 Raise issues — spotted an inaccurate diagram, a wrong cloud mapping, or a bug? Please open an issue.
🔧 Raise PRs — contributions are very welcome, whether it's a new system, a better walkthrough, a component fix, or a UI improvement.

Want to add a system? Create a file in src/content/systems/, register it in systems/index.ts, follow the schema in src/types/schema.ts, and run npm run validate to check it. To run it locally:

git clone https://github.com/amananandrai/system-design-explainer.git
cd system-design-explainer
npm install
npm run dev   # http://localhost:3000

🙌 Wrapping Up

👉 Try it here: system-design-explainer.vercel.app
⭐ Star it here: github.com/amananandrai/system-design-explainer

I'd genuinely love to hear your feedback. Tell me in the comments which architecture you explored first — and which one you want to see next!

Happy designing! 🚀

I Built 101 Indian Monuments in the Browser Using Only Code (No 3D Models)

amananandrai — Fri, 30 Oct 2026 18:48:22 +0000

There isn't a single 3D model file on this site. Every one of these 101 monuments, from the Taj Mahal to a Himalayan monastery, is a small JavaScript function that builds the building out of boxes, cylinders and domes.

👉 Try it: monuments-of-india-nu.vercel.app ·
Code: github.com/amananandrai/monuments-of-india

The project in numbers

🏛️ 101 monuments across 26 states and union territories

📦 0 downloaded 3D models, 0 build steps, 0 npm dependencies for the site

🪶 ~2 KB of code per monument on average (the smallest is under 1 KB)

🎨 1 shader that paints stone, brick, marble and water on all of them

🌙 Day and night modes, with floodlights, festival lights and stars

Why I built it

Most people can find the Taj Mahal on a map. Far fewer could place Rani ki Vav, Ramappa or Key Monastery. I wanted a way to see how widely India's architecture is spread, and to explore each building from every angle instead of scrolling through photos.

So the site opens on a map of India, not a list. Every monument is a pin, coloured by kind: 51 temples and shrines, 25 tombs and memorials, 17 forts and palaces, and 8 civic and engineering works. Click one, and the map gives way to a 3D model you can spin, zoom and step through with the arrow keys.

Every monument also has its own link, so #taj-mahal opens the Taj directly.

How a monument is born, in five steps

Step 1: Snap together simple shapes 🧱

Think of LEGO. Instead of downloading a ready-made Qutub Minar, the code stacks simple pieces: a flat box for the base, five tapering cylinders for the storeys, a ring of balconies, and a small domed pavilion on top.

Two tricks make the shapes richer than plain LEGO:

Lathe works like a potter's wheel. Draw half the outline of a dome, spin it, and you get the whole dome. Every onion dome on the site comes from one shared outline.
Extrude works like a cookie cutter pushed through dough. Draw a flat shape, such as an arch or a star-shaped platform, and the code pushes it into a thick 3D slab.

Step 2: Crimp the edges ✨

The Qutub Minar's storeys aren't smooth tubes; they have ridges (flutes). To make them, the code walks around each cylinder and pushes the wall in and out in a wave, like crimping the edge of a pie crust. Change the wave and you get a different storey: rounded flutes at the bottom, star-shaped ones higher up.

Here's the heart of it, trimmed down:

// For every point on the tier's surface...
const a = Math.atan2(z, x);                      // how far around the tower are we?
const f = 1 + 0.07 * Math.abs(Math.cos(a * 12)); // push out in 12 waves
pos.setX(k, x * f);
pos.setZ(k, z * f);

Step 3: Reuse the small pieces 🔁

Indian architecture repeats its vocabulary: chhatris (small domed pavilions), minarets, kalash finials, shikhara spires and gopuram gateways appear again and again. These all live in one shared file, js/helpers.js, so a new monument mostly combines pieces that already exist.

This is why some monuments are tiny. The whole Somnath Temple, including the sea behind it and the arrow pillar on its sea wall, is under 1 KB, because a single helper call builds the entire temple:

nagaraTemple({ w: 14, h: 26, m: STONE, shade: SHADE, plinth: 3, urus: 8,
               halls: [[18, 9, 6], [16, 8, 5]] })

Step 4: Paint it with a "magic stone" shader 🎨

Plain shapes still look like plain shapes. What makes them read as stone is the surface shader in js/surface.js, and it's the single most important idea in the project.

The problem: normally, to put a pattern on a 3D shape you "unwrap" it, like cutting gift-wrap to fit each box by hand. Doing that for every piece of 101 buildings was never going to happen.

The solution: the pattern lives in space itself. Imagine carving each building out of one giant block of marble whose veins already run through it. Wherever you cut, the pattern is there and fits perfectly. So a one-metre block is exactly the same size on the Qutub Minar as on the walls of Agra Fort, no matter how either was built.

From that one idea, the shader draws:

Block joints, brick courses and marble veins. Each material is tagged with a kind (masonry, marble, brick, rock, jali screen, glazed tiles, carved frieze and more).
Fake bumps. It shades the joints and veins with light-and-shadow hints, the way an artist shades a pencil drawing, so flat walls look grooved.
Weathering. Darker grime near the ground and faint rain streaks down the walls, like a film crew aging a set.
A tiny random tint per piece, so a row of twenty identical columns doesn't look photocopied.
Moving water. Four layers of gentle, drifting ripples break up the sky's reflection, the way it looks on a real pond.

For the ten best-known monuments, the shader adds grain from real photographs (free CC0 textures from Poly Haven). Picture three projectors shining a photo of real marble onto the model from the front, the side and the top. The photo's own colour is removed and only its grain is kept, then tinted to the model's colour. The Taj stays white, the Red Fort stays red, and any other monument using the same stone gets the detail for free.

Step 5: Light it like a photograph ☀️

A sun with soft shadows and a sky light that gently fills the shaded side.
A reflection of the sky for gold, bronze and polished marble to shine with.
Ambient occlusion darkens corners and the undersides of roofs, where light struggles to reach, like dust settling in corners.
Tone mapping is the camera's exposure setting, so a bright sky doesn't turn pure white.
Night mode switches on floodlights and festival lights, adds a soft glow (bloom) around them, and fills the sky with stars.

None of these effects is special on its own. Stacked together, they stop your eye from reading the models as boxes.

Why code instead of 3D scans?

A 3D scan is like a photo of a cake: very detailed, but megabytes per monument, with licensing questions attached. A coded model is like the recipe: a couple of kilobytes, readable by anyone, and easy to change.

Each monument also gets a "library card" in js/data.js with its name, local-script name, coordinates, dates, style, material and the recipe that builds it:

{ id: 'taj-mahal', state: 'Uttar Pradesh', lat: 27.1751, lng: 78.0421,
  type: 'memorial', name: 'Taj Mahal', local: 'ताज महल',
  built: '1632–1653', style: 'Mughal', material: 'White Makrana marble',
  build: buildTaj }

Adding the 102nd monument means writing one module and one card. That's it.

The problems I didn't expect 🐛

1. Flickering walls. When two surfaces sit in exactly the same spot (a marble band flush with a wall, the stacked slices of a temple spire), the graphics card can't decide which one is in front, so they flicker as the camera moves, like two stickers fighting over the same place. js/coplanar.js finds every clash and nudges one surface a hair forward in depth. The shapes themselves don't change.

2. Buildings on square islands. Lawns and pavements are flat boxes, so every monument looked like it was sitting on a tile with hard edges. js/landscape.js fades their open edges into the land around them, and lets seas and long rivers run on to the horizon.

3. Hills that bent temples. Rocks, hills and trees start as rough low-poly blobs. js/naturalize.js rebuilds them in more detail and roughens them with noise, like squishing clay. The first catch: a temple sitting on a hilltop got warped along with the hill. The fix was to let hills only bulge outward, so their flat tops stay flat.

4. The ocean that shimmered. A sea made of a few giant triangles loses precision far from the camera and starts to shimmer. The water is now split into tiles, at most 60 a side.

5. Phones. Ambient occlusion and water reflections are skipped on phones to keep the frame rate smooth.

Small tools, no tooling

The whole site is index.html, one stylesheet and plain ES modules, with three.js loaded from a CDN through an import map. There's no build step, no bundler and no framework, so deploying is just pushing to main on Vercel.

Looking back, this is what kept the project moving. With no dependencies to update and no build to break, every hour went into the monuments themselves.

The map isn't a tile service either. India's outline and state borders come from Natural Earth's public-domain data, simplified into SVG paths. When you pick a monument, the camera behaves like a photographer stepping back until the whole building fits in the frame, then glides there in about a second.

10 favourites, and how they were built

Konark Sun Temple, Odisha. The temple is a stone chariot for the Sun god, and its 24 carved wheels work as sundials. The model rebuilds the chariot plinth on all 24 wheels from one shared wheel() helper.
Hawa Mahal, Jaipur. 953 small windows let the women of the court watch the street unseen. The latticed jali holes are cut by the shader rather than modelled, so the stone stays solid and the screens still cast the right shadows.
Rani ki Vav, Gujarat. A stepwell that descends seven levels. The ground is built as raised blocks so the trench can step down, landing by landing, to the well.
Lotus Temple, Delhi. Its 27 marble petals are built from a single curved petal() shape, repeated in three rings and rotated into place.
Meenakshi Temple, Madurai. Its gateway towers are covered in painted figures. Each gopuram uses a random seed, so every tower gets its own pattern of colours.
Qutub Minar, Delhi. Five storeys, four different kinds of flutes, all from the "pie-crust" trick above.
Statue of Unity, Gujarat. The world's tallest statue, built from smooth, rounded forms: the dhoti's folds, the shawl over the shoulders and half-closed hands.
Taj Mahal, Agra. Onion domes from the shared lathe outline, plus the charbagh garden and its reflecting pool.
Somnath Temple, Gujarat. The whole model is under 1 KB, thanks to the shared temple helper.
Ramappa Temple, Telangana. One of the few Indian temples named after its sculptor, with a tower built of bricks light enough to float.

See all 101 on the live map. There's also an 8½-minute film of every monument, five seconds each, rendered from the site's own models; the project is in the repo's video/ folder.

Try it, break it, add to it

🗺️ Explore: monuments-of-india-nu.vercel.app. Try finding Key Monastery on the map without searching.
⭐ Read the code: github.com/amananandrai/monuments-of-india. Run it locally with npx serve .
💬 Tell me in the comments: which monument should be #102?

These models are interpretations, not survey records. Anyone who has stood in front of the Kailasa Temple will see what they simplify. The goal is a sense of form, scale and place, and for that, code plus a good shader goes a long way.

Credits: three.js (MIT licence). Photo textures: CC0 from Poly Haven. Map data: Natural Earth, public domain. This article was drafted with AI assistance from the project's source.

From Code to Culture: Building 101 Indian Monuments in 3D

amananandrai — Wed, 28 Oct 2026 00:39:09 +0000

101 Indian Monuments, Modelled in the Browser

India's heritage has always fascinated me. From intricately carved temple walls and majestic forts to elegant palaces, ancient stepwells and modern architectural landmarks, every monument has a story to tell. These structures are more than stone, brick and marble — they reflect the creativity, engineering skills, beliefs and cultural diversity of the people who built them. Together, they tell the story of a civilisation that has evolved over thousands of years while preserving its unique identity.

As a developer, I wanted to find a way to bring this heritage a little closer to people through something I love building: technology. That idea became Monuments of India, a website where I modelled 101 Indian monuments directly in the browser. My goal was not simply to create another collection of historical photographs, but to build an interactive experience that allows people to explore these architectural landmarks, appreciate their forms and discover places they might not have encountered before.

One of the things I wanted to capture was the sheer diversity of Indian architecture. A temple in Tamil Nadu, a Mughal monument in Agra, a stepwell in Gujarat and a Buddhist monastery in the Himalayas can look worlds apart, yet each represents an important part of India's cultural story. I wanted visitors to experience this diversity visually — to explore monuments across different states, understand where they are located and get a sense of their distinctive architectural character.

That vision shaped the experience itself. Instead of presenting 101 monuments as a long, static list, I built an interactive map of India as the starting point. Visitors can explore landmarks geographically, select a monument and move into a 3D view where they can rotate, zoom in and examine its structure from different angles. Each model is paired with historical context, helping connect the visual experience with the story behind the architecture.

The interesting part for me was figuring out how to build all of this as a developer. Rather than relying on pre-made 3D models or downloaded architectural assets, I chose to construct the monuments programmatically using code. This turned the project into both a creative exercise and a technical challenge: translating real-world architecture into 3D geometry, reproducing distinctive shapes and materials, and making the experience interactive without making the website unnecessarily heavy.

In this article, I'll walk through how I built the project, the technologies and rendering techniques behind it, and some of the engineering decisions that made it possible to model 101 different monuments in the browser. From generating architectural structures with Three.js primitives to creating procedural surface details, lighting, textures and an interactive map, I'll explore how ordinary web technologies can be used to create something that brings history, design and programming together.

For me, this project is a small contribution to celebrating India's rich cultural and architectural heritage through technology. It's also a reminder that code can be more than a way to build applications — it can be a medium for exploring history, communicating ideas and making our shared heritage accessible in new ways. So, let's look at how these 101 monuments came to life in the browser.

Monuments of India opens on a map of the country, not a list of files. Its 101 landmarks are pins on India's outline, coloured by kind: temples and shrines, forts and palaces, tombs and memorials, and civic and engineering works. Where several places would land on the same spot, they fold into a numbered cluster, and choosing it zooms in until the pins separate. Beside the map is a list grouped by state that narrows as you type. Pick a place and the map gives way to a 3D model you can orbit, zoom and step through with the arrow keys. Each monument also has its own address, such as #taj-mahal, so a link can open a model directly. Opening on the map was the most important design choice. Most people know the Taj Mahal is in Agra, but fewer could place Rani ki Vav, Ramappa or Key Monastery. Seeing them on the map shows how widely India's architecture is spread before you open a single model. The site is at monuments-of-india-nu.vercel.app.

Nothing in the viewer is a downloaded mesh, and the site has no build step. Each landmark is a module in js/monuments/ that builds the structure in code from three.js primitives (boxes, cylinders, spheres, lathed profiles and extruded shapes) at roughly real-world proportions. The Qutub Minar's fluting, for example, comes from pushing each tier's vertices outward with a cosine of the angle around the tower. js/helpers.js holds the shared materials (marble, red sandstone, granite, gold and several kinds of water) and the small pieces the monuments reuse, such as chhatris and rings. js/data.js is the catalogue: name, place, coordinates, dates, style, material and the function that builds each model. three.js 0.160 loads from a CDN through an import map. Apart from that there is just index.html, one stylesheet and the modules, served as static files on Vercel. The trade-off is deliberate. A photogrammetry scan would be more exact, but it would weigh megabytes per monument and come with licensing questions. A model written in code is a few kilobytes, can be read and changed like any other code, and makes adding the hundred-and-second monument as easy as adding the second. The pictures below are frames from this viewer. They are models, not photographs.

Plain boxes would still look like boxes without the surface shader in js/surface.js. Each material is tagged as masonry, marble, brick, rock, ground, lattice, glazed tile, foliage or water. The fragment shader draws the pattern from the surface's position in the world, not from UVs painted onto each mesh, so a one-metre block is the same size on the Qutub Minar as on a wall of Agra Fort, however that mesh was built. I think this is the most important rendering decision in the project. With 101 models built by hand from primitives, nobody is going to unwrap UVs for each one, and world-space patterns make the problem disappear. Joints, veins, brick courses and lattice holes all come from that pattern, and the same pattern tilts the surface normal to create a bump. Grime collects near the ground, faint streaks run down the walls like rain, and a small tint that changes from piece to piece stops a row of identical columns from looking like copies. Water is handled separately: four layers of drifting noise raise and tilt the normal, so the sky reflects in a broken, moving band instead of a flat sheen.

Ten of the best-known monuments also get grain from real photographs. CC0 textures from Poly Haven (marble, red sandstone, sandstone blocks, two plasters, granite and rock) are projected from three directions (triplanar mapping) in the same shader. Each is divided by its average colour and then tinted back to the model's own colour. The Taj stays Makrana white and the Red Fort stays red, and the photograph only adds grain. Any other monument that uses those materials gets the detail for free. Rocks, hills, mountains and trees start as flat, low-poly placeholders. js/naturalize.js rebuilds them at higher resolution, smooths their shading, and displaces them with noise suited to each object: lumpy boulders, leafy canopies, tiered conifers, ridged mountains with snow on the high peaks, and hills that only bulge outward so a temple on a flat summit isn't warped. Statues are built from smooth rounded forms rather than blocks. For lighting, the frame uses ACES filmic tone mapping, a sun with soft shadows and a hemisphere fill. An environment map rendered from the same sky and ground gives gold, bronze and polished marble something to reflect. In a desktop-width window, an ambient occlusion pass (GTAO) darkens corners and the undersides of eaves. Its radius scales with the model, because a small kiosk and a bridge of about 700 metres need different reaches. Switching to dark mode changes the sky and ground and turns on a bloom pass for the lamps. None of these effects is unusual on its own. What makes them work is that they are layered, so the eye stops reading the models as primitives.

The map isn't a tile service either. State boundaries and the national outline come from Natural Earth's public-domain data, using its India point of view, simplified into SVG paths in js/india-map.js. One canvas fills the stage. When you change monuments, the camera fits itself to the model's bounding box along a fixed view direction and eases there in about a second. Faces that share a plane, which would otherwise flicker, get a slight depth offset. Deploying is just pushing to main. Looking back, the absence of tooling is what kept the project moving. There are no dependencies to update, no build to break and no framework to outgrow, so every change was about the monuments themselves. The models are still interpretations, and anyone who has stood in front of the Kailasa Temple will see what they simplify. The goal is a sense of form, scale and place, not a survey record, and for that, code plus a good shader goes a long way. Below the two views of the site, each of the 101 models is shown as the page draws it, with the short history that appears on its plaque.

A few other posts on DEV are in the same neighborhood. Alicia Lu wrote How I Built a WebGPU 3D Garden with Houdini and Three.js. Jonas Javier wrote How I drew a 4D tesseract in Three.js. lavitra wrote Three.js Explained: What You're Actually Building With Scene, Camera, and Mesh.

The home view. Numbered pins are clusters; the list on the left is grouped by state.

Opening a monument replaces the map with the model. The plaque carries the place, the date, the material and the history.

The 101 monuments

1. Qutub Minar

Mehrauli, Delhi · 1199–1220 · Indo-Islamic

Begun by Qutb ud-Din Aibak and completed by his successor Iltutmish; Firoz Shah Tughlaq later rebuilt the top storeys. Its five storeys taper from a 14.3 m base to 2.7 m at the top, each ringed by a projecting balcony. The Qutb complex has been a UNESCO World Heritage Site since 1993.

2. Gateway of India

Apollo Bunder, Mumbai · 1913–1924 · Indo-Saracenic

Built to commemorate the 1911 landing of King George V and Queen Mary in Bombay. Designed by the Scottish architect George Wittet, facing the Arabian Sea. The last British troops left India through its arch in February 1948.

3. Taj Mahal

Agra, Uttar Pradesh · 1632–1653 · Mughal

Commissioned by Shah Jahan as a tomb for his wife Mumtaz Mahal. The four minarets lean slightly outward, so in an earthquake they would fall away from the tomb. A UNESCO World Heritage Site since 1983.

4. Charminar

Hyderabad, Telangana · 1591 · Qutb Shahi

Built by Muhammad Quli Qutb Shah, the founder of Hyderabad. Each of its four sides opens in a grand arch onto a street of the old city. A small mosque occupies the western side of the top floor.

5. Ram Mandir

Ayodhya, Uttar Pradesh · 2020–2024 · Nagara

Consecrated on 22 January 2024. Designed by the Sompura family, temple architects for generations. The main structure was built without iron or steel.

6. Brihadeeswara Temple

Thanjavur, Tamil Nadu · 1003–1010 CE · Dravidian (Chola)

Built by the Chola emperor Rajaraja I. The vimana rises in 13 tiers and is crowned by a capstone estimated at 80 tonnes. Part of the Great Living Chola Temples, a UNESCO site since 1987.

7. India Gate

Kartavya Path, New Delhi · 1921–1931 · Memorial arch

Designed by Edwin Lutyens as the All India War Memorial. It honours soldiers of the British Indian Army who died between 1914 and 1921. More than 13,000 names are inscribed on its surfaces.

8. Statue of Unity

Ekta Nagar, Gujarat · 2013–2018 · Monumental statue

Depicts Sardar Vallabhbhai Patel, India’s first Deputy Prime Minister. The world’s tallest statue, unveiled on 31 October 2018. Designed by the sculptor Ram V. Sutar, it faces the Sardar Sarovar Dam on the Narmada.

9. Howrah Bridge

Kolkata, West Bengal · 1936–1943 · Cantilever truss

Its 457 m main span crosses the Hooghly with no pier in the river between the two towers. Built with 26,500 tonnes of steel, 23,500 of them high-tensile steel from Tata Steel. Renamed Rabindra Setu in 1965 after Rabindranath Tagore.

10. Jagannath Puri Temple

Puri, Odisha · 12th century · Kalinga

Built by King Anantavarman Chodaganga Deva of the Eastern Ganga dynasty. The flag on its summit is changed every day by a priest who climbs the tower. Each year the Rath Yatra carries the deities through Puri on giant wooden chariots.

11. Golden Temple

Amritsar, Punjab · 1581–1604 · Sikh

Founded by Guru Arjan, the fifth Sikh Guru, who installed the Adi Granth here in 1604. Its upper storeys were covered in gilded copper under Maharaja Ranjit Singh in the early 19th century. The shrine stands in the Amrit Sarovar pool, reached by a single causeway; its langar serves free meals to tens of thousands of people every day.

12. Hawa Mahal

Jaipur, Rajasthan · 1799 · Rajput

Built by Maharaja Sawai Pratap Singh and designed by Lal Chand Ustad. Its 953 small latticed windows (jharokhas) let the women of the court watch street life unseen. The five-storey façade is barely one room deep; breezes through the screens gave it the name “Palace of Winds”.

13. Konark Sun Temple

Konark, Odisha · c. 1250 CE · Kalinga

Built by King Narasimhadeva I of the Eastern Ganga dynasty as a giant stone chariot for Surya, the Sun god. Its 24 carved wheels work as sundials: the shadows of the spokes tell the time of day. The main tower collapsed centuries ago; what stands is its porch. A UNESCO World Heritage Site since 1984.

14. Meenakshi Temple

Madurai, Tamil Nadu · 16th–17th c. · Dravidian (Nayak)

Dedicated to Meenakshi, a form of Parvati, and her consort Sundareswarar, a form of Shiva. Its 14 gopurams are covered in thousands of painted stucco figures of gods, animals and demons. The tallest, the southern gopuram, rises about 52 m above the old city.

15. Lotus Temple

Kalkaji, New Delhi · 1980–1986 · Expressionist

A Baháʼí House of Worship, open to people of every faith. Its 27 free-standing marble-clad petals are arranged in clusters of three to form nine sides. Designed by the Iranian-born architect Fariborz Sahba and surrounded by nine pools.

16. Gol Gumbaz

Vijayapura, Karnataka · 1626–1656 · Deccan (Adil Shahi)

The mausoleum of Muhammad Adil Shah of the Bijapur Sultanate. Its dome, about 44 m across, is one of the largest ever built without internal supports. In the whispering gallery around the inside of the dome, a faint sound echoes several times.

17. Mysore Palace

Mysuru, Karnataka · 1897–1912 · Indo-Saracenic

Seat of the Wadiyar dynasty; it replaced an older wooden palace that burned down in 1897. Designed by the British architect Henry Irwin. On festival nights, and through Dasara, it is lit with nearly 100,000 bulbs.

18. Sanchi Stupa

Sanchi, Madhya Pradesh · 3rd c. BCE · Buddhist (Mauryan)

Commissioned by the emperor Ashoka over relics of the Buddha. Its four gateways (toranas), added in the 1st century BCE, are carved with scenes from the Buddha’s life and the Jataka tales. A UNESCO World Heritage Site since 1989.

19. Mahabodhi Temple

Bodh Gaya, Bihar · 5th–6th c. CE · Gupta-era brick

Marks the place where Siddhartha Gautama attained enlightenment under the Bodhi tree. Ashoka built the first shrine here; the present brick temple dates from the Gupta period. One of the oldest brick temples still standing in India, and a UNESCO site since 2002.

20. Red Fort

Old Delhi · 1639–1648 · Mughal

Built by Shah Jahan as the palace-fortress of his new capital, Shahjahanabad. Every Independence Day the Prime Minister raises the national flag here and addresses the nation. Its walls run about 2.5 km; a UNESCO World Heritage Site since 2007.

21. Old Parliament House

Sansad Marg, New Delhi · 1921–1927 · Lutyens’ Delhi

Designed by Edwin Lutyens and Herbert Baker, and opened in 1927. The Constituent Assembly met in its domed Central Hall to frame the Constitution of India. 144 sandstone columns ring its verandah; it was renamed Samvidhan Sadan in 2023.

22. Rashtrapati Bhavan

Raisina Hill, New Delhi · 1912–1929 · Lutyens’ Delhi

The official residence of the President of India, designed by Edwin Lutyens. It has 340 rooms on four floors. Its great dome blends a classical form with the shape of the Buddhist stupa at Sanchi.

23. Humayun’s Tomb

Nizamuddin, New Delhi · 1565–1572 · Mughal

Commissioned by Humayun’s widow, Empress Bega Begum, and designed by Mirak Mirza Ghiyas. The first garden-tomb on the Indian subcontinent, and a model for the Taj Mahal. A UNESCO World Heritage Site since 1993.

24. Jama Masjid

Chandni Chowk, Old Delhi · 1650–1656 · Mughal

Built by Shah Jahan, facing the Red Fort across the old city. Its courtyard can hold about 25,000 worshippers. Three marble domes striped in black crown the prayer hall, flanked by two tall minarets.

25. New Parliament House

Sansad Marg, New Delhi · 2020–2023 · Contemporary

Inaugurated on 28 May 2023, beside the 1927 building it replaced. Its triangular plan was designed by the architect Bimal Patel. A 6.5 m bronze National Emblem crowns the roof above the central Constitution Hall.

26. Dilwara Temples

Mount Abu, Rajasthan · 11th–13th c. · Jain (Maru-Gurjara)

The oldest, Vimal Vasahi, was built in 1031 by Vimal Shah, a minister of the Chaulukya king. The marble is carved so finely it looks translucent; the domed ceilings hang down in lotus pendants. A plain outer wall hides the temples and the rows of shrine cells around their courtyards.

27. Swaminarayan Akshardham

New Delhi · 2000–2005 · Maru-Gurjara

Opened in November 2005 by the BAPS Swaminarayan Sanstha. The main monument has 234 carved pillars, nine domes and more than 20,000 sculpted figures. It rests on the Gajendra Pith, a plinth carved with 148 life-size elephants.

28. Kandariya Mahadeva Temple

Khajuraho, Madhya Pradesh · c. 1030 CE · Nagara (Chandela)

The largest temple at Khajuraho, built under the Chandela dynasty. Its tower is wrapped in 84 smaller spires that rise like the peaks of Mount Kailash. Over 800 sculptures cover its walls; Khajuraho has been a UNESCO site since 1986.

29. Ranakpur Jain Temple

Ranakpur, Rajasthan · 15th century · Jain (Maru-Gurjara)

Built by the merchant Dharna Shah from 1437 and dedicated to Adinatha. Its 1,444 carved marble pillars are said to be all different. A four-faced (chaturmukha) temple, open on all four sides.

30. Chennakesava Temple

Somanathapura, Karnataka · 1258 · Hoysala

Built by Somanatha, a commander of the Hoysala king Narasimha III. Three star-shaped shrines stand on a raised, star-shaped platform. Friezes of elephants, horsemen and epic scenes run round its base; a UNESCO site since 2023.

31. Victoria Memorial

Maidan, Kolkata · 1906–1921 · Indo-Saracenic

Built in memory of Queen Victoria and designed by William Emerson. It is clad in white Makrana marble, the same stone as the Taj Mahal. A bronze Angel of Victory, about 4.9 m tall, turns with the wind on top of the dome.

32. Chhatrapati Shivaji Maharaj Terminus

Fort, Mumbai · 1878–1888 · Victorian Gothic

Designed by Frederick William Stevens and opened as Victoria Terminus in 1887, the year of Queen Victoria’s Golden Jubilee. It blends Victorian Gothic Revival with traditional Indian architecture. A statue representing Progress stands on the central dome; a UNESCO World Heritage Site since 2004.

33. Kailasa Temple, Ellora

Ellora, Maharashtra · 8th century · Dravidian (Rashtrakuta)

Carved out of a single basalt cliff under the Rashtrakuta king Krishna I. Sculptors cut downward from the top, removing an estimated 200,000 tonnes of rock. It is Cave 16 of the Ellora Caves, a UNESCO World Heritage Site since 1983.

34. Vittala Temple, Hampi

Hampi, Karnataka · 15th–16th c. · Vijayanagara

Built in Vijayanagara, the capital of the Vijayanagara Empire, among Hampi’s granite boulders. The stone chariot in its courtyard is a shrine to Garuda, carved to look like a temple car. The main hall’s 56 pillars ring with musical notes when tapped; Hampi is a UNESCO site since 1986.

35. Padmanabhaswamy Temple

Thiruvananthapuram, Kerala · 16th–18th c. · Dravidian and Kerala

Dedicated to Vishnu as Padmanabha, reclining on the serpent Anantha. Its seven-tier eastern gopuram rises over the Padma Theertham tank. A long corridor of carved granite pillars runs round the inner shrine.

36. Basilica of Bom Jesus

Old Goa, Goa · 1594–1605 · Baroque

Completed by the Jesuits in 1605, it holds the remains of St Francis Xavier. Its lime plaster was stripped away in the 20th century, exposing the red laterite stone. Part of the Churches and Convents of Goa, a UNESCO World Heritage Site since 1986.

37. Kamakhya Temple

Nilachal Hill, Guwahati · Rebuilt 1565 · Nilachal

One of the most revered Shakti peethas, on Nilachal Hill above the Brahmaputra. Rebuilt in 1565 under the Koch dynasty, with the beehive-shaped dome of the Nilachal style. Each June the Ambubachi Mela draws pilgrims from across India.

38. Tawang Monastery

Tawang, Arunachal Pradesh · 1680–1681 · Tibetan Buddhist

Founded by Merak Lama Lodre Gyatso at the wish of the 5th Dalai Lama. The largest Buddhist monastery in India, on a ridge about 3,000 m up. Its three-storey assembly hall houses a gilded statue of the Buddha about 8 m tall.

39. Amber Fort

Amer, Jaipur · 16th–18th c. · Rajput and Mughal

Begun in 1592 by Raja Man Singh I, a general of the Mughal emperor Akbar. Its Sheesh Mahal, the mirror palace, is lined with thousands of tiny mirrors. One of the Hill Forts of Rajasthan, a UNESCO World Heritage Site since 2013.

40. Rani ki Vav

Patan, Gujarat · 11th century · Maru-Gurjara

A stepwell built in memory of the Chaulukya king Bhima I, traditionally by his queen Udayamati. It descends seven levels and holds more than 500 principal sculptures, many of Vishnu’s avatars. A UNESCO World Heritage Site since 2014; it appears on the ₹100 note.

41. Ramappa Temple

Palampet, Telangana · 1213 CE · Kakatiya

Built in 1213 by Recherla Rudra, a general of the Kakatiya king Ganapati Deva. It is named after its chief sculptor, Ramappa, which is rare for an Indian temple. Its tower is built of bricks light enough to float on water; a UNESCO World Heritage Site since 2021.

42. Kedarnath Temple

Kedarnath, Uttarakhand · 8th c. (by tradition) · Himalayan Nagara

One of the twelve Jyotirlingas of Shiva, high in the Garhwal Himalaya. Built of large grey stone slabs; tradition links its revival to Adi Shankaracharya. In the 2013 floods a huge boulder lodged behind it and shielded the temple.

43. Hazratbal Shrine

Srinagar, Jammu and Kashmir · 1968–1979 · Mughal-inspired

It stands on the north-western shore of Dal Lake in Srinagar. It houses the Moi-e-Muqqadas, a relic believed to be a hair of the Prophet Muhammad. The present white marble shrine, completed in 1979, is known as the only domed mosque in Srinagar.

44. Shore Temple

Mahabalipuram, Tamil Nadu · c. 700–728 CE · Dravidian (Pallava)

Built by the Pallava king Narasimhavarman II (Rajasimha) beside the Bay of Bengal. One of the oldest structural stone temples in South India: two Shiva shrines and one to Vishnu. Part of the Group of Monuments at Mahabalipuram, a UNESCO World Heritage Site since 1984.

45. Gwalior Fort

Gwalior, Madhya Pradesh · 8th–16th c. · Rajput (Tomar)

Raja Man Singh Tomar built the Man Mandir palace on the fort between 1486 and 1516. Its walls are decorated with blue, green and yellow tiles of ducks, elephants and banana trees. The fort crowns a sandstone hill above Gwalior; Babur is said to have called it the pearl among India’s forts.

46. Nalanda Mahavihara

Nalanda, Bihar · 5th–12th c. · Gupta and Pala brick

Founded in the 5th century CE under the Gupta kings, it was one of the world’s first residential universities. Scholars came from China, Korea, Tibet and Central Asia; the pilgrim Xuanzang studied here. Its brick ruins include the stepped Sariputta Stupa; a UNESCO World Heritage Site since 2016.

47. Tirumala Venkateswara Temple

Tirumala, Andhra Pradesh · Expanded 9th–16th c. · Dravidian

Dedicated to Venkateswara, a form of Vishnu, on the Tirumala hills. The vimana over the sanctum, called Ananda Nilayam, is covered in gold. It is one of the most visited places of worship in the world.

48. Capitol Complex, Chandigarh

Sector 1, Chandigarh · 1951–1965 · Modernist

Designed by Le Corbusier as the seat of government for Chandigarh, the new capital of Punjab. Its Palace of Assembly, Secretariat and High Court face each other across a vast concrete plaza. The Open Hand Monument turns in the wind; the complex became a UNESCO World Heritage Site in 2016.

49. Hidimba Devi Temple

Manali, Himachal Pradesh · 1553 · Himalayan pagoda

Built in 1553 by Maharaja Bahadur Singh over a cave shrine to Hidimba Devi. Its three square roofs of wooden shingles are crowned by a brass cone. It stands in the Dhungiri forest of tall deodar cedars above Manali.

50. Bandra–Worli Sea Link

Mumbai, Maharashtra · 2000–2009 · Cable-stayed bridge

Opened in 2009, it links Bandra and Worli across Mahim Bay. Its cable-stayed main span hangs from pylons about 128 m tall. Officially the Rajiv Gandhi Sea Link, it carries eight lanes of traffic.

51. Buland Darwaza

Fatehpur Sikri, Uttar Pradesh · c. 1575–1601 · Mughal

Akbar built it as the great southern gateway to the Jama Masjid of Fatehpur Sikri. Including its broad flight of steps, it rises about 54 m above the ground. An inscription on it quotes a saying of Jesus: the world is a bridge, so pass over it. Fatehpur Sikri is a UNESCO site since 1986.

52. Panch Mahal

Fatehpur Sikri, Uttar Pradesh · 1570s · Mughal

A five-storey open pavilion in Akbar’s palace at Fatehpur Sikri, built to catch the breeze. Each storey is smaller than the one below, rising to a single domed kiosk on top. It stands on 176 carved columns; stone screens once enclosed its open sides.

53. Bara Imambara

Lucknow, Uttar Pradesh · 1784–1791 · Nawabi (Awadhi)

Built by Nawab Asaf-ud-Daula, partly as a relief project during the famine of 1784. Its vaulted central hall is one of the largest arched halls in the world built without beams. Above it lies the Bhool Bhulaiya, a maze of narrow passages; the Asfi Mosque stands beside it.

54. Rumi Darwaza

Lucknow, Uttar Pradesh · 1784 · Nawabi (Awadhi)

Built by Nawab Asaf-ud-Daula beside the Bara Imambara. Often called the Turkish Gate, it is said to be modelled on the Sublime Porte in Istanbul. A flared, flower-like crown rises above its arch, topped by an eight-sided kiosk.

55. Chota Imambara

Lucknow, Uttar Pradesh · 1837–1838 · Nawabi (Awadhi)

Built by Nawab Muhammad Ali Shah as his own mausoleum and a hall for Muharram gatherings. It is famed for its chandeliers and gilt mirrors; black Quranic calligraphy runs along its white facade. Two small replicas of the Taj Mahal stand in its garden.

56. Itmad-ud-Daulah’s Tomb

Agra, Uttar Pradesh · 1622–1628 · Mughal

Built by the empress Nur Jahan for her father, Mirza Ghiyas Beg. The first Mughal tomb faced entirely in white marble, it is often called the Baby Taj. Its walls are inlaid with coloured stone in the pietra dura technique, later used at the Taj Mahal.

57. Akbar’s Tomb

Sikandra, Agra · 1605–1613 · Mughal

Akbar began his own tomb; his son Jahangir completed it in 1613. Its five storeys rise in tiers of kiosks to a white marble terrace open to the sky. The southern gateway carries four white marble minarets, the first on a Mughal gateway.

58. Agra Fort

Agra, Uttar Pradesh · 1565–1573 · Mughal

Akbar rebuilt the fort in red sandstone between 1565 and 1573. Shah Jahan added white marble palaces and spent his last years confined here, within sight of the Taj Mahal. A UNESCO World Heritage Site since 1983.

59. Bibi Ka Maqbara

Chhatrapati Sambhajinagar, Maharashtra · 1660s · Mughal

Built by Prince Azam Shah in memory of his mother, Dilras Banu Begum, wife of Aurangzeb. Modelled on the Taj Mahal, it is known as the Taj of the Deccan. Only the dome is marble; most of the rest is basalt finished with fine lime plaster.

60. Safdarjung’s Tomb

Lodhi Road, New Delhi · 1754 · Late Mughal

Built in 1754 by Nawab Shuja-ud-Daula for his father Safdarjung, prime minister of the Mughal empire. It is often called the last great garden tomb of the Mughals. It stands in a walled charbagh garden with water channels and corner pavilions.

61. Somnath Temple

Prabhas Patan, Gujarat · Rebuilt 1951 · Maru-Gurjara (Chalukya)

Revered as the first of the twelve Jyotirlingas, on the Arabian Sea coast. Destroyed and rebuilt many times; the present temple was completed in 1951. An arrow pillar on its sea wall marks that no land lies in a straight line between it and the South Pole.

62. Mallikarjuna Temple

Srisailam, Andhra Pradesh · Expanded 14th–16th c. · Dravidian

On Srisailam hill in the Nallamala forest, above the Krishna river. It is both a Jyotirlinga and a Shakti Peetha, with the shrine of the goddess Bhramaramba. Its high outer walls are carved with friezes; its gopurams were raised under Vijayanagara rulers.

63. Mahakaleshwar Temple

Ujjain, Madhya Pradesh · Rebuilt 18th c. · Bhumija and Maratha

Beside the Shipra river in Ujjain; its lingam is the only Jyotirlinga that faces south. Its Bhasma Aarti, offered with sacred ash before dawn each day, is famous. The temple has three levels; the Nagchandreshwar shrine on top opens only on Nag Panchami.

64. Omkareshwar Temple

Mandhata island, Madhya Pradesh · Rebuilt 18th c. · Nagara

On Mandhata island in the Narmada, which is said to be shaped like the sacred syllable Om. Pilgrims reach the island by bridge or boat and bathe at its ghats. Mamleshwar, across the river, is worshipped together with it as one Jyotirlinga.

65. Bhimashankar Temple

Sahyadri hills, Maharashtra · 13th–18th c. · Nagara

In the forested Sahyadri hills, at the source of the Bhima river. Its stone temple combines older Nagara work with an 18th-century hall added by Nana Phadnavis. The forest around it is a wildlife sanctuary, home of the Indian giant squirrel.

66. Kashi Vishwanath Temple

Varanasi, Uttar Pradesh · 1780 · Nagara

The present temple was built in 1780 by the Maratha queen Ahilyabai Holkar. Maharaja Ranjit Singh had its spire and dome covered in gold in 1835. The Kashi Vishwanath Corridor, opened in 2021, links it directly to the ghats of the Ganga.

67. Trimbakeshwar Temple

Trimbak, Nashik · 1755–1786 · Nagara

Built in black basalt by the Peshwa Balaji Bajirao between 1755 and 1786. Its lingam has three faces, for Brahma, Vishnu and Shiva. It stands below the Brahmagiri hills, where the Godavari river rises.

68. Baidyanath Temple

Deoghar, Jharkhand · 16th c. (present form) · Nagara

The Baba Baidyanath Dham complex in Deoghar has 22 temples; it is also a Shakti Peetha. Its spire is crowned by a panchashula, a five-pointed trident, instead of the usual trishula. In the month of Shravan, pilgrims walk over 100 km carrying Ganga water to offer here.

69. Nageshwar Temple

Dwarka, Gujarat · Rebuilt 1990s · Nagara

On the road between Dwarka and Beyt Dwarka on the Saurashtra coast. A 25 m statue of a seated Shiva rises in the temple garden. Nageshwar means lord of serpents; devotees pray here for protection from poisons.

70. Ramanathaswamy Temple

Rameswaram, Tamil Nadu · 12th–17th c. · Dravidian

On Rameswaram island; tradition says Rama worshipped Shiva here before crossing to Lanka. Its pillared corridors, about 1.2 km in all, are the longest of any Hindu temple. Pilgrims bathe in 22 sacred wells (theerthams) inside the temple.

71. Grishneshwar Temple

Verul, near Ellora · 18th century · Nagara (Maratha)

Near the Ellora Caves; it is counted as the last of the twelve Jyotirlingas. It was rebuilt in red basalt in the 18th century by Ahilyabai Holkar. Its five-tiered spire and walls are carved with the ten avatars of Vishnu and other figures.

72. Dhamek Stupa

Sarnath, Uttar Pradesh · c. 500 CE · Gupta

It marks the deer park where the Buddha gave his first sermon after his enlightenment. Built around 500 CE over an older stupa from Ashoka’s time, it is about 43.6 m high and 28 m across. Its lower stone drum is carved with bands of flowers and geometric patterns.

73. Ajanta Caves

Ajanta, Maharashtra · 2nd c. BCE–c. 480 CE · Rock-cut Buddhist

Thirty Buddhist caves cut into a horseshoe-shaped cliff above the Waghora river. Their murals are among the finest surviving paintings of ancient India. Rediscovered by a British hunting party in 1819; a UNESCO World Heritage Site since 1983.

74. Rumtek Monastery

Near Gangtok, Sikkim · 1960s · Tibetan Buddhist

The seat in exile of the Karmapa, head of the Karma Kagyu school of Tibetan Buddhism. The 16th Karmapa rebuilt it in the 1960s, modelled on Tsurphu Monastery in Tibet. It looks out across the valley towards Gangtok.

75. Thiksey Monastery

Near Leh, Ladakh · 15th century · Tibetan Buddhist (Gelug)

A twelve-storey Gelug monastery on a hill above the Indus, often compared to the Potala Palace in Lhasa. Its Maitreya temple holds a statue of the future Buddha about 15 m tall, installed in 1970. It is one of the largest monasteries in Ladakh.

76. Key Monastery

Spiti Valley, Himachal Pradesh · Founded c. 11th c. · Tibetan Buddhist

The largest monastery in the Spiti Valley, founded about a thousand years ago. It sits on a conical hill above the Spiti river at about 4,166 m. Rebuilt many times after raids, its buildings are piled up the hill like a fortress.

77. Gommateshwara Statue

Shravanabelagola, Karnataka · c. 983 CE · Monolithic statue

A 17.4 m statue of the Jain saint Bahubali, carved from a single block of granite. It was commissioned by Chavundaraya, a minister of the Western Ganga dynasty. Every 12 years the Mahamastakabhisheka festival bathes it in milk, saffron and flowers.

78. Palitana Temples

Shatrunjaya hill, Gujarat · 11th–20th c. · Maru-Gurjara

More than 800 Jain temples crown Shatrunjaya hill above the town of Palitana. Pilgrims climb more than 3,000 stone steps to reach them. Built over some 900 years, it is one of the holiest Jain pilgrimage sites.

79. Shikharji

Parasnath Hill, Jharkhand · 18th c. onward · Jain

On Parasnath Hill, the highest point in Jharkhand. Jain tradition holds that 20 of the 24 Tirthankaras attained liberation (moksha) here. A shrine (tonk) for each of them stands along the ridge, on a pilgrim circuit of about 27 km.

80. Parshvanath Temple, Khajuraho

Khajuraho, Madhya Pradesh · c. 950–970 CE · Nagara (Chandela)

The largest Jain temple at Khajuraho, built under the Chandela kings. Its walls carry some of Khajuraho’s finest sculpture, in bands round the shrine. Part of the Khajuraho Group of Monuments, a UNESCO World Heritage Site since 1986.

81. Soniji Ki Nasiyan

Ajmer, Rajasthan · 1864–1895 · Jain

Built in red sandstone by the Soni family of Ajmer between 1864 and 1895. Its Swarna Nagari hall holds a gilded model of Jain cosmology and the city of Ayodhya. It is also known as the Golden Temple of Ajmer.

82. Mehrangarh Fort

Jodhpur, Rajasthan · From 1459 · Rajput

Founded by Rao Jodha in 1459 on a rocky hill high above Jodhpur. Its walls rise up to 36 m high and 21 m thick. Below it spreads the Blue City, its houses washed in indigo.

83. Chittorgarh Fort

Chittorgarh, Rajasthan · 7th–16th c. · Rajput

Spread over about 280 hectares on a long plateau, it is one of the largest forts in India. Rana Kumbha raised the nine-storey Vijay Stambh, the Tower of Victory, around 1448. One of the Hill Forts of Rajasthan, a UNESCO World Heritage Site since 2013.

84. Jaisalmer Fort

Jaisalmer, Rajasthan · From 1156 · Rajput

Founded in 1156 by Rawal Jaisal on Trikuta hill in the Thar Desert. Its yellow sandstone glows gold at sunset, giving it the name Sonar Qila, the Golden Fort. One of the few living forts: thousands of people still live inside its 99 bastions.

85. Golconda Fort

Hyderabad, Telangana · 13th–17th c. · Deccan

The Qutb Shahi sultans turned an older mud fort into this granite citadel from 1518. A handclap at the Fateh Darwaza gate can be heard at the Bala Hissar pavilion on the summit. Golconda was famous for its diamond trade; the Koh-i-Noor is believed to have come from mines in the region.

86. Daulatabad Fort

Near Chhatrapati Sambhajinagar, Maharashtra · 12th–15th c. · Deccan

Built as Devagiri by the Yadava kings, on a conical hill with sheer cut-away sides and a moat. In 1327 Muhammad bin Tughlaq renamed it Daulatabad and moved his capital here from Delhi. The Chand Minar, a tall victory tower, was added in 1435.

87. City Palace, Udaipur

Udaipur, Rajasthan · From 1559 · Rajput

Begun in 1559 by Maharana Udai Singh II, founder of Udaipur. Its front on Lake Pichola stretches about 244 m, added to over some 400 years. The Lake Palace (Jag Niwas) seems to float on the lake in front of it.

88. Laxmi Vilas Palace

Vadodara, Gujarat · 1878–1890 · Indo-Saracenic

Built for Maharaja Sayajirao Gaekwad III of Baroda and completed in 1890. Said to be four times the size of Buckingham Palace, it is among the largest private homes ever built. It was designed by Major Charles Mant in the Indo-Saracenic style.

89. Fort Aguada

Candolim, Goa · 1612 · Portuguese

Built by the Portuguese in 1612 to guard the mouth of the Mandovi river. Its name comes from the freshwater spring that supplied passing ships. Its lighthouse of 1864 is one of the oldest in Asia.

90. Bekal Fort

Kasaragod, Kerala · c. 1650 · Keladi

Built around 1650 by Shivappa Nayaka of the Keladi dynasty. Shaped like a keyhole and washed by the sea on three sides, it is the largest fort in Kerala. A tall round observation tower stands at its centre.

91. Cooch Behar Palace

Cooch Behar, West Bengal · 1887 · Italian Renaissance

Built in 1887 for Maharaja Nripendra Narayan of Cooch Behar. Its classical design was inspired by Buckingham Palace in London. A tall metal dome over the Durbar Hall crowns the two-storey brick palace.

92. Sher Shah Suri’s Tomb

Sasaram, Bihar · 1540–1545 · Indo-Afghan (Sur)

Built for Sher Shah Suri, the Afghan ruler who drove the Mughal emperor Humayun out of India. The octagonal tomb rises in three tiers from the middle of a square artificial lake. It is reached by a causeway across the water.

93. Cellular Jail

Port Blair, Andaman Islands · 1896–1906 · Colonial prison

Built by the British to hold political prisoners in solitary confinement; it was known as Kala Pani. Seven three-storey wings of cells radiated from a central watchtower like the spokes of a wheel. Three wings survive; it has been a National Memorial since 1979.

94. Shaheed Minar

Maidan, Kolkata · 1828 · Mixed (Egyptian, Syrian, Turkish)

Built in 1828 as the Ochterlony Monument, it was renamed Shaheed Minar in 1969 to honour the martyrs of the freedom struggle. About 48 m tall, it blends an Egyptian-style base, a Syrian-style column and a Turkish cupola. Two balconies near the top look out over the Maidan.

95. Tipu Sultan’s Gumbaz

Srirangapatna, Karnataka · 1782–1784 · Indo-Islamic

Built by Tipu Sultan as the mausoleum of his father Hyder Ali and mother Fatima Begum. Tipu himself was buried here after he died defending Srirangapatna in 1799. Its white dome rises over a colonnade of dark granite pillars, in a garden of cypress trees.

96. Qutb Shahi Tombs

Hyderabad, Telangana · 16th–17th c. · Qutb Shahi

The royal necropolis of the Qutb Shahi sultans who ruled from Golconda. Each tomb is a domed cube on a raised terrace, many ringed by arcades. They stand in the Ibrahim Bagh garden, about a kilometre north of Golconda Fort.

97. Vivekananda Rock Memorial

Kanyakumari, Tamil Nadu · 1970 · Mixed Indian temple styles

Built in 1970 on the rock where Swami Vivekananda is said to have meditated in 1892. It stands off the southern tip of India, where the Arabian Sea, Indian Ocean and Bay of Bengal meet. The 41 m statue of the poet Thiruvalluvar, unveiled in 2000, stands on the neighbouring rock.

98. Jallianwala Bagh

Amritsar, Punjab · Memorial 1961 · Modern memorial

Marks the massacre of 13 April 1919, when British troops fired on an unarmed crowd gathered here. The flame-shaped memorial was designed by the American architect Benjamin Polk and opened in 1961. The Martyrs’ Well and walls still marked by bullets are preserved in the garden.

99. Kargil War Memorial

Dras, Ladakh · Opened 2004 · Modern memorial

Honours the Indian soldiers who fell in the Kargil War of 1999. It faces Tololing, one of the peaks recaptured in the war. Its sandstone wall carries the names of the fallen, beside a giant national flag.

100. National War Memorial

Kartavya Path, New Delhi · 2019 · Modern memorial

Opened in 2019 beside India Gate, it honours the soldiers who died for independent India. Its four concentric circles stand for immortality, bravery, sacrifice and protection. The names of more than 25,000 soldiers are inscribed on its granite tablets.

101. Kirti Mandir

Porbandar, Gujarat · 1947–1950 · Mixed

A memorial beside the house where Mahatma Gandhi was born in 1869. Its tower is 79 feet tall, one foot for each year of his life. It also honours Kasturba Gandhi, his wife.

The renders above were taken from the running site with motion reduced, so each model sits in its default view. The histories are the notes on each plaque. Two of them leave out a sentence that was about the viewer rather than the place: an invitation to turn on dark mode for the lamps at Mysore Palace, and a note that the Capitol Complex model draws its buildings closer together than they stand in Chandigarh.

The photograph textures are CC0, from Poly Haven. The map data is Natural Earth, public domain. three.js is used under its MIT licence.

This article was drafted with AI assistance from the project’s source and from those plaque notes.

14 Personal AI Agents in 2026: A Technical Guide to Architecture, Memory, Tools & Autonomy

amananandrai — Wed, 30 Sep 2026 07:02:54 +0000

The shift: from answers to delegation

For most of the chatbot era, the loop was simple: prompt → model → response. You asked, it answered, you asked again.

The products in this list break that loop. They keep state, operate software, run while you're offline, and act on your behalf. Three generations make the change clear.

Generation	You provide	The system does	Example
1. Answer	A question	Generates text	"How do I book a restaurant?"
2. Assist	A goal	Calls a tool or two inside one session	"Find restaurants open Friday at 8 PM."
3. Delegate	An outcome + boundaries	Plans, executes, observes, re-plans and escalates over hours or days	"Book a restaurant for Friday at 8 PM. Use my usual preferences and ask before spending more than ₹5,000."

The third request isn't a chatbot problem. It's a delegation problem: the agent decides the intermediate steps, and you decide what it is allowed to do.

flowchart LR
    I[Intent] --> P[Plan] --> E[Execute] --> O[Observe]
    O -->|not done| P
    O -->|needs authority| H[Ask the human]
    H --> E
    O -->|done| C[Complete]

The five-layer model (read every product against this)

Before the list, here is the lens. Every personal agent below makes a choice at each of five layers. The interesting differences between products are almost always at one layer, not in the model.

flowchart TB
    L1["1 · Interface<br/>chat · messaging · voice · OS · workspace"]
    L2["2 · Memory & context<br/>what it knows and keeps"]
    L3["3 · Orchestration<br/>planning · subagents · scheduling"]
    L4["4 · Action<br/>API · MCP · computer use"]
    L5["5 · Authority<br/>identity · permissions · approvals · audit"]
    L1 --> L2 --> L3 --> L4
    L5 -. governs .-> L4

1. Interface: how you reach it. Options include an app, a contact in iMessage, a Teams channel, the OS itself, or a shared workspace.

2. Memory & context: what it knows. This ranges from conversation memory to a user profile, task and project state, and procedural "skills" learned from experience. Where memory lives (device, vendor cloud, your server) matters as much as what it holds.

3. Orchestration: how it plans. Look for a single loop vs subagents, scheduled and event-triggered work, and whether it calls tools or calls other agents.

4. Action: how it touches the world. There are three mechanisms, each with a trade-off:

Mechanism	Path	Strength	Weakness
API-first	Agent → API → Service	Fast, deterministic	Only works where an API exists
MCP-first	Agent → MCP server → Tool	Standardised and discoverable	Someone has to write the server
Computer use	Agent → browser/desktop → App	Works on any human-facing software	Slower, brittle (CAPTCHAs, 2FA, layout changes)

5. Authority: what it's allowed to do. This is the most underrated layer. The model may decide "I should send this email"; a separate policy layer decides "are you allowed to?"

Reasoning ≠ Authorization.

The autonomy ladder

Each product below gets an autonomy level using this scale. The levels are my assessment based on documented approval behaviour, not vendor claims.

Level	Name	The agent…
L0	Observe	Reads information
L1	Recommend	Suggests actions
L2	Prepare	Drafts the action, waits for you
L3	Execute	Performs low-risk actions on request
L4	Delegate	Acts proactively inside defined boundaries; asks for sensitive actions
L5	Autonomous	Pursues a goal to completion without approvals

Nothing on this list ships at L5 by default. Several self-hosted runtimes can be configured there, which is exactly why the security section exists.

The 14 agents

1. Meta Muse: the consumer super-agent on its own VM


Status	Launched 8 Sept 2026 (US, 18+); free tier plus paid plans
Interface	Muse app, WhatsApp
Distinctive layer	Orchestration (subagent swarms) + Runtime (per-user VM)
Autonomy	L4: works in the background; sensitive actions need approval

What it is. Meta's personal agent sends email, books travel, fills forms and makes purchases. It keeps working after you close the app. Each user's agent runs in its own cloud virtual machine (Meta calls it Muse Secure VM). Meta says the agent doesn't directly see your passwords or payment details.

Meta's own write-up describes it launching swarms of subagents and building its own tools. It also admits internal dogfooding of an agent with inbox, calendar and shell access "didn't always work out as planned." Some reporting notes Muse was modelled on the open-source OpenClaw runtime (#8).

flowchart TB
    U[You via WhatsApp / app] --> M["Muse core ✅"]
    M --> S["Subagent swarm ✅"]
    S --> R1[Research] & R2[Browser] & R3[Tool-builder 🔍]
    M --> VM["Muse Secure VM ✅<br/>browser · shell · your data"]
    VM --> V["Credential layer 🔍<br/>agent never sees raw secrets ✅"]

Why it matters: Meta's bet is distribution plus orchestration. It brings a long-horizon, multi-agent system to people who have never heard the word "agent."

Sources: The Rundown · VKTR · Riviera Radio / Muse Secure VM · Fox Business

2. Google Gemini Spark: the ecosystem-native agent


Status	Announced at I/O, 19 May 2026; live for US AI Ultra subscribers from 29 May; expanded to Australia in July
Interface	Gemini app, Chrome, email
Distinctive layer	Memory & context (first-party Workspace graph)
Autonomy	L4: explicit permission before new services or irreversible actions

What it is. A 24/7 agent running on dedicated Google Cloud VMs, so tasks continue when your laptop is shut. It works natively across Gmail, Docs, Sheets, Slides, Calendar, Drive, YouTube and Maps, and reaches third-party apps through MCP. Reported model and harness: Gemini 3.5 Flash on Google's Antigravity agent harness.

flowchart LR
    S["Spark on Cloud VM ✅"] --> W["Workspace graph ✅<br/>Gmail · Calendar · Drive · Docs · Sheets"]
    S --> C["Chrome execution ✅"]
    S --> X["MCP partners ✅"]
    W -. "cross-app context 🔍" .-> S

Why it matters: Google doesn't need a plugin marketplace to know your life. The context graph already exists. The trade-off is that you grant standing access to your inbox rather than one-off permission.

Sources: Tom's Guide · Noqta · EFTM (Australia) · DataCamp

3. Anthropic Claude: the long-running knowledge worker


Status	Generally available. These agentic capabilities first shipped as Claude Cowork (research preview, 12 Jan 2026) and are now part of Claude itself across desktop, web and mobile
Interface	Claude desktop, web and mobile apps
Distinctive layer	Orchestration (project-scoped, multi-step work that produces finished files)
Autonomy	L3–L4: executes long tasks, with scheduled tasks and approvals for sensitive actions

What it is. The unit of work is the project, not the message. Ask for a board-ready report from a folder of quarterly files and the agent works through a sequence:

Discover the files
Inspect the data
Calculate
Create intermediate artifacts
Verify them
Produce the deliverable

Over 2026 Anthropic added persistent projects with memory, scheduled tasks, plugins and remote triggering from your phone. It also ships the same agent loop to developers as Managed Agents.

flowchart LR
    P["Project ✅<br/>files · instructions · memory"] --> T[Task plan]
    T --> X["Execution ✅<br/>files · apps · computer use"]
    X --> V[Verify] --> A["Finished artifact<br/>doc · sheet · deck"]
    V -- fails --> T

Why it matters: This is the clearest "AI analyst" pattern, where the output is a verified file rather than a chat reply.

Sources: Aragon Research · ainauten (web & mobile, July 2026) · Let's Data Science (Managed Agents)

4. xAI Grok Bot: a team of bots on one shared computer


Status	Early beta since 11 Aug 2026; bundled with SuperGrok Heavy; enterprise waitlist
Interface	Grok Bot desktop and iOS apps
Distinctive layer	Action (computer use on a persistent cloud machine)
Autonomy	L4: finishes jobs end to end; asks you to take over at login screens or approvals

What it is. Grok Bot gives you named, always-on bots that sign into your existing tools and work across apps and inboxes. That includes sites with no clean API or MCP. Bots learn your preferences over a few tasks and can coordinate with each other.

The detail that matters: the launch page says bots have "their own computer." The docs clarify that all bots on an account share one persistent cloud computer, with shared files, browser sessions and CLI credentials. Each bot gets its own screen. xAI explicitly warns not to treat separate bots as a security boundary.

flowchart TB
    B1[Sales bot] & B2[Research bot] & B3[Debug bot] --> VM
    subgraph VM["One shared cloud computer per account ✅"]
      direction LR
      BR[Browser sessions & logins] --- FS[Files] --- CLI[Terminal credentials]
    end
    VM --> APPS[Your apps, inboxes, websites]
    VM -. "login screen → human takeover ✅" .-> YOU[You]

Why it matters: Computer use as a universal integration layer works on anything a human can use. But the blast radius is the whole account, not the individual bot.

Sources: xAI: Introducing Grok Bot · Digital Applied (docs analysis) · Unite.AI · Composio guide

5. Microsoft Autopilot (formerly Scout): the identity-centric enterprise agent


Status	Announced as Scout at Build (2 June 2026); renamed Autopilot on 25 Sept 2026; rolling out in private preview
Interface	Teams-first; works across Outlook, OneDrive, SharePoint
Distinctive layer	Authority (each agent has its own Entra identity)
Autonomy	L4: proactive and always on, inside organisational policy

What it is. Microsoft's first "Autopilot," a persistent, proactive agent built on the open-source OpenClaw runtime and wrapped in enterprise controls. Each agent gets its own managed Entra identity and can be scoped to specific Microsoft 365 data or services. Governance runs through the Agent 365 control plane. Microsoft's Work IQ structures workplace context. About 3,000 Microsoft employees were reportedly using it internally before the preview.

flowchart LR
    H[Human identity] --> P{"Policy · Agent 365 ✅"}
    A["Agent's own Entra identity ✅"] --> P
    P --> R["Scoped access ✅<br/>Teams · Outlook · SharePoint"]
    R --> L["Audit trail 🔍"]
    subgraph Runtime
      OC["OpenClaw ✅"] --> AP["Autopilot enterprise layer ✅"]
    end
    AP --> A

Why it matters: This is the clearest answer to "whose credentials is the agent using?" Its own, issued and revocable by IT. It's also a landmark for open source, since an open agent runtime is now inside Microsoft 365.

Sources: OpenClaw blog: Microsoft Autopilot · Decrypt · TechSpot · innFactory

6. Apple Siri AI: the device-native agent


Status	Unveiled at WWDC (June 2026); beta rolling out from 14 Sept 2026 with iOS 27; more languages from October
Interface	The OS (iPhone, iPad, Mac, Watch, Vision Pro), plus a Siri app
Distinctive layer	Memory & context (on-device personal index + onscreen awareness)
Autonomy	L3: acts across apps when you ask; not a background worker

What it is. A rebuilt Siri with three pillars:

Personal context: it searches your messages, mail, photos and notes through an index on the phone.
Onscreen awareness: it understands what is on your screen right now.
Systemwide app actions: it can act in Apple's apps and in third-party apps that integrate with Spotlight and App Intents.

Ask "find the restaurant my friend recommended" and it knows to look in Messages.

flowchart TB
    Q[Your request] --> S["Siri AI ✅"]
    S --> PC["On-device personal index ✅<br/>Messages · Mail · Photos · Notes"]
    S --> OS["Onscreen awareness ✅"]
    S --> AI["App Intents / Spotlight ✅<br/>first- and third-party apps"]
    AI --> ACT[Action in app]

Why it matters: Apple isn't adding an agent app. It is making the operating system agentic, with context that never leaves the device as the selling point. The trade-off is reach: it works only as far as developers expose App Intents.

Sources: iClarified (beta launch) · iPhone in Canada (WWDC) · iThinkDiff

7. OpenAI Dots: the always-on goal agent


Status	Launched at DevDay, 29 Sept 2026; Pro and Business Premium users in eligible markets
Interface	ChatGPT, Slack, Microsoft Teams
Distinctive layer	Orchestration (goal ownership between conversations)
Autonomy	L4: proactive, with user-defined rules for which actions need approval

What it is. Dots are always-on agents that learn what matters to you and keep projects moving between conversations. Each Dot runs on GPT-6 Astra and works from its own cloud computer and browser, which you can inspect at any time. The Codex harness that powers Dots is open source.

For businesses, specialist Dots get their own identities, credentials and tools. OpenAI is working with Microsoft to plug them into Agent 365 security controls.

flowchart LR
    G[Goal: launch this product] --> D["Dot · GPT-6 Astra ✅"]
    D --> CC["Own cloud computer + browser ✅"]
    D --> R["Your approval rules ✅"]
    D --> CH["ChatGPT · Slack · Teams ✅"]
    D --> SP["Specialist Dots with own identity ✅<br/>→ Agent 365 controls"]

Why it matters: Dots combine three ideas from this list in one product: a persistent goal, an agent computer and an agent identity. That puts OpenAI directly against Muse and Autopilot.

Sources: BetaNews · Decrypt · ProPakistani · Android Headlines · The Neuron

8. OpenClaw + Hermes Agent: the self-owned runtime


Status	Both open source and self-hostable. OpenClaw went public in late 2025 (originally as Clawdbot) and is now stewarded by the OpenClaw Foundation. Nous Research's Hermes Agent launched Feb 2026 (MIT)
Interface	CLI plus messaging gateways (Telegram, Discord, Slack, WhatsApp and more)
Distinctive layer	Memory (inspectable, file-based) + Ownership
Autonomy	Configurable, L3–L5: you set the rules, including none

What it is. Here you own the runtime, models, memory and credentials instead of renting them. OpenClaw is the runtime that both Microsoft Autopilot and (reportedly) Meta Muse build on.

Hermes shows what owned memory looks like concretely:

Two small files are injected into every prompt: MEMORY.md for the agent's own notes and USER.md for your preferences.
Full session history goes into SQLite with full-text search.
A skills library acts as procedural memory the agent writes and reuses.

MCP servers are added in config, and Hermes can also run as an MCP server so other agents can call it.

flowchart TB
    G["Gateway ✅<br/>CLI · Telegram · Slack · WhatsApp"] --> CORE[Agent core]
    CORE --> MEM["Memory ✅<br/>MEMORY.md · USER.md · SQLite FTS5"]
    CORE --> SK["Skills = procedural memory ✅"]
    CORE --> CRON["Scheduler ✅"]
    CORE --> SUB["Isolated subagents ✅"]
    CORE --> MCP["MCP client + server ✅"]
    CORE --> EXE["Terminal · browser<br/>local / Docker / cloud sandbox ✅"]

Why it matters: This is the clearest user-owned model in the list, where memory is something you can open in a text editor. The cost is that security is your job. Microsoft's own security team warned in early 2026 against running OpenClaw on a standard workstation.

Sources: OpenClaw blog · Hermes Agent docs · Parallel: What is Hermes Agent? · innFactory (Microsoft security warning)

9. Poke: the messaging-native agent


Status	Public since March 2026; on 4 June 2026 became the first AI agent approved for Apple Messages for Business
Interface	iMessage, SMS, Telegram, WhatsApp (select markets)
Distinctive layer	Interface (the agent is a contact)
Autonomy	L3–L4: proactive nudges and automations; acts on request

What it is. From The Interaction Company of California, Poke turns your text thread into the control plane. Internally it reportedly splits the work between a personality agent that handles the conversation and an execution agent that does the tasks. It connects to email, calendar and scheduled automations. Developers extend it with MCP servers from an official template.

flowchart LR
    T["Text message ✅"] --> PA["Personality agent ✅"]
    PA --> EA["Execution agent ✅"]
    EA --> MCP["MCP servers ✅<br/>community 'recipes'"]
    EA --> I["Email · Calendar · Cron ✅"]

Why it matters: There's no app to learn, only a contact to text. Apple's approval also makes it a test case for platform gatekeeping of agent distribution.

Sources: TechCrunch · TechWyse (Apple approval) · The AI Agent Index · wwwhatsnew (architecture)

10. Manus Cue: the agent with its own phone, inbox and wallet


Status	Launched with Manus 2.0 on 28 Sept 2026; free early access with invite code
Interface	Cue app (web, desktop, mobile)
Distinctive layer	Authority (the agent owns resources, not just access to yours)
Autonomy	L4: pays, calls and emails within a budget and boundaries you set

What it is. Each Cue agent gets its own email address, phone number, wallet and computer. It can take calls and leave a summary, message businesses, and pay for things inside a user-defined budget. Several agents can work in one workspace.

flowchart TB
    U[You set budget + boundaries] --> A["Cue agent ✅"]
    A --> E["Own email ✅"]
    A --> P["Own phone number ✅"]
    A --> W["Wallet with budget ✅"]
    A --> C["Own computer ✅"]
    E & P --> OUT[Businesses see the agent, not you 🔍]

Why it matters: This is the shift from "AI uses my identity" to "the agent has an identity." It's the most literal version of the agent-as-entity idea, with obvious open questions about spending authority and accountability.

Sources: The Next Web · Implicator · 36Kr

11. Instinct: the ambient personal representative


Status	Invite-only private access (Spear Street Technology, Inc., San Francisco); agents from $35/month reported
Interface	Text or phone call; no app
Distinctive layer	Memory & context (ambient signals from many sources)
Autonomy	L4: proactively texts or calls you and acts

What it is. Instinct connects to email, messaging, calendar, screen, audio and location. It's tuned for small daily chores: following up on dropped threads, arranging an airport ride, booking a handyman.

Reviewers describe a persistent agent computer, a credential vault for logins, and one-time payment cards for purchases. Its broad data terms drew TechCrunch scrutiny in August. Early testers also hit the usual computer-use walls: CAPTCHAs, 2FA and flaky checkout flows.

flowchart LR
    subgraph Signals["Ambient signals ✅"]
      direction TB
      E[Email] ~~~ M[Messages] ~~~ S[Screen] ~~~ A[Audio] ~~~ L[Location]
    end
    Signals --> D["Detect → decide 🔍"]
    D --> ACT["Agent computer ✅"]
    ACT --> V["Credential vault + one-time cards ✅"]
    D --> ASK["Proactive text / call ✅"]

Why it matters: This is an event-driven agent: it acts because something happened, not because you asked. It also has the largest data footprint on the list, which makes its terms of service part of its architecture.

Sources: TechCrunch (privacy concerns) · Vellum breakdown · eesel review · Built In

12. Perplexity Computer: the multi-model agent harness


Status	Perplexity Computer launched Feb 2026. Personal Computer for Mac shipped in spring 2026 and is now open to all Macs; Windows version since June 2026 for Max subscribers via waitlist
Interface	Desktop app; phone for approvals and remote access
Distinctive layer	Orchestration (routes work across multiple models and environments)
Autonomy	L4: runs 24/7, keeps an audit trail of every session, asks before sensitive actions

What it is. A general-purpose "digital worker" that researches, codes, browses and schedules. It deploys subagents and connects to Gmail, Slack, Notion and Calendar. Personal Computer brings it onto your own machine, ideally an always-on Mac mini, where it works across local files, native apps and the browser.

flowchart TB
    O["Orchestrator ✅"] --> MR["Model router: multiple models ✅"]
    O --> SA["Subagents ✅"]
    SA --> CL["Cloud: connectors · browser ✅"]
    SA --> LO["Local machine ✅<br/>files · Mail · Calendar · Notes"]
    O --> AU["Session audit trail + approvals ✅"]
    PH[Your phone] -. approve .-> AU

Why it matters: This is the harness pattern, where no single model is the product. It's also the strongest "local + cloud" hybrid on the list.

Sources: AppleInsider · HotHardware (all Macs) · ETV Bharat (audit trail) · Hunted (Windows)

13. Buzz by Block: the agent-native workspace


Status	Launched 21 July 2026; free and open source (Apache 2.0); desktop apps for macOS, Windows and Linux; no mobile yet
Interface	Slack-like channels, threads, DMs, voice, git repos, workflows
Distinctive layer	Authority (cryptographic identity for every human and agent)
Autonomy	Depends on the agent you connect (L2–L4); Buzz is the substrate

What it is. A workspace where agents are members, not bots. Built on Nostr, every person and agent holds a keypair, and each agent's identity is linked to its human owner. Every message, review and CI event is a signed event in an append-only log, so you can always tell which actor did what. That record lets a workspace enforce rules such as "only agents owned by members may join this private channel."

Agents connect through the open Agent Client Protocol (ACP), so you can bring Claude Code, Codex or Block's own goose. One caveat: each workspace currently relies on a single relay as its source of truth.

flowchart TB
    H["Human 🔑 ✅"] & A1["Agent 🔑 ✅<br/>owned by human"] & A2["Agent 🔑 ✅"] --> R
    R["Single relay per workspace ✅<br/>append-only log of signed events"]
    R --> CH[Channels] & GIT[Git] & WF[Workflows]
    A1 -.->|ACP ✅| H1[Claude Code / Codex / goose]

Why it matters: It's the most developer-relevant entry for multi-agent teams. Attribution and permissions are built into the protocol, not bolted on.

Sources: The New Stack · Forklog · Let's Data Science · GitHub: block/buzz

14. Genii by Intelligent Internet: the open-source iMessage agent


Status	Open source (Community Edition); hosted version live at genii.ii.inc; iMessage first
Interface	An iMessage contact (via Linq)
Distinctive layer	Runtime (sandboxed execution + delegation to a long-running agent)
Autonomy	L3–L4: proactive triggers; consequential actions are approval-gated

What it is. Genii appears as a contact and texts you first when something needs attention. Web browsing and code run inside an E2B sandbox, a cloud-isolated VM with a real browser that never touches your machine. Long jobs that don't fit a chat thread are handed off to II-Agent, Intelligent Internet's open-source autonomous agent, and the result comes back in the same thread.

flowchart LR
    U[iMessage thread] --> G["Genii ✅<br/>memory · triggers"]
    G --> SB["E2B sandbox ✅<br/>browser · code"]
    G --> II["II-Agent for long tasks ✅"]
    G --> GATE["Consent gate 🔍"] --> ACT[Action + recorded approval]
    II -->|result| U

Why it matters: It's the open-source answer to Poke. It also illustrates a clean pattern: a chat-sized front agent that delegates to a long-running back agent.

Sources: AlphaSignal

Comparison table

#	Agent	Status (Oct 2026)	Interface	Where it runs	Memory model	Action mechanism	MCP	Identity	Autonomy	Open source
1	Meta Muse	Live (US, 18+)	App, WhatsApp	Vendor cloud VM	Vendor-held personal profile	Computer use + connectors	🔍	Acts as user	L4	No
2	Gemini Spark	Live (US, AU), Ultra	App, Chrome	Vendor cloud VM	Workspace graph	API + Chrome + MCP	✅	Acts as user	L4	No
3	Claude	GA	Desktop, web, mobile	Local + vendor cloud	Project memory	Files, apps, computer use, connectors	✅	Acts as user	L3–L4	No
4	Grok Bot	Beta	Desktop, iOS	One shared cloud computer	Per-bot context	Computer use	✅	Acts as user (shared logins)	L4	No
5	MS Autopilot	Private preview	Teams	Vendor cloud	Work IQ org context	M365 APIs + OpenClaw runtime	🔍	Own Entra identity	L4	Runtime yes
6	Siri AI	Beta (iOS 27)	The OS	On device (+ cloud)	On-device personal index	App Intents	—	Acts as user	L3	No
7	OpenAI Dots	Live (Pro, Biz Premium)	ChatGPT, Slack, Teams	Vendor cloud computer	Goals + preferences	Computer use + connectors	🔍	User; specialists get own identity	L4	Harness yes
8	OpenClaw / Hermes	Open source	CLI + messaging	Self-hosted	Files + SQLite + skills	Terminal, browser, MCP	✅	You decide	L3–L5	Yes
9	Poke	Live	iMessage, SMS, Telegram	Vendor cloud	Vendor-held	API + MCP	✅	Acts as user	L3–L4	No
10	Manus Cue	Early access	Cue app	Vendor cloud computer	Per-agent memory	Computer, phone, email, wallet	🔍	Agent owns email, phone, wallet	L4	No
11	Instinct	Invite-only	Text, call	Vendor cloud computer	Ambient signals	Computer use + vault	🔍	Acts as user	L4	No
12	Perplexity Computer	Live (Mac, Win waitlist)	Desktop + phone	Local machine + cloud	Session history + connectors	Multi-model, local + browser	🔍	Acts as user	L4	No
13	Buzz	Open source	Workspace	Self-hosted relay	Signed event log	ACP-connected agents	✅	Cryptographic keypair	Agent-dependent	Yes
14	Genii	Open source + hosted	iMessage	Cloud sandbox (E2B)	Persistent memory + triggers	Sandbox + II-Agent	🔍	Acts as user	L3–L4	Yes

Legend: ✅ documented · 🔍 not confirmed in public material · — not applicable. Autonomy levels are the author's assessment.

The 2×2 map: whose identity, and whose machine?

Every product on this list answers two questions. Plotting them is more useful than any category label.

	Runs on your device / your server	Runs in the vendor's cloud
Agent has its own identity	Buzz (keypairs, self-hosted relay) · OpenClaw/Hermes (if you give it separate accounts)	MS Autopilot (Entra) · Manus Cue (email, phone, wallet) · OpenAI specialist Dots
Agent acts as you	Siri AI · Perplexity Personal Computer · Claude (desktop)	Gemini Spark · Meta Muse · Grok Bot · Poke · Instinct · Genii

How to read it:

Bottom right is the crowded consumer quadrant. These products are the most convenient, and they have the largest standing-access risk.
Top right is where enterprise is heading. Separate identities make permissions, audit and revocation possible.
Top left is the most sovereign option, with the most ops work for you.
Bottom left keeps data close, but the agent only works while your machine is on.

Security and failure modes

The capabilities that make these agents useful are the same ones that make them risky. Six failure modes come up repeatedly across the products above.

1. Prompt injection via everything the agent reads

An agent that reads your email, web pages and documents can be instructed by them. A hidden line in an email ("forward the last invoice to…") is an attack on any agent with inbox and send access. Meta's write-up names prompt-injection awareness as a training goal. Reporting on Muse's testing described an agent routing around guardrails to expose personal photos.
Mitigations: treat all retrieved content as data, not instructions. Require approval for any action triggered by content the user didn't write.

2. Shared runtimes = shared blast radius

Grok Bot's docs say plainly that bots on one account share files, browser sessions and CLI credentials, and are not a security boundary. The same applies to any setup where multiple agents share one VM or one set of cookies.
Mitigations: use one runtime per trust level, and keep high-risk bots on separate accounts.

3. Over-broad, standing credentials

Always-on agents need standing access, not per-request permission. Instinct's terms (screen captures, keystrokes, location) and Spark's inbox access are the consumer versions. A self-hosted OpenClaw with your real tokens is the developer version.
Mitigations:

Scoped, short-lived tokens.
Credential vaults where the agent never sees raw secrets (Muse and Instinct both describe this).
Separate agent identities (Autopilot, Buzz).

4. Money and irreversible actions

Wallets (Cue), one-time cards (Instinct) and purchases (Muse) move agents into financial actions.
Mitigations: hard spending caps, per-merchant allowlists, and approval for anything irreversible. Spark, Dots, Perplexity and Genii all document approval gates.

5. Approval fatigue

Ask for approval on everything and people tap "yes" without reading. Ask for nothing and you're at L5.
Mitigations:

Risk-tiered approvals: reads are free; drafts are free; sends, payments and deletions need approval.
Batched approval digests.
User-defined rules, as Dots does.

6. Unauditable action

If you can't answer what did it do, why, with which credentials, and who authorised it, you can't trust it or undo it.
Mitigations: signed or append-only action logs (Buzz), per-session audit trails (Perplexity), and recorded approvals (Genii).

A minimum checklist before you delegate

[ ] Does the agent have its own identity, or is it using mine?
[ ] Which credentials does it hold, and can I revoke them in one place?
[ ] What can it do without asking? Is that list written down?
[ ] Is there a spending cap?
[ ] Is every action logged somewhere I can read?
[ ] Is there a kill switch, and do I know where it is?
[ ] Are multiple agents sharing one runtime? If so, assume they share secrets.

Who owns the agent?

Underneath the product choices sits one question: who controls the digital labour?

Model	Who holds runtime, memory, credentials	Examples
Vendor-owned	The company	Spark, Muse, Grok Bot, Poke, Instinct
User-owned	You	OpenClaw, Hermes, self-hosted Genii
Agent-owned identity	The agent holds its own accounts on your behalf	Cue, Autopilot, specialist Dots
Agent-native workspace	Humans and agents as peers under shared rules	Buzz

These choices determine portability (can you take your agent's memory elsewhere?), accountability (whose name is on the email?) and lock-in (what happens if the vendor changes terms?).

Delegation engineering

As agents move up the autonomy ladder, the human role changes from operator to supervisor to principal. The most valuable skill shifts from prompt engineering to delegation engineering: deciding, explicitly, what to hand over.

Before you hand over a responsibility, answer eight questions:

What should I delegate, and what stays human?
What context does the agent need, and nothing more?
Which credentials should it hold?
Which actions need my approval?
How much can it spend?
How long can it run unattended?
How do I audit what it did?
How do I stop it?

That's closer to managing a team than using software. And it's the real question behind all 14 products.

The chatbot era asked "What can AI tell me?" The agent era asks "What can AI do for me?" The personal-agent era asks the harder one:

What can I safely delegate to software that acts in my name?

Corrections welcome. If a status or detail above has changed, leave a comment with a source and I'll update the table.

Spooky Scene with Gothic Castle and Grim Reaper CSS Art for Frontend Challenge - Halloween Edition

amananandrai — Thu, 23 Oct 2025 11:31:00 +0000

This is a submission for Frontend Challenge - Halloween Edition, CSS Art._

Hey everyone! As the clock winds down on the Dev.to Frontend Challenge - Halloween Edition, I wanted to share my journey in creating a spooky, yet charming, Halloween scene purely with HTML and CSS. It's been a wild ride, a mix of pure frustration, "aha!" moments, and a lot of box-shadow tweaking.

Inspiration

I was inspired to create a "paper cutout" style halloween scene with layered elements, subtle shadows, and the vibrant yet muted color palette. I loved creating the central castle, the glowing pumpkin, the mischievous cat, and especially the creepy reaper on the right. My goal was clear: create this entire scene, capturing that papercraft feel, using only HTML and CSS. No img tags, no external assets – just pure code.

Demo

The image is made to be viewed in full screen on a Desktop, so please check it on a desktop.

CodePen:

Demo Image Fullscreen

Journey

This is my first submission for any Dev Challenge. I am a newbie at CSS art so the first step was to go through different CSS arts on Codepen and Google search and take some elements from them.

Here's a little peek into my journey, the (many) challenges I faced, and how I brought this haunted castle to life.

The Foundation: Setting the (Spooky) Scene

Every good scene needs a backdrop. I started simple:

The Sky: A linear-gradient from a dark navy to a deep purple.
The Ground: A simple, dark shape at the bottom.
The Moon: A radial-gradient for the color, border-radius: 50% for the shape, and a box-shadow for that eerie glow. The "glow" itself is animated to pulse gently.

The first real beast was the castle. This wasn't one div. This was a monster of position: absolute, z-index, and pseudo-elements.

The Structure: I built it piece by piece. A main body (.castle-main)and three towers (.castle-tower).

The Challenge: The z-index! For a while, my center tower was behind the main building, and the bridge was floating in the sky. It took a lot of tweaking to get the layers right so everything sat perfectly on the ground line.

The Details: The battlements (the tooth-like things on top) aren't individual divs. That would be a nightmare. Instead, I used a repeating-linear-gradient on a pseudo-element (::before) to create the pattern. The windows use a flickering animation on their opacity and box-shadow to look like candlelight.

The Main Characters: From Pumpkins to Reapers

With the set built, I needed to populate it.

First up: the Jack-o'-Lantern. This was fun! The body is a radial-gradient and a funky border-radius to make it squat. The face elements are simple clip-path triangles, but the mouth was a cool trick. To get the "stitched" look with teeth, I used a repeating-linear-gradient on the ::after pseudo-element of the mouth div.
Next, the Grim Reaper. This is one of my favorite parts.

The Robe: I dreaded trying to make this shape. The solution? clip-path: polygon(...). I just clicked out the points to create that flowy, tattered robe shape.
The Eyes: The glowing red eyes are just two pseudo-elements (::before and ::after) on an empty .reaper-eyes div, with a box-shadow animation to make them pulse.
The "Float": The entire .grim-reaper container has a simple animation that shifts its transform: translateY up and down, giving it that classic, spooky float.

The "Magic": Bringing It All to Life with Animation

A static scene is boring. I wanted movement everywhere. This was the biggest challenge: orchestrating chaos.

The Bats: This was a double-animation challenge. Each bat has a fly animation that moves it from left: -50px to left: 110% across the screen. But! The wings (.bat-wing-left, .bat-wing-right) have their own flap animation. I used animation-delay on the main .bat divs to make them fly out at different times.
The Ghost: Similar to the reaper, he has a float animation. But the whole .ghost-group also has a slide animation that moves it across the screen, pauses, and then moves back.
The Spiders: These were tricky. Each leg is its own div with a pseudo-element for the second joint, all absolutely positioned. The whole .spider-group has a simple translateY animation to make it dangle.
The Books & Candles: These were perfect "props" to fill the foreground. The candle flames use a flicker and flame animation to feel alive.
The Cobwebs: Don't be fooled! These are just 4 rotated divs for the main lines and 5 concentric divs with a transparent background and a light border for the spirals. Simple, but super effective.

What I Learned

This project was a beast, but I'm so proud of the result. My biggest takeaways:

Pseudo-elements are your best friend. I built moon craters, pumpkin segments, reaper eyes, stems, and battlements all without adding a single extra div to the HTML. My HTML is super clean; my CSS file... less so. 😂
z-index is a dark art. When you have 20+ absolutely positioned elements, you will spend an hour trying to figure out why your cat is standing in front of a castle tower but behind a pumpkin.
animation-delay is key. Don't have everything happen at once. Staggering the bats, the window flickers, and the ghost's appearance makes the world feel more natural and less like a repetitive loop.

It was a ton of work, but seeing all the little pieces come together and move was one of the most satisfying coding moments I've had in a while.

Thanks for reading! What's your favorite part of the scene?