One pool per environment, not one pool per application

A pool exists to amortize something expensive. Opening a PostgreSQL connection costs real work: TCP handshake, TLS, authentication, and the server spins up a dedicated process per connection. In a long-lived backend — a Nest service on Fargate, say — you open ten connections at boot and reuse them for days. You pay that cost once.

Lambda has no "at boot" in the sense you're imagining. It has one boot per execution environment, and AWS creates as many environments as you have concurrent invocations. If your peak is 200 concurrent invocations, you have 200 independent Node processes, each with its own pool. A pool of 10 per environment means 2,000 connections knocking on a database that can handle 100.

The math is brutally simple:

connections = Lambda concurrency × pool size per environment

A db.t4g.medium sits around 220 max_connections. At 50 concurrent invocations with a pool of 5, you're already at the ceiling. And unlike a server, you don't get to choose the concurrency here — traffic chooses it for you.

The mistake that multiplies the damage: creating the pool inside the handler

Before touching any infrastructure, look at where the client gets created. This is the pattern I run into most often, and it turns a scaling problem into an immediate one:

// BAD: a fresh pool on every invocation, and connections left dangling
export const handler = async (event) => {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const { rows } = await pool.query('SELECT id FROM users WHERE email = $1', [event.email]);
  return rows[0];
};

Every invocation opens a brand new pool. And if the end() is missing — it almost always is — the connection stays occupied until PostgreSQL reaps it on timeout. You've just turned every request into a leak.

The fix is to hoist it out of the handler, into module scope. That code runs once per execution environment, and the environment gets reused across invocations for as long as it stays warm:

// The pool lives in the execution environment and survives across invocations
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 1,                       // one environment serves one invocation at a time
  idleTimeoutMillis: 30000,     // release the connection when the environment goes idle
  connectionTimeoutMillis: 5000,
});

export const handler = async (event) => {
  const { rows } = await pool.query('SELECT id FROM users WHERE email = $1', [event.email]);
  return rows[0];
};

max: 1 looks wrong if you come from servers, but it's exactly right here: a Lambda environment handles one invocation at a time, so a pool of 10 is nine connections that never do any parallel work and absolutely do count against your limit.

Reserved concurrency: the ceiling you actually control

With max: 1, your connection count becomes precisely your concurrency. And concurrency you can cap, function by function:

resource "aws_lambda_function" "api" {
  function_name                  = "api-handler"
  reserved_concurrent_executions = 40   # hard ceiling of 40 connections
  # ...
}

It's an uncomfortable call, because it means accepting throttling: past 40 simultaneous invocations, Lambda starts rejecting. But I'll take a bounded failure in one function over a database that stops accepting connections and takes down the workers, the migrations and the admin panel along with it — none of which had anything to do with the spike. A limit isn't a restriction. It's deciding in advance who suffers first when something breaks.

RDS Proxy: what it solves and what it doesn't

RDS Proxy sits between Lambda and the database and maintains its own set of already-open connections. Your functions talk to the proxy, and the proxy multiplexes: many ephemeral clients over a handful of real, reused connections.

What you genuinely gain:

• It absorbs spikes. When the database is at its ceiling, the proxy queues instead of rejecting.
• It removes connection setup cost from every cold start. That shows up in p99 latency more than you'd expect.
• Cleaner failover. It holds the client connection open while the engine switches over.

What's worth knowing before you adopt it:

• It isn't free. It bills per vCPU of the database instance, and on small workloads it can cost more than simply sizing the database up.
• Pinning will ruin the party. Long transactions, session-level prepared statements, SET on session variables or temp tables all make the proxy pin a connection to your session and stop multiplexing. You end up paying for a proxy that reuses nothing. It's visible in CloudWatch as DatabaseConnectionsCurrentlySessionPinned, and it's the first thing I check when someone tells me the proxy "did nothing".
• It lives inside the VPC. Which means putting your Lambda in private subnets, with everything that drags along in cold starts and networking bills.

What I'd do today

The order matters, and almost nobody follows it:

1. Hoist the pool out of the handler and set max: 1. Five minutes, zero cost, and it solves most cases outright.
2. Set reserved_concurrent_executions on the functions that touch the database. Also free, and it turns a total outage into a bounded degradation.
3. Measure before you buy. Watch DatabaseConnections in CloudWatch during a real spike. If you're nowhere near the ceiling, you don't need a proxy.
4. Add RDS Proxy when traffic is genuinely spiky and you've confirmed your queries don't trigger pinning.

And one non-technical note: if 90% of your application is CRUD against PostgreSQL with reasonably steady traffic, the right answer probably isn't any of those four. It's a long-lived container with a normal, boring pool. Lambda is superb for bursty work. Against a relational database under sustained load, you're often paying in complexity to solve a problem you never had.

The centered spinner is the worst possible default

A spinner in the middle of the screen says exactly one thing: "something is happening, I do not know what, I do not know how long". It wipes out the structure you already knew and replaces it with a wheel. When the data arrives, the interface appears all at once in a different position and your eye has to re-orient itself.

The underlying problem is that it treats the page as an atomic unit: either everything is there or nothing is. That is almost never true. In a typical dashboard, the title, the navigation, the filters and the shape of the cards are all known before you request a single byte from the server. The only missing part is the numbers. Blocking the 90% of the interface you could already paint in order to wait for the 10% you cannot is throwing away perceived performance.

The rule I follow: paint everything you already know, and mark as pending only what genuinely depends on the server.

Skeletons that do not shift: reserve the real space

A skeleton is a placeholder shaped like the final content. It works for two reasons: it communicates what is about to appear and, more importantly, it reserves the space so nothing jumps when it does. If your skeleton is 40px tall and the real row is 72px, you have traded a spinner for a layout shift, which is worse.

That is why I build them from the same component instead of a parallel mockup that drifts out of sync on day one:

function CandidateRow({ data }) {
  return (
    <li className="row">
      <span className="avatar">{data ? <img src={data.avatar} alt="" /> : null}</span>
      <span className="name">{data ? data.name : <Block w="60%" />}</span>
      <span className="title">{data ? data.title : <Block w="35%" />}</span>
    </li>
  );
}

The row keeps the same height and the same grid in both states, so going from skeleton to data is a content change, not a layout change. CSS does the heavy lifting:

.row { display: grid; grid-template-columns: 40px 1fr 1fr; min-height: 72px; }
.avatar { aspect-ratio: 1; border-radius: 50%; background: var(--gray-200); }

@media (prefers-reduced-motion: no-preference) {
  .block { animation: pulse 1.4s ease-in-out infinite; }
}

Two details that always get forgotten: min-height on the row (it prevents CLS when the real content is taller) and honoring prefers-reduced-motion, because a screen full of pulsing blocks is exactly the kind of animation that makes some people queasy.

Streaming with Suspense: do not wait for the slowest call

When a page requests four things, the usual shape is 80ms, 120ms, 150ms… and 900ms. If you wait for all of them before painting, your page takes 900ms. With streaming, the server sends the HTML for whatever is ready and the rest arrives later over the same connection.

In React you express this with Suspense boundaries. Each boundary is a promise to the user: "this part is coming later, the rest is already here".

export default function Dashboard() {
  return (
    <Layout>
      <Header />                          {/* instant, no data */}
      <Suspense fallback={<KpisSkeleton />}>
        <Kpis />                          {/* fast */}
      </Suspense>
      <Suspense fallback={<TableSkeleton rows={8} />}>
        <ReportsTable />                  {/* the slow one: 900ms */}
      </Suspense>
    </Layout>
  );
}

The syntax is not the interesting part — where you put the boundaries is. One boundary per page buys you nothing: you are back to the global spinner with extra steps. One boundary per tiny component is not better either: you end up with a screen that flickers in pieces for two seconds and feels broken. My rule is to wrap blocks the user perceives as a single unit — a card, a table, a sidebar — and above all to isolate the slow thing so it does not hold the fast things hostage.

The detail that killed the most complaints: delay and hold

If a request takes 90ms and you show a skeleton, the user sees a flicker: it appears and disappears before the eye can process it. That flash reads as a glitch, not as speed. A skeleton shown for 40ms is more annoying than no skeleton at all.

The fix is not technical, it is about timing: do not show the loading state before ~200ms, and once you show it, hold it for at least ~400ms.

export function useVisibleLoading(loading: boolean) {
  const [visible, setVisible] = useState(false);

  useEffect(() => {
    if (!loading) return;
    const delay = setTimeout(() => setVisible(true), 200);
    return () => clearTimeout(delay);       // finished early: never seen
  }, [loading]);

  useEffect(() => {
    if (loading || !visible) return;
    const floor = setTimeout(() => setVisible(false), 400);
    return () => clearTimeout(floor);       // already visible: hold 400ms
  }, [loading, visible]);

  return visible;
}

With this, fast responses show nothing at all — which is what you want, since they are already fast — and slow ones show a stable state instead of a flicker. It is the smallest change I have shipped with the most direct impact on "hey, the app feels way better now".

What I do today on every new screen

Before writing the first fetch, I ask three questions: what can I paint with no data (that goes outside every boundary), which blocks does the user read as units (that is where the Suspense boundaries and their skeletons go), and which call is the slow one (that one always gets isolated, even if it is the most important thing on the screen).

The mental mistake that took me years to unlearn was thinking of loading as a binary moment — loading or loaded — when it is really a sequence you get to choreograph. The same 900ms request can feel like a broken app or a living one, and the difference is not in the backend: it is in what you choose to show during those 900ms. Getting that call from 900ms to 600ms costs an afternoon and almost nobody notices; designing what people look at in the meantime costs an hour and everybody does.

The cache key is 90% of the problem

A CDN stores responses indexed by a key. If two requests produce the same key, the second one is a hit. Everything you put into that key multiplies the number of possible entries and divides your hit rate.

The case I've run into most: someone forwards the session cookie to the origin "because the app needs it" and accidentally puts it in the cache key too. From that moment on, every user gets their own copy of every resource. Technically there's a cache; in practice it caches nothing. Same story with forwarding all query strings: a campaign's utm_source values turn one URL into fifty.

The piece that fixes this is realizing CloudFront has two separate policies: the cache policy defines what goes into the key, and the origin request policy defines what gets sent to the origin. They are not the same thing. The cookie can travel to your origin without fragmenting the cache.

resource "aws_cloudfront_cache_policy" "static" {
  name        = "static-assets"
  min_ttl     = 0
  default_ttl = 86400
  max_ttl     = 31536000

  parameters_in_cache_key_and_forwarded_to_origin {
    enable_accept_encoding_brotli = true
    enable_accept_encoding_gzip   = true

    cookies_config { cookie_behavior = "none" }
    headers_config { header_behavior = "none" }

    query_strings_config {
      query_string_behavior = "whitelist"
      query_strings { items = ["v"] }
    }
  }
}

The rule I apply without exceptions: the cache key starts empty and you add whatever you can justify. Never the other way around.

Cache-Control decides; the distribution only sets limits

The distribution's TTLs confuse a lot of people because they look like the main configuration, and they aren't. default_ttl only applies when the origin sends no cache headers. max_ttl is a ceiling. min_ttl is a floor. The real decision-maker is your origin, route by route.

And that's where the header with the best performance-per-character I know lives: s-maxage.

# Bundle with a content hash in its name: genuinely immutable
Cache-Control: public, max-age=31536000, immutable

# HTML for a page that changes: the browser doesn't keep it, the CDN does
Cache-Control: public, max-age=0, s-maxage=300, stale-while-revalidate=86400

max-age talks to the browser; s-maxage talks to shared caches —the CDN— and takes precedence over it. That separation is what lets you ship changes fast: the user's browser holds nothing, the edge holds five minutes, and purging the edge is under your control. Purging someone's browser never is.

💡 If your HTML leaves the origin with max-age=3600, you don't have a CDN problem: you have users stuck on an old version for an hour with no way to fix it. max-age=0, s-maxage=3600 caches just as well and can actually be rolled back.

Invalidation is plan B; versioning is plan A

Invalidations are the tool everyone reaches for first and the one you should need least. They're asynchronous, they take time, the first 1,000 paths a month are free and then billed, and above all: a /* on every deploy empties the whole cache and sends all your traffic to the origin at once, right at the moment you just deployed. That's the worst possible combination.

The alternative is making invalidation unnecessary. If your assets carry a content hash in the filename, a deploy doesn't modify files: it publishes new files, at new URLs, that nobody has cached. There's nothing to invalidate. The only thing that moves is the entry document, and that one already has a short s-maxage.

When it's still needed, I scope it:

# Plan B, and scoped: entry documents only
aws cloudfront create-invalidation \
  --distribution-id E2XXXXXXXXXXXX \
  --paths '/index.html' '/blog/*'

stale-while-revalidate: let the origin stop suffering

Without stale-while-revalidate, TTL expiry is a cliff: the request that arrives right after it waits for the origin to respond in full. Under real traffic, several requests arrive at once and all of them hit the origin for the same URL.

With SWR, the edge serves the stale copy immediately and revalidates in the background. The user never pays the refresh latency, and your p99 stops showing periodic spikes that correlate with nothing. Add stale-if-error and you get a degraded mode for free: if the origin returns a 5xx, the last good copy keeps being served instead of propagating the error.

If the origin still feels the revalidation traffic, Origin Shield adds an intermediate cache layer that consolidates those requests. It costs extra: I turn it on when the data asks for it, not by default.

How I measure before touching anything

The console's CacheHitRate tells you that you have a problem, not where it is. That's what the logs are for: every line carries x-edge-result-type with Hit, RefreshHit, Miss, Error. Grouping by URI and by that field gives you the diagnosis in one query.

SELECT uri, x_edge_result_type, count(*) AS n
FROM cloudfront_logs
WHERE date >= current_date - interval '7' day
GROUP BY 1, 2
ORDER BY n DESC
LIMIT 50;

If the same URI shows up near the top with Miss and high volume, there are only two explanations: the cache key is fragmenting it, or the origin is sending a Cache-Control that prevents caching. Both take ten minutes to fix once you know which one it is.

What I'd do today, in this order

Decide Cache-Control at the origin per route type before anything else. Start the cache key empty and add only what's justifiable. Put content hashes in asset filenames so invalidation becomes exceptional. stale-while-revalidate on anything that's HTML. And measure with x-edge-result-type before pulling the next lever.

A badly configured CDN isn't neutral: it adds a hop, a layer for bugs to hide in, and a transfer bill you pay twice. Configured well, it's one of the few things in AWS where savings and latency improve in the same direction. The difference between those two versions isn't the product: it's three decisions that fit in an afternoon.

What INP measures, and why LCP doesn't cover it

LCP (Largest Contentful Paint) answers "how long until the main content showed up?" It's a startup problem: it happens once, at the beginning. INP is something else entirely. Across the whole session, every click, every tap, every keystroke fires a cycle of "browser receives the event → runs your JavaScript → repaints." INP keeps the worst of those latencies, and that's your grade.

The distinction matters because modern apps live in interaction, not in load. A dashboard, an editor, a filter panel: the user loads once and then interacts a thousand times. If every filter they toggle freezes the UI for 300ms, your perfect LCP won't save you. A good INP threshold is 200ms; above 500ms it feels broken.

The culprit is almost always the same: long tasks

The browser runs your JavaScript on a single thread. While a function is running, it can't repaint or handle another event until that function returns. If clicking kicks off a computation or a render that takes 250ms, then for those 250ms the interface is dead: the button doesn't show its active state, nothing moves. That's a "long task," and it's 90% of the INP problems I've debugged.

The classic pattern: a search input that, on every keystroke, filters and re-renders a list of 2,000 items. Each press rebuilds the whole tree before letting the browser paint the very text you're typing. The result is an input that stutters even though the filtering is trivial.

// Find where the time goes: log any task that blocks >50ms
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.warn('Long task:', Math.round(entry.duration), 'ms', entry);
  }
}).observe({ type: 'longtask', buffered: true });

Before optimizing anything, I measure. The longtask PerformanceObserver tells you which interactions block the thread and for how long. Don't guess: it's almost never what you think.

Fixing it in React: separate the urgent from what can wait

The key idea is that not everything an interaction triggers is equally urgent. When you type into a search box, showing the character you just typed is extremely urgent; recomputing the filtered list can wait 50ms without anyone noticing. React 18 gave me the tools to say exactly that.

useDeferredValue marks a value as "low priority": React paints the urgent input (the text in the box) first and recomputes the derived work afterward, without blocking.

function Search({ items }) {
  const [query, setQuery] = useState('');
  const deferred = useDeferredValue(query);

  // Recomputed from the deferred value, not on every keystroke
  const filtered = useMemo(
    () => items.filter((i) => i.name.includes(deferred)),
    [items, deferred],
  );

  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <List items={filtered} />
    </>
  );
}

The input responds instantly because its render doesn't wait for the filtering. For heavier actions — switching tabs, applying a filter that reshuffles half the screen — I reach for useTransition, which wraps the expensive update and lets the click show its feedback before the work starts:

const [pending, startTransition] = useTransition();

function onFilter(next) {
  setActiveFilter(next);            // urgent: the button marks itself now
  startTransition(() => {
    setResults(recompute(next));    // non-urgent: doesn't block the click
  });
}

When there's no React involved: yield the thread

Sometimes the heavy work isn't a render, it's a loop: processing a CSV, transforming a large JSON. There the fix is to slice the long task into chunks and hand control back to the browser between them, so it can handle clicks and repaint. The modern way is scheduler.yield(); the timeless fallback is setTimeout(0).

async function process(rows) {
  for (let i = 0; i < rows.length; i++) {
    work(rows[i]);
    if (i % 100 === 0) await yieldToMain(); // breathe every 100 rows
  }
}

const yieldToMain = () =>
  'scheduler' in window && 'yield' in scheduler
    ? scheduler.yield()
    : new Promise((r) => setTimeout(r, 0));

If the work is genuinely CPU-bound and doesn't need the DOM, the right answer isn't chunking but moving it into a Web Worker: another thread, zero blocking of the main one. But for most cases, yielding the thread every N iterations already turns a freeze into something imperceptible.

What I learned by measuring, not guessing

INP taught me to stop conflating "fast to load" with "fast to use." They're different axes, and the user feels the second one most, because they spend 99% of their time interacting, not loading. The good news is it almost always gets fixed without rewriting anything: you find the long task with longtask, decide what's urgent and what can wait, and use the right tool — useDeferredValue, useTransition, yielding the thread, or a worker. My rule is simple: if an interaction blocks the thread for more than 200ms, it's not an optional micro-optimization, it's a quality-perception bug. And perception bugs are the ones that make people say "I don't know, it feels slow" and not come back.

The two axes: dimensions and precision

When you want an embedding to take up less space, there are exactly two levers. The first is truncating dimensions: keeping the first N components of the vector instead of all of them. The second is quantizing: lowering the precision of each component, from float32 to int8 or even to a single bit.

These levers multiply. A 1024-dimensional vector in int8 takes 1 KB versus 4 KB for the same vector in float32, and versus 12 KB for the full 3072-dimensional float32 vector. Twelve times less memory. The question isn't whether that saves money —obviously it does— but how much recall you lose along the way.

Truncating dimensions isn't as barbaric as it sounds

