DEV Community: Jurij Tokarski

45 Tabs I Stopped Opening

Jurij Tokarski — Thu, 09 Apr 2026 14:45:00 +0000

The JWT decoder I used to reach for sent the token to a server. I noticed because I had DevTools open for something else and saw the POST. A JWT often carries user IDs, emails, roles, expiration data. I'd been pasting production tokens into a stranger's endpoint for months.

That was the first tool I built for the toolkit. The rest followed the same pattern: I needed something, the available options were ad-heavy or required sign-up or made network calls that didn't need to happen. A Base64 encoder doesn't need a backend. Neither does a regex tester, a color converter, or a hash generator.

There are 45 tools now. No sign-up, no tracking, no data collection. Most run entirely in the browser — a few like DNS Lookup and SSL Checker need a server call by nature.

The Catalogue

Encoding — Base64, JWT Decoder, Image to Base64, Encrypt / Decrypt, Hash Generator

JSON & YAML — JSON Formatter, JSON ↔ YAML, YAML Validator

Markdown — Markdown Preview, Text Diff, HTML ↔ Markdown, Markdown to PDF, Markdown to DOCX, CSV Editor

Images — QR Code, Barcode, Image Converter, Favicon Generator, SVG Optimizer, Placeholder Images, Aspect Ratio

Design — Mesh Gradient, CSS Cover Art, Color Converter, Text to Gradient

Charts — Bar Chart Race, Line Chart Race, Bubble Chart Race, Area Chart Race

Network — DNS Lookup, CORS Tester, SSL Checker, OG Tag Validator, HTTP Status Codes, Robots.txt Validator, Sitemap Validator, User Agent Parser

Text — Regex Tester, Case Converter, Slug Generator, Word Counter, Copy Paste Characters

Generators — UUID, Password, Crontab, Unix Timestamp

Most are straightforward. Three outgrew the toolkit and became standalone npm packages.

Text to Gradient

The Text to Gradient tool and the Mesh Gradient Generator both needed the same thing: a way to turn an arbitrary input into a unique, stable visual. Same input, same gradient, every time. No database, no storage.

A djb2-style 32-bit hash is all it takes:

function textHash(str) {
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash) + str.charCodeAt(i);
    hash = hash >>> 0;
  }
  return hash;
}

Everything derives from that number. hash % palettes.length selects the color palette. seededRandom(hash + layerIndex * 1000) generates position and opacity variation per layer. The same string always produces the same gradient — looks hand-crafted, costs nothing to store.

The gradients themselves are layered radial-gradient() calls. There's no mesh-gradient() in CSS. What works is stacking 6-8 radial gradients positioned at organic spots — 15%, 37%, 63%, 82% — not pure corners or centers, which look algorithmic. Each one uses a 0px first stop for a crisp center and transparent at 50% for soft falloff. The browser composites them in layer order.

background:
  radial-gradient(ellipse at 15% 20%, rgba(120, 40, 200, 0.9) 0px, transparent 60%),
  radial-gradient(circle at 80% 10%, rgba(40, 180, 220, 0.8) 0px, transparent 50%),
  radial-gradient(ellipse at 55% 75%, rgba(200, 60, 120, 0.85) 0px, transparent 55%),
  #1a0a2e;

For tinting — hover states, borders, soft fills — color-mix() handles it without any HSL arithmetic:

background-color: color-mix(in srgb, var(--accent) 12%, white);
border-color: color-mix(in srgb, var(--accent) 25%, transparent);

One thing that cost me time: making these dynamic in Tailwind. A template literal like bg-[color-mix(in_srgb,${color}_12%,white)] silently produces nothing. Tailwind's compiler scans source files for complete static strings at build time. A class assembled from a variable doesn't exist as a string when the scanner runs — it gets skipped with no warning. Inline styles are the fallback for truly dynamic values.

Text to Gradient is now an npm package. It powers the default cover images across the site when a page has no custom visual. Those covers are also animated — which is where the next package came from.

Loopkit

Every tool, blog post, landing page, and discovery step on varstatt.com has an animated SVG cover — all powered by Loopkit. I had ~35 cover designs already in JSX when I started building the engine underneath them. The first decision was whether to keep composable React components or switch to schema-driven JSON.

JSON won because of output flexibility. A React component locks you into JSX. A schema is data — it can render to HTML for OG images, to SVG for exports, to CSS for emails, or to React for the live site. The core engine has no React dependency.

const cover = createCover(schema);
cover.html       // full HTML with inline styles
cover.style      // React style objects
cover.innerHtml  // just the elements
cover.hoverCss   // raw CSS rules

Phase ordering. I had the cycle structured as: animate forward, hold final frame, fade out, loop. Loop restarts were smooth, but the first play() call snapped instantly from the held frame to frame 0. Moving the fade to the beginning of the cycle fixed it — every iteration, including the first, starts with a reverse interpolation from wherever the animation sits, then plays forward.

Hover exits. mouseenter called play(), mouseleave called reset(). The reset snapped to the static frame — functional but mechanical. A settle() method reads the live position and interpolates smoothly from there to the end state over a capped duration. The key: tracking currentAnimElapsed during active animation is what makes settle() possible. Without it, mouseleave can only snap.

Stagger math. In a staggered loop where each element has its own delay, the cycle duration isn't animDuration. It's the time until the last element finishes, plus hold time. Using just animDuration cuts off late-starting elements before they complete.

let lastFinish = 0;
for (const el of schema.elements) {
  const delay = computeDelay(el.animate.sequence ?? 0, schema.stagger ?? 0);
  const duration = el.animate.duration ?? schema.duration ?? 1;
  lastFinish = Math.max(lastFinish, delay + duration);
}
const cycleDuration = lastFinish + holdDuration;

Re-centering all 48 schemas programmatically surfaced one more problem. The centering script computes a bounding box, then shifts coordinates to align with the canvas center. Loopkit schemas use [from, to] arrays for animated values — a bar animates with y: [247, 87]. The bbox script was reading [0], the start value. A bar starting at y=247 with height 180 gave a 427px bounding box on a 280px canvas. The fix was one index: read [1], the end state, because that's the visual rest position.

Loopkit is under 5KB with zero dependencies. It's an npm package now.

Markdown Repository

Markdown Repository began as a utility function inside this site. I query .md and .mdx files by frontmatter — filter by tags, sort by date, paginate. The API looks like Firestore's where/orderBy/limit chain. Once three of my projects used the same copy-pasted code, I extracted it into an npm package. The publish pipeline — trusted publishing with OIDC, no stored tokens — turned into its own post.

The Full List

45 tools, three npm packages. The full list is at varstatt.com/toolkit.

npm Publish Without Tokens

Jurij Tokarski — Tue, 07 Apr 2026 10:35:00 +0000

I published an npm package last week — markdown-repository, a Firestore-style query builder for markdown files. The code worked. The tests passed. The release pipeline took longer to get right than the package itself.

The Old Way

The standard npm publishing workflow uses a long-lived access token. You generate it on npmjs.com, store it as a GitHub Actions secret, and reference it in your workflow:

- run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

It works, but the token never expires, has write access to your packages, and lives in plain text in your CI secrets. If it leaks — through a copied workflow file or a careless log — anyone can publish under your name.

npm's granular tokens improved this slightly. You can scope them to specific packages and set a 90-day expiration. But you still have to rotate them manually.

Trusted Publishing

npm now supports trusted publishing with OIDC. Instead of a stored token, your GitHub Actions workflow proves its identity to npm using a short-lived OpenID Connect credential. npm verifies the credential against the workflow you've authorized, and accepts the publish.

No token to store. No token to rotate. No token to leak.

First Publish Is Manual

Before you can configure trusted publishing, the package must already exist on the registry. npm has no "pending publisher" feature — you can't set up OIDC for a package that doesn't exist yet.

For the very first version, publish from your machine:

npm login
npm publish --access public

I spent a while debugging my workflow before realizing trusted publishing only works from the second release onward. Once the package exists on npmjs.com, go to its settings and add a trusted publisher. From that point, the workflow handles everything.

Setting Up the Workflow

The setup has two parts.

On npmjs.com: go to your package settings, add a trusted publisher. Specify the GitHub org/user, repository, workflow filename, and optionally an environment name.

In the workflow: add id-token: write permission and an environment that matches what you configured on npm.

name: Release

on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24.x
          registry-url: https://registry.npmjs.org
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: npm publish --provenance --access public

Provenance attestation is automatic with trusted publishing. The --provenance flag is redundant but makes the intent explicit.

The Misleading 404

My first three releases failed with this error:

npm error 404 Not Found - PUT https://registry.npmjs.org/markdown-repository
npm error 404 'markdown-repository@1.1.0' is not in this registry.

The package existed. The version was correct. The OIDC token exchange succeeded — I could see the signed provenance statement in Rekor's transparency log. Everything worked except the actual publish.

The problem: Node 22 ships with npm 10.x. Trusted publishing requires npm 11.5.1 or later.

npm's documentation mentions this requirement. The error message doesn't. A 404 on PUT looks like a registry problem or a package name conflict. Nothing points you toward an npm version mismatch.

The Fix

Use Node 24.x in your workflow. On GitHub Actions, node-version: 24.x resolves to a recent patch that includes npm 11.5.1+ — markdown-repository publishes this way without an explicit npm upgrade.

- uses: actions/setup-node@v4
  with:
    node-version: 24.x

If you're stuck on an older Node version, upgrade npm explicitly:

- run: npm install -g npm@latest

With npm 11.5.1+, the same workflow publishes successfully. No tokens needed.

The Environment Mismatch

The same 404 shows up when the environment name on npmjs.com doesn't match the environment field in your workflow job. If your workflow says environment: release but npm has the environment field blank (or vice versa), the OIDC claims don't match and npm rejects the publish — with a 404, not a meaningful error.

What the Pipeline Looks Like Now

The full workflow for markdown-repository runs lint, tests, and build on every commit. On a GitHub release, it publishes to npm with provenance — no secrets configured anywhere in the repository.

Three Ways the Wrong Value Won

Jurij Tokarski — Tue, 31 Mar 2026 00:00:00 +0000

A user created a tender and immediately couldn't edit it. Not after a day, not after some permission change — immediately. They hit "Create," the page loaded, and the edit button was grayed out.

That was the first bug. It took three fixes across two projects before I understood what connected them: in each case, the value that reached the client wasn't the value I'd computed. Something else got there first — by being faster, by being stale, or by being last in the object literal.

The Value That Arrived Too Early

I pulled up the tender document in Firestore. The ai_driver field was missing entirely. The frontend created tenders like this:

const tenderData = {
  title,
  company_id: companyId,
  ...(companyData?.ai_driver && { ai_driver: companyData.ai_driver }),
};

New companies had no ai_driver set. The conditional spread evaluated to falsy, so the field was never written. That was supposed to be fine — a Cloud Function trigger would set the default after creation.

The Firestore snapshot listener had other plans. It fired before the Cloud Function, saw no ai_driver, and ran this check:

const isDiscontinuedDriver =
  !tender.ai_driver || DISCONTINUED_AI_DRIVERS.includes(tender.ai_driver);

Missing field. Falsy. "Discontinued." Read-only. The user just watched their tender lock itself. Every single tender created by a new company since this code shipped had been born locked.

The fix had two parts. The frontend writes every field it reads immediately after creation — no delegating defaults to triggers:

const tenderData = {
  title,
  company_id: companyId,
  ai_driver: companyData?.ai_driver || DEFAULT_AI_DRIVER,
};

And the discontinuation check had to distinguish "missing" from "actively deprecated":

const isDiscontinuedDriver =
  tender.ai_driver && DISCONTINUED_AI_DRIVERS.includes(tender.ai_driver);

Deployed both. Bug reports kept coming.

The Value That Outlived Its Meaning

Different users, same symptom. Tenders locked on creation. But these companies had ai_driver explicitly set in Firestore — set to assistants-api-gpt4o, a driver I'd discontinued months earlier.

I traced it to the organization settings form:

aiDriver: company.ai_driver || "assistants-api-gpt4o",

That hardcoded fallback was a leftover from migration. New companies had no ai_driver in Firestore, so the form loaded with a dead value nobody could see. The field wasn't even visible on the settings page — it was an internal config, not a user-facing dropdown.

The form submitted its entire state on every save. A user enables a jurisdiction toggle, hits save, and the payload includes ai_driver: "assistants-api-gpt4o". The backend guard:

if (payload.ai_driver) {
  update.ai_driver = payload.ai_driver;
}

Truthy string passes. The discontinued driver gets written to Firestore. Every tender created after that inherits it. The user who toggled a jurisdiction setting three weeks ago has no idea they just broke tender creation for their entire organization.

I dropped the hardcoded fallback. Deployed. Reports kept coming — users had the old bundle cached. Every save from a cached session re-wrote the stale value, undoing any Firestore cleanup I ran manually.

The frontend fix wasn't the real fix. The real fix was backend enum validation:

if (payload.ai_driver && Object.values(AIDriver).includes(payload.ai_driver)) {
  update.ai_driver = payload.ai_driver;
}

The backend rejects any value not in the current enum. Cached bundles, stale defaults, garbage input — all dropped. The frontend can send whatever it wants; the backend is the last line, and it has to act like it.

That stopped the bleeding. But the pattern was already in my head when I opened a different codebase weeks later.

The Value That Was Always Last

I was reviewing a feature flag called ai_chat_enabled. The backend computed it from the user's subscription plan — a careful if/else chain that looked up the plan, checked edge cases, and resolved to a boolean. Solid logic. Well-tested in isolation.

Then I looked at the response builder:

return {
  statusCode: 200,
  body: {
    email: email_address,
    name: name,
    plan: plan,
    ai_chat_enabled: ai_chat_enabled,
    ...customerPreferences,
  },
};

customerPreferences came from DynamoDB. It contained its own ai_chat_enabled key — the raw stored preference, not the computed one. The spread came after the explicit assignment.

JavaScript object literals follow last-writer-wins. The spread silently overwrote the computed value with whatever was sitting in the database. The entire plan-based computation — the lookup, the edge cases, the if/else chain — never reached the client. Not once. Not since the day this code shipped.

The tests checked that the computation logic returned the right boolean. They never checked that the response builder actually used it.

The fix was one line — move the spread before the explicit fields:

return {
  statusCode: 200,
  body: {
    ...customerPreferences,
    email: email_address,
    name: name,
    plan: plan,
    ai_chat_enabled: ai_chat_enabled,
  },
};

Computed values last. Raw data first. The spread provides defaults; the explicit fields override them.

The Wrong Value Always Has a Way In

Timing, staleness, ordering. Three mechanisms, same result: the value I intended never made it. If the frontend reads a field, the backend must validate it. If the backend computes a value, nothing downstream should be able to quietly replace it. The wrong value will always find a way in. The only defense is making sure the right value goes last.

An Empty AI Response Corrupted Chat History

Jurij Tokarski — Thu, 26 Mar 2026 00:00:00 +0000

The spinner ran. The stream closed. The chat bubble stayed empty. No error anywhere.

I was building a conversational discovery tool for founders — a multi-step Gemini-powered flow that walked people through product decisions, collected answers, and built a structured brief. Complex setup: long system prompt, tool definitions, large user messages. Genkit's generateStream handling each turn.

Intermittently, a user would send a message and get nothing back. No timeout, no catch block firing, no non-2xx status. Just a clean stream completion with zero content inside.

What the Logs Said When I Added Them

Standard error handling gives you no signal here:

try {
  const { stream, response } = await ai.generateStream({ ... });
  for await (const chunk of stream) {
    // exits immediately — no chunks arrive
  }
  // response.text() returns ''
  // no exception thrown
} catch (err) {
  // never reached
}

Adding chunk-level logging made it visible. The stream was completing, but the one chunk that arrived looked like this:

Chunk #1 has no content.
Keys: [ 'index', 'role', 'content', 'custom', 'previousChunks', 'parser' ]
role: model
content.length: 0

The content property existed. It wasn't null. It was an empty array. The keys custom, previousChunks, and parser are Genkit's internal markers for a thinking chunk. The model had spent the entire response budget on internal reasoning and had nothing left to output. HTTP 200. Genkit reported success.

Two Ways to Get Nothing

Gemini 2.5 Flash ships with thinking mode enabled by default. Under normal inputs that's fine. Under heavy inputs — long system prompt plus tool definitions plus a long user message — it can exhaust the entire token budget on reasoning before producing a single output token.