Truncating an arbitrary vector destroys information unpredictably: there's no guarantee the first components are the important ones. What changed the landscape is matryoshka-style training, where the model is explicitly trained so that prefixes of the vector are, on their own, useful representations. The first dimensions carry the coarse signal; the last ones refine nuance.

If your model supports this scheme —OpenAI's main models and several open ones do— truncating is literally slicing the array and renormalizing:

function truncate(vector: number[], dims: number): number[] {
  const slice = vector.slice(0, dims);
  const norm = Math.hypot(...slice);
  return slice.map((v) => v / norm); // renormalizing is mandatory
}

That renormalize is not optional. If you use cosine similarity with normalized vectors and truncate without normalizing again, magnitudes stop being comparable and distances get dirty. It's the most common error and the quietest one: nothing blows up, results just get worse.

If your model is not trained with matryoshka, don't truncate. There the honest reduction goes through PCA or a learned projector, and that's one more component to maintain, version, and reindex.

Quantizing: int8 nearly free, binary with caveats

Dropping from float32 to int8 preserves surprisingly high recall —in my tests the loss has been marginal— in exchange for a quarter of the memory. The trick is calibration: you need to know the actual range of your components in order to map it to int8's range, and that range is computed over a representative sample of your corpus, not over the first batch you happen to have on hand.

Binary quantization is another story. You reduce each component to one bit based on its sign, take up 32 times less space, and compare with Hamming distance, which is an XOR and a popcount: brutally fast. But you lose recall visibly. Nobody serious uses binary as the final answer; it's used as a filter.

💡 The right question isn't "what precision do I use?" but "what precision do I use in each phase?". Searching and deciding are different problems and deserve different representations.

The pattern I use: search cheap, decide expensive

Instead of choosing a single format, I store two. A small, quantized vector to traverse the index, and the full float32 vector —or something close— to rerank the few candidates that survive.

The first phase retrieves, say, the 200 nearest candidates using the cheap vector. It's a recall phase: it only has to guarantee the good ones are inside those 200, not that they're well ordered. The second phase takes those 200, computes similarity with the full-precision vector and orders them for real. That second phase touches 200 vectors, not a million, so index memory doesn't constrain it: the full vectors can live on disk or in a regular Postgres table.

-- Phase 1: cheap recall over the quantized vector (indexed)
WITH candidates AS (
  SELECT id
  FROM documents
  ORDER BY embedding_int8 <=> $1::vector
  LIMIT 200
)
-- Phase 2: rerank the 200 with the full-precision vector
SELECT d.id, d.title, d.embedding_full <=> $2::vector AS distance
FROM documents d
JOIN candidates c ON c.id = d.id
ORDER BY distance
LIMIT 10;

This is exactly the same idea as putting a reranker on top of semantic search, but one floor down: instead of an expensive model reordering, it's an expensive vector reordering. And you can combine both.

How I decide the cutoff

There's no magic number. What I do is measure. I freeze a set of queries with their known relevant results, define recall@10 with the full float32 vector as the reference, and try configurations: 3072/float32, 1024/float32, 1024/int8, 512/int8, binary+rerank. Each one gives a (recall, memory) pair. With that table in front of you the decision stops being an argument about opinions and becomes an explicit trade-off choice.

My default bias, when the corpus is large: medium dimensions with int8 in the index, full vector stored separately for the second phase. I chose that because the index's memory cost drops nearly an order of magnitude, in exchange for a two-step query instead of one and for keeping two columns in sync when you reindex. That's the real price, and it needs saying: every compression scheme is a pending migration. The day you change embedding models, you reindex both columns.

And a final warning: don't optimize this before you have the problem. With a hundred thousand vectors, full float32 fits in memory without breaking a sweat and you won't notice the difference. Compression is an answer to a concrete constraint, not a virtue in itself.

The base case: a <form> that already works

A form with action and method sends data to the server and navigates to the result. No JS. Inputs with required, type="email", minlength or pattern validate on the client without a line of code. The associated <label> gives you accessibility for free. The submit button shows a native browser loading state.

<form action="/api/contact" method="post">
  <label for="email">Email</label>
  <input id="email" name="email" type="email" required />
  <button type="submit">Send</button>
</form>

That works on a phone with half a network, while your bundle is still downloading, with JS disabled, or when a third-party script blows up and takes hydration down with it. On an Astro site, where most islands don't even hydrate, this isn't a hypothetical: it's the page's normal behavior.

Validation can't live in one place only

This is where discipline usually breaks. People validate on the client with a library, and on the server they validate again with different hand-written logic. Two sources of truth, which diverge the moment someone changes a rule.

What I do is have a single schema —Zod— and use it on both sides. On the server it's the truth; the client is a courtesy to give fast feedback. And crucially: if the JavaScript didn't load, the server still validates and returns a page with the errors. The base case is never left unprotected.

// shared
export const contact = z.object({
  email: z.string().email('Invalid email'),
  message: z.string().min(10, 'Tell me a bit more'),
});

// server: the only truth
export async function POST({ request }: { request: Request }) {
  const data = Object.fromEntries(await request.formData());
  const res = contact.safeParse(data);
  if (!res.success) {
    // no JS: render the page back with the errors
    return renderWithErrors(data, res.error.flatten().fieldErrors);
  }
  await save(res.data);
  return new Response(null, { status: 303, headers: { Location: '/thanks' } });
}

Note the 303 with Location. That redirect after a successful POST is the POST/Redirect/GET pattern, and it prevents refreshing the page from resubmitting the form. It's from 1998 and it's still correct.

💡 If your form breaks when JavaScript fails, you didn't have a form. You had a widget that looked like one.

Adding JavaScript on top, not underneath

With a solid base case, JS comes in to improve things. And it does so by listening to the submit of the form that already exists, not by building a new one.

form.addEventListener('submit', async (e) => {
  e.preventDefault(); // only runs if this script loaded
  const data = new FormData(form);
  const res = contact.safeParse(Object.fromEntries(data));
  if (!res.success) return paintErrors(res.error.flatten().fieldErrors);

  button.disabled = true;
  const r = await fetch(form.action, { method: 'POST', body: data });
  button.disabled = false;
  if (r.redirected) location.assign(r.url);
});

The key is the mental ordering: preventDefault() is an optional optimization that only happens if the script ran. If it doesn't run, the browser does its usual job. There's no broken path, there's a less polished path.

And notice something else: I use new FormData(form) instead of reading React state. The DOM is already the form's state. Keeping a copy in useState synced on every onChange is work the platform does for free, and it's the cause of half the form bugs I've debugged: controlled inputs that lose the cursor, browser autofill that doesn't fire the event, password managers that fill fields and React state never finds out.

What I gain and what I pay

I gain real robustness: the form works before hydration, on bad networks, with JS down. I gain accessibility nearly for free, because native elements already come with their semantics. I gain less code: no form state reducer, no form library, no duplicated validation.

What I pay is that certain very rich interactions cost more. A field with remote autocomplete, drag-and-drop file uploads, or a multi-step wizard with complex state don't come out of a bare <form>. There I do build a controlled component, but in a localized way: the complex island is controlled, and the rest of the form is still the platform. I chose this because complexity stays contained where I need it, in exchange for having two field-handling styles coexisting in the same file, which is ugly if you don't document it.

I also pay that the "no JS" case has to be tested. If you don't test it, it rots. On projects where this matters to me, I have a test that submits the form with a plain HTTP request, no browser, and checks that the response comes back with the errors rendered. It's a cheap test and it's the only one that guarantees the base case is still alive.

The conclusion isn't "don't use JavaScript". It's that JavaScript should be the second layer, not the foundation. A form that only exists once the bundle loads is a form with a dependency you never agreed to take on.

First: the prophets' track record

Let's review famous predictions and their actual status as of July 2026:

The pattern is crystal clear, and it's the key to this whole post: the optimists get the direction right and the timeline wrong — systematically too fast on the social side and too slow on the technical side. Nobody predicted agents would write code this well this soon; everybody overestimated how fast organizations would absorb it.

The number that anchors any serious prediction

If you can only watch one metric, watch METR's: the length of tasks an agent can complete autonomously (at a 50% success rate) doubles every few months — 196 days on the full historical average, but accelerating toward ~3 months in the post-2024 data. In January 2026, the best models completed tasks of ~5 hours of human work; unofficial trackers already place current models above 14 hours.

If the trend holds — and it has held for six years — by mid-2027 we're talking about agents completing tasks worth a week of human work. That single curve explains almost everything that follows.

The coming months (rest of 2026): agentic consolidation

What I consider practically certain between now and December, because it's already underway:

• Orchestration becomes the job. Karpathy named it "agentic engineering" and he was right: the conversation is no longer "which editor do you use" but "how many agents do you direct in parallel." Fleet tooling (dynamic workflows, remote tasks, cloud agents) becomes standard.
• Bill shock. This year's billing changes (Copilot credits, usage limits everywhere) are the symptom: agentic compute cost becomes a serious line item in every team's budget. FinOps tooling for agents will emerge.
• MCP locks in as the universal standard. The July spec (embedded apps, long-running tasks, serious OAuth) plus Linux Foundation governance make it the TCP/IP of agents. If your product doesn't expose MCP in 2027, it doesn't exist for agents.
• Verification becomes the official bottleneck. With benchmarks like SWE-bench saturated (95% for the best model), the problem is no longer generating code — it's reviewing it. 66% of devs say they lose more time fixing "almost right" AI code than writing. That's where the next wave of tools is.

2027: the year of the interface

My central bet for 2027 isn't about code — it's about interfaces. The pieces are already on the table: agentic browsers (Atlas, Comet, Dia) with tens of millions of users, ChatGPT as an app platform with built-in checkout, and WebMCP so sites can expose actions directly to agents.

What that means in practice:

• Your website will have two audiences: humans and agents. Just as mobile-first happened, agent-first is coming: clean APIs, explicit semantics, actions exposed via MCP/WebMCP. A growing share of your "visits" will never see your CSS.
• Generative UI will find its place — which is not everywhere. The dream of "the app is generated on the fly and deleted after" will collide with what Nielsen has warned about for years: an interface that changes every time is an interface no one can learn. The equilibrium: your UI as a reference implementation, with data and actions open so the user's agent can compose its own.
• Agentic commerce becomes normal. With hundreds of millions of weekly assistant users and standardized purchase protocols, "I asked my agent to order it" stops sounding weird. SEO mutates: from ranking pages to ranking actions and data.

💡 If you maintain a web product, the question for 2027 isn't "do I have a mobile app?" but "can an agent use my product without a screen?". Whoever has a good API and good semantics wins the new channel for free.

2027–2028: what happens to programmers

This is where the noise is loudest and where the data says something more nuanced than the headlines:

• The pyramid restructures; it doesn't disappear. Software engineers are now 55% of Big Tech hiring — more than in 2019 (46%). But new grads are only 7% of those hires, half the pre-pandemic share. More senior hiring, less junior: the pyramid is inverting.
• The jobs moved; they didn't vanish. US dev postings are up 14% year over year, but 71% of that increase is senior roles and 37% carry "AI" in the title. Average AI engineer compensation sits around $242K, and agent-focused roles are growing +136% year over year.
• The 2029 shortage is being manufactured today. CS enrollment falling 8% a year, bootcamps closing in waves, companies not hiring juniors. Nobody is training the seniors of five years from now. Concrete prediction: around 2028–2029, a senior-talent-shortage panic and "AI apprenticeship" programs everywhere, hiring juniors again — with a different profile: systems design and verification, not syntax.
• The "because of AI" layoffs will continue — and won't be only because of AI. 2026 has seen ~120,000 tech layoffs with AI as a partial excuse — a mix of real automation, past overhiring and margin pressure. Untangling how much is which will be impossible, and the "AI took my job" narrative will coexist with record demand for engineers who know how to direct it.

2028–2030: the three scenarios

More than two years out, the honest move is scenarios with probabilities, not certainties. Mine:

• Continued acceleration (~35%). The METR curve holds with no ceiling: agents with weeks of autonomy in 2027, a functional "digital employee" toward 2028–29. This is the labs' scenario (though even Amodei and Altman have softened the apocalypse talk this year — curiously, on their way to IPOs).
• Useful plateau (~50%). The one I find most likely. Code generation keeps improving but the hard problems — persistent memory, continual learning, long-horizon coherence — prove stubborn, as Marcus and LeCun warn (LeCun left Meta to found a world-models startup precisely over this). Agents become infrastructure the way the cloud did: transformative, not apocalyptic. "AI 2027"-style forecasts have already slipped to "early 2030s," and Metaculus puts 50% on AGI by 2033.
• Partial winter (~15%). Compute spending doesn't find returns at the promised pace, a hard valuation correction, consolidation. Note: even here, the capabilities already deployed don't go away — nobody is going back to writing CRUD by hand.

My concrete predictions, so I can fail in public

Since I've spent this post auditing other people's predictions, it's only fair to leave mine in writing, dated, so they can be audited:

// Predictions — July 2026 (review in July 2027)
// 1. By Dec 2026: agents reliably complete tasks worth
//    ~2 days of human work.                          [80%]
// 2. By Jun 2027: >50% of new code at tech companies is
//    AI-generated (industry average, not just labs).  [70%]
// 3. By 2027: at least one top-100 app drops its
//    traditional UI for an agentic/conversational one. [60%]
// 4. By 2028: junior hiring recovers in an AI-apprentice
//    format after the shortage panic.                 [65%]
// 5. By 2030: MORE people work in software than in 2025
//    (counting the new roles).                        [75%]
// 6. AGI / drop-in digital worker before 2030.        [25%]

The honest closing

Prediction number 5 is the one that really matters, and the one I'm most convinced will come true. Every time the cost of creating software has collapsed — compilers, open source, the cloud — the world didn't want less software: it wanted orders of magnitude more. Software demand has always been supply-constrained, and we just made the supply nearly infinite.

What disappears isn't the programmer; it's the programmer defined as "a person who translates specifications into syntax." What's being born looks more like a systems director who decides, verifies and answers for the result. The next three years will be uncomfortable, uneven and full of exaggerated headlines in both directions. But if I had to pick one moment in history to know how to build software, I'd pick exactly this one.

Why the NAT Gateway exists

A private subnet, by definition, has no route to an Internet Gateway. That's what makes it private: nothing outside can initiate a connection inward. But your containers do need to get out: to pull an image from ECR, to read a secret, to call a third-party API.

The NAT Gateway solves that: it lives in a public subnet, private subnets route their outbound traffic to it, and it translates addresses so responses come back. It works, it's managed, it's highly available within its AZ. And that's why everyone puts it there and forgets about it.

The problem is its pricing model. You pay an hourly rate per NAT Gateway —and since each one lives in an AZ, the recommended high-availability practice asks for one per AZ, so multiply— plus a rate for every gigabyte that crosses it. That per-gigabyte charge applies to processed traffic, and it accumulates without anyone watching.

The uncomfortable discovery: much of that traffic is internal

Here's the detail that changes the analysis. When your Fargate task in a private subnet writes an object to S3, that traffic exits through the NAT Gateway, goes to S3's public endpoint, and comes back. You're paying transfer to talk to an AWS service that sits in the same region as you.

Same with DynamoDB, with SQS, with Secrets Manager, with CloudWatch Logs —and CloudWatch Logs is the big silent suspect, because if you have verbose logs, every line is billed traffic— and with ECR every time a task starts and pulls image layers.

In well-populated serverless or container architectures, most outbound traffic isn't really going to the internet. It's going to AWS.

VPC endpoints: two flavors, very different prices

A VPC endpoint lets your private subnet talk to an AWS service without going through the internet or the NAT. There are two types, and confusing them is expensive.

Gateway endpoints exist only for S3 and DynamoDB. They're an entry in the route table. They cost nothing: not per hour, not per gigabyte. There is no defensible reason not to have them if you use S3 or DynamoDB from private subnets. It's money thrown away.

Interface endpoints (PrivateLink) are for everything else: SQS, Secrets Manager, ECR, CloudWatch, KMS. They create a network interface in your subnet with a private IP. These do cost: an hourly rate per endpoint per AZ, plus a per-gigabyte charge —quite a bit cheaper than the NAT's, but not zero.

💡 S3 and DynamoDB gateway endpoints are free. If your private subnets don't have them, you're paying NAT Gateway to talk to S3. That's the first place to look, and usually the most profitable.

How I decide which endpoints to create

With interface endpoints the math isn't automatic, because they have a fixed cost per hour per AZ. An endpoint pays off when the savings in NAT traffic exceed that fixed rate. The way to know is to look at the data, not guess: I enable Flow Logs on the NAT Gateway's elastic network interface and group by destination IP, resolving those IPs against AWS's published ranges to know which service is which.

With that table in front of you the decision is arithmetic. If 60% of your NAT traffic is to S3, a free gateway endpoint takes all of it. If another 20% is CloudWatch Logs, the interface endpoint pays for itself. If there's 5% to KMS, the fixed cost probably isn't worth it.

In OpenTofu it's so little code it's almost embarrassing not to have it:

# Free. No excuses.
resource "aws_vpc_endpoint" "s3" {
  vpc_id            = aws_vpc.main.id
  service_name      = "com.amazonaws.${var.region}.s3"
  vpc_endpoint_type = "Gateway"
  route_table_ids   = aws_route_table.private[*].id
}

# Paid: creates one ENI per subnet. Justify it with data.
resource "aws_vpc_endpoint" "logs" {
  vpc_id              = aws_vpc.main.id
  service_name        = "com.amazonaws.${var.region}.logs"
  vpc_endpoint_type   = "Interface"
  subnet_ids          = aws_subnet.private[*].id
  security_group_ids  = [aws_security_group.endpoints.id]
  private_dns_enabled = true # without this, your SDK keeps going to the public endpoint
}

That private_dns_enabled is what makes it work without touching code: it resolves the service's public name to the endpoint's private IP. If you leave it at false, you create the endpoint, pay for it, and your application keeps happily exiting through the NAT. It's an error you only see on the bill.

The most uncomfortable question: do you need the NAT?

Before optimizing the NAT Gateway it's worth asking whether it's needed at all. If your containers only talk to AWS services and never call a third-party API, you can cover everything with endpoints and remove it. It's the only optimization that takes that cost to zero.

In practice there's almost always something going out to the internet: a webhook, a payment gateway, an LLM provider. So the NAT stays, but with most traffic diverted, and its bill goes from being a mystery to being a small, explainable line.

The honest trade-off: you add networking components that have to be maintained, versioned in your IaC, and debugged when a misconfigured security group makes an endpoint throw timeouts instead of clear errors. In exchange, internal traffic stops touching the internet —which is also better security posture— and the bill stops growing with your log volume. For me it's always been worth it. But decide it with Flow Logs, not with this article.

This isn't a motivational post or a list of "5 courses so you don't fall behind." It's what I see from the inside — working every day with agents that write most of my code — about what's really changing, what's losing value, what's gaining it, and what I would do today depending on where you are in your career.

First: separate signal from noise

The confusion comes from mixing up two different questions. "Can AI write code?" — yes, it has for a while now, and better than most of us on well-scoped tasks. "Can AI do an engineer's job?" — no, because the job was never writing code.

The job was always something else: understanding an ambiguous problem, deciding what to build (and what not to), negotiating constraints, noticing that the ticket asks for one thing but the business needs another, and answering for what ships. None of that has been automated. What got automated was the part in the middle: translating decisions into syntax.