There's a second cause that produces the same result: silent rate limiting. Rather than returning a 4xx, Gemini returns a valid, complete, empty stream. The observable symptom is identical. The detection is identical: assert that at least one content chunk arrived after the stream closes.

For the thinking mode case, the fix is one line in the Genkit config:

const { stream, response } = ai.generateStream({
  model: MODEL,
  system: systemPrompt,
  messages,
  tools,
  config: {
    thinkingConfig: { thinkingBudget: 0 },
  },
});

thinkingBudget: 0 disables extended thinking. For a conversational flow where latency matters more than deep reasoning, there's no reason to let the model spend the budget on internal traces.

Fix deployed. I moved on.

The Save That Made It Permanent

What I hadn't checked: the database. Every one of those empty responses had already been saved to Firestore. An empty string is a valid string. The save ran. Nothing flagged it.

The stream handler read finalResult.text after generateStream resolved and wrote it as the AI's message. When thinking mode ate the budget, finalResult.text was "". Firestore now held a record of every affected conversation — each one storing a legitimate-looking AI turn with no content.

History as Poison

When those users came back and sent new messages, getChatHistory pulled their messages from Firestore and formatted them for Gemini:

return messages.map((msg) => ({
  role: msg.role === "ai" ? "model" : "user",
  content: [{ text: msg.content }],
}));

When msg.content is "", that produces { role: "model", content: [{ text: "" }] }. A valid-looking empty model turn in the middle of a real conversation. Gemini received it, interpreted it as unfinished context, entered thinking mode to reason about it, exhausted the budget, returned nothing — which got saved as another empty message, which poisoned the next turn.

The conversation was permanently, silently broken. No exception at any layer. No signal the user could act on. Just a chat that would never respond again.

The Fix That Requires Two Places

Fixing only the stream detection isn't enough — the database is already corrupted. Fixing only the history filter isn't enough — new empty responses can still arrive and be saved. Both defenses are required.

Never write an empty AI message:

const finalText = accumulatedText || finalResult.text || "";
if (finalText) {
  await saveAIMessage(chatId, finalText);
} else {
  console.warn("[StreamHandler] Skipping empty AI message save");
}

And filter empty turns before sending history to the model:

return messages
  .filter((msg) => msg.content)
  .map((msg) => ({
    role: msg.role === "ai" ? "model" : "user",
    content: [{ text: msg.content }],
  }));

Miss either one and the loop can restart. The stream guard stops new corruption. The history filter handles the records already in the database.

The Retry That Made It Worse

The first instinct after detecting an empty stream was to retry. The naive retry called the same send function — which re-inserted the user's message into the messages array. The model received the question twice. On an already-stressed conversation with heavy context, this accelerated the problem rather than resolving it.

The fix is an isRetry flag that skips message insertion on retry calls:

async function streamMessage(content, sessionId, token, { isRetry = false } = {}) {
  if (!isRetry) {
    setChatMessages(prev => [
      ...prev,
      { id: userMsgId, role: 'user', content },
      { id: aiMsgId,   role: 'assistant', content: '' },
    ]);
  } else {
    setChatMessages(prev => [
      ...prev.filter(m => m.id !== aiMsgId),
      { id: aiMsgId, role: 'assistant', content: '' },
    ]);
  }

  await streamAIResponse(sessionId, token);
}

The user message stays in history exactly once. Without this, retry logic breaks an already-broken conversation faster.

Why Every Layer Said "Success"

What made this hard to debug: every layer reported success. HTTP 200, no caught exceptions, valid Firestore writes, clean history formatting. The failure was in the semantics, not the mechanics. An empty model turn is not a successful model turn — and asserting that distinction at each boundary is the only thing that stops the loop.

Software Engineering Principles for Startups

Jurij Tokarski — Mon, 23 Mar 2026 00:00:00 +0000

Most software engineering principles are written for teams of 50. Agile ceremonies, sprint retrospectives, quarterly planning — built for organizations, not for founders shipping products.

I run a solo development studio. I ship to production every week, manage multiple client projects simultaneously, and maintain everything I build. Over the years I wrote down the principles that make this work. There are 33 of them, organized across five areas: philosophy, discovery, delivery, partnership, and diligence.

Here's what actually matters when you're building software for startups.

Start With What's Worth Building

The most expensive software is software that shouldn't exist. Before writing any code, I run every project through a simple filter: is this worth building?

Most ideas aren't. Not because they're bad ideas — but because they solve the wrong problem, or solve it at the wrong time, or solve it for a market that doesn't care enough to pay.

When something passes that filter, the next step is finding the core — the one capability that makes this product exist. Not the feature list. Not the competitor parity matrix. The single thing that, if it doesn't work, means nothing else matters.

Jane's booking app needed staff-to-service matching that handled real salon complexity. Everything else — payment processing, notifications, calendar sync — is infrastructure you can buy. The core is the only part worth building custom.

Fix the Budget, Flex the Scope

Startups don't have unlimited time or money. The traditional approach — estimate everything, add buffer, hope it fits — doesn't work because estimates are wrong.

I use appetite, not estimates. You decide how much time a problem is worth — two weeks, six weeks — and that's your constraint. Then scope shaping fits what you build inside that box.

This sounds backwards but it changes everything. Instead of "how long will this take?" the question becomes "what's the best version we can ship in three weeks?" That question has a useful answer.

Ship Continuously, Not Eventually

Startup velocity comes from short feedback loops. Every principle in my delivery system optimizes for one thing: getting working software in front of users faster.

WIP One means one task in progress at a time. Finish it, deploy it, move on. Context switching kills solo developers faster than bad architecture.

Production is done means nothing counts until it's live. Not "done on my machine." Not "ready for review." Live in production with monitoring in place. This sounds obvious but most projects have weeks of "almost done" work that never ships.

Continuous flow replaces sprints with a priority queue. No sprint planning, no velocity tracking, no ceremony. Just: what's most important right now? Do that. Deploy it.

For startup teams, this means you can change direction on Monday and ship the new thing by Wednesday. No "we'll add it to next sprint."

Software Development Is a Cost, Not a Craft

This is the one that makes developers uncomfortable: software development is a business cost. It's an operational expense, like rent or hosting.

That doesn't mean quality doesn't matter. It means quality serves the business, not the developer's ego. The scout rule — leave the codebase better than you found it — keeps quality high without separate "refactoring sprints" that never get prioritized.

Consolidation means fewer tools, fewer vendors, fewer moving parts. Every additional service is another bill, another dashboard, another thing that breaks at 2 AM. For startups, simplicity is a feature.

Build the Boring Parts Last

Context over purity means making pragmatic decisions, not architecturally perfect ones. Use the default stack. Buy what you can. Build only what's core.

I keep a default stack and use it for everything unless there's a specific reason not to. Deep expertise in familiar tools beats starting fresh with the "best" technology for each project.

When a client asks "should we use microservices?" the answer is almost always no. Not because microservices are bad — because for a startup, a monolith you ship in three weeks beats a distributed system you ship in three months.

Transparency Over Everything

Startup partnerships fail on misaligned expectations, not technical problems. Every partnership principle I follow addresses this directly.

Transparency means full visibility into progress, problems, and decisions. No weekly status reports that hide bad news. When something goes wrong — and it will — the client knows the same day.

Weekly accountability creates a billing cycle that forces honest conversations. If the week didn't produce visible progress, that's a problem we discuss before the next week starts.

Exit freedom means clients can leave at any time. No contracts, no lock-in, no hard feelings. If the work isn't valuable, you should be able to stop paying for it immediately. This keeps me accountable in a way that six-month contracts never could.

Maintenance Is Not a Phase

The biggest lie in software development: "We'll build it, launch it, then maintain it." As if building and maintaining are separate activities.

No split means development and maintenance happen continuously. Every feature I ship includes monitoring. Every deployment includes the ability to roll back. Quality gates and feature flags make it safe to fail and fast to fix.

For startups, this means you don't need a separate "operations team" from day one. The development process IS the operations process. Ship code, watch it run, fix what breaks, improve what works.

The Full System

These principles aren't independent tips — they form a system. Discovery principles prevent you from building the wrong thing. Delivery principles get the right thing shipped fast. Partnership principles keep everyone aligned. Diligence principles make sure it keeps working.

I documented all 33 principles as a reference — not as rules to follow blindly, but as a starting point for founders who want their engineering process to actually work.