💡 The sentence that keeps my head straight: AI isn't coming for your job, it's coming for your tasks. If your job was the sum of those tasks, you do have a problem. If your job was the judgment that ordered them, you just got multiplied.

What's losing value (and it hurts to say)

Let's be honest about what's already worth less in the market:

• Writing correct, clean code by hand. It was our identity. Today it's the baseline any well-directed agent produces.
• Knowing a framework by heart. Encyclopedic API knowledge used to be a competitive edge; now it's one prompt away from anyone.
• The junior who only executes tickets. This is the hardest hit and the most real one: "take this well-defined task and bring it back done" is exactly what agents do best.
• Typing speed as a productivity metric. Producing more lines no longer sets anyone apart. What does is producing fewer lines that survive longer.

What's appreciating

The opposite list is more interesting, because it's where you should invest:

• Review judgment. AI-generated code looks impeccable — formatted, sensibly named, commented. The danger lives in what looks correct. Reading code with suspicion is now worth more than writing it.
• Architecture and decomposition. An agent performs in direct proportion to how well-scoped the problem is. Slicing a system into pieces an AI can execute without breaking anything is the new senior skill.
• Business context. Understanding why something is being built is the one thing AI can't infer from your repo. The engineer who talks to product and to customers becomes impossible to replace.
• Verification. Tests, evals, observability, staging environments that resemble production. When code volume multiplies, the bottleneck moves to trust: how do I know this works?
• Accountability. Someone has to sign off on the deploy. The AI doesn't attend the postmortem. That "someone" is trading up.

The new workflow (mine, at least)

My day-to-day no longer resembles what it was three years ago. The pattern that works for me has three phases, and none of them is "writing code":

// My division of labor with agents
// 1. BEFORE — invest in context: clear specs, documented
//             conventions, explicit acceptance criteria.
// 2. DURING — steer, don't dictate: the agent proposes, I cut
//             scope, correct course, ask for alternatives.
// 3. AFTER  — verify with hostility: read the diff as if it were
//             written by someone trying to fool me, run the
//             tests, poke at the edges.

The ratio surprises anyone who hasn't lived it: I spend roughly 40% of my time in phase 1. The quality of what comes out of an agent is a nearly linear function of the quality of the context that goes in. Teams that adopt AI and see no improvement almost always fail there: they delegate the writing but don't invest in the specification.

If you're just starting out: the uncomfortable advice

The entry-level rung broke, and denying it helps no one. But notice the nuance: the rung broke, not the ladder. Companies still need seniors, and seniors aren't born — they're made. Sooner or later the market will have to rebuild the pipeline, and the juniors who survive this transition will be the ones who arrived differently:

• Use AI to learn, not to avoid learning. Ask it to explain every line it generates. The difference between "it works and I don't know why" and "it works and I know why" is your entire career.
• Build complete things. A deployed side project, with real users and real bugs, teaches what no tutorial can: the part of the craft AI doesn't cover.
• Learn to actually debug. When the agent gets stuck — and it does — the person who can drop down to the log, the breakpoint and the protocol is the one who unblocks the team.
• Fundamentals don't expire. Networking, operating systems, databases, complexity. The frameworks AI has mastered change every year; the things they stand on don't.

If you've been at this for years: your risk is different

The senior doesn't compete against AI; they compete against the senior who uses it well. And there I see two symmetric mistakes. The first is rejection: "I review better than any model" — true today, irrelevant within two improvement cycles. The second is surrender: accepting everything the agent generates without reading it, until a production incident reminds you whose name was on the deploy.

The middle ground has a boring name: management. You direct a small fleet of agents the same way you used to coordinate people — with specs, with review, with standards. If you ever considered moving into management but didn't want to stop touching code, the good news is that this hybrid role was just invented and nobody has ten years of experience in it.

What doesn't change

After all the vertigo, one thing calms me down: software is still the discipline of deciding what should happen and making sure it does. The tools for getting there have changed more in three years than in the previous twenty, but the nature of the craft — judgment, accountability, translating between what people need and what the machine does — remains intact.

Surviving this era isn't about outrunning the AI. It's about moving one level above it — which is exactly the same move made by those who went from assembly to compilers, and from physical servers to the cloud. The ones who clung to the layer being automated had a rough time. The ones who moved up a layer couldn't keep up with all the work.

Fair warning: there is no perfect stack, only stacks that fit your team and your stage. What follows is biased toward what a small startup optimizes for: iteration speed, low maintenance, and predictable bills.

Coding agents: the most important decision

The tool you write code with defines your velocity more than any framework. The current landscape:

My read: the category no longer competes on "better autocomplete" — it competes on orchestration: how many agents you can direct at once, and with how much confidence. Claude Code is my daily driver for exactly that reason; Cursor is still the best editor if you want a traditional IDE with an agent inside.

💡 Trap of the month: GitHub swapped Premium Requests for "AI Credits" in June, and teams are reporting bills 10x higher on agentic workflows. Whatever your tool, set spend alerts before you unleash parallel agents.

Models: July 2026 prices

If you're building product on top of LLMs, this is what a million tokens costs today (input/output):

The sensible strategy for a SaaS: a cheap model (Sonnet 5, Terra, Gemini) for 90% of calls, escalating to the top tier only when the case justifies it. A 30-line model router saves you thousands of dollars a month.

Web frameworks: less drama than it seems

• Next.js 16.2 remains the rational default for SaaS: Turbopack is stable and on by default, React Compiler is integrated, and the ecosystem of examples is unbeatable. Boring and correct.
• Astro — just acquired by Cloudflare in January — is still my pick for anything content-shaped (this blog runs on Astro). Still MIT, still open governance.
• TanStack Start hit stable v1.0 in March and is the serious alternative if you want extreme type-safety without Next's magic.
• SvelteKit and React Router 7 are mature and excellent; choosing them is more a matter of team taste than capability.

The uncomfortable truth: with agents writing most of the code, framework choice matters less than it did three years ago. Agents perform better on frameworks with a bigger public corpus — another point for Next and Astro.

Backend and infra: the stat of the year

The stat that best sums up 2026: Supabase reported that the majority of its new databases are now deployed by AI agents, not humans — database creation growing 600% year over year. Your infrastructure is no longer chosen only by your team; agents "choose" it too, and they go with what they know how to use.

• Postgres wins by a landslide: Supabase (just raised $500M at a $10.5B valuation) as a full backend, or Neon (now inside Databricks) if you only want the database.
• Vercel for deployment if you go with Next: Fluid Compute genuinely eliminated cold starts.
• Cloudflare Workers + D1 + R2 is the cost-effective alternative — and with Astro in the family, increasingly polished.
• Runtimes: Node 24 is still the enterprise default. Bun — acquired by Anthropic in December — completed its Rust rewrite in May and is my pick for new projects: speed plus built-in tooling.

Your product's AI layer

This is where I see the most over-engineering. What a startup actually needs:

// The minimum viable AI layer in 2026
// 1. SDK: Vercel AI SDK 6 (TypeScript), or the Claude Agent SDK
//    if the product IS an agent. LangGraph 1.0 if you need
//    complex state graphs (that's how Uber and Klarna use it).
// 2. Context: MCP. It's a Linux Foundation standard now,
//    97M monthly downloads. Don't invent your own protocol.
// 3. Vectors: pgvector up to ~10M vectors (~$30/mo).
//    Don't pay for a dedicated vector DB before you have the problem.
// 4. Evals from day one: if you don't measure LLM quality,
//    every deploy is a gamble.

Point 3 deserves emphasis: pgvector in your regular Postgres covers almost any startup with 8–25ms latencies. Notion cut its search costs ~60% by moving off a dedicated vector DB onto object-storage-backed search; you probably don't even need that yet.

Vibe coding: use it for what it is

Lovable ($400M ARR in February, reportedly in talks to raise at an eleven-figure valuation), Replit ($9B valuation in March), v0, Bolt. They are idea-validation machines: prompt to deployed prototype in an afternoon. What they are not — yet — is the foundation of a product that has to scale with serious security and data requirements. The pattern I see working: prototype in Lovable or v0, validate with real users, and rebuild on your stack once there's signal.

My concrete recipe

If I started a B2B SaaS tomorrow, with no more context than "I want to validate fast and not burn money":

• Code: Claude Code as the primary agent + human review of everything touching money, permissions or data.
• App: Next.js 16 + TypeScript on Vercel. Content/marketing: Astro.
• Data: Supabase (Postgres + auth + storage + pgvector).
• AI: Vercel AI SDK 6, Sonnet 5 by default with escalation to Opus 4.8, MCP for integrations, evals with real cases from week one.
• Runtime: Bun locally and in CI; Node 24 wherever the platform demands it.

Is it the most powerful stack possible? No. It's the one that lets you iterate every single day with two and a half people — and in 2026 that's exactly the game: the edge is no longer in the infrastructure you set up, but in how fast you learn what to build.

Before we start, a note on method: I only use publicly sourced figures. When a number is a third-party estimate (rather than company-confirmed) I flag it as such. Even with that filter, what remains is hard to believe.

The curve that defines the era: Cursor

Anysphere (Cursor) was at one point the fastest SaaS in history to reach $100M ARR. That was January 2025. What happened next is the chart that defines this era:

From $100M to ~$4B in annualized revenue in 17 months, with around $2.6B coming from enterprise (B2B). Its November 2025 Series D valued it at $29.3B, and by April 2026 there were reports of talks to raise at ~$50B. For calibration: Salesforce took more than a decade to reach the revenue Cursor hit in three years.

The multipliers of 2026

Cursor is not an isolated case. This is the table for the year so far:

And the backdrop: Anthropic went from a $9B run-rate at the end of 2025 to $47B in May 2026, and Claude Code alone hit $1B annualized within six months of launch. Demand for building with AI is the tide lifting all of these boats.

The most disruptive stat: revenue per employee

What truly breaks mental models is not how much they earn, but with how few people. Annual revenue per employee, in millions of dollars:

For perspective: a well-run traditional software company sits around $200,000–400,000 per employee. The cases above are 5 to 40 times higher:

• Gamma passed $100M ARR with about 50 people, profitable for over two years.
• Midjourney earns ~$500M with fewer than 110 employees and has never raised a dollar of venture capital. Ever.
• Mercor crossed $1B ARR with ~200 people and positive cash flow.
• Cursor operates ~$4B with around 300 employees (an estimate; the figure isn't official).

The small ones: solo founders who exited through the front door

Unicorns get the headlines, but the more replicable stories are elsewhere:

• Base44 (Maor Shlomo). A single bootstrapped founder, building with AI. Launched in early 2025, hit $1.5M ARR in 4 weeks and $3.5M with 300,000 users in 6 months. Wix bought it for $80M in cash six months after launch — and subsequent milestones paid him an extra $38M. Eight employees at the time of sale.
• Cal AI (Zach Yadegari and Henry Langmack). Two founders who started at 17: an app that counts calories from photos using AI. $30M in revenue in 2025, $5.7M in January 2026 alone, and in March — at $50M ARR — MyFitnessPal acquired it.

💡 The pattern they share: neither invented new technology. They applied models anyone can call over an API to a boring, concrete problem, and executed faster than everyone else. The edge is no longer access to AI — it's iteration speed on a use case.

And underneath it all: AI is already writing the code

These successes float on a measurable structural shift. Google has been publishing it with dates:

At Anthropic the reported internal figure exceeds 90%. And at Y Combinator — the best window into the immediate future: already in the W25 batch, 25% of startups had 95% of their code AI-generated; at the W26 Demo Day (March 2026), 14 startups arrived with over $1M ARR before Demo Day — triple the previous year and an all-time record — with average growth of 14% per week, the highest YC has recorded in 20 years.

The patterns that repeat

After looking at all these cases, the common denominators I see:

• Tiny teams by design, not for lack of money. Lovable raised hundreds of millions and stays at ~250 people. The headcount constraint is strategy: less coordination, more agents.
• Speed as the only moat. Almost none of them have defensible technology per se; they have a shipping cadence competitors can't match.
• Distribution first. Cal AI grew through social media before the product matured; Lovable turned every user into marketing with "look what I built."
• B2B pays for the curves. Cursor's and Devin's acceleration comes from enterprise contracts (Goldman Sachs, Citi and NASA are Cognition customers), not individual developers.

The fine print

To be fair to the data: several 2026 ARR figures (Lovable ~$500M, Replit ~$525M, Claude Code) are estimates from trackers like Sacra, not official confirmations; Lovable's round at ~$12B was still in negotiation as of this writing; and for every success story there are hundreds of GPT wrappers that died without a headline — survivorship bias in this list is maximal.

But even discounting all of that, the signal is clear: in 2026 there is no longer a correlation between team size and business size. And for anyone who knows how to build software, that is the best news in decades: it has never been this cheap to try.

First I ask: is this a knowledge problem or a behavior problem?

This is the fork that orders everything else. If the model fails because it doesn't know something —your domain data, internal documentation, facts after its training cutoff— it's a knowledge problem, and knowledge is injected through context, not baked into weights. There, RAG is the default answer.

If the model knows what it needs but consistently responds with the wrong format, tone, or structure, it's a behavior problem. And behavior is a candidate for fine-tuning… but only after prompting falls short, which is later than people think.

Confusing these two branches is the most expensive mistake I see. Nobody fixes the model not knowing your product catalog with fine-tuning: you train it today and tomorrow the catalog changed. And nobody fixes the model refusing to return clean JSON with RAG: no matter how many documents you feed it, the problem is shape, not data.

Prompting: the rung I almost always underestimate

My starting point is always prompting, because it's the only change I ship in minutes and revert in seconds. Before touching anything else, I squeeze clear instructions, representative few-shot examples, and an explicit output structure. At JXBS, a good chunk of what looked like it needed a fine-tuned model was solved with three well-chosen examples in the prompt and a strict output schema.

The cost of this branch is context: every example you add takes tokens you pay for on every call, and a 20-example prompt becomes expensive and slow at scale. That's exactly the symptom that maybe it's time to climb a rung: when you need so many examples that the prompt is half your bill, the pattern is already there and it may be worth baking in.

💡 If you haven't tried to solve it with prompting for at least an afternoon, you don't have the data to justify fine-tuning. "We tried a prompt and it didn't work" isn't prompting, it's an anecdote.

RAG: for knowledge that changes and must be citable

When the problem is knowledge, RAG almost always wins for a reason beyond the technical one: traceability. A RAG system can tell you which document the answer came from. A fine-tuned model gives you the answer from inside its weights, with no source, and when it hallucinates you have nowhere to look.

// Knowledge lives outside the model and updates without retraining
const context = await searchChunks(question, { topK: 5 });
const answer = await llm.complete({
  system: 'Answer only with information in <context>. If it is not there, say so.',
  context,
  question,
});

The trade-off I accept with RAG is operational: now I maintain an ingestion pipeline, embeddings, a vector index, and a chunking strategy. It's more infrastructure than a prompt. In exchange, I update knowledge by changing documents, not retraining, and in a fast-moving domain that's worth gold.

Fine-tuning: the last rung, and I know why I'm climbing it

I reach fine-tuning only when three things hold at once: the behavior I want is stable and repeated, prompting gives it to me but at an unsustainable token cost, and I have enough quality real examples to train on. If any of the three is missing, I don't climb.

What I buy with fine-tuning is a model that does what I want with a short prompt, cheaper and faster per call. What I pay is rigidity: every behavior change is a retrain, the dataset becomes an asset you have to version and care for, and I've introduced an artifact that can go stale silently. Fine-tuning doesn't eliminate RAG either: the most powerful thing I've built combines a model fine-tuned on how to answer with RAG for what to know.

The mistake of skipping rungs

The antipattern that's cost me most is starting at the end. Teams that build fine-tuning for a problem a prompt would have solved, and end up with an expensive-to-maintain model that performs no better than the baseline they never measured. Starting cheap isn't being conservative: it's generating the evidence that justifies the next step. When you finally do fine-tuning after exhausting prompting and RAG, you know exactly what you're buying and why. That clarity is the difference between an engineering decision and a purchase driven by hype.

The problem: orchestration hidden in the code

When one Lambda invokes the next, the process logic —the order, the retries, what to do if step three fails— lives scattered across functions. There's no single place to read "this is how the whole flow works." To understand it you open five files and reconstruct the graph in your head.

The day that process fails in production halfway through, the key question is "which step did it get stuck on and with what data?". With chained Lambdas, the answer is buried in logs from five different functions that you have to correlate by hand. With an orchestrator, the answer is a screen: you see the execution, the exact state where it died, and the input it received.

The state machine as executable documentation

What I value most about Step Functions is that the flow definition is the diagram. There's no Confluence doc going stale: the source of truth for the process is the state machine running in production.

{
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:validate",
      "Retry": [{ "ErrorEquals": ["Timeout"], "MaxAttempts": 3 }],
      "Next": "ChargePayment"
    },
    "ChargePayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:charge",
      "Catch": [{ "ErrorEquals": ["States.ALL"], "Next": "Compensate" }],
      "Next": "Confirm"
    },
    "Compensate": { "Type": "Task", "Resource": "arn:aws:lambda:...:revert", "End": true },
    "Confirm": { "Type": "Task", "Resource": "arn:aws:lambda:...:confirm", "End": true }
  }
}

Notice where the retry and compensation policies live: in the definition, declarative, not scattered across try/catch in every function. Each Lambda goes back to doing a single thing and the orchestrator handles the rest. That's the split of responsibilities I was after.

Retries and compensation without hand-writing them

The reason I migrate flows to Step Functions most often is failure handling. In chained Lambdas, retrying with backoff, distinguishing transient from permanent errors, and compensating already-executed steps when something fails halfway is code you write, test, and maintain yourself, badly, in every function.

In the state machine, Retry and Catch are part of the definition. A timeout retries three times with exponential backoff without me writing a loop. And the saga pattern —if payment fails after reserving inventory, revert the reservation— is expressed with a compensation state you jump to with Catch, instead of with flags scattered across half the backend.

💡 The question I use to decide: do I need to know the exact step where a failed execution got stuck, weeks later? If the answer is yes, explicit orchestration pays for itself in the first incident.

Where I do NOT use Step Functions

Being honest about the trade-offs is what separates a decision from an act of faith. I don't put Step Functions in everything.

For a simple synchronous flow where the user waits for a response on screen, an orchestrator only adds latency and a layer nobody asked for; a direct Lambda is right. I also don't use it for very high-volume, short-duration processes where every state transition is billed: the Standard model charges per transition and at millions of short executions that scales into your bill in surprising ways. For that case I look at Express, which changes the pricing model and the durability guarantee, or straight to an SQS queue with a consumer that does all the work at once.

And there's a human cost: the definition language is one more thing the team has to learn and read. If your flow has two steps and will never grow, that curve isn't worth it.

The real price I paid

The most expensive part of adopting Step Functions wasn't the service, it was rewiring the team's mindset. We went from "the logic is in the code" to "the logic is in the state definition," and for a while people kept putting coordination inside the Lambdas out of habit, duplicating what the machine already did. The rule I set was clear: Lambdas do work, the state machine decides the order. Once the team internalized that boundary, debugging a long process stopped being log archaeology and became looking at a diagram that tells you exactly where you are. That shift, not the JSON syntax, is what makes it worth it.

The symptom that tells you you need a worker

Not every computation goes to a worker. The concrete signal I look for is a long task: a synchronous function that occupies the main thread for more than a few dozen milliseconds and during which the page stops responding. If you open the performance panel and see long yellow blocks right when the UI stutters, there's your culprit.

Typical cases that have led me to a worker: parsing and transforming large files the user uploads, sorting or filtering a dataset of tens of thousands of rows client-side, geometry or image calculations, and running light models in the browser. What they have in common is that they're pure, prolonged CPU work, not network waits. For waiting on a server you don't need a worker: async/await already frees the thread. The worker is for work that burns CPU, not work that waits.

The cost people forget: the message boundary

A worker doesn't share memory with the main thread. They communicate by passing messages, and that data is copied when crossing the boundary (structured clone). That detail is what decides whether the worker pays off: if you send a huge object to the worker, wait for a trivial computation, and get another huge object back, the cost of serializing and copying eats the gain.

The rule I follow is to push a lot of work per boundary crossing. A worker pays off when you send it data once and it does a big computation, not when you call it in a tight loop for small operations. When the data is genuinely large, I use transferable objects: an ArrayBuffer is transferred instead of copied, changing owner without duplicating memory.

// Main thread: transfer the buffer, don't copy it
const worker = new Worker(new URL('./process.ts', import.meta.url), { type: 'module' });
worker.postMessage({ buffer }, [buffer]); // the second arg transfers ownership
worker.onmessage = (e) => renderResult(e.data);

The pattern I use to avoid suffering with postMessage

The raw postMessage / onmessage API turns into event spaghetti the moment you have more than two message types. What I do is wrap the worker in a promise, so that from the rest of the code calling the worker feels like a normal await and not like wiring an event bus.

function runInWorker<T>(worker: Worker, payload: unknown): Promise<T> {
  return new Promise((resolve, reject) => {
    worker.onmessage = (e) => resolve(e.data as T);
    worker.onerror = (e) => reject(e);
    worker.postMessage(payload);
  });
}

For serious cases I use Comlink, which does exactly this but properly: it lets you call worker functions as if they were local, with await, and hides all the messaging. The first time you wrap a worker like this, the mental barrier of "this is complicated" disappears: the worker becomes just another async function.

💡 A worker doesn't make your code faster; it makes your UI smoother. The computation takes the same time or slightly more because of the data copy. What you gain is that the user can keep scrolling and clicking meanwhile. It's an improvement in perception, not throughput.

Where I do NOT reach for a worker

Being honest about the trade-off matters. I don't use a worker when the computation is short: if it takes 5 ms, moving it to another thread only adds messaging latency and a layer of complexity for nothing. Nor when the work is waiting on the network, because that no longer blocks. And I avoid the worker if the algorithm needs to touch the DOM: workers have no DOM access by design, and if your "computation" actually manipulates the interface, it's not a candidate.

The other cost is tooling and maintenance: a worker is another file, another entry point for the bundler, another piece someone has to understand when reading the code. With Vite or whatever modern bundler, the friction dropped a lot, but it's not zero. That's why my threshold is clear: a worker only when there's a measurable long task that visibly stalls the UI. If I can't point to that yellow block in the profiler, there's no worker. Optimizing a block nobody notices is adding complexity to show off architecture, and that isn't engineering, it's decoration.

The mechanics: pgvector is enough

You don't need new infrastructure. If you already use PostgreSQL with pgvector for semantic search — which is my usual setup with Prisma — the cache is just one more table:

CREATE TABLE llm_cache (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  query_text TEXT NOT NULL,
  query_embedding vector(1536) NOT NULL,
  response TEXT NOT NULL,
  model TEXT NOT NULL,
  hit_count INT DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT now(),
  expires_at TIMESTAMPTZ NOT NULL
);

CREATE INDEX ON llm_cache
  USING hnsw (query_embedding vector_cosine_ops);

The read path is a nearest-neighbor query with a threshold:

const [hit] = await prisma.$queryRaw<CacheHit[]>`
  SELECT response, 1 - (query_embedding <=> ${embedding}::vector) AS similarity
  FROM llm_cache
  WHERE expires_at > now()
  ORDER BY query_embedding <=> ${embedding}::vector
  LIMIT 1
`;

if (hit && hit.similarity >= 0.92) {
  return hit.response; // cache hit: zero tokens spent
}

If there's no hit, you call the model, store the response with its embedding, and the next user asking the same thing in different words no longer pays.

The threshold is a product decision, not a technical detail

The whole pattern lives or dies on that 0.92. Too low, and you serve wrong answers to questions that only look alike on the surface — "how do I cancel my subscription?" and "how do I cancel a payment?" have uncomfortably close embeddings. Too high, and your hit rate collapses and the cache never pays for its own complexity.

My approach: start at 0.95, log every hit with both the original and the cached question, and manually review a sample every week. Lower the threshold only when the false positives in the next band are acceptable. In domains with a closed vocabulary (support for a specific product) I've gone down to 0.90; in open domains I wouldn't go below 0.93.

💡 The similarity threshold is not a hyperparameter you tune once: it's a product policy defining how much imprecision you tolerate in exchange for cost. Treat it as such — with logging, periodic review, and an owner.

Invalidation: the hidden price

A semantic cache inherits the classic cache problem and adds one of its own. The classic one: answers expire. If your product changes its billing flow, every cached answer about billing is now a well-written lie. That's why every entry carries expires_at and, more importantly, a category-based invalidation mechanism: I tag entries with the functional area they touch, and when I deploy a change in that area, I wipe the whole category. It's blunt, but it's predictable.

The problem of its own: personalized answers. If the model's response includes user data ("your current plan is Pro"), caching it and serving it to another user is a data leak, not an optimization. My rule is binary: only what passes a prior "generic question" classifier enters the cache. Anything that depends on user context stays out, no exceptions and no special cases.

When not to do it

Trade-offs rule. A semantic cache pays off when traffic has high semantic redundancy (support, FAQs, onboarding), cost per call is relevant, and latency matters — a hit responds in ~50ms versus the 2-4 seconds of a large model. It doesn't pay off when every question is unique (creative tools, analysis of user documents), when answers depend on personal context, or when volume is so low that the LLM bill is noise.

In my case, the signal to build it came from looking at the logs: when you see the same intent expressed twenty different ways day after day, the cache justifies itself. If you haven't looked at your logs yet, start there — you may not need any of this, and that's good news too.

The media query lie

The problem is one of abstraction level. A well-built component knows nothing about the outside world: it takes props, renders, and is supposed to adapt to wherever you place it. But a media query breaks that encapsulation entirely, because it queries a global state —the viewport width— that the component neither controls nor should know about.

The result is that the same component needs to know which layout it's going to live in. The card that looks perfect in the main three-column grid breaks in the sidebar, not because it's poorly built, but because its breakpoint assumes a window width that doesn't match the width it actually has. You end up adding props like variant="compact" to tell it by hand what it should be able to figure out on its own. Every one of those props is a leak in the abstraction.

How it works: the container declares, the child queries

The mechanism has two parts. First you declare that an element is a query container. Then, inside it, you query its size instead of the screen's.

.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

.card {
  display: grid;
  grid-template-columns: 1fr;
}

@container card (min-width: 400px) {
  .card {
    grid-template-columns: 120px 1fr;
  }
}

What changes from a media query is subtle and huge at once: @container card (min-width: 400px) doesn't ask "is the screen wide?" but "is my container at least 400px?". The same card, without a single extra prop, renders in one column inside a 300px sidebar and in two columns inside a wide grid. The component finally adapts to its reality, not to an assumption about the window.

The case that convinced me: one card in three different places

In the design system I had a ProductCard that appeared in three contexts: the catalog grid (wide), a recommendations carousel (medium), and a "recently viewed" sidebar (narrow). With media queries I had three variants and an if in the consumer deciding which to use based on where it went. Three code paths for a single card.

With container queries I deleted the variants. The ProductCard became a single implementation that queries its container and reorganizes on its own. The component stopped needing context about its location, which is exactly what a component should not need. Fewer props, fewer branches, less surface where something can drift out of sync.

💡 If your component needs a variant prop just to fit different widths, you don't have an API design problem: you have a media query where a container query should be. Fix it at the bottom and the prop disappears by itself.

Trade-offs I accepted

None of this is free. Declaring container-type: inline-size creates a size containment context, and that has a consequence you have to understand: the container stops sizing itself to its content along the queried axis. In practice this rarely bites if you wrap with a dedicated wrapper instead of turning an element that already did other things into a container, but it's a real footnote, not a detail you can ignore.

I also accepted a bit more nesting in the markup. The clean pattern is a wrapper that is the container and a child that is what gets styled; querying an element's size while also styling that same element with the query doesn't work well. One extra div per component is a price I pay gladly in exchange for deleting a whole category of context props.

Why this is more than a convenience

What really changed wasn't the CSS, it was where the responsibility lives. With media queries, the responsibility for a component looking good is split between the component and whoever places it: the consumer has to pick the right variant for the slot. With container queries, the responsibility goes back entirely to the component, which is where it belongs.

That's the difference between a design system that scales and one that turns into a catalog of special cases. Every time a component needs to know where it goes to look right, you've created a coupling between the piece and its context. Container queries cut that coupling, and with it, the kind of debt that never shows up in a ticket but slows you down on every new screen.

The problem it solves: the producer shouldn't know its consumers

Picture a simple domain event: OrderConfirmed. When an order is confirmed, you need to bill, notify the customer, reserve inventory, and update analytics. The naive version has the orders service call all four. The day marketing wants to hear about it too, someone has to open the orders code, add the fifth call, test it, and deploy it. The producer piles up responsibilities that aren't its own.

With an event bus, the orders service emits a single event and is done. Each consumer decides whether it cares. Adding marketing means creating a new rule pointing at its target, without touching orders. Coupling shifts from "code to code" to "event schema to event schema," which is far cheaper to maintain.

The rules pattern: filter on the bus, not in the consumer

What I liked most about EventBridge over a classic SNS is that filtering lives in the rule, declaratively, over the event content. I don't hand the event to a Lambda so it can decide whether it matters: the bus only delivers what matches.

{
  "source": ["orders.service"],
  "detail-type": ["OrderConfirmed"],
  "detail": {
    "total": [{ "numeric": [">", 500] }],
    "country": ["ES", "MX", "CO"]
  }
}

That rule only fires for confirmed orders over 500 in three countries. The consumer doesn't run even once for the rest. That if used to live inside the function, invoked millions of times to discard most cases; now the discard is free and doesn't show up in my Lambda bill or my logs.

Where EventBridge is NOT the answer

Being honest about the trade-offs is what separates an architecture decision from an act of faith. EventBridge isn't free on complexity.

If you need the consumer's response, don't use a bus. It's fire-and-forget: you emit and you don't know what happened next unless you set up another event coming back. For a request/response flow —the user is waiting for a result on screen— a direct synchronous call is still the right thing. Dropping an event bus in there only adds latency and a state machine nobody asked for.

I also don't use it when strict ordering is a hard requirement. EventBridge doesn't guarantee order, and it can deliver the same event more than once. If your case needs to process things in exact sequence, an SQS FIFO queue fits better. In fact, a pattern that works for me is EventBridge for the fan-out and SQS as a buffer in front of each slow consumer, combining the best of both.

💡 The question that decides everything: does the producer need to know what happened to the consumer? If the answer is yes, you don't have an event, you have a call. Don't dress it up as event-driven.

At-least-once delivery forces you to be idempotent

This is the detail people discover in production, not in design. EventBridge guarantees at-least-once delivery, which means your consumer can receive OrderConfirmed twice for the same order. If you bill on every reception, you just charged twice.

The solution isn't praying it won't happen: it's designing the consumer so that processing the same event twice yields the same result as processing it once. An idempotency key per event, a table that records "I already processed this ID," and an INSERT ... ON CONFLICT DO NOTHING in Postgres before doing the work with side effects.

async function handle(event: OrderConfirmed) {
  const inserted = await db.processedEvents.createIfAbsent(event.id);
  if (!inserted) return; // already processed, exit clean
  await bill(event);
}

It's not elegant code, it's code that survives reality. Any event-driven architecture that doesn't treat idempotency as a first-class requirement is building on sand.

Observability: the real price I paid

The most expensive thing about adopting EventBridge wasn't the service, it was observability. In a synchronous call you follow the stack trace and see the whole path. On a bus, the producer emitted and left; the consumer failed three hops later; and correlating the two requires that you propagated a correlationId in every event's detail from day one.

I learned it late and paid for it in incidents that cost extra hours just because I couldn't join cause to effect. Now every event carries its correlation ID, every consumer logs it, and a DLQ per rule captures failures so no event is silently lost. With that, the decoupling pays off. Without it, you're trading a coupling problem for a blind-debugging one, and it's not clear you come out ahead.

Where they shine: the classic form mutation

The happy case is a form that mutates data and revalidates the view. With an action, shared Zod validation, and React's own pending state:

// app/projects/actions.ts
'use server';

import { revalidatePath } from 'next/cache';
import { projectSchema } from '@/schemas/project';

export async function createProject(formData: FormData) {
  const session = await getSession();
  if (!session) throw new Error('Unauthorized');

  const parsed = projectSchema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors };
  }

  await prisma.project.create({
    data: { ...parsed.data, ownerId: session.userId },
  });

  revalidatePath('/projects');
  return { ok: true };
}

Zero endpoints, zero HTTP client, the return type travels inferred all the way to the component. For 80% of the mutations in an internal dashboard, this is all you need, and going back to writing route handlers for those cases is nostalgia, not engineering.

The red line: business logic living in the action

The problem starts when the action stops being an adapter and becomes the home of the logic. An action that calculates prices, orchestrates three services, and decides business rules is code that can only be invoked from a React component in that Next.js project. The day the mobile app arrives, or the cron job, or the team that wants a public endpoint, that logic has to be exhumed.

My structural rule: the action calls a service, and the service doesn't know Next.js exists.

// services/projects.ts — framework-agnostic, testable in isolation
export async function createProjectForUser(
  input: ProjectInput,
  userId: string
) {
  // all business logic lives here
}

The action ends up as three lines: authenticate, parse, delegate. If tomorrow I need to expose the same thing via a route handler or an SQS worker, the service is already there. I chose this separation knowing it duplicates a bit of ceremony; in exchange, no business decision is held hostage by the framework.

💡 A Server Action is a transport mechanism with syntactic sugar, not an architecture layer. If deleting Next.js from your project takes business logic with it, the logic was in the wrong place.

The operational limits nobody tells you about until production

They are sequential POSTs. Server Actions execute serially by default from the same client: if the user fires three, they queue. For a form it doesn't matter; for high-frequency interactions (autosave, drag and drop on a board) it's a bottleneck you discover late.

They are neither cancelable nor cacheable. A GET to a route handler can be CDN-cached and aborted with AbortController. An action cannot. Anything that's a read — search, autocomplete, filters — has no business being in an action: that's a route handler or directly a Server Component reading from the database.

Error handling is opaque. A throw in an action reaches the client as a generic error in production (by design, to avoid leaking internals). That forces you to model expectable errors as return values — the { error } in the example — and reserve throw for the truly exceptional. It's more Result than Exception, and it's worth deciding on day one so you don't mix styles.

The criteria in one sentence

A mutation initiated by a user from that same project's UI: Server Action delegating to a service. Reads, APIs consumed by third parties, webhooks, high frequency, anything that might one day need another client: route handler or a proper backend. With that line drawn, Server Actions are an excellent tool — small, boring, and in their place, which is exactly how I like my tools.

Logs as data, not prose

The fundamental shift is to stop writing logs for humans and start writing them for machines. A prose log ("Error processing order 123 for user 456") is pleasant to read but impossible to query at scale. A structured log is a JSON object with consistent fields:

logger.error('order_processing_failed', {
  orderId: order.id,
  userId: user.id,
  errorCode: err.code,
  correlationId: ctx.correlationId,
  durationMs: Date.now() - start,
});

CloudWatch Logs Insights understands JSON natively. With structured logs, "how many orders failed this week with this error code, and from which users?" stops being a heroic grep and becomes a query:

fields @timestamp, orderId, userId
| filter level = 'error' and errorCode = 'PAYMENT_TIMEOUT'
| stats count(*) by userId
| sort count(*) desc

I don't use a homemade logger: AWS Lambda Powertools for TypeScript already solves serialization and levels, and automatically adds the invocation context (request ID, function name, cold start). Reinventing that is wasted time.

The correlation ID: the thread that ties the system together

In an event-driven architecture, the problem isn't logging: it's correlating. The user's request triggers a Lambda that enqueues a message in SQS that's processed by another Lambda that writes to DynamoDB. Four different log groups, four different request IDs, no visible relationship between them.

My rule: the first entry point generates a correlationId (or adopts the one arriving in the X-Correlation-Id header), and that ID travels with everything. In SQS messages it goes inside the message attributes; in service-to-service calls, in a header; in every log, as a mandatory field. Powertools lets you inject it once into the logger and forget about it: every log from that invocation carries it.

With that, reconstructing the complete story of a request is a single Logs Insights query across all the log groups involved. What used to be an afternoon of archaeology is now thirty seconds.

💡 Observability isn't added when there's an incident: it's designed beforehand. The day something breaks in production, your logs already are what they are. Every field you didn't log is a question you can't answer.

Metrics without a hammer: EMF

For business metrics (orders processed, matchings generated, growing queues) I don't use CloudWatch API calls, which add latency and cost money per request. I use Embedded Metric Format: you write the metric as part of the JSON log with a special format, and CloudWatch extracts it asynchronously. Zero marginal cost on the hot path, and the metrics show up in dashboards and alarms like any other.

metrics.addMetric('MatchingCompleted', MetricUnit.Count, 1);
metrics.addMetric('MatchingDurationMs', MetricUnit.Milliseconds, elapsed);

The discipline I impose on myself: every Lambda emits at least one success metric and one failure metric with a business name, not a technical one. "Errors" tells me nothing at 3 a.m.; "PaymentTimeouts" does.

What I decided not to do

I didn't set up X-Ray everywhere. I tried it, and at my scale full distributed tracing was more noise than signal: most of my flows have two or three hops, and the correlation ID in structured logs covers them more than well enough. I reserve X-Ray for flows with more hops or when I suspect inter-service latencies the logs can't explain. It's an honest trade-off: less automatic visibility in exchange for less cost and less configuration to maintain.

I also don't centralize logs in an external tool. CloudWatch Logs Insights has a mediocre UX and queries billed per GB scanned, but adding a third party means another shipping pipeline, another contract, and another invoice. While the volume allows it, I prefer the pain I know. The day queries become truly slow or expensive, that decision gets revisited with data: GB scanned per month and minutes lost per incident.

The result

None of this is glamorous. It's three habits: JSON instead of prose, an ID that travels with the request, and business metrics embedded in the logs. But the operational difference is enormous: incidents went from "let me see if I can reproduce it" to "give me the correlation ID and I'll tell you what happened". In serverless you can't SSH into the server, so the system had better tell its own story.

Why the bi-encoder falls short