The best engineering principles for your startup are the ones that let you ship every week. Everything else is overhead.

Live: varstatt.com/principles

Why Scrum Fails In Small Teams

Jurij Tokarski — Sat, 21 Mar 2026 00:00:00 +0000

A few years ago, my development team of three was sitting through a 90-minute sprint planning ceremony. The feature we planned took two days to build.

We spent more time estimating and discussing the work than doing it. I was the team lead, and this was the moment I started questioning what we were actually doing here.

Scrum Solved a Real Problem — Then Became One

Scrum is a project management framework built around fixed-length iterations called sprints — usually two weeks. Each sprint has a planning ceremony, daily standups, a review, and a retrospective. There's a product owner who manages the backlog, a scrum master who facilitates the process, and a development team that executes.

It was created in the 1990s to bring structure to software projects that were failing under waterfall — the old approach of planning everything upfront, building for months, and hoping the result matched reality. Scrum introduced short feedback cycles. Ship something every two weeks. Inspect and adapt. That was genuinely better than what came before.

The agile manifesto that underpins scrum development prioritizes individuals over processes, working software over documentation, customer collaboration over contracts, and responding to change over following a plan. Good principles. The problem is what the industry built on top of them.

Sprint Boundaries Are Artificial

Tasks don't fit neatly into two-week boxes. Some take three days. Some take twelve. Forcing them into fixed time boundaries creates two failure modes: you either pad estimates to fill the sprint, or you rush to hit an arbitrary deadline that has nothing to do with the actual complexity.

When a priority shifts mid-sprint, scrum says wait until the next planning ceremony. In a small team, that's absurd. The client calls, explains why Feature B is now urgent, and you should be able to switch today — not in nine days when the sprint ends.

Velocity Tracking Becomes Theater

Story points were meant to help teams estimate work. In practice, they become a performance metric. Teams optimize for point throughput instead of actual value delivered. A refactoring task that prevents six months of tech debt gets 2 points. A trivial UI change that the PM can demo gets 8.

When one person does the work, velocity tracking is particularly absurd. You already know your throughput. You lived it yesterday.

Ceremonies Replace Communication

Daily standups. Sprint planning. Sprint review. Sprint retrospective. Backlog grooming. For a team of fifteen with cross-functional dependencies, these rituals serve a real purpose — they force information sharing that wouldn't happen naturally.

For a team of three? Or a solo developer working with a client? These meetings replace the actual communication they were designed to facilitate. You don't need a standup when you can send an async update after each work session. You don't need sprint planning when the priority queue is a shared list that either side can reorder at any time.

When the framework produces more Jira tickets, confluence pages, and status updates than actual shipped code, something has gone wrong. The best process is invisible — it stays out of the way while work gets done.

Every Time I Switched to Kanban, Delivery Rocketed

I've led dev teams twice. Both times we started with scrum because that's what the organization used. Both times we shifted toward kanban. And both times the same thing happened: delivery rocketed and people became happier.

The only meeting that survived was a real daily standup — five minutes to talk about blockers and maybe share plans. That's it. The entire status was visible on the Jira board. Anyone could look at it anytime. No ceremony needed to extract information that was already public.

I've shipped software since 2011. Now I run my own practice based on continuous flow — Kanban, not Scrum. Here's how it works:

A Priority Queue, Not a Sprint Backlog

The client maintains a ranked list. The top item is the highest priority. I work top-down: finish what's in front, then pull the next thing. Priorities shift? The client reorders the list. No replanning ceremony. No negotiating what fits in the sprint. The developer is always working on what matters most right now.

One Thing at a Time, Then Ship It

One task at a time. Finish it. Deploy it. Then move on. This forces honest prioritization and kills context switching. It prevents the trap of being "90% done on five things" while nothing is actually working.

Code review isn't done. QA passed isn't done. Merged isn't done. Working in production is done. This changes how you think about deployment. If deploying is hard, it gets avoided. If it's easy, it happens constantly. Feature flags handle incomplete work — deploy behind the flag, keep building, flip it when it's ready.

Async Updates Beat Standups

Updates go out after each work session — not at end of day, not at a standup, but when the work is actually done. Meetings happen only for decisions that genuinely need real-time discussion. Everything else is written. This keeps calendars empty and focus time protected.

For significant features, I think in six-week cycles — long enough to deliver something end-to-end valuable, short enough to stay honest. A cycle isn't a deadline. It's a planning horizon. "In six weeks, we expect X to be working." The cycle serves orientation, not ceremony.

For Big Orgs, Scrum Is Still Revolutionary

I'm not anti-process. I'm anti-unnecessary-process.

For old-school corporations that have been running waterfall for decades, scrum is genuinely revolutionary. It introduces feedback loops, iterative delivery, and customer involvement where none existed before. That's a massive upgrade. If scrum is moving your 200-person org from annual releases to biweekly ones — keep going. That's real progress.

Scrum works when you have large teams with cross-functional dependencies, regulated environments where audit trails are compliance requirements, organizations that need guardrails to prevent chaos, or teams coming from waterfall who need a stepping stone.

But your dev team of four is probably shooting itself in the foot with this.

Small Is a Strength, Not a Problem to Fix

Here's what I see constantly: small teams and startups adopting processes designed for organizations ten times their size. Scrum is one of those processes. So are SAFe, detailed PRDs, elaborate RACI matrices, and weekly all-hands with thirty-slide decks.

It comes from the same instinct — wanting to look and feel like a "real" company. But it's backwards. Being small is not a weakness to compensate for. It's an advantage to exploit.

A team of four can make a decision in a Slack thread that would take a 40-person team two sprint ceremonies and a steering committee. You can deploy a hotfix in twenty minutes while a large org is still scheduling the incident review. You can pivot your roadmap over lunch.

My advice: use the strength you actually have. You're small, so act quick. Don't import the overhead of organizations that would kill to have your agility.

The Best Process Disappears

The agile manifesto got it right: individuals and interactions over processes and tools. Somewhere along the way, the industry built an entire certification industry, a tooling ecosystem, and a consulting practice around processes and tools.

The best development process is the one you don't notice. Work comes in, gets prioritized, gets built, gets shipped. No theater. No rituals that exist to feel productive rather than be productive.

Build it. Deploy it. Get feedback. Pull the next priority.

Three Bugs That Were Actually My Prompts

Jurij Tokarski — Thu, 19 Mar 2026 00:00:00 +0000

Three debugging sessions. Three different features. Every investigation eventually landed in the same place: my own prompt files.

The AI wasn't broken. I was a contradictory author.

The STRICT Rule That Was Overriding Itself

I built a structured interview tool — the kind that walks a founder through their idea one question at a time. The system prompt had this near the top:

STRICT: Ask only ONE question per message. Never bundle questions.

Users kept getting messages like "How will you make money? What are the major costs to build and run this?" I read the prompt again. Rule was right there. Added emphasis. Still happened. Moved it higher. Still happened.

Then I read the interview flow section — the part describing what topics to cover across the session. Step 4 read:

**Revenue Streams + Cost Structure** — How will you make money?
What are the major costs to build and run this?

The model wasn't defying the STRICT rule. It was following the flow description, which listed two topics as a single step and framed them as two inline questions. That structure implicitly granted permission to bundle. The more specific instruction — a concrete flow item with actual question text — overrode the more abstract one.

The fix was two things. Unbundle every flow item into separate steps. And add a concrete bad example directly inside the STRICT rule — not just the prohibition:

STRICT: Ask only ONE question per message. Never bundle questions.
Example of what NOT to do: "How will you make money? What are your costs?"
is TWO questions — send one, wait for the answer, then ask the next.

Abstract rules lose to specific structural descriptions. The model resolves contradictions by specificity, not by which rule came first or which one you emphasized. If your flow section describes two questions in the same bullet, that description is an instruction — regardless of what you wrote elsewhere.

The Tool That Read the Prohibition

After a discovery session, users could request a full report by email. The tool was registered. The backend handler existed. Users clicked the button. The AI said it couldn't send emails.

I checked tool registration — correct. Checked the API call — correct. Checked the backend handler — correct. Everything looked wired up properly at every technical layer.

The issue was in a place I hadn't thought to look. I grepped the prompt files for "report":