An embedding compresses an entire document into a fixed vector before knowing what you're going to ask it. That's its great advantage (you can precompute and index it) and its structural limit: the compression loses the nuances that only matter against a specific query. Two candidate profiles can be equally "close" to a job opening in vector space for different reasons, and cosine similarity can't tell whether the closeness comes from what's essential or what's incidental.

A reranker is a cross-encoder: it receives the query and the document together, and produces a relevance score by looking at the interaction between the two. It's far more precise at ordering, and far more expensive: you can't precompute anything, every query-document pair is an inference. That's why nobody ranks an entire corpus with a cross-encoder. The pattern is retrieve cheap, reorder expensive over few candidates.

The architecture: retrieve 50, rerank to 10

My pipeline ended up in two stages. The first is the one I already had: pgvector retrieves the 50 nearest neighbors. The second passes those 50 through the reranker and keeps the best 10 according to the new score.

-- Stage 1: cheap retrieval, deliberately over-retrieving
SELECT id, titulo, contenido
FROM documentos
ORDER BY embedding <=> $1
LIMIT 50;

// Stage 2: reranking over the candidates
const scored = await rerank({
  query: userQuery,
  documents: candidates.map((c) => c.contenido),
});

const top = scored
  .sort((a, b) => b.relevanceScore - a.relevanceScore)
  .slice(0, 10);

The number 50 isn't sacred. It's the balance I found between two failure modes: retrieve too few and the right document never even reaches the reranker, so there's nothing to reorder; retrieve too many and you pay latency and inference for candidates that never had a chance. I chose 50 because in my tests the correct result was inside the bi-encoder's top 50 practically always; in exchange, I accept that if retrieval fails at the root, the reranker won't rescue it. Garbage in, garbage out — just better sorted.

Latency: the real price and how I contained it

Reranking adds a network call and an inference per request. In my case that meant going from ~80ms to ~350ms at p50. For an interactive search that was too much, and I contained it with three decisions:

First, only rerank when it matters. If the bi-encoder's top candidate score has a wide lead over the second, the ordering is already clear and I skip the second stage. Second, truncate documents: the reranker doesn't need the document's 3,000 words — the title and the first relevant fragment are enough to discriminate, and cost grows with tokens. Third, cache normalized query-document pairs; in a real product, queries repeat far more than you'd think.

💡 The reranker doesn't improve your retrieval: it improves your precision at the top. If your problem is that good results don't even show up in the top 50, your problem is in the embeddings or the chunking, and no reranker will save you.

How I measured it was worth it

Before integrating anything I built a small evaluation set: ~100 real queries with the result a human considered correct marked by hand. The metric I cared about was MRR (mean reciprocal rank): if the correct result is first it scores 1, second scores 0.5, and so on. With the bi-encoder alone I had a mediocre MRR; with the reranker it went up clearly and consistently. I'm not giving exact figures because they depend brutally on the domain and the dataset, but the pattern repeats on almost any corpus: the bi-encoder finds, the cross-encoder orders.

What does generalize is the method: don't integrate a reranker because it's fashionable. Build the 100 human-judged queries first, measure your baseline, and let the number make the decision. In my case the number was conclusive and the extra latency was paid for.

Trade-offs I accepted

I chose a managed reranker via API instead of serving my own cross-encoder, because at my scale the per-request cost was lower than the fixed cost of keeping a GPU warm. In exchange, I accepted an external dependency in the search's critical path, mitigated with a fallback: if the reranker doesn't respond within 500ms, I return the bi-encoder's ordering as-is. Slightly worse search is infinitely better than search that's down.

I also accepted that the system is harder to reason about: there are now two models that can degrade independently. That's why the evals run against the full pipeline, not against each piece in isolation. What reaches the user is the output of the whole chain, and that's the only thing worth measuring.

The flow in three steps

The pattern has three actors: the browser, your API, and S3. The API never sees the file.

// 1. The backend generates the signed URL (Lambda or a regular endpoint)
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const s3 = new S3Client({});

export async function createUploadUrl(userId: string, contentType: string) {
  if (!ALLOWED_TYPES.has(contentType)) {
    throw new Error('File type not allowed');
  }

  const key = `uploads/${userId}/${crypto.randomUUID()}`;

  const url = await getSignedUrl(
    s3,
    new PutObjectCommand({
      Bucket: process.env.UPLOADS_BUCKET,
      Key: key,
      ContentType: contentType,
      ContentLength: undefined, // limit via POST policy conditions if needed
    }),
    { expiresIn: 300 } // 5 minutes, not one more
  );

  return { url, key };
}

The browser does a direct PUT to that URL with the file as the body. When it finishes, it notifies your API with the key, and there you register the file in PostgreSQL via Prisma, trigger async processing, or whatever applies.

The three security decisions that matter

The key is generated by the server, always. If you let the client pick the file name, you're letting it pick where it writes in your bucket. The key includes the authenticated userId and a UUID: the client contributes not a single character.

Short expiration and pinned content-type. Five minutes is enough to start any upload. And signing the ContentType into the URL forces what's uploaded to match what was declared — it doesn't stop someone from renaming an executable to .jpg, but it closes the easy path.

The uploads bucket is not the final bucket. Everything lands in a staging bucket with a lifecycle rule that deletes objects after 24 hours. A later process — in my case a Lambda triggered by the s3:ObjectCreated event — validates the file for real (magic bytes, size, scanning if applicable) and moves it to the definitive bucket. Whatever nobody validates self-destructs on its own.

💡 A presigned URL is not "access to S3": it's ONE operation, on ONE key, during ONE interval. If your signed URL allows more than that, you haven't understood the pattern — you've opened a hole with extra steps.

The confirmation event: don't trust the client

The classic mistake with this pattern is marking the file as "uploaded" when the browser says it finished. The browser lies: the tab closes, the network fails, the user cancels. The source of truth is S3, not the client.

That's why the database record has two phases: the API creates the row in pending state when signing the URL, and the ObjectCreated event Lambda moves it to available when the object actually exists. Rows stuck in pending for more than an hour get cleaned up by a job. The client can notify to speed up the UX, but its notification is an optimization, never the truth.

When not to use this pattern

As always, there are trade-offs. If files are small (JSON, avatars of a few KB) and volume is low, going through the backend is simpler and simplicity wins. If you need to transform the file inline before storing it (resizing, synchronous transcoding), the backend has to see it anyway. And if your frontend is an offline-first PWA, direct upload complicates the sync queue: there I sometimes prefer to queue the file locally and upload it from a service worker when there's network, which changes the whole design.

For everything else — documents, images, anything that weighs megabytes and arrives with concurrency — letting S3 do the heavy lifting is one of the few architecture decisions I've never regretted.

The boundary that changes everything

When you give a model tools, the real loop is: you pass it the user's request and the schema of available tools; the model responds either with text, or with one or more tool calls (name + arguments in JSON); your code executes whichever ones it decides to; you return the result to the model; and the model continues. The LLM never touches your database or your API. It's a generator of structured intentions.

That boundary is the best news of the architecture, because it means all the security control lives on your side. The model can ask to delete a record; whether it gets deleted depends on an if of yours. Treating the tool call as a request subject to authorization, and not as an order, is what separates an agent you can put in production from a demo that scares you.

Schemas are your contract, and the model reads them

The quality of a tool-using agent depends brutally on how well described the tools are. The model chooses what to call based on the name, the description, and the parameter schema. Vague descriptions produce wrong calls; precise descriptions produce correct calls.

const tools = [{
  name: 'search_candidates',
  description: 'Search candidates by skills and seniority. ' +
    'Use it only when the user asks for specific profiles, ' +
    'not for general questions about the market.',
  input_schema: {
    type: 'object',
    properties: {
      skills: { type: 'array', items: { type: 'string' } },
      seniority: { type: 'string', enum: ['junior', 'mid', 'senior'] },
    },
    required: ['skills'],
  },
}];

That enum isn't decoration: it restricts the output space and makes it far less likely that the model invents a value your backend can't handle. Every restriction you put in the schema is a class of bug you eliminate before it happens. I've learned to invest in strict schemas with the same seriousness I design a public API, because to the model that's exactly what they are.

Validate the output as if it came from a hostile client

Here's the point most people skip. The model generates the arguments as text, and even if you give it a schema, there's no hard guarantee it respects your business invariants. It can hand you a valid seniority per the enum but an empty skills array, or a correctly formatted date that's in the past.

That's why I validate every tool call with Zod before executing it, with the same distrust I'd apply to user input. The tool call is user input, just generated by a model. If it doesn't validate, I don't execute: I return the error to the model as the tool result and let it retry with corrected arguments. That "you failed validation, here's why, try again" loop is surprisingly effective and keeps the system safe without human intervention.

💡 A tool call is an untrusted request that happens to come from an LLM instead of a browser. Validate it, authorize it, and log it exactly like any external input. The model is not part of your trust boundary.

Side effects: separate reading from writing

Not all tools are equal, and treating them as if they were is asking for trouble. I distinguish two categories with different rules. Read-only ones —search, query, calculate— I run without friction: if the model gets the query wrong, the cost is a poor answer, nothing irreversible. Write ones —create, update, delete, send— go through a much stricter filter.

For write tools with real impact, the pattern that works for me is not to give the model the destructive tool directly, but one that proposes the action and leaves it pending an explicit confirmation. The model can draft the email; sending it requires a step my code controls, often with a human in the loop. I chose this caution in exchange for less "magical" agents, and I'd choose it again: an agent that can send messages without supervision is an incident waiting its turn.

Why this mental model scales and the other doesn't

When you think the LLM executes, every new tool scares you, because you're widening what a non-deterministic system can do on its own. When you understand that the LLM only proposes, adding tools is cheap: each one is one more intention your code knows how to validate, authorize, and execute under your rules.

The agent stops being a black box you pray to and becomes a planner whose proposals pass through a control layer you wrote and understand. All of the model's creativity, none of its ability to cause harm without permission. That division of responsibilities isn't an implementation detail: it's the difference between an agent you can defend in a security review and one you can't.

The real problem: two sources of truth that diverge

Duplicated validation doesn't fail the day you write it: it fails six months later, when someone changes a rule in the backend (a character minimum, a new postal code format) and nobody touches the frontend. From then on you have two behaviors: what the form says is valid and what the API actually accepts. The user suffers the difference.

The solution isn't discipline ("remember to change both places"), because discipline doesn't scale. The solution is structural: make it so only one place exists.

The schema as a shared contract

In a monorepo, the schema lives in its own package, with no React or Node dependencies:

// packages/schemas/src/registro.ts
import { z } from 'zod';

export const registroSchema = z.object({
  email: z.string().email('Invalid email'),
  telefono: z
    .string()
    .transform((v) => v.replace(/\s+/g, ''))
    .pipe(z.string().regex(/^\+?\d{9,15}$/, 'Invalid phone number')),
  password: z.string().min(12, 'Minimum 12 characters'),
});

export type RegistroInput = z.input<typeof registroSchema>;
export type RegistroOutput = z.output<typeof registroSchema>;

Two details matter here. First, the transform + pipe: normalization (stripping spaces from the phone) is part of the schema, so the "phone with spaces" is valid in both worlds and gets normalized the same way in both worlds. Second, exporting z.input and z.output as separate types: what goes in (with spaces) and what comes out (normalized) are different types, and TypeScript forces you not to confuse them.

On the client: the same schema drives the form

With react-hook-form and its Zod resolver, the form validates against the shared schema without writing a single extra rule:

const form = useForm<RegistroInput>({
  resolver: zodResolver(registroSchema),
});

The error messages you defined in the schema appear under each field. If tomorrow the password minimum goes up to 14, you change one number in one file and the form and the API find out at the same time.

On the server: parse, don't trust

In the API, the same schema is the boundary between the outside world and your typed code:

export async function POST(req: Request) {
  const parsed = registroSchema.safeParse(await req.json());
  if (!parsed.success) {
    return Response.json(
      { errors: parsed.error.flatten().fieldErrors },
      { status: 422 },
    );
  }
  // parsed.data is RegistroOutput: normalized and typed
  await crearUsuario(parsed.data);
}

I use safeParse and return fieldErrors with the same structure the form consumes. That way, even if a malicious client skips browser validation, the error the server returns fits into the same per-field error UI. Client validation is UX; server validation is security. Same logic, different roles.

💡 "Parse, don't validate": the schema doesn't just check that the data is correct, it transforms it into a type that can no longer be incorrect. Past the boundary, no function ever asks again whether the email is valid: the type guarantees it.

The limits of the pattern

Not everything is shareable, and pretending it is produces monstrous schemas. Validations that depend on server state (does this email already exist? is this coupon still active?) don't belong in the shared schema: they're backend business rules and get checked there, returning errors in the same fieldErrors format so the UI renders them identically.

I also decided not to share API response schemas with the same enthusiasm. Input schemas change slowly and you control them; typing every response with Zod at runtime adds a parsing cost that buys nothing on most endpoints. There, the TypeScript type contract generated from the schema itself is enough for me.

The pattern's overall trade-off is coupling: frontend and backend share a package, which demands a monorepo or publishing a versioned package. I chose a monorepo with pnpm workspaces because the cost of coordinating versions across separate repos was exactly the kind of friction I was trying to eliminate. In exchange, a schema change forces a coordinated deploy of both sides. I accept it: I prefer an explicit coordinated deploy over a silent divergence discovered by a user.

The mental model: HTML by default, JS on demand

In a classic SPA everything is JavaScript: the framework mounts entirely on the client, hydrates the whole tree, and governs the page from there. It's comfortable for the developer and expensive for the user, who pays the cost of booting the framework even when 90% of the screen is text that never changes.

Astro flips the premise. It renders your components to HTML on the server or at build time, and by default discards the JavaScript that generated them. What reaches the browser is plain HTML that paints instantly. The "islands" are the specific zones that do need a life of their own — a carousel, a form with validation, a dropdown menu — surrounded by a sea of static HTML that costs nothing. Each island hydrates independently; the rest of the page never notices.

The client: directives are the decision, not a detail

The lever is the directive you give the component when you use it. Each one describes when that island hydrates, and choosing well is where the performance lives:

---
import Carousel from '../components/Carousel.jsx';
import NewsletterForm from '../components/NewsletterForm.jsx';
import HeavyChart from '../components/HeavyChart.jsx';
---

<!-- Hydrates as soon as the page loads: for what's above the fold -->
<Carousel client:load />

<!-- Hydrates when it enters the viewport: for what's further down -->
<HeavyChart client:visible />

<!-- Hydrates when the browser is idle: for non-urgent stuff -->
<NewsletterForm client:idle />

client:load hydrates immediately: use it only for what's interactive from the first visible pixel. client:idle waits for the main thread to breathe. client:visible is my favorite: it doesn't spend a byte of JavaScript until the component enters the screen, ideal for everything below the fold. The directive isn't a syntax ornament: it's literally the load policy of each island, and placing them carelessly is how JavaScript the user doesn't need sneaks in.

When NOT to hydrate (which is almost always)

The most common mistake for people arriving from React is treating every component as if it needs state. It doesn't. A card, a heading, a list of posts, a footer: all of that is HTML that paints once and never changes again. If there's no event, there's no state and no interaction, there's no island. It stays as a static Astro component and ships zero JavaScript.

The question I ask of every component isn't "can it be interactive?" but "does it have to respond to something from the user on the client?". A button that's just a link isn't an island, it's an <a> tag. An accordion can be built with native <details> and <summary> without a line of JS. The more I push interactivity toward native HTML and CSS, the fewer islands I need and the lighter the page stays.

💡 In Astro, every client: you write is JavaScript the user downloads. The best optimization isn't hydrating faster, it's not hydrating.

Islands don't share state, and that's on purpose

Here's the trade-off you have to be clear on before marrying the model. Each island is an isolated component: it hydrates on its own and doesn't magically share state with the others. If I'm coming from a SPA where a global store wires everything together, this feels like a limitation. Two islands that need to talk to each other don't do it through props, because they're independent trees mounted separately.

The solution exists — browser events, shared nanostores, signals — but it's real friction, and that friction is the sign that maybe you're using the tool against the grain. If your page is basically an app with tightly interwoven state, many parts talking to each other constantly, Astro will ask you to do gymnastics for something a SPA framework gives you for free. There I don't force Astro: I pick the right tool.

Why I chose this model anyway

Astro shines when content leads and interactivity is occasional: blogs, marketing sites, documentation, portfolios, e-commerce with product islands. That's exactly the shape of most of the web, and of this site. I accept the friction of coordinating islands in exchange for every page being born weightless by default, and for me being the one who decides and justifies every kilobyte of JavaScript I add.

That shift of the default is everything. In a SPA, JavaScript is the norm and removing it takes work; in Astro, JavaScript is the exception and adding it is a conscious decision. I'd rather have a system where the cheap thing is the easy thing and the expensive thing requires me to ask for it on purpose. That inversion of the default burden is, for the kind of sites I build, the best performance decision I can make without optimizing a single line.

What problem they actually solve

In a traditional MPA site every navigation is a full document reload. It works, it's robust, and it's what Astro does out of the box, but it feels rough: between one page and the next there's a blank instant, the browser resets the scroll, and anything playing gets cut off. In a SPA that doesn't happen because you never reload: a router intercepts the click and replaces the content with JavaScript. The price is that you take on the whole SPA apparatus —the router, hydration, client state— even if your site is mostly content.

View Transitions sit in the middle. Astro intercepts the navigation, fetches the next page, swaps the <body> content without reloading the document, and animates the transition using the browser's View Transitions API. You keep serving normal HTML pages, but navigating between them stops flashing. Turning it on is one line in the layout.

---
// src/layouts/Layout.astro
import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
  <head>
    <ClientRouter />
  </head>
  <body>
    <slot />
  </body>
</html>

With that <ClientRouter /> in the <head>, every internal link now navigates without a reload and with a smooth default transition. You haven't written a router or turned anything into a SPA: it's still Astro serving HTML.

Named animations: the detail that sells it

The default transition is a discreet fade, but what hooks people is being able to animate specific elements from one page to another. If I mark two elements on different pages with the same transition:name, the browser understands they're "the same" and animates the change in position and size between them. The typical case is an article thumbnail that grows into the detail page's header.

<!-- In the listing -->
<img src={post.cover} transition:name={`cover-${post.slug}`} />

<!-- On the detail page -->
<img src={post.cover} transition:name={`cover-${post.slug}`} />

The name has to be unique per element on each page; that's why I derive it from the slug. If you repeat the same transition:name for several elements visible at once, the browser can't tell which is which and the animation breaks. It's the most common mistake starting out.

The state you want to survive

Here's the less obvious win. Since there's no full reload, I can ask certain elements to persist across navigations instead of being recreated. An audio player, a heavy map, a menu with its open state: with transition:persist the element is kept as-is when moving between pages, without resetting.

<audio src={song} controls transition:persist />

Without this, every navigation would destroy the <audio> and recreate it, cutting the playback. With transition:persist, the same DOM node travels to the next page and keeps playing. It's exactly the kind of continuity people build a whole SPA for, and here I get it with an attribute.

💡 Every persisted element is a node you decide not to recreate. Use it for things that need real continuity —audio, video, an expensive map— and not as a patch to avoid recomputing something that should actually refresh with the new page.

The edges you have to know

None of this is free, and it's fair to say where it pinches. The first is scripting. Since the page doesn't reload, the <script> that ran on DOMContentLoaded doesn't run again on each navigation: it ran once and the new page doesn't fire it again. Any initialization you took for granted on every load has to be re-hooked to the astro:page-load event, which Astro emits on the initial load and after each transition.

// Runs on first load and after every navigation
document.addEventListener('astro:page-load', () => {
  initWidgets();
});

This is the bug that's hardest to spot, because the site works perfectly on a manual reload and only breaks when navigating between pages: the scripts simply weren't re-hooked.

The second edge is degradation. View Transitions rely on an API that not every browser implements the same way; where it's missing, Astro gracefully falls back to a normal navigation with reload. That means you can't treat the transition as guaranteed: it's a progressive enhancement, not a base to build logic on. And the third, more judgment than technical, is not overdoing it: animating everything is dizzying. I reserve named animations for one or two visual connections that genuinely add continuity, and leave the rest as the discreet fade.

Why it's worth it to me

I chose View Transitions in Astro rather than jumping to a SPA because I keep what I wanted from the framework —served HTML, minimal JavaScript, independent pages that cache and index well— and on top of that gain the fluidity that used to require changing the entire model. In exchange I accept a handful of concrete edges: re-hooking scripts on astro:page-load, treating the transition as progressive, and being disciplined with animations. It's a trade I almost always accept, because the cost is bounded and known, whereas moving into a SPA just to get an animation would mean paying in bundle, complexity, and SEO a price far above the problem it solves.

Why I enqueue instead of answering inline

When a recruiter posts a role, the HTTP response shouldn't wait for embeddings to be generated, matches recomputed, and notifications fired. I send that to a queue and return immediately. The user perceives a fast app; the heavy lifting happens behind the scenes, at its own pace.

The queue gives me three concrete things. It absorbs spikes: if a hundred roles come in at once, they're processed at the rate the consumer can handle, not all at once. It isolates failures: if the email provider is down, the task retries itself without taking down the original request. And it decouples: the producer neither knows nor cares who consumes.

The real problem: "at least once"

Standard SQS guarantees delivery, not uniqueness. The same message can arrive twice: because the consumer took longer than the visibility timeout and SQS redelivered, because of a network retry, or because the process died right after working but before deleting the message.

If my consumer just sends an email per message, a candidate gets two. If it creates a charge, I bill twice. Duplicate delivery isn't a rare edge case that happens once a year: it's the system's normal behavior, and you have to design assuming it will happen.

Idempotency: the only defense that scales

The fix isn't to avoid duplicates, it's to make processing twice yield the same result as processing once. That's idempotency, and I implement it with a stable key per unit of work.