grep -r "report" mod/discovery/steps/*/prompt.md

Every single step prompt had lines like:

Do NOT offer to send a report.
Do NOT mention sending a report.

I'd written those prohibitions months earlier during a different phase of the project. The tool didn't exist yet when I wrote them. By the time it did, I'd forgotten those lines were there.

The model wasn't defective. It was obedient to instructions I'd authored and then lost track of. Ten minutes of grepping would have found this immediately. Instead I spent days checking tool registration and API calls.

Before investigating code when an AI-powered feature does nothing, grep your prompt files for explicit prohibitions against the behavior you're expecting. Search for "do not" and "don't" across your entire prompt corpus against the relevant action. It takes ten seconds and it would have saved me days on this one.

The Precondition That Lived Only in Prose

After fixing the prohibitions, a new problem surfaced. The model was supposed to ask for the user's email before calling send_report. The prompt said:

ALWAYS ask for the user's email before calling send_report.
Never call send_report without confirmed contact details.

In testing, the tool got called with founder@example.com. A placeholder the model had generated rather than asking for a real address. The instruction was clear. The model treated it as a suggestion.

I made the prompt stronger. Same result — it would comply sometimes, skip the step other times, depending on how the conversation had flowed. Prompt-only enforcement of a precondition is probabilistic.

The fix was to move validation into the tool handler itself:

const PLACEHOLDER_DOMAINS = ['example.com', 'test.com', 'placeholder.com'];

function validateEmail(email) {
  const domain = email.split('@')[1]?.toLowerCase();
  if (!email || !domain) {
    return {
      error: 'No email provided. Ask the user for their email address before calling this tool.'
    };
  }
  if (PLACEHOLDER_DOMAINS.some(d => domain.includes(d))) {
    return {
      error: `"${email}" looks like a placeholder. Ask the user for their real email address.`
    };
  }
}

Two things to notice. First, the validation returns errors instead of throwing them. A thrown exception terminates the tool call with a runtime error the model can't act on. A returned error lands back in the model's context as a tool result — the model reads it, understands what went wrong, and retries:

// This crashes. The model gets a runtime error and no useful signal.
if (!user_email) throw new Error('user_email is required');

// This works. The model reads the error and asks for the real address.
if (!user_email) {
  return {
    error: 'user_email is required. Ask the user for their email address, then call this tool again.'
  };
}

Second, required in a tool schema is a hint to the model, not a runtime guarantee. Models will omit required fields — sometimes because the value wasn't extracted yet, sometimes for reasons that aren't obvious from the logs. Treat every parameter as potentially absent at the handler boundary.

ALWAYS X in a prompt is a suggestion. Enforcing X belongs in code.

The Prompt Is the Program

All three bugs came from the same misread of what a system prompt is. I was treating it as documentation — a description of intended behavior that the real system (the code) would enforce. For an LLM-powered feature, that's backwards.

The system prompt isn't documentation. It's source code executed by a natural-language interpreter. Contradictions in it don't fail to compile — they resolve according to specificity and proximity rules you never wrote down. Prohibitions execute. Structure is semantics. A flow description with two inline questions is an instruction to ask two questions, regardless of the STRICT rule above it.

The debugging instinct to check the API, the tool registration, the network logs — all of that is valid. But it should come after you've read your own prompts as a hostile reader looking for contradictions, prohibitions, and preconditions that only exist in prose.

The model is rarely the bug. Read your prompts first.

Nobody Finishes a 15-Minute AI Interview

Jurij Tokarski — Tue, 17 Mar 2026 00:00:00 +0000

Last year I launched an AI-powered discovery tool for software founders. The idea was simple: instead of paying for a product consultant, sit through a 15-minute AI interview and get a comprehensive development roadmap. Business model, market sizing, personas, competitive analysis, PRD, tech stack, budget, action plan — all in one session, delivered as a PDF report.

The output was genuinely useful. Founders who completed it got something they could hand to a developer and start building from.

But most founders didn't complete it.

Where Sessions Died

I didn't need sophisticated analytics to see the pattern. Founders would start, get three or four exchanges in, and disappear. Not because the questions were wrong. Because they'd hit a question they couldn't answer yet.

"What's your monetization model?" at minute six, right after they'd just gotten excited describing the product idea. Or a market sizing question when they hadn't done that research. The session demanded answers in a fixed order. Real founder thinking doesn't work that way.

I spent weeks trying to fix the session — better prompts, shorter flows, smarter branching. None of it changed the completion rate. I was solving the wrong problem: "how do I get founders to finish a 15-minute interview" instead of "what does a founder actually need, when they need it."

The Insight Came From SEO

While researching keywords for content, I noticed something. "Competitive analysis template for startups" — thousands of monthly searches. "TAM SAM SOM calculator" — same. "PRD generator" — same. Each stage of the founder journey had its own search intent, its own moment of urgency.

I had been thinking about building a standalone tool around one of these keywords. Then it struck me: my discovery tool already does all of this and more. But a founder searching for "lean canvas generator" doesn't think of it as part of a 15-minute discovery interview. They want the canvas. Right now.

The monolithic tool was doing eight things well, packaged in a way that required commitment to all eight. The fix wasn't better prompting. It was decomposition.

Eight Tools, Eight Deliverables

The rebuild started with twelve steps, got trimmed to ten, and settled at eight. One per stage of the founder journey:

Business Model Canvas — lean canvas with revenue streams, cost structure, key partners
Competitive Analysis — positioning matrix, differentiation signals, competitor tech indicators
Market Sizing — TAM/SAM/SOM with growth assumptions
User Personas — typed persona objects with platform preferences and jobs-to-be-done
Feature Prioritization — domain classification (core / supporting / generic)
Tech Strategy — build-vs-buy decisions mapped to domain classification, specific stack recommendations
Project Requirements — scoped feature list, acceptance criteria, out-of-scope boundary
Build Cost & Plan — weekly estimate with a concrete action plan attached

The last two were originally four separate tools: Build vs Buy, Tech Stack Advisor, MVP Cost Estimator, and Action Plan. I merged them in pairs. "Should I build auth?" and "which auth provider?" aren't sequential questions — they're the same question. A cost estimate without an action plan is just a number that makes founders anxious. Eight made more sense than ten or twelve.

Each tool is fully self-contained. It works with no prior context, no prior steps. But designed to hand off cleanly if the founder continues.

The Architecture

Each tool gets its own SEO landing page — keyword-targeted hero, explanation copy, FAQ, and an input form, all server-rendered. The page doubles as the app: before generation it's a landing page Google can crawl, after the founder starts it becomes the chat interface. One URL, two render states.

The chat itself is a streaming conversation with a constrained AI model. Each tool has its own system prompt scoped to the decisions that step owns — Feature Prioritization scores by business value only, no effort or cost questions (those belong to later steps). The AI drives the conversation, but the scope is narrow: ask the right questions for this deliverable, produce a typed artifact, stop.

Three server-side tools do the heavy lifting:

update_artifact — incrementally builds the step's structured output as the conversation progresses
complete_step — finalizes the artifact, captures analysis and summary
send_report — collects all completed artifacts, generates a consolidated PDF, delivers via email

The artifact panel shows the structured output updating in real time as the conversation progresses — the founder sees their canvas or competitive matrix forming, not just chat bubbles.

How Context Moves Between Tools

Each tool produces a typed artifact. The Business Model Canvas produces an object with key_partners, revenue_streams, cost_structure. User Personas produces an array of persona objects. Feature Prioritization produces a classification map.

When a founder continues to the next tool, those artifacts get injected into the new tool's system prompt as structured JSON. Chat history doesn't cross tool boundaries — the back-and-forth of step one is noise inside step six. What crosses is the concluded output.

Each tool ends with two inline options rendered as suggestion pills on the last AI message: Continue to [next tool] or Send report via email. If the founder requests the report, all completed artifacts get compiled into a PDF and delivered to their inbox. If they continue, the next tool opens with context already loaded. Both outcomes are first-class. Stopping after step two means you have a competitive analysis report — that's a complete deliverable, not an abandoned session.

Email capture happens at the moment a founder requests their report — after they've gotten value, not before they've seen anything. That single change converted capture from a gate into an offer.

The Prompt Engineering That Wasn't

Early in the build, I added a line to each tool's system prompt: "Use prior context if available to inform your analysis." Seemed reasonable.

It didn't work. The model would occasionally reference something from an earlier step, but inconsistently and shallowly. Feature Prioritization wasn't connecting domain classifications to the Tech Strategy decisions that depended on them. I spent two hours trying different phrasings before accepting the problem wasn't the wording.

The fix was specificity. Not "use prior context" — enumerate every upstream artifact by name, every relevant field, and exactly how it should influence the current step:

## Prior Step Context

If the following steps are complete, use their outputs as described:

- **Feature Prioritization** — use `domain_classification` (core / supporting / generic)
  to anchor build-vs-buy decisions. Core = build custom. Generic = always buy.
- **User Personas** — use `technical_proficiency` and `platform_preferences`
  to shape deployment and integration decisions.
- **Market Sizing** — use TAM/SAM/SOM scale to calibrate infrastructure complexity.

The model follows explicit field references. It ignores vague instructions to "use context." The more precisely you enumerate the step name, the field name, and how to apply it — the more consistently the output reflects what prior steps actually found.

Build Around the Deliverable

The session format is an inherited assumption from chat UIs. It made sense for general-purpose assistants. It doesn't make sense for a process that unfolds across days or weeks, where each stage has its own mental context and its own moment of urgency.

Decomposing the monolithic tool changed everything downstream. Eight tools means eight landing pages means eight keywords. Each tool is a complete product for someone who needs just that one thing. The full journey still exists for founders who want it — they just don't have to commit to it upfront.

If your AI tool covers something that spans multiple sittings and mental states, the deliverable is the right unit to build around. Not the conversation.

Live: varstatt.com/discovery

The Production Bugs That Never Threw an Error

Jurij Tokarski — Wed, 11 Mar 2026 00:00:00 +0000

Six production failures. Every log said success. The API returned 200. The job exited clean. Each one cost real time — not because the bug was hard to find once I knew where to look, but because the system accepted the input, confirmed receipt, and executed something different from what I intended. No exception. No warning. Just a quietly wrong outcome at the other end.

The OAuth Token That Baked In the Past

A content automation script returned a 403 from the Twitter v2 API. The message: Your client app is not configured with the appropriate oauth1 app permissions for this endpoint.

I'd already upgraded the app from Read to Read+Write in the Developer Portal. The settings showed the correct value. The error said otherwise.

OAuth 1.0a tokens carry the permission scope active at the moment they were generated. Changing the app's permissions afterward does nothing to existing tokens — they permanently hold the scope they were issued with. The Developer Portal shows you a clean green state with no indication that your tokens are now stale relative to your updated settings. The 403 message says "app configuration," which points you at the thing you already fixed.

Lesson: After any permission change on Twitter, regenerate the Access Token and Access Token Secret immediately. Don't test anything first.

BTW: Since X moved to pay-per-use pricing in early 2026, the same 403 with the same "oauth1 app permissions" message can also mean your account has no active billing. The Free tier officially supports POST /2/tweets, but developers report it returning 403s intermittently with no configuration changes on their end (1, 2, 3). If you've regenerated tokens and the error persists, check whether your account needs a paid plan or a billing top-up before debugging further.

The Cache That Survived the Uninstall

Removed @sentry/nextjs from a project. Pulled it from package.json, ran install, cleaned up the config. Next dev run threw this:

Error: Cannot find module '@sentry/nextjs'
Require stack:
- .next/server/instrumentation.js

The package wasn't in node_modules. Wasn't in package.json. Nowhere. But Next.js kept looking for it.

Inside .next/server/ was a compiled instrumentation.js from a previous build — one Sentry had hooked into during installation. The incremental build never touched that file because I hadn't changed the instrumentation source, only the package. It just sat there, referencing something that no longer existed.

rm -rf .next

Then yarn dev. No errors. Thirty seconds of actual work after ten minutes of confusion.

Lesson: Removing a plugin that hooks into Next.js instrumentation means deleting .next as part of the removal. Not after the next error — as part of the removal.

The Job That Reported Success While Running Nothing

A scheduled launchd job on macOS. The plist was configured, the wrapper script pointed at the right Node script, everything looked right. launchd reported completed successfully on every run. Nothing was being posted.

I added logging, ran it manually. The log showed the Node process starting, then silence. Ran it directly from the terminal — it worked fine.

With verbose output piped to a log file, the job finally showed something:

Error: spawn claude ENOENT

The claude binary lives at ~/.local/bin/claude. My terminal knows that because my shell config adds that path. launchd doesn't. It starts processes with a stripped-down environment — no user shell, no ~/.local/bin, nothing accumulated over years of machine setup. The Node script was swallowing the subprocess error and exiting 0 regardless. launchd saw a clean exit and called it a success.

Fix: One line in the wrapper script:

export PATH="/Users/jurijtokarski/.local/bin:/opt/homebrew/bin:$PATH"

Lesson: Use absolute paths in launchd plists. Test jobs with the same stripped environment launchd uses — not from your terminal.

The Node That Activated Fine, Then Didn't

Added an IF node to an n8n workflow to branch between two processing paths. Saved cleanly. Validated cleanly. The editor showed no warnings. Activated the workflow and got:

Cannot read properties of undefined (reading 'execute')

No node name. No stack trace. Nothing pointing anywhere useful.

I checked the Code nodes. Checked the Merge node. Checked the connections. The IF node wasn't even on my radar — it had saved without complaint. Eventually I pulled the raw workflow JSON:

{
  "type": "n8n-nodes-base.if",
  "typeVersion": 2.3,
  "parameters": { ... }
}

The n8n instance didn't have typeVersion: 2.3 of the IF node. The editor accepted it — it doesn't validate typeVersion against what's installed on the runtime. The execution engine hit an undefined handler and threw.

Downgrading to 2.2 fixed it immediately.

Lesson: The n8n editor and the n8n runtime have different views of what's valid. When an activation error is opaque and traceless, check typeVersion before anything else.

The Stream That Delivered No Audio

Building a screen and audio capture feature. Every API call succeeded. Production recordings came back with only the microphone — no shared app audio. No error in the console. getDisplayMedia had resolved cleanly, the stream object was there, the video track was present.

I spent a while assuming the AudioContext mixing was wrong before checking something obvious:

const stream = await navigator.mediaDevices.getDisplayMedia({
  video: true,
  audio: true
});

console.log(stream.getAudioTracks().length); // 0

Zero audio tracks. The user had gone through the picker and selected a tab without checking the "Share audio" checkbox. The browser doesn't reject the promise in that case. No warning, no error, no indication the audio side of the request was skipped. The spec gives you an empty array and moves on.

Lesson: Check audioTracks.length immediately after resolution. If it's zero, surface an explicit re-prompt before proceeding. A resolved getDisplayMedia call is not a guarantee that you got what you asked for.

The Sub-Agent Searching the Wrong Store

A multi-step analysis pipeline: an orchestrator that reads documents, spawns specialist agents to evaluate content, streams structured results back to the UI. The orchestrator chains turns via previous_response_id. Sub-agents were supposed to be isolated, stateless calls.

At one step, agent responses were coherent but consistently wrong. Clean outputs, plausible reasoning, wrong knowledge base.

What previous_response_id carries isn't just conversation history — it inherits the full tool configuration of the parent response, including attached file_search vector stores. The orchestrator had a tender documents store bound to it. Every chained orchestrator call accumulated that binding. When the orchestrator's final response ID was passed to a specialist agent — one explicitly configured with a completely different store — the API silently merged the orchestrator's tool configuration in. The agent queried the wrong store. No error. No warning.

Fix: Agent calls are stateless. They have no legitimate reason to continue a conversation chain.

// Before
const resp = await this.model.responses.create({
  model: DEPLOYMENT_NAME,
  instructions,
  input,
  tools,
  previous_response_id: previousResponseId,
  stream: false,
});

// After — agents never inherit the orchestrator's chain
const resp = await this.model.responses.create({
  model: DEPLOYMENT_NAME,
  instructions,
  input,
  tools,
  stream: false,
});

Lesson: Any sub-agent that needs isolated tools must be a fresh, stateless request with no chain ID. Explicitly configuring different tools does not override what the chain carries in.

What These Six Have in Common

None of them failed at the point of input. The token was accepted. The build succeeded. The job exited. The editor saved the node. The stream resolved. The agent returned a clean response. Every failure happened at the output — in the actual result, not the API boundary.

The gap between "I accepted your input" and "the right thing occurred" is where these live. The fix isn't adding more logging to the call sites. It's verifying at the output layer: check audioTracks.length after resolution, not before. Pull the raw JSON of a node that failed at activation. Log err.data on a 403, not just err.message. Check what the agent actually searched, not what you told it to search.

Success at the API boundary tells you the system is running. It tells you nothing about what the system is doing.

Merging Two Firestore Listeners for Cross-Field OR Queries

Jurij Tokarski — Tue, 10 Mar 2026 00:00:00 +0000

The assignment feature needed a real-time subscription: show tenders where creator_id == userId OR assignee_ids array-contains userId. A cross-field OR.

Firestore's Filter.or() works for same-field conditions. For fundamentally different field types — equality vs. array-contains — composite OR queries don't compose cleanly, and the SDK support varies by version. The alternative is a denormalised collection: fan out writes to a user_tenders subcollection on every state change. That's a write-time tax and more surface area for issues down the line.

The working approach: two separate onSnapshot listeners, results merged client-side into a Map keyed by document ID.

export const firebaseCompanyTendersSubscribeByCreatorOrAssignee = (
  companyId,
  userId,
  callback
) => {
  const merged = new Map();

  const unsubCreator = onSnapshot(
    query(COLLECTION_TENDERS(companyId), where("creator_id", "==", userId)),
    (snap) => {
      snap.docs.forEach((doc) => merged.set(doc.id, { id: doc.id, ...doc.data() }));
      snap.docChanges().forEach(({ type, doc }) => {
        if (type === "removed") merged.delete(doc.id);
      });
      callback(Array.from(merged.values()));
    }
  );

  const unsubAssignee = onSnapshot(
    query(COLLECTION_TENDERS(companyId), where("assignee_ids", "array-contains", userId)),
    (snap) => {
      snap.docs.forEach((doc) => merged.set(doc.id, { id: doc.id, ...doc.data() }));
      snap.docChanges().forEach(({ type, doc }) => {
        if (type === "removed") merged.delete(doc.id);
      });
      callback(Array.from(merged.values()));
    }
  );

  return () => {
    unsubCreator();
    unsubAssignee();
  };
};

Deduplication is automatic — same document ID overwrites itself in the Map. Either listener updating triggers a re-merge and emits a fresh array. The cleanup path requires calling both unsubscribes; returning just one leaks the other listener.

No fan-out collection. No schema changes. The subscription logic stays in one place.

Using Firestore Transactions to Handle Race Conditions

Jurij Tokarski — Tue, 10 Mar 2026 00:00:00 +0000

The system creates an OpenAI vector store per company — a dedicated knowledge base the AI secretary queries when answering questions. Creating it is expensive: an API call to Azure OpenAI, followed by writing the returned ID back to the company doc in Firestore.

What I ran into: multiple cloud function instances can process triggers at the same time. If two invocations both check workflow_2_vector_store_id, find it empty, and both proceed to create a vector store — you've just orphaned one. It sits there, billed by the token, never used.

My first instinct was "just check before creating." That doesn't work — the check and the write are not atomic. Two instances read an empty field at the same millisecond, both proceed.

What worked is a Firestore transaction as the gate:

export const patchCompanyWithVectorStoreIfMissing = async (
  companyId: string,
  vectorStoreId: string,
  assistantId: string,
): Promise<{ vectorStoreId: string; wePatched: boolean }> =>
  runDBTransaction(async (tx) => {
    const snapshot = await tx.get(DOC_COMPANY(companyId));
    const existing = snapshot.data()?.workflow_2_vector_store_id?.trim();

    if (existing) {
      return { vectorStoreId: existing, wePatched: false };
    }

    tx.update(DOC_COMPANY(companyId), {
      workflow_2_vector_store_id: vectorStoreId,
      workflow_2_assistant_id: assistantId,
    });

    return { vectorStoreId, wePatched: true };
  });

Both instances still create a vector store optimistically — that's unavoidable, the external API call can't be inside the transaction. But only one wins the write. The loser gets wePatched: false and immediately fires cleanup:

const { vectorStoreId, wePatched } = await patchCompanyWithVectorStoreIfMissing(
  company.id,
  result.vectorStoreId,
  result.assistantId,
);

if (!wePatched) {
  llm.cleanupCompanyVectorStoreAndAssistant(result.vectorStoreId, result.assistantId)
    .catch(() => {});
}

The transaction is the single source of truth for "has this resource been claimed?" Optimistic creation outside it is fine — as long as the loser always cleans up.

SwiftUI Is Like React + CSS-in-JS

Jurij Tokarski — Wed, 04 Mar 2026 00:00:00 +0000

A client brought me into an iOS project mid-stream. The app was already built — screens, navigation, state management, the works — and I needed to understand it fast enough to contribute meaningfully.

The codebase was SwiftUI. I had zero SwiftUI experience.

My usual move in this situation is to find the mental model that bridges the gap. I've been doing web development long enough that React, CSS, and async JavaScript are second nature. So instead of starting from scratch, I used Claude Code to explore the codebase and kept asking one question: what's the web equivalent of this?

After a few hours of that, something clicked. SwiftUI is not exotic. If you know React, you already know 80% of the concepts — just with different syntax and a few iOS-specific primitives layered on top.

This post is the reference I built during that session. I stripped the client-specific code and kept the patterns that apply universally.

Core Concept: SwiftUI = React + CSS-in-JS + Declarative UI

SwiftUI is declarative and component-based, just like React. Instead of JSX you write Swift, but the mental model is the same: describe what the UI should look like, and the framework figures out how to render it.

The three things that felt foreign to me at first — and clicked once I found the right analogy:

No CSS files. Styles live directly on the component as chained modifiers. Think CSS-in-JS but without the library — it's just how the language works.
No DOM. SwiftUI renders to native UIKit controls under the hood. You never touch them directly, just like you never touch the DOM in React.
State drives everything. Change a @State variable and the view re-renders. Same contract as useState, same mental model, different syntax.

1. Components — Structs that return a view, not JSX

In React a component is a function that returns JSX. In SwiftUI it's a struct that conforms to the View protocol and implements a body property. The props become let constants declared directly on the struct, and instead of a return statement you describe the layout inline.

function NoteCard({
  title,
  subtitle,
  dateLabel
}) {
  return (

      <h3>{title}</h3>
      <p>{subtitle}</p>
      <p>{dateLabel}</p>

  );
}

struct NoteCardView: View {
    let title: String?
    let subtitle: String
    let dateLabel: String

    var body: some View {
        VStack(
          alignment: .leading,
          spacing: 8
        ) {
            if let title = title {
                Text(title)
            }
            Text(subtitle)
            Text(dateLabel)
        }
        .padding(16)
        .background(Color("NeutralCool0"))
    }
}

Key differences:

struct instead of function
var body: some View instead of return
Swift types (String?, Int) instead of JavaScript types
Modifiers (.padding(), .background()) instead of CSS classes

2. Layout — Named containers instead of flex properties

On the web layout is a property you set on an element — display: flex, flex-direction: row. In SwiftUI layout is structural: you pick a container (VStack, HStack, ZStack) and nest views inside it. There are no flex properties to remember because the direction is baked into the container name.

.container {
  display: flex;
  flex-direction: column;
}

.header {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

// like flex-direction: column
VStack(spacing: 0) {
    // like flex-direction: row
    HStack {
        Text("My App")
        Spacer() // like flex-grow: 1
        Button { ... } label: { ... }
    }
    .padding(.horizontal, 20)
}

Layout containers:

VStack → display: flex; flex-direction: column
HStack → display: flex; flex-direction: row
ZStack → position: relative + absolute children
Spacer() → flex-grow: 1
LazyVGrid → CSS Grid

3. Styling — Modifiers chain where CSS classes would go

There are no class names, no stylesheets, no CSS-in-JS library. Every visual property is a modifier method chained directly onto the view. Order matters — .padding() before .background() gives a different result than after it, just like stacking CSS properties in a specific order can change rendering.

.card {
  padding: 16px;
  background-color: #fff;
  border-radius: 12px;
  box-shadow: 0 1px 2px rgba(0,0,0,0.06);
}

VStack { ... }
    .padding(16)
    .background(Color("NeutralCool0"))
    .cornerRadius(12)
    .shadow(
        color: Color.black.opacity(0.06),
        radius: 2, x: 0, y: 1
    )

Common modifiers:

.padding(16) → padding: 16px
.padding(.horizontal, 20) → padding-left: 20px; padding-right: 20px
.background(Color.red) → background-color: red
.foregroundColor(.blue) → color: blue
.font(.system(size: 17)) → font-size: 17px
.fontWeight(.medium) → font-weight: 500
.cornerRadius(12) → border-radius: 12px
.frame(width: 100, height: 50) → width: 100px; height: 50px
.frame(maxWidth: .infinity) → width: 100%
.shadow(...) → box-shadow: ...
.overlay(...) → ::before or ::after pseudo-element

4. State Management — Property wrappers instead of hooks

@State is useState. The syntax is different but the contract is identical: declare a variable, mutate it, the view re-renders. What takes more time to learn is the broader family of property wrappers — SwiftUI has several, each with a specific purpose, where React hooks tend to blur together.

function Counter() {
  const [count, setCount] = useState(0);
  const [loading, setLoading] = useState(false);

  return (

      <p>{count}</p>
       setCount(count + 1)}&gt;
        Increment

      {loading &amp;&amp; }

  );
}

struct CounterView: View {
    @State private var count = 0
    @State private var loading = false

    var body: some View {
        VStack {
            Text("\(count)")
            Button("Increment") {
                count += 1
            }
            if loading {
                ProgressView()
            }
        }
    }
}

State property wrappers:

@State → useState() — local component state
@StateObject → useState() with object — owns an ObservableObject
@ObservedObject → props (object) — observes external ObservableObject
@Published → state in class component — triggers UI updates
@Binding → props callback — two-way data binding

For shared state, ObservableObject fills the same role as React Context or Redux. You mark properties with @Published and the views that observe it re-render automatically — no dispatch, no selectors.

class AppViewModel: ObservableObject {
    @Published var items: [Item] = []
    @Published var isLoading: Bool = false
    @Published var error: String? = nil

    func loadItems() async {
        isLoading = true
        let result = try await repository.fetchItems()
        self.items = result
        isLoading = false
    }
}

5. Conditional Rendering — Plain if/else, no ternary tricks

React leans on ternaries and && because JSX is an expression — it has to return something. SwiftUI uses plain if/else blocks because the body is just code, not an expression. The result is actually easier to read once you have three or four states to handle, since you're not nesting ternaries.

{isLoading ? (

) : error ? (

) : (

)}

if viewModel.isLoading {
    ProgressView("Loading...")
} else if let error = viewModel.error {
    ErrorView(message: error)
} else if viewModel.items.isEmpty {
    Text("Nothing here yet")
} else {
    ScrollView {
        ForEach(viewModel.items) { item in
            ItemCardView(...)
        }
    }
}

Key differences:

No ternary nesting — if/else reads linearly
if let unwraps optionals inline — common Swift pattern
Empty state (items.isEmpty) fits naturally as another branch

6. Lists — ForEach maps items to views

ForEach is Array.map(). The one gotcha: items need to conform to the Identifiable protocol, which is SwiftUI's version of React's key prop — it needs a stable identity to track which items changed between renders. In practice this usually means your model has an id property, which it probably already does.

{items.map(item =&gt; (

))}

ForEach(viewModel.items) { item in
    ItemCardView(
        title: item.name,
        subtitle: item.description,
        date: formattedDate(item.createdAt)
    )
}

Key differences:

ForEach replaces .map() — no key prop needed if item conforms to Identifiable
For grids, swap VStack for LazyVGrid — CSS Grid with lazy loading built in
LazyVGrid takes an array of GridItem values to define columns

7. Event Handlers — Actions as trailing closures

Web events are attributes you attach to elements. In SwiftUI interactive views like Button take an action closure as their first argument. For non-interactive views you attach .onTapGesture, .onAppear, or .onDisappear as modifiers — the same way you'd add onClick to a div in React.

 handleClick()}&gt;
  Click me


 setValue(e.target.value)} /&gt;

Button("Click me") {
    handleClick()
}

// $ = two-way binding
TextField("Enter text", text: $textValue)

Event modifiers:

Button { action } → <button onClick={action}>
.onTapGesture { } → onClick on any element
.onAppear { } → useEffect on mount
.onDisappear { } → useEffect cleanup on unmount
TextField(..., text: $value) → <input onChange={...}>

8. Design Tokens — Color assets instead of CSS variables

CSS variables live in a stylesheet. SwiftUI color tokens live in Assets.xcassets — a file managed through Xcode's visual editor, not in code. You reference them by name string, which feels fragile at first, but in practice it works the same way. For component variants, Swift enums replace CSS class modifiers cleanly.

:root { --primary-color: #00a86b; }

.button {
  background-color: var(--primary-color);
}

// Colors live in Assets.xcassets
.background(Color("PrimaryGreen600"))
.foregroundColor(Color("NeutralCool800"))

Key differences:

Colors defined in Assets.xcassets, referenced by name string
No cascade — colors don't inherit down the tree unless you set them explicitly
Enums replace CSS class variants for component styles:

enum ButtonVariant {
    case primary
    case secondary

    var backgroundColor: Color {
        switch self {
        case .primary:   return Color("PrimaryGreen600")
        case .secondary: return Color.clear
        }
    }
}

9. Async Operations — Task instead of useEffect

The async/await syntax is nearly identical to JavaScript — this was the one area where SwiftUI felt immediately familiar. The difference is how you trigger async work from a view: instead of useEffect, you use .onAppear combined with Task { }. Task creates a new async context from synchronous code, the same way you'd call an async IIFE in JavaScript.

async function loadData() {
  setLoading(true);
  try {
    const data = await fetch('/api/data');
    setItems(data);
  } catch (error) {
    setError(error.message);
  } finally {
    setLoading(false);
  }
}

useEffect(() =&gt; {
  loadData();
}, []);

func loadItems() async {
    isLoading = true
    do {
        let items = try await repository.fetchItems()
        self.items = items
    } catch {
        self.error = error.localizedDescription
    }
    isLoading = false
}

.onAppear {
    Task { await viewModel.loadItems() }
}

Key differences:

.onAppear + Task { } replaces useEffect on mount
do/catch replaces try/catch — same idea, slightly different syntax
@MainActor on the ViewModel ensures UI updates happen on the main thread, same reason React's state setters are synchronous

10. Navigation — NavigationStack wraps the whole screen tree

React Router lives outside your component tree and you declare routes centrally. SwiftUI's NavigationStack wraps directly around the content — you place it in the view hierarchy and NavigationLink handles the push transition. It's more like Next.js file-based routing in feel: navigation is co-located with the UI that triggers it.



    } /&gt;
    }
    /&gt;

// like 
NavigationStack {
    ScrollView {
        ForEach(viewModel.items) { item in
            // like 
            NavigationLink(
                destination: ItemDetailView(
                    id: item.id
                )
            ) {
                ItemCardView(...)
            }
        }
    }
}

Key differences:

No central route config — destination is declared at the link site
NavigationStack manages the back stack automatically
Wrap the root view once; all nested NavigationLinks push onto the same stack

11. Responsive Design — Device checks instead of breakpoints

CSS media queries respond to viewport width. SwiftUI doesn't have a viewport — it has devices. The idiomatic approach is a simple device type check (UIDevice.current.userInterfaceIdiom) and a ternary at the modifier level. It's more explicit than media queries but also simpler: iPad or not iPad covers most cases.

.container {
  padding: 20px;
}

@media (min-width: 768px) {
  .container {
    padding: 32px;
  }
}

private var isIPad: Bool {
    UIDevice.current.userInterfaceIdiom == .pad
}

var body: some View {
    VStack { ... }
        .padding(.horizontal, isIPad ? 32 : 20)
        .padding(.top, isIPad ? 69 : 16)
}

Key differences:

No breakpoints — device type replaces viewport width
Ternary inline on each modifier instead of a separate media block
SizeClass environment variable available for more nuanced layouts

Summary

The syntax is new. The concepts are not. Every pattern here has a direct equivalent you already know — and once that clicks, reading an unfamiliar SwiftUI codebase stops feeling like learning a new paradigm and starts feeling like reading familiar code in an accent you haven't heard before.

The things that genuinely differ from web: no CSS files, no DOM, modifiers instead of class names, and Identifiable instead of key. Everything else maps cleanly.

If you're jumping into an iOS codebase, start with the component structure and state — get those two right and the rest follows.