CREATE TABLE processed_message (
  idempotency_key TEXT PRIMARY KEY,
  processed_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

Before doing any work, the consumer tries to insert the key. If it already exists, the message is a duplicate and I discard it with no side effects.

async function handle(msg: Job) {
  const inserted = await db.processedMessage
    .create({ data: { idempotencyKey: msg.id } })
    .catch(() => null); // hits the PK if already processed

  if (!inserted) return; // duplicate: do nothing

  await doTheActualWork(msg);
}

I don't invent the key at random: I derive it from the message's intent. For a welcome email it's welcome-email:{candidateId}, not a fresh UUID per attempt. That way two messages representing the same action collide and only one wins.

💡 A safe retry isn't one that never repeats; it's one that can repeat without anyone caring.

Visibility timeout and the DLQ

Two SQS pieces need tuning. The visibility timeout must be longer than the realistic worst-case processing time: if I take longer, SQS assumes I failed and redelivers while I'm still working. I size it against the consumer's p99, not the average.

And the dead-letter queue: after N failed attempts, the message leaves the main queue and lands in a DLQ. Without it, a poison message —one that always fails— retries forever and clogs the queue. The DLQ is where I inspect what broke without it blocking everything else. I put an alarm on it: if something lands there, I want to know.

What I'd do differently

At first I put the idempotency logic inside each handler. I ended up repeating it and getting it wrong differently in each one. Today it lives in a single wrapper: it takes the key, checks, executes, and no handler thinks about duplicates again. The pattern matters more than the infrastructure. SQS is replaceable; the discipline of assuming every message can arrive twice is what actually saves you.

Why DynamoDB isn't Postgres with different skin

In Postgres I normalize, create tables per entity, and let the planner resolve joins at query time. It's flexible: if tomorrow I need a new query, I write it and the engine figures it out, maybe with an extra index. I pay for that flexibility with performance that depends on the plan the engine picks.

DynamoDB flips the deal. There are no joins and no planner: every access is a lookup by key, and if you didn't design the key for that query, that query is either impossible or forces a Scan that walks the whole table. In return, a well-designed access has predictable latency no matter how much data there is. The consequence is brutal: in DynamoDB you can't start from the data model, you have to start from the list of queries your product is going to make.

Start from the access patterns, always

Before touching a table, I write the list of accesses in plain language. For an orders product it'd be something like: give me a user by id; give me all of a user's orders; give me an order with its line items; give me a user's orders sorted by date. That list isn't documentation, it's the design. Each pattern has to map to a partition-key Query, not a Scan.

This step is the one people coming from SQL skip, and it's exactly the one you can't skip. If a pattern you didn't foresee shows up later, in Postgres it's a new query; in DynamoDB it can be a key redesign or a global secondary index. The cost of getting this wrong is high, so this is where I spend the thinking.

Generic keys: PK and SK that don't mean one single thing

The single-table trick is that the partition key and sort key aren't called user_id or order_id. They're called plain PK and SK, and their contents change depending on the entity. A user lives at PK = USER#123, SK = PROFILE. Their orders live in the same partition, PK = USER#123, SK = ORDER#456. So asking for a user and all their orders is a single Query on PK = USER#123: the partition already brings the profile and the orders together, no join.

// All of a user's items (profile + orders) in one query
const res = await ddb.query({
  TableName: 'app',
  KeyConditionExpression: 'PK = :pk',
  ExpressionAttributeValues: { ':pk': 'USER#123' },
});

// Orders only: narrow by the sort key prefix
const orders = await ddb.query({
  TableName: 'app',
  KeyConditionExpression: 'PK = :pk AND begins_with(SK, :prefix)',
  ExpressionAttributeValues: { ':pk': 'USER#123', ':prefix': 'ORDER#' },
});

The begins_with on the sort key is the lever: by prefixing the types (ORDER#, PROFILE, ADDRESS#) I can pull exactly the subset I want from a partition, sorted, in a single call.

💡 In DynamoDB the sort key doesn't sort data, it designs queries. The prefix you give it is what decides which questions you'll be able to ask cheaply.

GSIs: when you need to look at the data along another axis

Patterns that don't fit the primary key are solved with global secondary indexes. A GSI is essentially a projection of the table with a different PK and SK, maintained by DynamoDB asynchronously. If I need "all orders with status PENDING sorted by date," I create a GSI whose PK is the status and whose SK is the date, and that access is a clean Query again.

The pattern I use is index overloading: the same generic GSI1PK and GSI1SK attributes mean different things depending on the entity, just like the primary key. With a couple of well-thought-out GSIs I cover almost any product. What I don't do is create a GSI on a whim: each index costs writes and storage, because every put on the table replicates to the indexes that apply.

The trade-offs nobody tells you about up front

Single-table is powerful, but it's fair to admit what it costs. The first thing is the mental curve: modeling this way is uncomfortable until you internalize thinking in accesses, and a new team takes a while to read a table where everything is called PK and SK. The second is rigidity: if a truly unforeseen access pattern appears, adapting costs more than in SQL, where an ad-hoc query is always possible even if it's slow.

That's why I don't use single-table for everything. When a product has exploratory queries, shifting reports, or relationships I can't anticipate, Postgres gives me a flexibility that DynamoDB would charge dearly for. I pick DynamoDB when the access patterns are known, bounded, and I need predictable latency at scale without operating a relational engine. There the single-table shines: fewer pieces, flat latency, and a bill that scales with real usage and not with the size of the table. Like everything in AWS, it isn't the best tool, it's the best tool for a problem with the right shape.

It isn't serverless versus containers

The first misunderstanding is treating it as serverless versus containers. Fargate is also serverless: you define a task, AWS runs it, and you never touch an EC2 instance. The real difference is the execution model. Lambda is ephemeral and event-invoked: a request arrives, an environment spins up, your handler runs, it responds, and it shuts down. Fargate is a long-lived process: your container starts once, sits listening, and serves requests until you scale it or kill it.

That difference colors everything. In Lambda you don't control the lifecycle: there's no "startup" of yours where you open a connection pool and calmly reuse it, because the environment can be recycled at any moment. In Fargate you do have a stable process with its startup, its warm memory, and its connection pool alive between requests. Choosing is, at bottom, choosing how much control you want over that lifecycle.

The shape of traffic rules

The first thing I look at is how the work arrives. If traffic is intermittent, bursty, or unpredictable —a webhook that fires now and then, a cron that processes on schedule, an endpoint with odd spikes— Lambda fits naturally. It scales from zero to many parallel invocations without you configuring anything, and when there's no traffic you pay nothing. That "zero to a thousand without warning" is exactly where Fargate struggles: holding capacity for the spike means paying for containers sitting idle, and reactive scaling is slower than a Lambda cold start.

If traffic is sustained and constant, the math flips. A service under steady load all day, on Lambda, is a continuous drip of invocations billed by the millisecond that ends up expensive next to a handful of Fargate containers at full tilt. There a long-lived process squeezes more out of each CPU: it doesn't repeat the startup cost on every request and keeps warm the resources Lambda would rebuild over and over.

💡 Lambda charges per invocation and duration: it shines when traffic is sometimes zero. Fargate charges per running container: it shines when traffic is almost never zero. Before deciding, draw a day's traffic curve.

Duration and limits: the 15-minute clock

The second axis is how long each unit of work lasts. Lambda has a hard cap of fifteen minutes per invocation. For an API or event processing that's plenty, but any job that might run over —a long migration, video processing, a job that walks a large dataset— doesn't fit, and slicing it to fit is complexity that doesn't always pay off. Fargate has no such clock: a task can run for minutes or hours, which makes it the natural home for long batch work or processes that simply have to stay alive.

There's also the cold start. When Lambda spins up a fresh environment, the first invocation pays the cost of initializing the runtime. For latency-tolerant loads it doesn't matter; for an endpoint sensitive to tail latency, that occasional cold hit shows. It's mitigated —provisioned concurrency, lightweight runtimes— but it's a real factor. Fargate has no per-request cold start: you pay startup once when you scale a new task, not on every invocation.

State, connections, and dependencies

The third axis is how much state and which dependencies the process needs. The classic case is the database. A connection pool lives on reusing connections between requests, and that fits a long-lived process like Fargate. In Lambda, each concurrent environment opens its own, and under a spike you can exhaust PostgreSQL's connections without noticing; the fix is an intermediate connection proxy, one more piece in the diagram. It's not impossible to run Lambda against a relational database, but it's friction Fargate doesn't have.

// In Fargate this initializes ONCE at container start
// and the pool is reused on every request.
import { Pool } from 'pg';

const pool = new Pool({ max: 10 }); // lives between requests

export async function handler(req: Request) {
  const client = await pool.connect(); // reuses, doesn't reopen
  try {
    return await query(client, req);
  } finally {
    client.release();
  }
}

That same pattern in Lambda is treacherous: the pool survives while the environment is reused, but it multiplies per concurrent environment, and that's where the database blows up under load.

My rule, and why I mix the two

In the end my criterion is simple. I start on Lambda when the work is short, event-triggered, with irregular traffic and little state: webhooks, async tasks, glue between AWS services. I move to Fargate when the work is sustained, long-running, or needs live connections and lifecycle control: APIs under constant load, queue workers processing nonstop, long batch.

And I don't pick one for the whole system. In the same product an HTTP service on Fargate with a stable Postgres connection coexists with Lambda functions for incoming webhooks and async jobs. I chose to mix rather than force a single model because each workload has its shape, and fighting the tool to do something it isn't built for always costs you: in Lambda with proxies and slicing, in Fargate with idle capacity waiting for a spike that never comes. Like almost everything in AWS, there's no best tool, there's the best tool for the shape of your problem.

An LLM has no unit tests, and that's the problem

When you write a normal function, a unit test pins down its contract: this goes in, that comes out, and if someone breaks it the pipeline warns you. With an LLM-based feature that contract blurs. The same prompt with the same input can give different answers, and a seemingly harmless change —reordering two sentences of the system prompt, bumping from one model version to the next— can degrade cases you didn't even know depended on that detail.

The mental mistake is treating the prompt as stable code and the model as a fixed dependency. They're neither. The prompt is a parameter you tune constantly, and the model is a dependency that shifts under you without warning. Without a battery of cases you run on every change, you're shipping blind and discovering regressions through your users. Which is the worst way to discover them.

The minimum eval: a golden dataset and a metric you care about

You don't need an eval platform to start. You need a file with representative cases and a function that scores. A case is a real input, the expected output (or a property the output must satisfy) and optionally why it's there. I pull them from three places: examples I know work, edge cases that worry me, and above all the real bugs people report —every production regression becomes an eval case so it can't happen again.

type EvalCase = {
  name: string;
  input: MatchInput;
  // An assertion about the output, not exact equality:
  // with LLMs, comparing strings word by word is useless.
  expect: (output: MatchOutput) => boolean;
};

const cases: EvalCase[] = [
  {
    name: 'senior candidate with exact stack ranks first',
    input: seniorReactExact,
    expect: (out) => out.ranked[0].id === 'cand_42',
  },
  {
    name: 'does not invent skills absent from the CV',
    input: cvWithoutKubernetes,
    expect: (out) => !out.ranked[0].reasons.includes('Kubernetes'),
  },
];

Notice I don't compare the whole output character by character. With an LLM that's doomed to fail over irrelevant wording differences. What I check are properties: that the right candidate lands on top, that no hallucinated skill shows up, that the format is parseable. Each assertion encodes something I genuinely care about in the behavior, not the exact shape of the text.

Scoring the subjective: when I use an LLM as a judge

Many outputs can't be verified with an if. "Is this explanation of the match clear and well-grounded?" is not an obvious boolean property. For that I use a second LLM as an evaluator: I pass it the input, the output and a concrete rubric, and ask for a score with justification. It works surprisingly well for catching large degradations, and it's far cheaper than reviewing hundreds of outputs by hand.

But I chose to use LLM-as-judge with my eyes open, not as a silver bullet. It has known biases: it tends to reward long answers, favors style over substance, and if you ask it to score its own model it turns lenient. I treat it as a noisy filter, not the truth: it's good for catching big quality drops between versions, not for telling whether something went from 8.2 to 8.4. For the properties I can verify with code, I use code, which is deterministic and free.

💡 Every LLM bug that reaches production is an eval case you were missing. Before fixing the prompt, add the failing case to your dataset. That way the fix is locked in and that specific regression can never come back.

Running evals where it hurts: before you deploy

An eval dataset you run when you remember is worthless. The value shows up when it runs automatically on every change that touches the prompt, the model or the orchestration logic. I wired it into the pipeline as one more step: if the pass rate over the dataset falls below a threshold, the deploy stops just as it would if a test failed.

async function runEvals(cases: EvalCase[]) {
  const results = await Promise.all(
    cases.map(async (c) => ({
      name: c.name,
      passed: c.expect(await runFeature(c.input)),
    })),
  );

  const passed = results.filter((r) => r.passed).length;
  const rate = passed / results.length;

  console.table(results);
  if (rate < 0.9) {
    throw new Error(`Evals below threshold: ${rate}`);
  }
}

The threshold isn't 100% on purpose. With LLMs there are genuinely ambiguous cases where an occasional miss is tolerable, and demanding a perfect green pushes you to overfit the prompt to your dataset. I prefer a high but realistic threshold and I watch the trend: if the rate has been dropping for three versions, there's a problem even if each version cleared the bar.

Where I put the effort today

If I had to give a single piece of advice to someone shipping their first LLM into a product, it would be this: build the evals before polishing the prompt, not after. It's tempting to spend the time on the creative part of writing clever instructions, but without a way to measure you're optimizing blind. I chose to invest in the evaluation harness before the perfect prompt because the harness pays for itself on the first regression it catches, and its value grows with every case you add. I'll rewrite the prompt ten times; the evals tell me which of those ten versions is better.

The real problem isn't the model, it's the edge

An LLM inside a product doesn't live alone: its output feeds a function, a query, or a call to another API. That contact point between natural language and typed code is the fragile edge. If the model returns free text, the edge fills up with defensive parsing: find the first {, count braces, strip the ```json, catch the JSON.parse that blows up. Every one of those lines is debt that breaks the moment the model decides to get conversational.

For a while I tried to solve it with prompt engineering. "Respond with valid JSON only, no explanations." It helps, but it guarantees nothing: the prompt is a plea, not a contract. The lesson that took me a while to accept is that reliability isn't requested, it's enforced at the API layer.

Function calling as a contract, not a trick

Modern models accept a tool or response schema and commit to returning something that fits it. That changes the game: instead of describing the format in prose, I declare it as structure and the model fills in the blanks. I stop parsing intentions and start receiving data.

I model it like this: I define the shape I need, pass it as a response schema, and the rest of my code assumes it will receive exactly that. The prompt goes back to talking about the task — what to extract, how to prioritize — and not about commas and quotes.

import { z } from 'zod';

const CandidateExtraction = z.object({
  seniority: z.enum(['junior', 'mid', 'senior', 'lead']),
  primary_stack: z.array(z.string()).max(8),
  years_experience: z.number().int().min(0).max(50),
  location: z.string(),
  open_to_remote: z.boolean(),
});

type CandidateExtraction = z.infer<typeof CandidateExtraction>;

That schema is the source of truth. From it comes the TypeScript type, from it comes the JSON schema I hand the model, and against it I validate the response. One definition, three uses.

Zod: the net that catches what the model doesn't guarantee

Here's the nuance a lot of people skip: the API accepting a schema doesn't mean the result is correct in the sense I care about. The model can return structurally valid JSON that's semantically absurd: a years_experience of 200, a stack with fifteen duplicate entries, an enum that never existed. The shape is right; the content isn't.

That's why I always validate at the edge with Zod, even when using structured outputs. It isn't belt-and-suspenders paranoia: it's that the API's guarantee and my domain's guarantee are different things. Zod lets me express the second one — ranges, max lengths, closed enums — and turns a dubious response into an error I can handle before it pollutes the database.

const raw = await callModelWithSchema(prompt, CandidateExtraction);
const parsed = CandidateExtraction.safeParse(raw);

if (!parsed.success) {
  // I don't propagate garbage: I retry with the error as context,
  // or fall back to a manual flow. I never write without validating.
  return handleInvalid(parsed.error);
}

await saveCandidate(parsed.data); // parsed.data is already the correct type

💡 An LLM in a product isn't a source of truth, it's a source of proposals. Validation is what turns a proposal into data you trust.

Retries with the error as context

When validation fails, the instinct is to retry with the same prompt. You waste tokens repeating the same mistake. What actually works is re-injecting the failure: I hand the model back what I expected and what it gave me, and ask it to fix it. In practice, 90% of validation failures resolve in a single informed retry, because they're almost always dumb slips — a missing field, a misspelled enum — that the model corrects immediately once you point at the exact spot.

I cap the retries, of course. If after two attempts it still doesn't fit, the problem isn't the model having a bad day: it's that the task is poorly framed or the schema asks for something the input doesn't contain. There, the loud failure is a gift, because it forces me to fix the cause instead of hiding it.

The trade-off I accepted

Structured outputs isn't free. Boxing the model into a schema reduces its flexibility: for genuinely open-ended tasks, where I don't know the shape of the answer ahead of time, the schema gets in the way more than it helps. And adding Zod plus retries is code and latency I didn't have before.

I chose structured outputs anyway because in a product I almost never want creativity at the edge: I want determinism. I'd rather pay in rigidity and a few lines of validation in exchange for the rest of my system being able to treat the LLM's output the way it treats any other typed API. That's the real goal: the model stops being a special exception everyone tiptoes around and becomes just another component, with its contract and its error handling, like any other piece I already trust.

A module models a concept, not a list of resources

The mistake I made most often was building modules around "things I usually deploy together" instead of around a concept with a clear boundary. A "web-service" module that creates the ECS service, its load balancer, its DNS, its database and its alarms feels convenient, but it couples decisions that change at different rates. The day you want a service without a database, or one sharing a database with another, the module fights you.

The rule that works for me is that a module should model a concept worth naming on its own. "A service on Fargate" is a concept. "An SQS queue with its DLQ" is a concept. "Everything project X needs" is not: it's a composition, and compositions belong in the root, not inside a module. When each module has a clean conceptual boundary, composing them is easy and swapping one for another doesn't break the rest.

Configuration booleans are debt in disguise

Every time you add an enable_something variable to a module, you're introducing a fork in its behavior. With two or three flags it's still understandable. With eight, your module has hundreds of possible combinations and you've only tested the four you use. The rest are minefields waiting for someone.

# The module that ages badly: configured with flags
# that toggle incompatible branches of behavior.
module "service" {
  source          = "./modules/service"
  enable_https    = true
  enable_autoscaling = true
  enable_spot     = false
  enable_efs      = true
  # ...and on until nobody knows which combinations work
}

I prefer smaller modules with fewer options, and I resolve variation by composing instead of configuring. If one service needs persistent storage and another doesn't, I don't add an enable_efs flag: I make the volume a separate module I wire in when needed. The service module knows nothing about EFS and has no untested branch. The composition shows up in the root, where it should, not hidden behind a boolean.

Outputs are the contract; treat them like an API

What a module exposes in its outputs is its public interface, and changing it breaks consumers just as you'd break the clients of an API. Early on I exposed everything "just in case", and ended up with modules whose consumers depended on internal details I wanted to change. Now I treat outputs with the same discipline as a contract: I expose the minimum a consumer needs to wire this module to another —an ARN, an id, an endpoint— and none of the internal plumbing.

# Expose identifiers to compose with, not whole resources.
output "service_arn" {
  value = aws_ecs_service.this.id
}

output "task_role_arn" {
  # Other modules attach policies to this role;
  # that's the extension point I want to offer.
  value = aws_iam_role.task.arn
}

Exposing a role's ARN instead of the whole role is a small but important example: it gives the consumer the exact point to extend (attach a policy) without opening the full resource for them to poke at things that would break my module.

💡 Before adding a variable to a module, ask whether the variation belongs inside the module or in whatever composes it. Most of the time it belongs outside. A module with few inputs and clear outputs gets reused; one with twenty flags gets copy-pasted.

State is where design mistakes get paid

In IaC the design isn't truly tested until you apply changes over existing infrastructure, and that's where state sends you the bill. A badly bounded module shows itself when a plan wants to destroy and recreate something you only meant to nudge, because you moved a resource around or swapped a count for a for_each. Migrating to OpenTofu taught me to treat state structure as part of the design, not a detail: moved blocks exist precisely to refactor without destroying, and using them carefully is what lets you reorganize modules without a scare in production.

I chose small, clearly bounded modules knowing the price: there are more pieces to compose in the root and composition is more verbose than one mega-module with flags. In exchange, each piece is understandable, testable and replaceable on its own, and a change in one doesn't threaten to recreate half the infrastructure. For code that will live for years and that I apply changes to every week, that predictability is worth far more than the convenience of writing fewer lines on day one.

Where I put the effort today

If I had to sum it all up in one sentence: design modules around how they'll be composed and changed, not around how much you type today. Infrastructure as code isn't a script you run once, it's a codebase you maintain, and it suffers the same ills as any other —coupling, untested branches, contracts that break— with the added twist that here a mistake can take down a service. Fewer options, clear boundaries and outputs treated like an API are what keep a module yours six months from now instead of being the corner of the repo nobody wants to touch.

The retriever can only return what you indexed well

A RAG has two halves: retrieve the relevant fragments and generate an answer from them. The second half gets all the attention because that's where the flashy LLM lives. But generation is bounded by what reaches it: if the retriever brings back three mediocre fragments, no model, however large, will invent the missing context. At best it will fake it, which is worse.

And what the retriever can return depends entirely on how you cut the text. An embedding represents the meaning of a whole fragment. If that fragment mixes two distinct ideas, its vector lands at an in-between point that represents neither well, and similarity search skips it exactly when you need it. The problem isn't the embedding model: it's that you handed it a piece of text with no clear idea inside.

Splitting by characters is the default mistake

The recipe almost every tutorial ships is: cut every 1000 characters with 200 of overlap. It's convenient and it's what I did at first. The problem is that 1000 characters mean nothing semantically: the cut falls mid-sentence, separates a definition from its example, or puts the end of one section and the start of the next in the same chunk. You end up with vectors representing fragments split down the middle.

The first cheap fix is to split by structure, not by length. Documents already come with semantic boundaries: paragraphs, headings, list items. Cutting along those boundaries makes each chunk hold a reasonably complete idea.

// Instead of blindly chopping every N characters,
// respect the document's natural boundaries
function chunkByStructure(markdown: string): string[] {
  // Split by section headings first
  const sections = markdown.split(/\n(?=#{1,3}\s)/);

  return sections.flatMap((section) => {
    // A short section is a whole chunk
    if (section.length <= 1200) return [section];
    // A long one subdivides by paragraphs, not characters
    return section
      .split(/\n\n+/)
      .reduce<string[]>((acc, para) => {
        const last = acc[acc.length - 1];
        if (last && (last + '\n\n' + para).length <= 1200) {
          acc[acc.length - 1] = last + '\n\n' + para;
        } else {
          acc.push(para);
        }
        return acc;
      }, []);
  });
}

It isn't sophisticated, but the quality jump over blind cutting is immediate because each vector now represents a unit of meaning rather than an arbitrary slice.

Chunk size is a trade-off, not a magic number

There's no correct value here, there's a tension you have to resolve for your case. Small chunks give very precise embeddings —the vector represents a concrete idea— but they fragment context: the answer to a question can be spread across five slices and the retriever only brings back the three most similar. Large chunks preserve context but dilute the embedding: the more text you cram in, the more the meaning averages out and the less the search discriminates.

My practical rule is to start with medium chunks, the size of a couple of paragraphs covering a single subtopic, and adjust by watching what the system retrieves on real queries. If I see correct answers getting cut off, I raise the size; if I see fragments that talk about several things at once, I lower it. Overlap between adjacent chunks helps so an idea straddling two slices isn't lost, but overlap doesn't fix a cut made in the wrong place.

💡 Don't optimize chunk size in the abstract. Write ten real queries from your product, look at which fragments the system retrieves for each, and adjust from there. A manual eval of ten cases tells you more than any heuristic.

Metadata and context: the chunk doesn't live alone

A fragment ripped from the middle of a document loses where it came from. "The term is thirty days" means nothing without knowing the term of what. That's why I attach metadata to every chunk —document title, section, date— and where I can I prepend a line of context to the text that gets embedded, so the vector also captures what the fragment belongs to. That small header makes ambiguous fragments retrievable by the right query.

Metadata also gives you pre-filtering. In pgvector I can combine similarity search with a WHERE over regular columns, narrowing the search space before comparing vectors.

SELECT id, content
FROM chunks
WHERE document_type = 'contract'
  AND language = 'en'
ORDER BY embedding <=> $1
LIMIT 5;

Filtering by metadata before ordering by distance doesn't just improve precision: it shrinks the set the vector search runs over, and with it the latency.

Where I put the effort today

If I had to divide up the time again, I'd spend the bulk of it on the ingestion phase —how I split, what metadata I store, how I enrich each chunk with its context— and far less trying models. The embedding model matters, and the generator LLM matters, but both operate on what ingestion prepares for them. I chose to invest in chunking instead of a bigger model because chunking is cheap to iterate and its effect is a multiplier: it improves every query the system serves, today and in the future. In exchange, it's unglamorous work that's hard to show off. It's still worth it to me.

Impossible states shouldn't be representable

The pattern that most changed how I write code is this: if a state can't happen in your domain, make it so it can't be written in your type either. The canonical example is the classic "loading / loaded / error". The naive version models it with loose optional fields:

// The type allows states that make no sense:
// loading true and data present at once, or error with data.
type State = {
  loading: boolean;
  data?: Result;
  error?: Error;
};

That type admits { loading: true, data: something, error: somethingElse }, a state that should never exist but which the compiler happily accepts. Every component that consumes it has to remember to check the combinations by hand, and the day someone forgets, a bug appears. The discriminated union closes the door:

// Now each variant carries exactly the data it has,
// and no impossible combination is representable.
type State =
  | { status: 'loading' }
  | { status: 'success'; data: Result }
  | { status: 'error'; error: Error };

With this version, accessing data without first checking that status is 'success' won't compile. The compiler forces you to handle each case, and the "loading with data and error at the same time" state simply can't be written. I haven't added a single test and I've eliminated an entire family of bugs.

Branded types: not all strings are equal

A string can be a user id, an email or a token, and to TypeScript they're interchangeable. That means passing an id where an email was expected compiles without complaint, and that error is found at runtime or never. Branded types put a label on the type so the compiler distinguishes things that are structurally equal but conceptually not.

type UserId = string & { readonly __brand: 'UserId' };
type Email = string & { readonly __brand: 'Email' };

function sendInvitation(to: Email) { /* ... */ }

const id = 'usr_123' as UserId;
sendInvitation(id); // ❌ won't compile: UserId is not Email

The trick is that __brand doesn't exist at runtime —it's pure type, zero cost— but it forces a UserId and an Email not to be confused. Combined with validation at the boundary (a function that validates a string and returns a branded Email), you get the type system to guarantee, from that point on, that whatever flows around is already validated. Validation stops being something you "hope someone did earlier".

💡 When you're torn between validating at runtime and trusting a type, do both once at the boundary: validate the incoming data and return it branded. From there the compiler propagates that guarantee for free through all your code, without a single extra check.

Letting inference work instead of annotating everything

A common mistake is annotating types everywhere out of habit, even where TypeScript infers them better than you do. Over-annotating isn't safer: it couples your code to type names that are hard to change later, and sometimes it hides behind a wide type what inference would have kept precise. I prefer to annotate the boundaries —the public signatures of functions, the contracts between modules— and let inference do the work inside.

// `as const` makes the inferred type exact,
// not a generic `string[]`.
const TAGS = ['IA', 'AWS', 'Frontend'] as const;
type Tag = (typeof TAGS)[number]; // 'IA' | 'AWS' | 'Frontend'

That pattern lets me keep a single source of truth —the TAGS array— and derive the type from it. If tomorrow I add a tag to the array, the type updates itself and every place doing an exhaustive switch over Tag starts throwing a compile error until I handle the new case. The data and the type can't drift apart because one is derived from the other.

The cost, because there always is one

Modeling the domain with rich types isn't free. Discriminated unions force you to write more explicit branches, branded types add ceremony at the boundaries, and there's a point where insisting on expressing an invariant in the type system produces signatures nobody wants to read. I chose this style accepting that cost because in a dashboard I maintain for years the compiler is the only reviewer that never tires or gets distracted, and every invariant I manage to express as a type is a test I don't have to write or maintain. But I know when to stop: if a type becomes harder to understand than the bug it prevents, that's where a runtime check and an honest comment win.

Where I put the effort today

My rule of thumb is to invest in types where the domain has rules that genuinely matter —which states are valid, which data is validated, which values are interchangeable and which aren't— and not spend effort typing every last internal detail that inference already covers. Used that way, TypeScript stops being a nuisance asking for annotations and becomes a design tool: you write the model once, and the compiler makes sure that nobody, including you six months from now, can misuse it without noticing.

After months working this way in a monorepo with thousands of commits — where a meaningful share of the code goes through AI-assisted workflows — here is what worked, what failed, and what I would do differently from day one.

AI doesn't replace judgment, it demands it

The first mistake we made was treating AI like just another junior developer: hand it a task and trust the result. The code compiled, the tests passed… and it still broke project conventions that were written down nowhere, because they lived in the team's heads.

The fix was to invert the flow: before generating code, we generate context. We documented the implicit conventions — how we name services, where shared types live, which error patterns we use — in files the tools read every session. AI is only as good as the context you give it.

💡 Team rule: if a pattern gets corrected twice in code review, it gets documented for the AI. The third time shouldn't exist.

What we automated (and what we didn't)

Not all work benefits equally. Our split ended up like this:

• We automate: module scaffolding, edge-case unit tests, repetitive migrations, mechanical cross-package refactors, and the first version of any CRUD.
• We assist: API design, business logic and complex queries — AI proposes, the human decides.
• We never delegate: architecture decisions, security, permissions and anything touching money or personal data.

Code review changed shape

Reviewing AI-generated code is not like reviewing human code. AI code looks good — it's formatted, sensibly named and commented. The danger is in what looks correct. So we shifted the focus of review: less style, more behavior.

// Review checklist for AI-assisted code
// 1. Are the edge cases real or invented?
// 2. Does it reuse what exists or duplicate a helper?
// 3. Does error handling follow our pattern?
// 4. Are there tests that fail if behavior changes?
// 5. Did it touch anything outside the ticket's scope?

Point 5 turned out to be the most important: AI tools tend to "improve" neighboring code nobody asked them to touch. A clean, scoped diff is worth more than a brilliant, sprawling one.

What I'd do differently today

I'd start with context documentation from day one, not after the first incident. And I'd set one simple metric that is, in the end, the only one that matters: not how much code the team generates, but how much code survives six months in production without being rewritten.

AI made us faster, yes. But the real change was something else: it forced us to make explicit all the knowledge that used to be tribal. And that would have been worth it even without the speed.

Why serverless made sense here

I don't reach for serverless by default. I reach for it when the load pattern is spiky and the team is small. This project was both.

• Bursty traffic. The panel was used in specific windows: content uploads, catalog updates, the odd query. In between, almost nothing. Paying for an EC2 box to sit idle for that is burning money.
• No platform team. There were no SREs. With Lambda and DynamoDB I don't patch operating systems, I don't manage scaling, and I don't get paged because a disk filled up.
• Per-event isolation. Every request is an invocation. A spike doesn't take the whole service down; it scales up and then back to zero.

The price you pay is elsewhere: model DynamoDB well from day one, keep an eye on cold starts, and accept that you're married to AWS. It's worth it if you're honest about those costs.

Modeling DynamoDB: single-table and access patterns

The most common mistake with DynamoDB is treating it like Postgres without joins. It isn't. In DynamoDB you model the access patterns first, and the table second.

For the panel I used a single-table design: one table, generic PK and SK, several entity types living side by side. The patterns we needed were clear: fetch a vehicle by id, list vehicles by category, fetch the content tied to a model.

{
  "PK": "VEHICLE#corolla-2023",
  "SK": "METADATA",
  "type": "vehicle",
  "name": "Corolla",
  "year": 2023,
  "category": "sedan",
  "GSI1PK": "CATEGORY#sedan",
  "GSI1SK": "VEHICLE#corolla-2023"
}

The trick: fetch-by-id goes against PK/SK, and list-by-category goes against a global secondary index (GSI1PK/GSI1SK). No full-table scans. Every read is a Query against a known partition key, which is the only thing DynamoDB does cheaply and predictably.

Rules that saved me pain:

1. Write down the list of access patterns before touching the table. If a new one shows up later, it's almost always one more GSI, not a redesign.
2. Prefix your keys (VEHICLE#, CATEGORY#) so different entities coexist without colliding.
3. Never a Scan on the hot path. If you need to filter by something, that something belongs in a key.

Cold starts: real, but tameable

Cold starts exist and they're annoying, but in 2026 the drama is overblown. In this panel, the backend was Node functions on Lambda behind API Gateway, and the extra latency on the first invocation was never a business problem: this was an internal tool, not a checkout with a millisecond SLA.

That said, here's what I actually do:

• Keep the bundle small. Fewer dependencies to load means a faster start. Bundling with esbuild and dropping what I don't use matters more than any clever trick.
• Instantiate the DynamoDB client outside the handler, so the connection is reused across warm invocations.
• Memory as a CPU lever. On Lambda, CPU scales with allocated memory; bumping from 128 to 512 MB is often cheaper and faster, because the function finishes sooner.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";

// Outside the handler: reused across warm invocations.
const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

export const handler = async (event: { category: string }) => {
  const res = await ddb.send(
    new QueryCommand({
      TableName: process.env.TABLE_NAME,
      IndexName: "GSI1",
      KeyConditionExpression: "GSI1PK = :pk",
      ExpressionAttributeValues: { ":pk": `CATEGORY#${event.category}` },
    }),
  );
  return { items: res.Items ?? [] };
};

💡 With serverless you don't pay for servers — you pay for designing your access patterns right on day one. That design debt doesn't refactor cheaply.

Amplify for the frontend and auth

The panel itself shipped on Amplify: frontend hosting, auth with Cognito underneath, and the glue between the client and the Lambdas. For an internal panel with a login, Amplify saves you weeks of plumbing. You don't stand up the session flow or the CI-backed hosting yourself.

It's convenient, at a price: Amplify is opinionated. The moment you step off its happy path, the abstraction starts to weigh on you, and debugging what it generates underneath gets tedious. For the scope of this project, the trade was a good one.

Infrastructure as code and the ops trade-offs

All of this lives in code. No hand-clicking resources in the console: tables, functions, IAM roles — all declared. Today, with the experience of running JXBS's infra in OpenTofu (ECS Fargate, queues, Secrets Manager, CI/CD), I'm even more convinced that the worst mistake is having resources nobody knows the origin of. If it isn't in code, it doesn't exist.

The upside of this model, no dressing it up:

• No servers to patch or maintain.
• Scale to zero: no traffic, no compute bill.
• A smaller ops surface for a small team.

The uncomfortable part, with the same honesty:

• Real lock-in. DynamoDB and Lambda don't migrate to another cloud without a rewrite.
• Debugging is different. There's no server to SSH into; you live in logs and traces.
• Cost can surprise you if you Scan or model badly: DynamoDB is dirt cheap used well and brutal used badly.

What I'd do differently today (2026)

I'd pick serverless again for this case; the shape of the problem hasn't changed. But I'd change a few things:

• Less Amplify, more explicit control. Today I'd wire up hosting and auth more directly and keep Amplify for prototypes, not for something that has to live for years.
• Start in OpenTofu, not the proprietary tool. It's what I run in production now, and I wouldn't go back.
• Invest in observability earlier. Distributed tracing from day one; in serverless, not having it is flying blind.

Painless serverless doesn't mean serverless without decisions. It means making the hard decisions up front — data modeling, IaC, observability — so you're not paying for them at 3 a.m. later.

Offline-first is not the same as offline-tolerant

An offline-tolerant app assumes the network is the norm and offline is the exception: when it fails, it shows a friendly error and waits. An offline-first app flips that premise. The immediate source of truth is local; the network is an implementation detail used to propagate and refresh data when it happens to be available.

At the Toyota event this wasn't an aesthetic choice. A rep capturing an interested customer's details can't sit staring at a spinner because the hall has saturated the mobile network. The capture had to complete every time, save locally, and go out to the server whenever it could. The backend was serverless on AWS —Amplify, Lambda, and DynamoDB— but from the frontend's point of view, the server might not exist for minutes and the app stayed fully usable.

Caching strategies in the service worker

The service worker is the heart of an offline-first PWA. The key is not to use a single strategy, but to pick one per resource type:

• App shell (precache): HTML, JS, CSS, and shell assets are precached on install. The app boots with no network.
• Stale-while-revalidate: for resources that can be slightly out of date (catalog images, icons). I serve the cache instantly and refresh in the background.
• Network-first with cache fallback: for data I want fresh when there's signal, but that can't block the experience when there isn't.

// sw.js — routed by resource type
self.addEventListener('fetch', (event) => {
  const { request } = event;
  const url = new URL(request.url);

  // API data: network-first with cache fallback
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(
      fetch(request)
        .then((res) => {
          const copy = res.clone();
          caches.open('api-cache').then((c) => c.put(request, copy));
          return res;
        })
        .catch(() => caches.match(request))
    );
    return;
  }

  // Catalog assets: stale-while-revalidate
  if (url.pathname.startsWith('/catalog/')) {
    event.respondWith(
      caches.match(request).then((cached) => {
        const network = fetch(request).then((res) => {
          caches.open('catalog-cache').then((c) => c.put(request, res.clone()));
          return res;
        });
        return cached || network;
      })
    );
    return;
  }

  // App shell: cache-first
  event.respondWith(caches.match(request).then((c) => c || fetch(request)));
});

Pending writes in IndexedDB

Reading offline is easy; writing offline is where the real work lives. Every data capture a rep made was first saved to IndexedDB as a pending operation, with its own client-generated id (a UUID), a timestamp, and the full payload. The UI gave immediate feedback: the record was saved, full stop. It didn't wait on the server.

That local queue is what turns offline into something you can trust. Nothing lives only in memory; if the rep closed the tab or ran out of battery, the operation was still there on reopen.

💡 In offline-first the network isn't the source of truth, it's just a sync channel. If your UI waits on the server to confirm anything, you're still building an offline-tolerant app in disguise.

Deferred sync when the signal returns

When connectivity came back, that queue had to be drained. I used the Background Sync API to hand that work to the browser: I register a sync event and the system itself decides when there's a stable network to run it, even if the tab is no longer in the foreground.

// When queuing a write, ask for a deferred sync
async function queueWrite(record) {
  await idbPut('pending-writes', record); // save to IndexedDB
  const reg = await navigator.serviceWorker.ready;
  if ('sync' in reg) {
    await reg.sync.register('flush-writes');
  }
}

// In the service worker: drain the queue when the browser allows it
self.addEventListener('sync', (event) => {
  if (event.tag === 'flush-writes') {
    event.waitUntil(flushPendingWrites());
  }
});

async function flushPendingWrites() {
  const pending = await idbGetAll('pending-writes');
  for (const record of pending) {
    const res = await fetch('/api/leads', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Idempotency-Key': record.id, // the client UUID
      },
      body: JSON.stringify(record),
    });
    if (res.ok) await idbDelete('pending-writes', record.id);
  }
}

Conflicts and idempotency

The scenario you can't ignore: the write did reach the server, but the response got lost on the network before coming back. The client thinks it failed and retries. Without protection, you duplicate the record.

The fix was idempotency using the client's key. That UUID generated when the data was captured traveled as the Idempotency-Key. In the Lambda, if a record with that key already existed, we returned the existing result instead of creating a new one. Retrying was safe by design: a thousand retries produced a single record.

For edit conflicts on the same piece of data, the rule was simple and explainable: last-write-wins by client timestamp. It wasn't CRDTs or anything sophisticated, but for the event's flow —mostly independent captures— it was enough and predictable.

The UX of sync state

Everything above is invisible to the rep, and that's how it should be almost always. But "almost" is the operative word. The person at the booth needs confidence, not technical detail. We showed three simple states:

• Saved (local, not yet synced): a check and "saved on device."
• Syncing: a discreet indicator while the queue was draining.
• Synced: confirmation the data now lived on the server.

I also showed a "pending to send" counter. That reassured a non-technical person: they knew nothing had been lost even without signal, and they knew when everything was safe before closing out their shift.

What I'd do differently in 2026

Today I'd rethink a couple of things. First, I'd lean more on mature libraries instead of writing so much by hand: Workbox for the service worker strategies, and a layer like Dexie over IndexedDB instead of the raw API. Second, for sync I'd evaluate a real local-first engine —something with CRDT-based reconciliation when the flow justifies it— so I'm not locked into last-write-wins in cases with genuine concurrent editing. And third, I'd be more deliberate about observability: record queue metrics (size, operation age, retry rate) to diagnose in the field, because at an event you don't have time to open DevTools. The core idea, though, I wouldn't touch: the signal is optional, the work is not.

Why I stayed in Postgres

The pull toward Pinecone, Weaviate, or Qdrant is real. But every new datastore is one more thing to operate, monitor, back up, and keep consistent. In a recruitment product, semantic similarity never travels alone: I always cross it with structured data. Location, seniority, availability, whether the opening is still active. If the vectors live in another system, every search becomes two queries and a join stitched together by hand in application code.

Keeping it all in Postgres buys me three concrete things. Transactions: when I update a candidate and their embedding, either both land or neither does. Joins: I filter on structured columns and order by vector distance in the same query. And operational simplicity: one backup, one place to monitor, one Prisma migration. On ECS Fargate with OpenTofu, every extra piece of infrastructure is paid for in maintenance time.

How embeddings work, at a practical level

An embedding is a vector of numbers representing the meaning of a piece of text. Similar texts land close together in that space; unrelated ones land far apart. I don't need to understand high-dimensional geometry to use it: I hand the text to an embedding model, it returns an array of floats, and I store it.

What matters is which text I feed it. For a candidate I don't pass the raw résumé wholesale — I build a structured summary of experience, technologies, and role. For an opening, the title plus the actual requirements. Garbage in, garbage out: embedding quality depends on the quality of the source text far more than on the model.

Storing vectors with pgvector

pgvector adds a vector type and distance operators. The table looks like this:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE candidate_embedding (
  candidate_id  UUID PRIMARY KEY REFERENCES candidate(id),
  embedding     vector(1536) NOT NULL,
  seniority     TEXT NOT NULL,
  location      TEXT NOT NULL,
  is_available  BOOLEAN NOT NULL DEFAULT true,
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX ON candidate_embedding
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

The <=> operator is cosine distance. Smaller distance, higher similarity. I pick cosine because I care about the vector's direction, not its magnitude.

Index choice: HNSW vs IVFFlat

pgvector offers two index types and the difference matters. IVFFlat groups vectors into lists and searches only the nearest ones: it builds fast and stays small, but its recall depends on how many lists you probe and it struggles as the data grows. HNSW builds a layered navigable graph: better recall at lower query latency, in exchange for slower builds and higher memory use.

I went with HNSW. In recruitment, a relevant candidate who never surfaces is a silent failure — nobody reports it, but it quietly degrades the product. I'd rather pay in index build time and RAM for stable recall. ef_construction controls graph quality at build time; at query time, raising ef_search improves recall at the cost of latency. That's the lever for the trade-off, and I move it based on what I measure, not on a hunch.

💡 Cosine distance tells you what's similar; it doesn't tell you what's right. That gap is the whole product.

Hybrid search: why I don't trust cosine alone

This is the point that took me longest to learn. Semantic similarity is great at finding things that resemble each other, but "resembles" isn't "correct." A senior backend engineer in Caracas and a junior one in another time zone can have close embeddings because they share technologies. Cosine has no idea the opening demands high seniority and local presence.

So I run hybrid search: vector similarity is a signal, not the verdict. I filter with WHERE on structured columns and blend the distance with a structured score.

SELECT
  c.candidate_id,
  1 - (c.embedding <=> $1::vector)              AS similarity,
  CASE WHEN c.seniority = $2 THEN 0.3 ELSE 0 END AS seniority_boost
FROM candidate_embedding c
WHERE c.is_available = true
  AND c.location = $3
ORDER BY (c.embedding <=> $1::vector)
         - CASE WHEN c.seniority = $2 THEN 0.3 ELSE 0 END
LIMIT 20;

The WHERE trims the space to eligible candidates before ranking. Semantic similarity orders within that set, and a structured boost adjusts the final order. The weights are configurable, and I tune them against what the recruitment team considers a good match, not against an abstract cosine metric.

Chunking and keeping embeddings fresh

Long résumés don't go in as a single pass. I split them into meaningful sections (experience, skills, education) so the "backend experience" embedding isn't diluted by three paragraphs of hobbies. It's pragmatic chunking, guided by document structure rather than a fixed token size.

Freshness: an embedding is a snapshot of the text at a moment in time. If a candidate updates their profile or an opening changes its requirements, the vector goes stale. I store a hash of the source text; when it changes, I re-enqueue regeneration. That way I only recompute what actually changed, and I don't burn model calls for nothing.

Costs, and when I would reach for a vector DB

Generating embeddings costs per token, and that's the real spend — not storage. Re-enqueuing only on a hash change keeps the bill in check. HNSW is heavy in RAM, so I size the Postgres instance with the index in mind, not just the rows.

When would I leave Postgres? If I hit hundreds of millions of vectors with very high, sustained search traffic, where the index no longer fits comfortably in memory and latency becomes the business bottleneck. At that scale, a dedicated vector engine with sharding earns its keep. But that's a decision you make with real load numbers, not by front-running a problem that may never arrive. Until then, Postgres with pgvector does the job and leaves me with fewer moving parts that can break.

Why one backend stopped scaling with us

The problem was never performance. It was coupling and the blast radius of every deploy.

When everything lives under one NestJS root module, the boundaries blur on their own. A candidates service starts importing something from the companies module "just for now." A guard meant for admin sneaks into a public route. And since it's a single process, everything shares the same config, the same PostgreSQL connection pool, the same startup cycle.

Three concrete symptoms pushed us to move:

• Deploy blast radius. A change in the admin portal forced a redeploy of the entire backend. If something broke, it all went down, including the public candidates portal that hadn't changed in weeks.
• Mixed audiences. Different portals have different auth requirements, different rate limits, different exposure surface. Cramming them into one process meant the most sensitive route set the paranoia level for everything.
• Shared cognition. Every person on the team had to load the whole domain into their head just to touch a small part of it.

What "per-audience backends" means

The idea is simple: one backend per portal. One for candidates, one for companies, one for admin. Each is its own independent NestJS 11 service, with its own deploy, its own config, and its own API surface. The frontend stays Next.js 15 with React 19, and each portal talks to its backend.

What does not change is the database or the domain. We're still on PostgreSQL + pgvector with Prisma. The trick is that shared code —entities, domain logic, utilities, the Prisma client— lives in monorepo packages (Turborepo + pnpm), not duplicated across services.

apps/
  candidates-api/        # NestJS 11 — candidates portal
  companies-api/         # NestJS 11 — companies portal
  admin-api/             # NestJS 11 — admin portal
  web-candidates/        # Next.js 15
  web-companies/         # Next.js 15
packages/
  domain/                # pure domain logic, no NestJS
  database/              # Prisma client + repos
  auth/                  # reusable auth module
  config/                # env loading + validation

The rule that saved us: packages under packages/ expose classes and functions; the apps/ decide how to wire them. The domain doesn't know which backend it's running in.

The pnpm + dependency-injection traps nobody mentions

This is where I lost hours. NestJS assumes a provider is a singleton within its container. pnpm, with its strict node_modules layout and its symlinks, can quietly break that assumption.

The first hit: duplicated provider instances. If a shared package declares a provider and two different modules import it via slightly different paths, you end up with two instances. A "singleton" that isn't one. You notice it when an in-memory cache or a connection pool behaves inconsistently.

The cause is almost always the same: the provider token isn't identical across importers, or the shared dependency got installed in two places in the tree.

The pattern that avoids it: a global dynamic module with an explicit token, declared exactly once.

// packages/database/src/database.module.ts
import { Global, Module, DynamicModule } from '@nestjs/common';
import { PrismaService } from './prisma.service';

export const PRISMA = Symbol('PRISMA'); // stable, unique token

@Global()
@Module({})
export class DatabaseModule {
  static forRoot(): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [{ provide: PRISMA, useClass: PrismaService }],
      exports: [PRISMA],
    };
  }
}

Each app calls DatabaseModule.forRoot() once in its root module. The token is an exported Symbol, so there's no string ambiguity and no collision risk.

The other two that bit me:

• Peer deps, not direct deps. Shared packages declare @nestjs/common and @nestjs/core as peerDependencies, never as regular dependencies. If a package ships its own copy of NestJS, its decorators and metadata live in a different realm and DI simply won't recognize them. In pnpm-workspace.yaml, leaning on the catalog to pin a single version helps a lot.
• Module boundaries, not folder boundaries. A package can export code; whether it's a NestJS @Module is a separate decision. We kept packages/domain NestJS-free —pure classes and functions— and only packages/auth and packages/database expose modules. That way the domain gets reused without dragging the DI container everywhere.

💡 In a monorepo, a "singleton" is only a singleton if the token is identical and the dependency is installed exactly once. pnpm won't warn you when that's false: it tells you in production.

How to share domain logic without recoupling it

The obvious risk of splitting the monolith is rebuilding the coupling inside the packages. A shared package that knows everything is the monolith with a new name.

What worked:

• The domain imports no infrastructure. packages/domain knows nothing about Prisma or NestJS. It takes interfaces; the apps inject implementations.
• One package, one responsibility. auth, database, config kept separate. If you're unsure which package something belongs to, it probably belongs to the app.
• No cross-backend dependencies. candidates-api never imports from companies-api. If they need to talk, it's over an API or a shared contract in packages/, never a direct import.

Deploying multiple services on ECS Fargate

Each backend is its own service on ECS Fargate: its own task definition, its own image, its own auto-scaling. We manage CI/CD with OpenTofu, so adding a backend is declaring a new module, not clicking through a console.

Turborepo gives us the other pillar: affected builds. Only what changed gets built and deployed. Touching admin-api doesn't rebuild candidates-api. That was the original goal —shrinking the blast radius— and this is where it becomes real.

The detail that watches the budget: each service sizes its CPU and memory to its own load. The candidates portal and the admin portal don't have to pay for the same task size.

Doing it without a big-bang

We rewrote nothing all at once. We extracted one backend first —the lowest-risk one— leaving the monolith serving the rest. Portal by portal, we moved routes to the new service and pointed the corresponding frontend at it. The monolith kept shrinking until it was gone.

What I'd tell my past self

Draw the audience boundaries from day one, even if everything lives in a single process at first. Separating modules with clear limits is cheap; untangling a coupled monolith is expensive. And treat dependency injection in a pnpm monorepo as what it really is: a question of instance identity, not of imports. Pin the versions, use explicit tokens, keep the domain pure. The rest follows.

Tokens are the contract, not a detail

Before you talk about components you have to talk about tokens, because they're the first thing you break without noticing. A token is a design decision with a stable name: a color, a spacing step, a type scale. If one portal hardcodes #2563eb and another uses var(--color-primary), you don't have a design system, you have two systems that happen to match by accident.

I treat tokens as the public contract. Consumers don't ask for hex colors; they ask for semantic intent.

:root {
  /* Primitives: never used directly in components */
  --blue-600: #2563eb;
  --gray-900: #111827;
  --space-2: 0.5rem;
  --space-4: 1rem;

  /* Semantic: this is what the consumer touches */
  --color-action: var(--blue-600);
  --color-text-strong: var(--gray-900);
  --radius-control: 0.5rem;
}

[data-theme="dark"] {
  --color-text-strong: #f9fafb;
}

The semantic layer is what lets me theme without touching a single component. I change the mapping, not the signature. And that split between primitives and semantics is exactly what stops someone from coupling their portal to a specific blue that I'll want to move tomorrow.

A component's API is a promise

With React 19 and TypeScript, a component's signature is a contract as serious as any HTTP API. Every prop I expose is something I'll have to hold up across versions. That's why I lean on composition over configuration: instead of a <Card> with twenty boolean props, I expose pieces that combine.

// Bad: configuration that grows without end
<Card title="..." footer withBorder elevated dense hasIcon />

// Better: composition, the consumer assembles their case
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>...</Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>

Two rules I don't negotiate. First: don't leak the internal DOM. If I expose a className that lands on some arbitrary <div>, and tomorrow that <div> disappears, I break everyone who relied on that structure. I'd rather offer explicit extension points (asChild, slots, typed variants) than let people style my guts. Second: stable props are sacred. Renaming variant to kind "because it reads better" isn't a refactor, it's breaking six teams at once.

💡 A design system isn't measured by how many components it has, but by how many people can build on top of it without messaging you.

Versioning inside the monorepo without hurting people

Turborepo and pnpm let everything live together, and that has a trap: it's far too easy to "bump everything" at once. I use changesets with real semver. A semantic color change is a patch. A new optional prop is a minor. Removing a prop, renaming it, or changing DOM that someone might be selecting is a major —and a major demands notice, a migration guide, and sometimes a window where the old version keeps living alongside the new one.

What I religiously avoid is the reflex "bump everything." If I only touch Button, I don't want to force a portal that doesn't even use it to rebuild and re-verify. Granular versioning is what keeps trust alive: when you upgrade, you know what's going to hurt before it hurts.

Accessibility for free, and the social side

At Acid Tango, in Madrid, I pushed WCAG 2.1 AA as a team standard, and that experience changed how I build libraries. The best accessibility is the kind the consumer gets for free. If my Dialog handles focus, Escape, aria-modal, and returning focus to the trigger, then every portal is accessible without its developer knowing anything about ARIA. Keyboard support, focus management, and contrast aren't optional features: they're the floor.

But the hardest part isn't technical, it's social. A design system has governance whether anyone writes it down or not. I try to make it explicit: who decides what gets in, how you propose a new component, and —the uncomfortable one— how you say no. I say no when something serves a single portal; that lives in the portal, not in the core. To onboard a new component I ask for three things: a real, repeated use case, documentation with copy-pasteable examples, and accessibility solved before it merges. Without examples, people reinvent; and every reinvention is a crack in the contract.

What I'd do differently in 2026

I'd document before coding. For a while documentation showed up afterward, and that's too late: if you can't explain the API in a short example, the API is wrong. Today I'd write the usage example first and let it dictate the signature.

I'd also be more aggressive about graduated deprecation. Marking a prop @deprecated in TypeScript, letting it keep working for a few versions, and warning on every build is infinitely kinder than a surprise major. A mature design system isn't measured by how fast it changes, but by how predictable it is when it does.