I've built three AI-backed products — TaxLens (income tax from bank statements), TrustRail (BNPL underwriting), and BuffByte (AI content optimisation for creators) — and across all three I've had to think carefully about where model calls happen, how often they happen, and how to avoid paying for the same computation twice.

This article is the distillation of those decisions, it's the specific layers I use, the conditions under which each one applies, and the honest evaluation of what each buys you.

Let's dig in.

Why Caching Is Different for AI Products

In a traditional API, caching is about latency: you cache to serve responses faster.(sometimes too about costs, one could argue time costs money too)
In an AI product, caching is primarily about cost(monetary): you cache to avoid paying OpenAI for a response you've already paid for.

This distinction changes the calculus. For a fast traditional API response (~20ms), you might cache results that are only marginally expensive to recompute. For an LLM call ($0.06–0.15 per request, 2–5 seconds), you cache aggressively because the cost of a cache miss is substantial.

It also changes the invalidation strategy. Traditional caches invalidate on data changes. LLM response caches must also account for prompt changes, model version changes, and the inherent non-determinism of model outputs. A cache that returns a stale LLM response because the underlying data changed and the cache key didn't capture it is a silent correctness bug.

The design question is not "should I cache?" — you should. The design question is "at which level do I cache, with which key, and with which TTL?"

Level 1: The Gate as a PreComputation Firewall

The first and most impactful caching decision isn't a response cache at all — it's the gate pattern described in an earlier article in this series. But it belongs here because its primary function is cost avoidance.

TaxLens's runPipeline runs a cheap gate model before the expensive analysis model:

// Tier 1: cheap model (~$0.002)
const gate = await llmClient.structured({
  tier: 'gate',
  model: env.OPENAI_GATE_MODEL,
  // ...
});

if (!gate.data.valid) {
  // Pipeline terminates. Analysis model never fires.
  return;
}

// Tier 2: expensive model (~$0.06–0.08)
const analysis = await llmClient.structured({
  tier: 'analysis',
  model: env.OPENAI_ANALYSIS_MODEL,
  // ...
});

At a 15% invalid document rejection rate, this saves ~13% on total model spend with no change in output quality for valid documents. At a 30% rejection rate — which is plausible for a consumer product where users experiment with non-bank-statement PDFs — it saves ~26%.

The gate also prevents one category of abuse: a user uploading documents in a rapid loop to test the system would trigger a gate failure on non-bank-statement documents without ever burning expensive analysis credits. This isn't a complete abuse prevention system, but it's a meaningful cost control at minimal engineering cost.

Cache key consideration: The gate result is not cached by document content — PDFs are large, content-hashing is expensive, and the same user might legitimately re-upload after fixing a problem. The gate is a per-submission cost, not a per-unique-document cost. For the TaxLens use case (one bank statement per tax process), this is the right model.

Level 2: Exact-Match Response Caching

For queries where the same input is likely to produce the same useful output, exact-match response caching is the most straightforward win.

The Ajala AI SDK (my open-source multi-provider AI integration library) implements this as a first-class feature. When cachable: true is set, the SDK computes a cache key from the hash of system prompt + user prompt + provider + model and returns the cached response if a matching entry exists:

const result = await ai.prompt('Get weather in {{CITY}}', {
  expectJson: true,
  jsonStructure: { temp: 'number', condition: 'string' },
  validateJSON: true,
  cachable: true,
}, { CITY: 'Lagos' });

If this exact prompt, with this exact variable substitution, against this exact model, has been called within the TTL window, the SDK returns the cached response. No API call. No tokens consumed.

Where This Works Well

Classification tasks. BuffByte's content analyser classifies creator content against a taxonomy of topics, tones, and engagement patterns. A specific YouTube title or hook will receive identical analysis regardless of how many users trigger the analysis. Exact-match caching means the second user to submit the same content gets an instant response at zero incremental cost.

Reference data queries. "What are the NTA 2025 income tax bands?" has a stable answer that doesn't change between tax years. The TaxLens chat system could cache this kind of reference query and serve it from cache for the duration of the tax year.

Validation queries. The gate call in TaxLens asks "is this document a valid Nigerian bank statement?" The answer for a given document doesn't change between users. If two users upload the same bank statement file (rare, but possible in a shared-access product), exact-match caching would serve the second validation instantly.

Where Exact-Match Fails

User-specific queries. "Why is my tax liability ₦240,000?" is specific to the user's computation object. Two users with different incomes will have different context in their prompts even if the question is identical. Exact-match caching on the full prompt + context is unlikely to produce cache hits because the context varies per user.

Long prompts. If the cache key is a hash of a 20KB prompt (a bank statement CSV embedded in the prompt), the hash computation itself is cheap but the cache may be too specific to produce hits. Segment the cache key: hash the static parts (system prompt, model) separately from the dynamic parts (user content), and cache based on the static + a meaningful key from the dynamic part.

Level 3: Process-Level Response Reuse (Conversation Threading)

TaxLens's pipeline makes two sequential model calls — gate, then analysis. Both calls process the same PDF. Without any mechanism to avoid redundancy, the PDF is sent to the model twice.

OpenAI's Responses API supports previous_response_id: a new call can continue from a previous response, and the API server reuses the cached prior context. TaxLens uses this directly:

// Tier 2 continues from Tier 1's response
const analysis = await llmClient.structured({
  tier: 'analysis',
  previousResponseId: gate.responseId,  // ← continues the conversation
  // No PDF attached — the model has it from the prior turn
  // ...
});

When previous_response_id is set, the model's context from the prior response is reused server-side. The PDF doesn't need to be re-sent. The input tokens for the second call are reduced to the new user prompt and system prompt only.

The chat tier chains further:

// Chat questions continue from the analysis response
const chat = await llmClient.structured({
  tier: 'chat',
  previousResponseId: process.analysisResponseId,
  user: `\({context}\n\nQUESTION: \){question}`,
  // ...
});

Each chat question pays for: the system prompt, the context block (the computed tax figures — a few hundred tokens), and the user's question. It does not re-pay for the bank statement content, the gate verdict, or the analysis output — those are in the cached prior response context.

For a user who asks 10 follow-up questions, this difference is substantial. Without threading, each question re-sends the full context. With threading, the marginal cost per question is just the question tokens and the answer tokens.

Condition: This only works with providers that support server-side response caching and conversation threading. OpenAI's Responses API supports it. Not all providers do. When building with Ajala, check provider capabilities before designing around this pattern.

Level 4: Prompt Structure for Provider-Side Cache Hits

Both Anthropic and OpenAI offer server-side prompt caching: if a call's prompt shares a long prefix with a recent call to the same model, the provider charges a reduced rate (often 50–90% less) for the cached prefix tokens.

The key constraint: the cached prefix must be identical across calls. Variable content must come after the stable prefix.

This changes how you structure prompts. The wrong structure:

// Bad: user-specific content mixed into the prefix
const system = `You are TaxLens. The user's gross income is ₦${grossAnnualKobo}. 
Answer only personal income tax questions under the NTA 2025.`;

Every user has a different grossAnnualKobo. Every call has a different system prompt. No provider-side cache hits.

The right structure:

// Good: stable instructions as prefix, variable context in the user turn
const system = `You are TaxLens, a grounded assistant for Nigerian PERSONAL income tax 
under the Nigeria Tax Act 2025 (NTA 2025), effective 1 January 2026.

HARD RULES:
- Answer ONLY personal income tax questions under the NTA 2025...
- You may ONLY explain the computed numbers provided to you in the CONTEXT below...
- Every substantive answer MUST cite the relevant NTA 2025 section...`;

// Variable context goes in the user turn
const user = `CONTEXT — the only numbers you may discuss:\n${JSON.stringify(computation)}
\n\nQUESTION: ${question}`;

The system prompt is now identical across every chat call from every user. The provider caches it after the first call. Subsequent calls from any user hit the cache for the static portion. Only the variable user turn is charged at full rate.

This is the structure TaxLens uses in ai.service.ts. The SYSTEM constant is defined once at module level — no runtime interpolation, no user-specific content. All variable content goes into the user message.

How Much Does This Save?

System prompts of 500–1,000 tokens at gpt-4o pricing (~\(0.0025/1K input tokens) save ~\)0.001–0.002 per call with a 70% cache hit. At 10,000 calls/day, that's $10–20/day — not enormous, but not trivial. For the analysis system prompt (which is longer and contains classification guidance), the saving is proportionally larger.

More importantly: prompt structure for cache hits is zero-cost to implement once you're aware of the constraint. It's one of the few cost optimisations with no trade-off.

Level 5: Background Processing as a Demand Smoother

TrustRail's statementAnalysisJob doesn't respond to user requests in real time. It processes up to 10 pending applications per minute on a cron schedule:

const pendingApplications = await Application.find({ status: 'PENDING_ANALYSIS' })
  .sort({ submittedAt: 1 })
  .limit(10);

This is a form of demand shaping. A sudden surge of 50 simultaneous application submissions doesn't produce 50 simultaneous GPT-4o calls — it produces a queue that drains at a controlled rate over 5 minutes. The cost curve stays linear and bounded regardless of submission spikes.

For interactive products (TaxLens, BuffByte), this pattern doesn't apply directly — users are waiting for results. But the principle generalises: any AI computation that doesn't need to happen in the request path should be deferred to a background job. Asynchronous content analysis for a creator platform, batch report generation, digest emails — these are all better suited to a queue than to inline model calls.

The cost property: A queue with a throughput ceiling creates a predictable cost ceiling. If the ceiling is 10 calls/minute and each call costs \(0.08, the maximum cost is \)4.80/hour regardless of submission volume. Without the ceiling, cost is fully variable with user behaviour.

The Token Budget: Constraining the Chat Tier

The chat tier is the highest-risk tier for runaway costs. A single engaged user sending 30 questions in a session is 30 model calls. At $0.01–0.05 per call depending on answer length, that's manageable per user. At 1,000 concurrent users all doing the same thing, it's not.

Practical controls:

Per-session question limits — TaxLens processes are scoped to a single tax computation. The session naturally terminates when the user leaves or the process expires. But for open-ended chat products, a per-session or per-day question limit is a meaningful cost control. Implement it at the application layer before it becomes necessary at the billing layer.

Context compression — The buildContext function in TaxLens passes JSON.stringify(computation) as the user context. For a typical tax computation, this is 1–3KB. If context grows (historical data, multiple analyses), it should be summarised rather than passed in full. A summarised context that's 500 tokens instead of 2,000 tokens changes the per-question cost from \(0.06 to \)0.015 — a 75% reduction.

Response length constraints — System prompts that say "keep answers concise" are not just UX guidance — they reduce output tokens. A 500-token answer costs more than a 100-token answer. For a constrained domain (personal income tax questions, not open-ended conversation), short answers are often better answers anyway.

Monitoring as a Prerequisite

None of the above can be optimised without visibility into what's actually happening. TaxLens's llm_audit collection records inputTokens, outputTokens, latencyMs, tier, model, and circuitState for every model call.

This makes cost questions answerable:

• "Which tier is consuming the most tokens per day?" — query llm_audit, group by tier, sum inputTokens + outputTokens

• "Is any user or process burning disproportionate chat turns?" — group by code, count tier: 'chat', surface outliers

• "Are cache hits registering on the provider's side?" — compare inputTokens for chat calls with previousResponseId vs. without; a significant difference confirms caching is working

• "Is the circuit breaker affecting cost?" — count calls with circuitState: 'open'; if non-zero during business hours, adjust the failure threshold

The promptHash field (SHA-256 of system + user prompts) enables deduplication analysis: calls with the same hash that produce different outputTokens indicate model non-determinism; calls with the same hash that could be served from a response cache identify caching opportunities you haven't implemented yet.

Putting It Together: Cost Profile for TaxLens

A complete TaxLens analysis + one chat question, with all caching layers applied:

Without caching (no threading, no prefix caching, no gate):

• Gate: skipped (1 analysis call does the work)

• Analysis: 20K input tokens (PDF + full prompt), 500 output → ~$0.055

• Chat: 5K input tokens (full re-sent PDF context + question), 150 output → ~$0.015

• Total: ~$0.070

The difference: ~\(0.049 per complete user session, or ~70% cost reduction from caching layers. At 1,000 sessions/day, that's ~\)49/day saved ($1,470/month) from architecture decisions that don't change the user experience at all.

Trade-offs

Caching introduces correctness risk. A cached LLM response that was correct when computed may be incorrect after a model update or a prompt change. Response caches must be invalidated when prompts change. The Ajala SDK's cache key includes the model version for this reason — a model upgrade automatically invalidates cached responses.

Conversation threading creates longer dependency chains. If the analysis response that subsequent chat turns depend on is deleted (by a reaper job clearing old processes), those chat turns can no longer thread correctly. TaxLens handles this by including the full computation context in every chat user turn as a fallback — the threading is an optimisation, not a requirement.

Background queues don't suit interactive workloads. The throughput ceiling that makes queues cost-predictable also makes them latency-unpredictable. If response time matters to the user, background queuing isn't the right shape.

Provider-side caching has minimum length requirements. OpenAI's prompt caching applies to prompts above a certain length threshold (currently 1,024 tokens). Short system prompts don't benefit. This is only relevant for very terse prompts — in practice, most production system prompts with meaningful instructions clear this threshold.

The Mental Model

LLM calls have three cost dimensions: how often they're made, how many tokens they use, and whether you pay full price or cached price. Every caching layer addresses one of these dimensions.

The gate addresses frequency (some calls are simply never made). Response caching and background queues address frequency from a different angle (calls are deduplicated or rate-limited). Conversation threading and prefix caching address token cost (you pay for less content per call). Provider-side prompt caching addresses per-token price (you pay a fraction of the normal rate for cached portions).

No single layer is sufficient. A product with a perfect gate but no threading still pays full token cost for every chat question. A product with threading but no gate pays full cost for every invalid document submission. The layers compound.

Design the cost architecture before the first user arrives. The bill does not wait for you to be ready for it.

That's not what this is.

I've applied FSD across three different products at genuinely different scales and domains: TrustRail (a B2B BNPL platform), Medcord (a hospital management system), and WordShot (a real-time multiplayer word game). All three follow the same structural rules. All three look different. The interesting part is understanding why — and where the pattern holds, where it bends, and when you shouldn't use it at all.

Let's get cracking,

The Problem It Solves

Here's the folder structure I used to fall into on every project:

src/
├── components/     (47 files)
├── hooks/          (23 files)
├── utils/          (31 files)
├── types/          (18 files)
└── pages/          (12 files)

This feels tidy at the start. It's a disaster at scale.

Want to understand how multiplayer works in WordShot? You grep /components for multiplayer-related components, /hooks for multiplayer state, /utils for multiplayer helpers, and /types for the WebSocket event shapes. Those four folders tell you what type of thing each file is — they tell you nothing about which feature it belongs to.

Want to add a new feature? You touch files in four folders simultaneously, creating coupling between unrelated features at the filesystem level.

Want to remove the demo mode? You grep for demo across all four folders, hope you found everything, delete what you found, run the build, fix the broken imports you missed, repeat.

The folder-by-type structure is fine for small projects. The moment a project has more than about four independent features, it actively works against you.

The Core Rule

Feature-Sliced Design's core rule can be stated in one sentence:

A feature owns everything it needs to function. Code that's needed by two or more features lives in shared/. Code that's needed by one feature lives inside that feature.

Corollaries:

• A feature never imports from another feature

• A feature can import from shared/

• shared/ never imports from any feature

• Code starts in the feature. It gets promoted to shared/ when the second consumer arrives — not before

That's it. Everything else — the naming conventions, the sub-folder structure, the decision about whether to use sub-features — is derived from this rule applied to your specific domain.

TrustRail: FSD at the Small End

TrustRail's frontend is a React application with five features. It's the simplest case — a clean, unambiguous application of the pattern.

src/
├── features/
│   ├── auth/
│   │   ├── api/
│   │   │   ├── use-login.ts
│   │   │   └── use-register.ts
│   │   ├── guards/
│   │   │   ├── auth-guard.tsx
│   │   │   └── guest-guard.tsx
│   │   ├── helpers/
│   │   │   ├── nigerian-banks.ts
│   │   │   ├── token-storage.ts
│   │   │   └── validation.ts
│   │   ├── providers/
│   │   │   └── auth-provider.tsx
│   │   ├── screen/
│   │   │   ├── login-screen.tsx
│   │   │   ├── register-screen.tsx
│   │   │   └── parts/
│   │   │       ├── business-details-step.tsx
│   │   │       └── document-upload-step.tsx
│   │   └── auth.routes.tsx
│   │
│   ├── dashboard/          (overview metrics, application summary)
│   ├── applications/       (list, details, approve/decline)
│   ├── trust-wallets/      (BNPL product configuration)
│   └── public/             (the applicant-facing form)
│
└── shared/
    ├── constants/
    │   ├── api.ts
    │   └── routes/routes.ts
    ├── helpers/
    │   └── api-client.ts
    └── types/
        ├── auth.ts
        └── index.ts

Each feature contains its complete stack: API hooks (use-login.ts), screens (login-screen.tsx), component parts (business-details-step.tsx), helpers (nigerian-banks.ts), providers (auth-provider.tsx), and routes (auth.routes.tsx). Everything the auth feature needs to function is inside the auth folder.

shared/ is minimal and intentional. It contains three things: API constants, the API client instance (used by every feature's API hooks), and base types. Nothing that belongs to a single feature.

Notice what's not in shared/: no UI components, no business logic, no screens, no feature-specific helpers. The Nigerian banks list (nigerian-banks.ts) is in auth/helpers/ because only the registration form uses it. If another feature ever needed to display a bank selector, that file would move to shared/helpers/. It hasn't moved yet. It won't move until that second consumer exists.

The Naming Convention

Every file follows a consistent naming pattern across the entire project:

• API hooks: use-{resource}.ts — use-login.ts, use-applications-list.ts, use-trust-wallet-details.ts

• Screens: {resource}-screen.tsx — login-screen.tsx, application-details-screen.tsx

• Screen parts: {part}-{type}.tsx — business-details-step.tsx, action-modal.tsx

• Providers: {name}-provider.tsx — auth-provider.tsx

• Guards: {condition}-guard.tsx — auth-guard.tsx, guest-guard.tsx

• Routes: {feature}.routes.tsx — auth.routes.tsx, applications.routes.tsx

This convention means a new developer navigating the codebase can predict file locations before finding them. "Where is the hook for fetching application details?" — features/applications/api/use-application-details.ts. No search required.

Medcord: FSD at the Large End

Medcord is a hospital management system. It handles patient registration, EMR records, lab orders, staff management, asset tracking, and workspace administration. It's substantially more complex than TrustRail — the kind of project where a poor folder structure becomes actively painful.

The top-level feature count is nine. But the more important distinction from TrustRail is that most features contain sub-features — a second level of the same pattern applied recursively.

src/
├── features/
│   ├── auth/
│   │   ├── api/
│   │   ├── features/
│   │   │   ├── forgot-password/
│   │   │   ├── login/
│   │   │   │   ├── parts/
│   │   │   │   │   ├── login-form.tsx
│   │   │   │   │   └── two-fa-step.tsx
│   │   │   │   └── screen/
│   │   │   │       └── login-screen.tsx
│   │   │   ├── register/
│   │   │   ├── reset-password/
│   │   │   └── setup-2fa/
│   │   └── shared/
│   │       └── parts/
│   │           └── auth-layout.tsx
│   │
│   ├── patients/
│   │   ├── features/
│   │   │   ├── patient-list/
│   │   │   ├── patient-profile/
│   │   │   ├── patient-register/
│   │   │   ├── patient-admitted/
│   │   │   ├── patient-checkedin/
│   │   │   └── patient-transfers/
│   │   └── shared/
│   │       └── types/
│   │           └── patient.ts
│   │
│   ├── emr/
│   │   ├── features/
│   │   │   ├── chart-overview/
│   │   │   ├── vitals/
│   │   │   ├── medications/
│   │   │   ├── procedures/
│   │   │   ├── history/
│   │   │   ├── immunizations/
│   │   │   ├── documents/
│   │   │   └── access-log/
│   │   └── shared/
│   │       ├── chart-layout.tsx
│   │       └── types/emr.ts
│   │
│   ├── labs/
│   ├── staff/
│   ├── assets/
│   ├── workspace/
│   ├── notifications/
│   └── queue/
│
└── shared/
    ├── api/
    ├── components/
    ├── guards/
    ├── hooks/
    ├── providers/
    ├── types/
    └── widgets/
        └── app-shell/

When to Use Sub-Features

The decision to make patients a domain with sub-features rather than a single flat feature comes down to one question: do these sub-capabilities have meaningfully independent lifecycles?

A patient list screen and a patient profile screen do not share state. A patient registration flow and a patient transfer flow have entirely different API hooks, different screen components, and different form logic. They happen to be about the same domain entity (the patient), but they're developed, tested, and modified independently.

If they lived in a flat patients/ folder, you'd have a folder with 30+ files that are only loosely related. Sub-features give each capability its own clean boundary. patient-register/ contains exactly what you need to understand the registration flow. patient-transfers/ contains exactly what you need to understand the transfer flow. Neither reaches into the other.

The rule I follow: introduce a sub-feature level when a top-level feature would otherwise contain more than about 15–20 files, or when distinct capabilities within that feature need to be understood independently.

Feature-Level shared/

Each top-level domain has its own shared/ folder for code shared across its sub-features but not needed by other top-level features:

• emr/shared/chart-layout.tsx — the layout wrapper used by every EMR sub-screen (vitals, medications, procedures all share the same chrome)

• emr/shared/types/emr.ts — the TypeScript types for EMR entities

• patients/shared/types/patient.ts — the patient type shared across all patient sub-features

This is the same promotion rule applied one level down: code starts in the sub-feature, moves to the domain-level shared/ when the second sub-feature needs it, moves to the top-level shared/ when two top-level features need it.

The App-Level shared/

Medcord's top-level shared/ is more substantial than TrustRail's because the application is larger:

shared/
├── api/
│   └── use-hospital-by-slug.ts   (used by auth + workspace + all features)
├── components/
│   └── entity-link.tsx           (universal cross-entity navigation)
├── guards/
│   ├── auth-guard.tsx
│   └── hospital-guard.tsx
├── hooks/
│   ├── use-auth.ts
│   ├── use-hospital-slug.ts
│   └── use-permissions.ts
├── providers/
│   ├── auth-provider.tsx
│   └── user-bootstrap.tsx
├── types/                        (shared domain types: Hospital, Patient, Staff...)
└── widgets/
    └── app-shell/                (sidebar, topbar, user menu — used by every feature)

use-permissions.ts is in shared/hooks/ because RBAC permission checking is used across 6 different features (staff management, patient registration, EMR write access, lab order creation, asset management, workspace settings). Moving it to shared/ the first time two features needed it was the right call — it has never needed to move again.

WordShot: The Decision That Proved the Pattern

WordShot's FSD structure was discussed in the previous series of posts on this blog, but it's worth revisiting through the lens of a specific decision: demo mode.

Demo mode is an interactive walkthrough for first-time users. It shows the game flow step-by-step without making any API calls, without joining a real game room, without touching the WebSocket. It's entirely self-contained.

Before FSD, building demo mode in the old folder-by-type structure would have required:

• Adding demo-specific state to the existing Redux store (or creating a parallel store)

• Adding conditional rendering to game components to handle "am I in demo mode?" checks

• Threading a isDemoMode prop through the component tree

• Hoping that game logic changes don't break the demo flow

With FSD, demo mode was features/demo/. It contained its own state machine, its own screen components, its own mock data, its own routing. It shared only the base UI components from shared/ui/ that it visually needed. The game and multiplayer features were not touched.

The demo took two days to build because the structure made it easy. There was no untangling to do. No "wait, this component is used by both the real game and the demo, how do I make them diverge?" There was no entanglement in the first place.

When the decision to remove demo mode later came up, it was a folder deletion and three route changes. That's the proof.

The shared/ Discipline

The most common way FSD falls apart in practice is shared/ becoming a dumping ground.

I've seen codebases that claim to use FSD where shared/ contains:

• Feature-specific components that "might be reused someday"

• Utility functions used by exactly one feature

• A misc/ folder

• Business logic that belonged in a feature service

When shared/ is polluted, the cross-feature import rule becomes unenforceable because everything is already in shared/. Features stop having clear boundaries. The original problem returns in a different location.

The discipline is: shared/ must earn every file it contains. A file enters shared/ when a second consumer appears. Not when you think it might be reused. Not because it "looks generic." When the second consumer actually arrives and needs it.

In practice, I've found that healthy shared/ layers contain:

• The API client instance (one, used everywhere)

• Auth primitives (the session hook, the auth provider, route guards)

• The app shell / layout chrome

• Base TypeScript types for domain entities that genuinely cross feature boundaries

• A small set of UI utilities (token-safe wrappers, error display primitives)

Healthy shared/ layers do not contain:

• Form components (forms are feature-specific in almost every real codebase)

• Anything with "business logic" in the filename or in the code

• More than about 30–40 files total in a mid-sized application

Where FSD Bends

Three real failure modes I've encountered:

The cross-feature import temptation. You're building applications in TrustRail and you need the list of trust wallets to render a dropdown. trust-wallets has a use-trust-wallets.ts hook that fetches exactly the data you need. The temptation is to import it directly. Don't.

The correct move: expose the data through a shared type and a prop or context, not through a direct import. If applications needs to know which trust wallet an application belongs to, that relationship lives in the application data itself, not in a cross-feature import.

If two features genuinely need to share data access at a deep level, that's a signal that the feature boundary was drawn incorrectly. Merge them, or extract the shared data concern to shared/.

The premature sub-feature. Adding sub-feature levels when a flat feature would work fine adds cognitive overhead without benefit. auth/features/login/screen/login-screen.tsx has one more path component than auth/screen/login-screen.tsx. If the auth feature has three flows (login, register, forgot password) and each is less than 10 files, a flat structure is cleaner.

The sub-feature level is worth introducing when the sub-capability count makes the flat structure unwieldy — Medcord's patients/ with six sub-features is clearer with the sub-level than without it.

The naming inconsistency. FSD's value compounds when naming is consistent. When half the features use use-{resource}.ts for hooks and the other half use {resource}Hook.ts, the predictability breaks. When some screens are {feature}-screen.tsx and others are {Feature}Page.tsx, grep becomes your primary navigation tool again.

Establish the convention once, at project start, in a brief README. Enforce it in code review. It takes a day to establish and saves weeks over the lifetime of the project.

When Not to Use FSD

Feature-Sliced Design has overhead. For the right project, the overhead pays for itself quickly. For the wrong project, it's bureaucratic noise.

Don't use FSD when: the project has fewer than 3–4 independent features. A landing page site with one interactive form. A prototype with one screen. A personal tool with one workflow. Flat folder structures are faster to navigate and faster to change for small projects.

Do use FSD when: the project is expected to grow, different parts of it are owned or will be owned by different people, features need to be added and removed without cross-feature contamination, or you've already experienced the folder-by-type pain and want to not experience it again.

The most predictable sign that a project needs FSD: you've opened the wrong file three times in the last day because two features have a component with the same name in the same components/ folder.

Evaluation

Across TrustRail, Medcord, and WordShot, FSD produced several consistent properties:

Feature isolation — Changes to one feature never broke another. In Medcord, shipping a major rework of the patient transfer flow required touching exactly five files, all inside patients/features/patient-transfers/. No other feature was touched.

Predictable navigation — A developer new to TrustRail could find any file in the codebase by following the naming convention without ever searching. Feature → sub-folder → file. The structure teaches itself.

Clean deletions — WordShot's demo mode removal was a folder deletion. In Medcord, the queue/ feature (a work-in-progress) could be removed at any point without touching anything else. Feature-scoped code deletes cleanly.

Proportional complexity — TrustRail's five-feature flat structure and Medcord's nine-domain two-level structure are both instances of the same pattern, at different scales. The pattern doesn't impose Medcord's complexity on TrustRail or TrustRail's simplicity on Medcord.

The Honest Conclusion

Feature-Sliced Design is not a silver bullet. It won't fix bad abstractions, poor naming, or unclear feature boundaries. What it does is give you a consistent, enforceable rule for where code lives — one that scales with project growth instead of collapsing under it.

The folder-by-type structure tells you what your code is. FSD tells you what it does and who owns it. At small scale, the distinction doesn't matter much. At medium and large scale, it's the difference between a codebase you can navigate and one you can only survive.

The structure is not the architecture. But the right structure makes the architecture legible.

I did what most engineers do. Opened a screen recorder, ran through the flow, hoped the demo gods were watching. They weren't. Three takes, and one accidental tab switch later, I had a funny recording and I was too tired to redo.

So I tried the other route, I sat with an LLM, described what I wanted scene by scene, asked it to help me piece together some animation code. It worked, kind of. But it was painful. The model kept hallucinating component APIs that didn't exist, the code it generated needed heavy editing, and the mental overhead of managing keyframes, timing offsets, and animation libraries manually was exhausting. I spent more time debugging the video than building the feature it was supposed to show.

That experience planted a question I couldn't let go of: what if LLMs could generate product videos the same way they generate UI components?

The answer is Ìrísí.

The Name

Ìrísí (ee-REE-see) is a Yoruba word. It means appearance, the way a thing looks, the form it takes, how it presents itself to the world.

I've been naming my developer tools after Yoruba words with real meaning. My AI SDK is called Ajala, after the legendary traveler who cycled the entire world. The name carries weight. Ìrísí felt right for this because that's exactly what the library is about: controlling how things appear, shaping the form of your product's story.

The Vision

There's a version of the future I keep thinking about.

You finish building a feature. You write a short description of what it does. You hand it to an LLM. Two minutes later, you have a polished product video, animated, cinematic, the kind that makes your PM think you have a motion design team. You didn't touch a timeline. You didn't screen-record anything. The AI just... made it.

That's what Ìrísí is designed to enable.

The reason this is possible at all is because JSX is just text. It has a clear grammar, semantic component names, and readable props. When you write <Button variant="primary">Submit</Button>, a model doesn't need to guess what that does.

The problem with existing video tools is they weren't built with this in mind. They're built for humans operating GUIs — timeline panels, keyframe handles, layer stacks. That's a completely different paradigm from "write text that describes what you want."

Ìrísí is built on a different premise. What if a product video was just JSX?

<Presentation theme="dark">
  <Frame duration={5} transition="fade">
    <BackgroundGradient colors={["#1e3a5f", "#0a0a0a"]} />
    <Center>
      <Stack>
        <Eyebrow animate="fadeIn" delay={0.2}>NEW FEATURE</Eyebrow>
        <Title animate="slideUp" delay={0.5} staggerBy="word">
          Instant Working Capital Loans
        </Title>
        <Subtitle animate="fadeIn" delay={1.2}>
          Approved in under 60 seconds.
        </Subtitle>
      </Stack>
    </Center>
  </Frame>
</Presentation>

Five seconds. Animated headline, staggered word reveal, gradient background, fade transition. An LLM can write that. It's just props.

The LLM-First Design Decision

When I was speccing out Ìrísí, I made one decision that shapes everything: the API has to be something a model can generate reliably without needing the docs open.

That means three things:

Component names read as plain English. <ScrambleText> scrambles text. <MaskReveal> reveals behind a mask. <BackgroundAurora> is an aurora background. No abbreviations, no cleverness.

Prop values are named before they're numeric. animate="slideUp" not animation={2}. easing="bounce" not easing={[0.68,-0.55,0.27,1.55]}. The model should be able to infer what a prop does from its name alone.

Zero required props where possible. A <Frame> with nothing on it still renders. A <Title> with just children looks good out of the box. The 80% case should be one line of JSX.

The result: when you hand Ìrísí's component descriptions to Claude and say "make me a product video for this feature", the code it writes should run. Not "pretty close, needs tweaks." Runs.

The Part That Makes It Real

The component I'm most excited about is <UICursor>.

The hardest thing to fake in a product demo is interaction. You want to show a user clicking a button, filling a form, navigating a flow. Today your options are: screen-record the real thing and hope it cooperates, or spend an afternoon in a design tool animating every click manually.

<UICursor> lets you script it:

<UICursor
  moves={[
    { to: { x: 0.3, y: 0.4 }, duration: 0.8 },
    { to: { x: 0.6, y: 0.5 }, duration: 0.6, click: true },
    { type: "Feranmi Adeniji", duration: 1.5 },
    { to: { x: 0.7, y: 0.7 }, duration: 0.4, click: true }
  ]}
/>

The cursor moves, clicks, types, choreographed, deterministic, zero screen recording. Pair it with <UIInput>, <UIButton>, <UIModal>, and you can build a complete product walkthrough for a feature that doesn't even exist yet.

An LLM can generate this. Describe the user flow in English, it writes the cursor script, the video renders.

How I'm Building It

The spec is done, 170+ components across 17 categories, all documented with props. Text, layout, media, charts, UI mockups, backgrounds, transitions, annotations, audio, scroll controls, the works.

Implementation starts now. And I'm going to lean heavily on Claude Code for most of the actual coding.

There's a certain irony in using an LLM to build a library designed for LLMs to use. I'm fine with that.

Follow Along

The repo is live at https://github.com/spiderocious/irisi, star it to stay updated, open issues for features you want to see, or reach out if you want to contribute.

I'll be writing about the interesting engineering problems as they come up. The timeline engine is going to be non-trivial.

If you've ever finished a feature and wished the demo just built itself, that's what this is for.

Ìrísí. The way your product appears to the world.

In Nigeria — and across most of sub-Saharan Africa — that assumption breaks for a significant portion of small and medium businesses. They transact in cash or on mobile money. They haven't borrowed from a formal institution before. They're not in any bureau. Their creditworthiness is real, but it's invisible to the standard pipeline.

TrustRail is a BNPL underwriting platform I built for this context. A merchant offers "buy now, pay in instalments" to their business customers. The customer submits a bank statement. TrustRail reads it, produces a trust score, and makes an approval decision. No bureau required.

This article is about the architecture of that pipeline — the data model, the analysis engine, the two-tier LLM integration, and the specific design decisions driven by the Nigerian financial context.

Let's dig in.

The Input Signal

In the absence of a credit bureau, the bank statement is the richest available signal. A 3–6 month statement from a Nigerian bank (GTBank, Access, Zenith, Kuda, OPay, Moniepoint) tells you:

• Income patterns — frequency, amounts, source classifications (salary, business receipts, transfers)

• Spending behaviour — recurring obligations, loan repayments, utility payments, gambling activity

• Balance health — average balance, minimum balance, whether the account goes negative

• Behavioural signals — bounced transactions, failed direct debits, overdraft usage

• Debt exposure — identifiable loan repayments to lenders like Carbon, FairMoney, PalmCredit, Renmoney

None of these are as clean as a bureau-sourced credit score. But combined, they support a decision with meaningful predictive validity for the specific question being asked: "Can this business afford ₦X per month for the next N months?"

The challenge is that bank statements arrive as PDFs or CSVs in wildly different formats. GTBank's statement looks nothing like Kuda's. OPay's narrations are truncated differently from Access Bank's. A traditional rule-based parser that handles one bank's format doesn't handle another's without significant engineering for each.

This is where GPT-4o earns its place.

The Two-Engine Architecture

TrustRail has two analysis paths for a submitted statement, and the choice between them depends on what the applicant uploaded.

Primary Path: GPT-4o

When the application includes an OpenAI file ID (set during upload via the openaiService.uploadFileToOpenAI call), the background job uses GPT-4o to read the PDF directly:

if (application.openai?.fileId) {
  const { analysisResult, fullResponse, fullPrompt } = await analyzeFileWithOpenAI(
    application.openai.fileId,
    application.installmentAmount,
    trustWallet.approvalWorkflow,
  );
  // ...
}

The model receives the PDF, the installment amount being applied for, and the approval thresholds configured by the merchant. It returns a structured TrustEngineAnalysisResult — but crucially, as discussed in the previous articles, it does not compute the trust score. The score is computed by the deterministic TypeScript engine after the model's extraction is complete.

Fallback Path: TypeScript CSV Engine

If the GPT-4o call fails, or if the application was submitted with a CSV buffer instead of a PDF file ID, the system falls back to a pure TypeScript CSV parser:

if (application.bankStatementCsvData) {
  trustEngineOutput = await analyzeApplication(application.applicationId);
}

The CSV engine uses keyword-based transaction classification against a catalogue of known Nigerian financial institution narrations. It handles standard CSV exports from the major banks, though it lacks the format flexibility of the LLM path.

The fallback is intentional architecture, not an error recovery afterthought. CSV analysis costs \(0 per application. PDF analysis via GPT-4o costs ~\)0.06–0.08 per application. For merchants with high application volumes and low average approval amounts, the CSV path may have better unit economics than the LLM path even when both are available.

The Classification Vocabulary

The analysis engine classifies every transaction against a domain-specific taxonomy built for the Nigerian context. This is not a generic financial classifier — it's tuned to the specific institutions, product names, and transaction narration patterns that appear on Nigerian bank statements.

Income Sources

const CATEGORY_KEYWORDS = {
  salary: ['SALARY', 'SAL', 'WAGES', 'PAYROLL'],
  freelance: ['TRANSFER', 'REMITTANCE', 'UPWORK', 'FIVERR'],
  business: ['POS', 'PAYMENT FOR', 'SALES'],
};

The freelance category deliberately includes TRANSFER and REMITTANCE — in Nigeria, the vast majority of business-to-business and client-to-freelancer payments arrive as bank transfers with narrations that include these words. An overly conservative classifier that marks all transfers as non-income will systematically undercount income for self-employed applicants and freelancers.

This is the same classification problem TaxLens encounters with the Kuda format. The solution in TrustRail's CSV engine is the same: bias toward counting credits as income, reserve transfer classification only for credits you're confident are not income (reversals, refunds, self-transfers).

Spending Categories

const CATEGORY_KEYWORDS = {
  bills: ['PHCN', 'EKEDC', 'IKEDC', 'DSTV', 'GOTV', 'STARTIMES', 'AIRTEL', 'MTN', 'GLO', '9MOBILE'],
  loans: ['LOAN', 'REPAYMENT', 'INSTALLMENT', 'CARBON', 'BRANCH', 'FAIRMONEY', 'PALMCREDIT', 'RENMONEY'],
  gambling: ['BET', 'BETKING', 'SPORTYBET', 'NAIRABET', '1XBET', 'BET9JA', 'MSPORT', 'MERRYBET'],
};

The lender names in the loans category (Carbon, FairMoney, PalmCredit, Renmoney, Branch) are specifically Nigerian digital lenders. An applicant who is already repaying three of these simultaneously has a materially different risk profile from one with no active loans — even if both have the same average monthly income.

The gambling keywords are Nigerian-specific bookmakers. Frequent high-value transactions to betting platforms are a risk flag. They don't automatically trigger a decline — one bet per month isn't a signal — but above a threshold (₦10,000+ in gambling spend), a risk flag is raised.

Bounce Detection

const BOUNCE_KEYWORDS = [
  'INSUFFICIENT FUNDS',
  'REVERSAL',
  'DECLINED',
  'FAILED',
  'REJECTED',
];

Bounced transactions are identified by narration keyword matching. Bounce count feeds directly into the trust score (zero bounces: +5 points; 1–2 bounces: +2 points; 3+ bounces: -5 points). More than three bounces in a 3-month window triggers a FREQUENT_BOUNCES risk flag at HIGH severity.

The Trust Score Formula

The trust score is a weighted sum across five independent dimensions. Each dimension is computed from structured transaction data. The score ranges from 0 to 100.

Score = Income Stability (30) + Spending Behaviour (25) + Balance Health (20)
      + Transaction Behaviour (15) + Affordability (10)

Income Stability (30 points max)

Two sub-components:

Income consistency (0–15): incomeConsistency × 15. The consistency metric is the ratio of months with meaningful credit activity to total months analyzed. An account with regular monthly credits close to the expected salary date scores near 1.0. An account with sporadic, irregular credits scores lower.

Income-to-installment ratio (0–15):

• Ratio < 0.2: +15 (installment is less than 20% of monthly income)

• Ratio < 0.3: +10

• Ratio < 0.4: +5

• Ratio ≥ 0.4: +0

This ratio directly tests whether the requested credit is proportionate to the applicant's income. A ₦50,000/month installment for someone earning ₦500,000/month is a very different risk from the same installment for someone earning ₦100,000/month, even if the absolute income is "adequate."

Spending Behaviour (25 points max)

Debt ratio (0–10): max(0, 10 - debtRatio × 20). Existing loan repayments as a fraction of monthly income, penalised at 20× the ratio. An applicant already paying back 40% of their income in loan repayments scores 0 on this sub-component.

Gambling penalty (variable): If gambling spend is detected, the score is reduced by min(10, gamblingSpend / 1000). Up to 10 points can be lost here. The divisor (1,000) is denominated in naira — ₦10,000 in gambling spend removes the full 10 points.

Savings rate (0–15): min(15, savingsRate × 20). savingsRate = (avgMonthlyIncome - avgMonthlySpending) / avgMonthlyIncome. An applicant who saves 75% of their income scores 15. An applicant who spends everything they earn scores 0.

Balance Health (20 points max)

Average balance vs. installment (0–10):

• Average balance > 2× installment: +10

• Average balance > 1× installment: +5

• Average balance ≤ installment: +0

Minimum balance vs. installment (0–10):

• Minimum balance > installment: +10

• Minimum balance > 0.5× installment: +5

• Minimum balance ≤ 0.5× installment: +0

The minimum balance test is particularly revealing. An account that has a good average balance but frequently drops near zero has a cash flow pattern inconsistent with reliable monthly payments. The minimum balance score penalises this specifically.

Transaction Behaviour (15 points max)

Bounce count (+5/+2/-5): Described above.

Overdraft usage (+5/-5): An account that has gone negative receives -5 points. An account that has never gone negative receives +5. This tests the account's buffer — not just its average behaviour.

Transaction volume (+5/+2/+0): More than 30 transactions: +5. More than 15: +2. Fewer than 15: +0. A very low transaction count is a signal that the account may not be the applicant's primary account — they may be submitting a secondary account with selected favourable transactions.

Affordability (10 points max)

affordabilityRatio = installmentAmount / disposableIncome
disposableIncome = avgMonthlyIncome - (avgMonthlySpending + existingLoanRepayments)

• Ratio < 0.2: +10

• Ratio < 0.3: +7

• Ratio < 0.4: +4

• Ratio ≥ 0.5: canAffordInstallment = false → automatic DECLINED

The canAffordInstallment flag is a hard gate. If the installment exceeds 50% of disposable income, the application is declined regardless of the trust score. This rule is evaluated before the score is used for the decision.

The Decision Gate

The merchant configures three thresholds per TrustWallet (a TrustWallet is a product offering — the merchant may have multiple with different terms):

• autoApproveThreshold: scores at or above this → APPROVED

• autoDeclineThreshold: scores below this → DECLINED

• minTrustScore: the floor — any score below this declines regardless of the other thresholds

The decision function:

const makeDecision = (
  trustScore: number,
  approvalWorkflow: IApprovalWorkflow,
  affordabilityAssessment: AffordabilityAssessment,
): 'APPROVED' | 'FLAGGED_FOR_REVIEW' | 'DECLINED' => {
  if (!affordabilityAssessment.canAffordInstallment) return 'DECLINED';
  if (trustScore < approvalWorkflow.minTrustScore) return 'DECLINED';
  if (trustScore < approvalWorkflow.autoDeclineThreshold) return 'DECLINED';
  if (trustScore >= approvalWorkflow.autoApproveThreshold) return 'APPROVED';
  return 'FLAGGED_FOR_REVIEW';
};

Scores between autoDeclineThreshold and autoApproveThreshold are FLAGGED_FOR_REVIEW — they're routed to a human reviewer on the merchant's side. This band gives the merchant control over their risk tolerance without requiring them to binary-classify every application. A conservative merchant might auto-approve only at 80+ and manually review everything from 55–79. An aggressive merchant might auto-approve at 65+ and only manually review 45–64.

This is the right model for a system replacing a credit bureau: the algorithm provides a signal, not an edict. The merchant keeps the approval authority and calibrates the thresholds based on their actual loss rates over time.

Risk Flags

Beyond the score, the engine produces a set of named risk flags that the merchant can use to inform their manual review decisions:

A FLAGGED_FOR_REVIEW decision with HIGH_DEBT_TO_INCOME and FREQUENT_BOUNCES should inform a human reviewer differently than the same decision with only OVERDRAFT_USAGE. The flags add texture to the decision that the single-number score cannot.

The Approved Path: Mandate Creation

When an application is approved, TrustRail doesn't just send a webhook and stop. It creates a direct debit mandate via PayWithAccount/NIBSS so that installment collections can be automated without the customer having to manually make each payment.

The mandate creation runs immediately after the APPROVED decision:

if (trustEngineOutput.decision === 'APPROVED') {
  application.status = 'APPROVED';
  await application.save();

  const mandateResult = await createMandate(
    {
      accountNumber: application.customerDetails.accountNumber,
      bankCode: application.customerDetails.bankCode,
      bvn: application.customerDetails.bvn,
      // ...
    },
    business.billerCode,
    application.totalAmount,
  );

  application.pwaMandateRef = mandateResult.mandateRef;
  application.status = 'MANDATE_CREATED';
  await application.save();
}

The mandate reference is then available for the merchant to initiate collection on each instalment due date. The underwriting pipeline produces not just a decision but a collection infrastructure reference.

BVN data is encrypted at rest using an AES-based scheme before storage. The encryption key is environment-specific. BVN is transmitted to the mandate provider but never stored in plaintext in the application document.

Trade-offs and Honest Limitations

The classification keywords are a maintenance surface. The list of known lender names, utility providers, and gambling operators needs updating as the market changes. A new digital lender that isn't in the loans keyword list won't have its repayments counted against the debt ratio. This is a known gap. The LLM path mitigates it for PDF analysis — GPT-4o can identify "CARBON FINANCE REPAYMENT" as a loan repayment even without the keyword list — but the CSV fallback is keyword-dependent.

Transaction volume is a weak proxy for account completeness. The +5 points for 30+ transactions per period is designed to penalise accounts with suspiciously few transactions. But a high-income individual who uses their corporate card for most expenses and only transfers their salary through the statement account might legitimately have 12 transactions in a month. The signal is directional, not definitive.

The income consistency metric is simplified. The current implementation approximates consistency as creditTransactions.length / (5 × monthsAnalyzed), assuming roughly 5 credits per month as a baseline. This works adequately for salary earners with regular deposits, but understates consistency for business owners who receive many smaller payments spread across the month. A more precise implementation would group transactions by calendar month and measure the variance in monthly credit totals — a project for v2.

The trust score is not calibrated against outcomes. The weightings (30/25/20/15/10) and sub-component thresholds are based on financial domain knowledge, not trained against a labelled dataset of historical applications and their actual repayment outcomes. As TrustRail accumulates repayment data, those weightings should be revisited against actual loss rates per score band. The current score is a principled starting point, not a validated predictor.

BVN encryption is application-layer, not field-level. The BVN is encrypted before the application document is created, but it's stored as a single encrypted string in the document. A database-level field encryption with key rotation would be more robust — this is the kind of compliance detail that matters more as transaction volume grows.

Evaluation

The architecture produces several measurable properties relevant to the use case:

Format flexibility — The LLM path handles any Nigerian bank's PDF format without parser engineering for each institution. New bank statement formats are handled automatically, within the classification guidance in the system prompt.

Explainability — Every component of the trust score maps to a named sub-component with a formula. A declined applicant can be shown exactly why: "Your trust score is 44. Your income-to-installment ratio cost you 0/15 on income stability. Your debt-to-income ratio is 47% — above the 40% threshold — which triggered a HIGH_DEBT_TO_INCOME flag." This is not achievable with a black-box model score.

Merchant control — The three-threshold configuration (auto-approve, auto-decline, minimum score) gives merchants genuine control over their risk appetite without requiring them to understand the underlying formula. They calibrate based on their observed approval rates and loss rates, not on score internals.

Zero-bureau operation — The entire pipeline runs without querying any credit bureau, credit registry, or external data provider beyond the bank statement itself and the mandate creation API. This is the deliberate design choice that makes the system useful for the specific population of applicants who are invisible to conventional underwriting.

The Honest Conclusion

Bank statement underwriting is not a replacement for bureau-based credit scoring at scale. Bureaus aggregate repayment history across thousands of lenders and years of data. A 3-month bank statement is a much noisier signal.

What it is, is a viable signal for a specific use case: a merchant offering BNPL to their existing customers, where the merchant has prior relationship context and the amounts involved are moderate. The trust score doesn't need to be as precise as a FICO score — it needs to be more informative than a gut feeling, and it needs to reach the population that the bureau pipeline cannot.

For that use case, in that market, with those constraints, the architecture described here does the job.

The credit bureau is not the only path to a lending decision. It's just the one the infrastructure was built around.

My testing stack looks normal at the bottom: Vitest for units, Jest where the team's already standardised on it, Cypress and Playwright for end-to-end, Testcontainers for integration against real Postgres, k6 for load. I click through the UI myself when something feels off. I write tests like everyone else.

What's different is what sits on top of all of that, a layer of AI QA agents that act like a small swarm of senior QA engineers. One drives a real Chromium browser via a CLI called agent-browser. One hits live APIs and the database directly. One runs my existing regression suites against the latest build, marks which tests need re-running after a fix, and writes new test scripts that get committed back into the suite. Another reviews the design system implementations against the source HTML. The Demo Director persona produces launch films from real product DOM.

The agents don't replace the testing infrastructure. They sit above it and exercise it intelligently, generating edge cases I wouldn't have thought of, load-testing patterns I wouldn't have bothered scripting, source audits I wouldn't have had time to run by hand.

None of the infrastructure underneath is novel. The interesting part is the layer of discipline that makes the AI agents above it produce QA passes I actually trust.

This is Part 2 of a series on how I use AI to code effectively. Part 1 covered spec-driven development, the persona/skill/codebase model, context management with Opus and Sonnet, and code review at scale. This part covers the agents that go beyond writing code, testing, design, orchestration, and the things I've built when no existing tool fit.

Everything I'll reference is in the open-source repo at github.com/spiderocious/agentic-workflow. Open it in a tab and follow along.

Let's get cracking.

Why Not Just Playwright? The obvious question: I have Playwright. I have Vitest. I have Cypress for some flows. Why bother adding an AI QA agent on top?

The short answer: because the framework runs the cases I already thought to write. The agent generates the cases I didn't.

A Playwright suite knows exactly what I told it. If I wrote 40 tests for the checkout flow, it runs 40 tests. It doesn't ask "what about the case where the user opens two tabs and submits both?" It doesn't notice that the empty state has no aria-label. It doesn't try the "rapid-fire click the submit button twice" race condition I forgot to spec. It doesn't decide to throw 50 concurrent requests at the idempotency endpoint just to see what happens.

The AI QA agent does all of that. It thinks like a senior QA engineer thinks, what could break this?, and then it goes and tries. It generates edge cases as a function of the feature shape, not as a function of the test list I happened to write three months ago.

Five things the agent does that the framework alone doesn't:

1. Generates edge cases dynamically. Given a feature spec, the agent enumerates: happy path, empty state, boundary values, concurrent submissions, expired tokens, wrong roles, malformed input, network failures, race conditions, idempotency mismatches. The framework runs the cases the agent invents and the cases I previously wrote.

2. Runs my existing regression suites and triages. When the agent kicks off a QA pass, it runs the full Vitest + Playwright suite first, parses the output, classifies failures into "actually broken" / "flaky" / "blocked by something earlier," and writes a triage report. The framework is the execution engine; the agent is the engineer reading the output.

3. Writes new test scripts that get committed back. Edge cases the agent discovers become permanent. The agent generates a *.test.mjs or a Playwright spec that captures the failure, the fix lands, the test joins the regression suite. The agent feeds my pyramid.

4. Drives interactive load tests. "Hit this endpoint 50 times in parallel with different idempotency keys and tell me what the DB looks like at the end" is one prompt. Setting that up in k6 is a script I'd skip writing for a one-off check. The agent does it in 20 seconds.

5. Runs source audits in parallel with execution. Before the browser even opens, the agent greps the codebase for known anti-patterns (raw && in JSX, missing onError on mutations, useEffect + fetch races) and files them as bugs alongside the runtime tests. The two streams of findings, static and dynamic, land in the same report.

The relationship: the framework is the floor; the agent is the senior engineer running circles on top of it. Vitest doesn't get replaced. Playwright doesn't get replaced. They get used harder, and by something that knows what to look for beyond the cases I had time to write.

The Web QA Agent — 8 Phases

The web QA agent runs on agent-browser, a CLI tool that exposes a persistent Chromium daemon as bash commands. It complements Playwright rather than replacing it, Playwright owns the regression suite that runs on every commit; agent-browser is what the AI agent reaches for when it's exploring, generating edge cases on the fly, or driving the browser to reproduce a one-off scenario before deciding whether it deserves a permanent Playwright spec.

The persona at personas/qa-frontend.md loads two skills:

• agent-browser.md: the command reference (29KB)

• agent-browser-qa-guide.md: the field manual (38KB)

The agent follows an 8-phase loop on every QA pass:

Phase 1: Pre-flight

Confirm backend is healthy, confirm frontend is up, seed test data via API (never via UI):

curl http://localhost:3000/api/v1/health
curl http://localhost:5173 | head -3
TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@app.test","password":"Pass123!"}' | jq -r '.data.tokens.accessToken')

If the backend isn't responding, the agent stops. It doesn't try to test against a dead server. It says "the backend is down" and waits.

Phase 2: Source audit before opening the browser

Grep the codebase for known anti-patterns before touching the UI. File findings as CC-## (cross-cutting) entries in the test plan with P1/P2/P3 severity:

# Raw && in JSX (must be <Show when={...}>)
grep -rn "{.*&&" src/features/ --include="*.tsx" | grep -v "//\|test"

# Missing onError on mutations (silent failure bug)
grep -rn "useMutation\|mutationFn" src/features/ --include="*.ts" -l \
  | xargs grep -L "onError" 2>/dev/null

Every grep hit is a candidate bug. The agent files it before execution, then either confirms or refutes it in the browser.

Phase 3: Write the test plan

A markdown table written before execution. Columns: ID | Test | Expected | How to verify. This is the contract, what the agent will check, what passing means.

Phase 4: Open the browser session

agent-browser close --all
agent-browser open http://localhost:5173
agent-browser snapshot -i
agent-browser fill @e4 "test@app.test"
agent-browser fill @e8 "Pass123!"
agent-browser click @e6
agent-browser wait --url "**/dashboard"

The @e4, @e8, @e6 are accessibility-tree references from the snapshot. They reset on every snapshot, which is one of the agent's most common foot-guns (see the gotchas section).

Phase 5: Execute per case

For every test case: navigate → screenshot the initial state → action → wait for completion → screenshot the final state → record PASS / FAIL / SKIP / BLOCKED.

Critical discipline: never sleep. Always wait on an explicit signal:

agent-browser wait --load networkidle
agent-browser wait --text "Dashboard"
agent-browser wait --url "**/h/**"
agent-browser wait "#spinner" --state hidden

sleep 2 is the QA agent equivalent of try { ... } catch (e) { /* ignore */ }. It hides flakiness instead of fixing it.

Phase 6: Verify persistence after every mutation

After any state change, reload and re-check. A "success toast" that fires but doesn't actually persist is a real bug, and it's the kind that source review can't catch.

agent-browser click @e12   # Save button
agent-browser wait --load networkidle
agent-browser eval "document.body.innerText" | grep -E "success|saved"
agent-browser reload
agent-browser wait --load networkidle
agent-browser eval "document.body.innerText"   # Verify the change persisted

Phase 7: Test all four React Query states

Loading, success, error, empty. The agent tests all four for every data-fetching screen:

# loading — screenshot immediately on open
agent-browser navigate http://localhost:5173/feature
agent-browser screenshot /path/loading.png

# success — wait for data
agent-browser wait --text "Expected Content"
agent-browser screenshot /path/success.png

# error — mock the API
agent-browser network route "*/api/v1/feature*" \
  --body '{"error":{"code":"internal","message":"Service unavailable"}}'
agent-browser reload
agent-browser screenshot /path/error.png
agent-browser network unroute

# empty — fresh account or filter to nothing
agent-browser screenshot /path/empty.png

This catches the bugs nobody tests: the loading state that flickers, the error state that crashes, the empty state that shows "0" because of the && bug.

Phase 8: Write the execution report

The report comes after all tests complete. Never written mid-run. Format includes a Summary table, per-screen results, and new bugs found at the bottom.

DOM Patterns That Don't Lie

The agent has three patterns for interacting with the DOM that are non-obvious and worth showing.

React controlled-input fill

agent-browser type doesn't work on React controlled inputs, typing into a <input> whose value comes from useState doesn't fire React's onChange. The workaround:

agent-browser eval "
  const input = document.querySelector('input[name=email]');
  const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
  setter.call(input, 'new@value.com');
  input.dispatchEvent(new Event('input', {bubbles: true}));
"

This uses the property descriptor setter to bypass React's input proxy. Or just use agent-browser fill @ref "text" which handles this internally.

Modal detection trick

agent-browser eval "document.body.childElementCount"
# Returns 2 = no modal
# Returns 3 = modal open

agent-browser eval "document.body.children[2].innerText"
agent-browser eval "document.body.children[2].querySelectorAll('button')[2].click()"

Most modal libraries portal into document.body. Counting body children is a cheap, reliable way to detect modal presence without selectors that change between renders.

Verify the API was actually called

The agent can record HAR (HTTP Archive) traces and inspect them:

agent-browser network har start
agent-browser eval "document.querySelectorAll('button')[3].click()"
agent-browser wait 2000
agent-browser network requests --method POST --filter /result
# If empty: button did NOT call the result endpoint
# If present: it did

This is how the agent catches "save button fires the wrong mutation" bugs that look fine in source review.

Never Stop Investigating on the First Error

The single most important QA agent anti-pattern, from the agent-browser-qa-guide.md skill:

Toast didn't appear → check if the API call was made at all → API call not made → check if the button click fired → button click fired → check if the mutation was set up correctly → mutation wrong → check what endpoint it's calling.

When something fails, dig one level deeper. The default "this test failed" output is useless. The "this test failed because the button click didn't fire the mutation because the mutation was bound to a different selector because the component re-rendered and lost its handler" output is actionable.

The agent's other hard rules (verbatim from the skill):

Never report PASS if you didn't verify it. Never mark a test PASS based on source code alone. Never use sub-agents for testing: agent-browser is operated directly via Bash. Sub-agents cannot see your browser session.

The browser is the source of truth. The agent's report is not.

Running the Existing Regression Suite, Triaging, and Feeding It Back

The QA agent doesn't just run its own ad-hoc tests. The first thing it does on any non-trivial pass is execute the project's existing Playwright + Vitest + Cypress suites against the current build, parse the output, and write a triage report.

pnpm test --run --reporter=json > /tmp/vitest-results.json
pnpm playwright test --reporter=json > /tmp/playwright-results.json

Then the agent reads the JSON output and classifies every failure:

• Actually broken: assertion mismatched the implementation. File as a bug.

• Flaky: passed on retry, or a timing-related failure pattern. File as a flake and add to the "stabilise" backlog.

• Blocked by an earlier failure: a downstream test that depends on a fixture an earlier test was supposed to create. Mark BLOCKED, don't mark FAIL.

• Out of date: assertion is checking for behaviour that was intentionally changed. The test needs updating, not the code. Flag for human review.

The triage report lands at the top of the QA pass output. By the time I read it, I already know which failures are real, which are noise, and which need a test update versus a code fix. This is the work that used to consume the first 30 minutes of every QA review.

Writing test scripts that get committed back

The most valuable thing the agent does, in my opinion: when it discovers an edge case during exploratory testing, it writes a permanent test for it.

The pattern: agent generates a "what about..." case → executes it against the live app → confirms it's a bug (or a missing test) → writes a *.test.mjs script (for API) or a Playwright spec (for UI) → adds it to the appropriate suite → opens a PR with the test.

Example: the agent is testing the bulk-reclassify endpoint. It tries 1, 10, 100, 1000 transactions. All pass. It tries 10,000. The endpoint times out at 30 seconds. The agent doesn't just report the bug: it writes:

// docs/qas/backend/scripts/bulk-reclassify-limits.test.mjs
await test('BR-LIM-01', 'Bulk reclassify of 10,000 transactions completes under 30s', async () => {
  const txns = await createTransactions(10_000);
  const start = Date.now();
  const res = await post('/statements/bulk-reclassify', { transactionIds: txns });
  const elapsed = Date.now() - start;
  assertStatus(res, 200);
  assert(elapsed < 30_000, `took ${elapsed}ms, expected < 30000ms`);
});

The script gets committed alongside the fix. The regression suite is now one edge case smarter. The next time someone touches the bulk-reclassify code, the suite catches the regression before it ships.

This is the loop that makes the testing tier compound. Each QA pass leaves the suite stronger than it found it. The agent isn't replacing the test framework, it's feeding it.

Marking what must be re-run after a fix

When a bug is fixed and the agent re-runs verification, it doesn't run the entire suite from scratch (slow). It identifies the minimum set of tests affected by the fix:

git diff HEAD~1 --name-only | xargs -I {} pnpm test --related {}
pnpm playwright test --grep "@touched-by-fix"

Then it runs those, plus the test that originally reproduced the bug, plus any test the fix's diff touches. The agent writes the re-run list explicitly in the report, "I ran these 14 tests after the fix, here's why these and not the other 480." When the report lands, I can see exactly what was verified and what wasn't.

For high-risk fixes (security, financial, auth), the agent re-runs the full suite. For surgical fixes (typo in a string), it runs the targeted set. The classification is part of the bug entry itself.

The API QA Agent — Same Shape, Different Hands

The API QA agent at personas/qa-backend.md follows the same 8-phase shape, but with different tools: curl, jq, psql, mongosh, redis-cli. No browser.

The first thing the agent does, before any test, is confirm the URL mount points:

grep -n "app\.use" src/index.ts

This sounds trivial. It isn't. The single most common QA agent mistake is assuming admin routes mount at /api/v1/admin when they actually mount at /admin. The agent always confirms before testing.

The per-feature reading order

For every feature the agent tests, it reads the source in this order:

# 1. Schema/validation — ground truth for field names and enums
cat src/features/hospitals/hospital.schema.ts
# 2. Service — what it returns
cat src/features/hospitals/hospital.service.ts
# 3. Repo — what DB fields are selected/excluded
cat src/features/hospitals/hospital.repo.ts
# 4. Controller — what response shape is built
cat src/features/hospitals/hospital.controller.ts
# 5. Routes — paths, methods, middleware
cat src/features/hospitals/hospital.routes.ts

This is the order that catches drift. The docs lie. The code is truth. The schema is the most reliable starting point because field names there are checked at runtime by Zod, not just at compile time.

Plain Node fetch, no test framework

The test script is plain Node ESM with fetch, no test framework. From backend-qa-agent.md:

const BASE = 'http://localhost:8085/api/v1';

async function request(base, path, { method = 'GET', body, token } = {}) {
  const headers = { 'Content-Type': 'application/json' };
  if (token) headers['Authorization'] = `Bearer ${token}`;
  const res = await fetch(`\({base}\){path}`, {
    method, headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  let data;
  try { data = await res.json(); } catch { data = null; }
  return { status: res.status, data };
}

let passed = 0, failed = 0, blocked = 0, skipped = 0;
const failures = [];

function pass(id, label)         { console.log(`  \({id}: \){label}`); passed++; }
function fail(id, label, reason) { console.log(`  \({id}: \){label}\n    -> ${reason}`); failed++; failures.push({id,label,reason}); }
function block(id, label, reason){ console.log(`  \({id}: \){label} [BLOCKED: ${reason}]`); blocked++; }
function skip(id, label, reason) { console.log(`  \({id}: \){label} [SKIP: ${reason}]`); skipped++; }

The four-state framework: PASS / FAIL / SKIP / BLOCKED — is the same as the web QA agent. BLOCKED means "prerequisite broken." Never PASS.

A real test:

await test('A-HP-01', 'Register new user returns 201 with user+tokens', async () => {
  const res = await post('/auth/register', {
    email: 'testuser_a_hp_01@app.test',
    name: 'Test A-HP-01',
    password: 'Pass123!',
  });
  assertStatus(res, 201);
  const d = res.data.data;
  assert(d.user?.id, 'user.id present');
  assert(d.tokens?.accessToken, 'accessToken present');
  assert(d.tokens?.refreshToken, 'refreshToken present');
});

await test('A-EG-01', 'Register duplicate email returns 409', async () => {
  const res = await post('/auth/register', { /* existing email */ });
  assertStatus(res, 409);
  assertEqual(res.data.error?.code, 'conflict');
});

The rules for writing these tests (verbatim from the skill):

Always use fresh tokens. Never hardcode a token. Login at bootstrap time. Always propagate IDs. Create a resource, capture its ID, use it in dependent tests. If creation fails, block() all dependents explicitly. Never swallow 204 body parsing. Quote the actual response in failures don't just say "got 400", say got 400: {"error":{"code":"validation_error","message":"..."}} Use Date.now() for unique slugs. Hardcoded unique values get 409 conflicts on the second run.

The full how-to is in docs/how-to-use-qa-agents.md.

The Security Agent

The security agent is the most senior of the QA personas. Its identity is "you are a security engineer auditing this codebase for the kinds of bugs that show up in postmortems six months from now." It loads a dedicated security skill (skills/security-review.md) plus the universal hard-lessons.md, and it runs against whatever surface I point it at: a feature branch, a specific file, a full module, the entire backend.

It works the way the other QA agents do: source audit first, then live execution, then a structured report. The differences are in what it audits, what it executes, and how it grades severity.

What it audits (statically)

A series of grep + reading passes against the source, looking for known security anti-patterns:

Password and credential handling.

• bcrypt usage flagged: the workspace default is Argon2id (memoryCost: 64MB, timeCost: 3, parallelism: 1, tuned to ~200ms per hash on production hardware).

• Any plaintext password storage or logging.

• Any password comparison that isn't constant-time.

• API keys, JWT secrets, or webhook secrets stored anywhere except environment variables.

Token and session handling.

• Access tokens longer than 15 minutes flagged for review.

• Refresh tokens stored without server-side sha256(token) indirection.

• Refresh token rotation missing, every /auth/refresh must invalidate the old token and issue a new one.

• Refresh token reuse detection missing, a revoked refresh token presented again must revoke all sessions for that user.

• Sensitive actions (change email/phone/password, delete account, withdraw above threshold) without a fresh OTP gate.

HTTP and authz surface.

• Async route handlers without asyncHandler (unhandled rejection risk).

• Routes missing auth middleware (compared against the project's public-route allowlist).

• Routes missing role-check or ownership-check middleware.

• Route registration order, specific paths must precede parameterized paths (catches the /me vs /:userId shadowing class of bug).

• Any service that accepts req as a parameter (HTTP leaking into business logic; obscures authz reasoning).

Validation and input handling.

• z.any() in Zod schemas, bypasses validation entirely.

• Missing validation middleware on POST/PUT/PATCH routes.

• SQL string concatenation in repositories, parameterised queries only.

• File upload endpoints without size limits, MIME type checks, or content-type validation.

• SSRF risk: any handler that fetches arbitrary user-provided URLs.

Rate limiting and abuse vectors.

• Auth endpoints (/login, /register, /forgot-password) without per-IP and per-identity rate limits.

• 429 responses without Retry-After headers.

• Forgot-password endpoint that returns different responses for existing vs non-existing emails (enumeration leak).

• Login lockout missing after N failures.

Webhook and signature verification.

• Webhook handlers without HMAC signature verification.

• HMAC comparison with === instead of crypto.timingSafeEqual (timing attack risk).

• Missing replay-attack protection on webhooks (no event_id UNIQUE constraint).

Financial and money handling.

• Money fields stored as number / float / DECIMAL instead of bigint kobo/cents.

• Floating-point arithmetic on monetary values.

• Wallet ledger missing append-only enforcement (UPDATE/DELETE on wallet_entries).

• Missing reconciliation check between cached balance and ledger sum.

Logging and PII.

• Loggers without redaction config: must redact req.body.password, req.body.otp, *.password_hash, *.refresh_token, authorization, BVN/SSN/national-ID fields, full PAN.

• Error stack traces returned to the client in production.

• Console logs left in production code.

Storage and client-side concerns.

• Authentication tokens in localStorage (must be HttpOnly cookies).

• Any sensitive data in localStorage or sessionStorage unencrypted.

• Missing X-Frame-Options, Content-Security-Policy, or Strict-Transport-Security headers (Helmet config audit).

Supply chain.

• .npmrc missing minimum-release-age=10080 (the 7-day release-age guard against day-zero supply chain attacks).

• npm audit output parsed; high/critical findings filed as bugs.

• Direct git dependencies ("package": "github:user/repo") flagged for review.

What it executes (dynamically)

After the static audit, the agent runs targeted live tests against the running server:

Auth matrix. For every protected endpoint: no token → 401; expired token → 401 with code: token_expired; valid token wrong role → 403; refresh token reuse → 401 and all sessions revoked; token after account disable → 401 (tests tokenVersion invalidation).

Authz fuzzer (in-progress, see "what's next"). For every endpoint that takes a resource ID, the agent attempts the request with a valid token belonging to a different user. Expected: 403 or 404 (whichever the project's convention says). Any 200 is an IDOR finding filed at P0.

Rate limit storm. For each rate-limited route, the agent fires N+10 requests in a tight loop. Expected: 429 after N requests, with Retry-After header and X-RateLimit-Remaining: 0. Missing headers or unbounded responses are filed as findings.

Idempotency triple test. For each endpoint that accepts Idempotency-Key:

• First call with key K → creates resource

• Second call with key K, same body → returns identical response, no duplicate DB record

• Third call with key K, different body → 422 idempotency_mismatch

The agent verifies all three states in the database with psql / mongosh and checks Redis for the cached idempotency key.

Webhook replay. For each webhook endpoint, the agent re-fires a previously-processed event. Expected: 200 with no side-effect re-execution (idempotent), and the event_id UNIQUE constraint catches the duplicate.

Financial ledger reconciliation. For any wallet/ledger operations, the agent runs the reconciliation query:

SELECT
  (SELECT balance_kobo FROM wallet_balances WHERE wallet_id = $1) AS cached,
  (SELECT SUM(amount_kobo) FROM wallet_entries WHERE wallet_id = $1) AS ledger_sum;

Cached and ledger_sum must match. Any divergence is filed at P0.

Enumeration check. For /forgot-password and similar endpoints, the agent submits both a known-existing and a known-non-existing email and compares the responses. Must be identical (same status, same body, same timing within ~50ms).

What it produces

A structured report with findings tagged by severity:

Every finding includes: file + line, observed behaviour, expected behaviour, root-cause hypothesis, and a suggested fix specific enough that the dev agent can act on it without asking questions.

What it has actually caught

Sanitised postmortems from real audits:

CI credential leakage: a webhook test passed locally with real production credentials and failed in CI with the network blocked. The credentials had been in CI environment variables for three weeks. Rule installed: external service credentials are never in CI env vars. All third-party services are stubbed in test environments.

HTTP status info leak: /auth/verify-otp was returning 404 for "OTP not found" and 410 for "OTP expired" different responses leaked whether the OTP was ever generated. Fix: collapse to a single 410 otp_invalid regardless of cause.

Service/HTTP coupling enabling an authz hole: a service method was accepting req to read user_id. A test was passing a forged req to the service in unit tests, which masked the fact that the production controller wasn't actually enforcing the auth check the test was relying on. Rule: services must never accept req. Use requestContext.getStore().

Route shadowing: /api/v1/me returning 404 because /api/v1/:userId was registered first. The auth middleware was on the parameterized route, not on /me, so /me was accidentally public. Fix: register specific routes before parameterised ones; the audit now greps every router file for ordering.

Float-precision money bug: a calculation produced 99.99999999998 instead of 100. The bug surfaced in a balance reconciliation diff. Rule: all monetary values are bigint kobo or cents, branded with a Kobo type that prevents accidental conversion to number.

Webhook signature timing attack vector: webhook signature comparison was using === instead of crypto.timingSafeEqual. Theoretical risk, but the agent catches it as a P1 regardless. Fixed across every webhook handler.

How it composes with the other QA agents

The security agent doesn't replace the API QA agent: it runs alongside it. The API QA agent verifies functional correctness. The security agent verifies that the same endpoints can't be abused. Both file findings into the same report format with the same severity scheme.

When both agents are run on a feature branch, the merged output is the security posture of the change. The dev agent doesn't merge until both reports are clean (or the findings are explicitly accepted with a comment in the rules-lessons doc explaining why).

The full spec for what the security agent loads and runs is at skills/security-review.md. It's the most opinionated skill in the repo because security is the area where being right matters most.

The Two-Agent Design System

I ship design systems for the products I build. About 28 components each, full token systems, real scenes, the works. The output usually looks like the kind of thing a small in-house design team would produce after two months: except I do it solo, in a couple of days, with an AI pipeline.

The pipeline is two slash commands with non-overlapping jobs:

Before getting into how they work, the question that comes up first.

Why an Agent and Not Just Stitch (or v0, Lovable, Bolt)?

I use Stitch. I covered it in Part 1. It's excellent at producing a single screen from a detailed brief. v0, Lovable, Bolt, similar tools, they're all good at the same thing: take a prompt, produce a beautiful-looking screen, ship.

That's not what a design system is.

A design system is one stance applied consistently across 28 components and 5+ real surfaces. A button that matches the input that matches the card that matches the table that matches the empty state. The same accent color, the same border radius logic, the same shadow scale, the same typography ramp, composed deliberately so that any combination of components looks like it belongs in the same product.

Stitch and the rest can produce a beautiful login screen. Ask them to produce a consistent login screen + dashboard + settings page + onboarding flow + empty states + the critical "delete account" modal, all in the same visual language, and you'll spend the rest of the week reconciling differences between outputs.

The design system agent solves a different problem: commit to one visual stance and apply it ruthlessly across an entire system. It picks one stance (from a catalogue of 25), runs a structured discovery to understand the product, and then builds every component, every state, every scene against that one stance. The output isn't a single mockup. It's a complete system that survives composition.

The other difference: the agent's output is built to be shipped, not just looked at. Stitch produces an image or a code snippet for one screen. The design agent produces a folder of HTML scenes (with foundation CSS, design tokens, all states, all variants) that the shipper agent then translates into a real React component library inside a real codebase. The chain ends with merged PRs, not screenshots.

The Designer's Discipline

The designer agent operates under a small set of rules that are non-negotiable. These exist because every one of them is something I learned by getting it wrong first.

One stance, never blended. The first version of the agent let me say "modern flat with a touch of editorial and some Bauhaus accents." The output was generic. Indistinguishable from the default AI aesthetic. The fix was a hard constraint in the system prompt:

If you find yourself reaching for "modern flat with a touch of editorial and some Bauhaus accents," stop. Pick one stance. Ship one stance. The user will reward conviction.

The catalogue has 25 stances:- Bauhaus, Editorial Broadsheet, Brutalist Dossier, Japanese Minimalism, Soviet Poster, Surgical Paper, Risograph Print, Glassmorphic Studio, Industrial Telemetry, Cartographer Atlas, and others. Each one is a complete worldview: typography choices, color logic, geometric language, motion language. The agent picks one and commits. Half-baked blends produce half-baked output.

Scenes, not catalogues. Most design system docs show components in isolation: here's a button on a white background, here's an input in the default state, here's a card with placeholder content. The designer agent rejects that. State variants are rendered inside real situations, the loading state of a transaction confirmation, the error state of a payment retry, the empty state of a new account's transactions tab. You can't judge a button until you see it inside the screen where it'll actually appear.

No Bootstrap defaults. If the accent is Tailwind blue or the neutral is Slate, the agent has failed the brief. The constraint is in the prompt because it's the easiest place to drift. The default Tailwind palette is fine. It's also what every AI-generated UI defaults to, which is why all AI-generated UI looks the same. The agent must pick palettes that belong to this product, not to "modern SaaS aesthetic."

The CRITICAL modal is mandatory. Every system has at least one irreversible action, delete account, cancel subscription, transfer funds, archive case file. Most design systems skip designing the modal for it, because the happy path is more fun to draw. The agent doesn't get to skip it. The CRITICAL modal is designed as part of every system.

Speak plainly. The user (me, or whoever invokes the agent) is treated as non-technical. No "design tokens," "atomic components," "semantic colour pairs" without translation. The agent's job is to produce design judgment, not to lecture about design vocabulary.

The Five-Act Flow

The designer agent runs a structured flow, not a freeform chat:

Act I: Discovery. 8-10 questions about the product. Skip anything the brief already answered. Output: a short discovery doc captured in design-system/notes/<slug>/discovery-<date>.md.

Act II: Style proposal. Three stances from the catalogue, each with one paragraph explaining why this stance fits this product. Not "Bauhaus is a clean minimal style" — "Bauhaus fits because your product is about precision in financial decisions, and Bauhaus's geometric clarity reinforces that posture."

Act III: Variation pick. The most important act. The agent builds a single _variations.html file showing A/B/C visual variations side-by-side for a handful of key surfaces (the dashboard, the form, the list, the empty state). I pick one. Or I say "A for everything except the list row, give me three alternatives just for that." The agent iterates until the foundation is locked.

Act IV: Build. In order: foundation CSS first (tokens, type scale, geometry, motion), then primitives (buttons, inputs, badges, selects), then data display (tables, cards, charts), then 3+ named surface scenes, then overlays (modals, toasts, tooltips, the CRITICAL modal).

Act V: Register. The agent appends the project to projects.json, mirrors to the inline window.__PROJECTS__ for the Studio gallery, and builds a thumb.html so the project shows up in the index.

The flow exists because design systems built in freeform chat drift. The five acts give the human (me) discrete review checkpoints: discovery, stance pick, variation pick, build progress, registration. I can intervene at any one. I don't have to discover three days later that the agent chose a stance I never approved.

Why the Designer Output Looks Like a Designer Made It

This is the part most AI design tools get wrong, and the part the agent gets right:

Real content, not placeholder. Every scene uses plausible names, varied entities, believable values, earned non-round numbers. Actual names that vary in length, actual transactions with values like ₦48,250 and not ₦1,000,000.00, actual dates that are recent and sensibly spaced. The visual rhythm of the design depends on real content, because real content is what the design actually has to hold.

Type does work. The agent picks a typography system where serif does the thinking ("Your monthly summary"), humanist sans does the chrome ("Settings · Notifications"), and mono does the record numbers (account IDs, transaction references). Three faces, three jobs, clear hierarchy. Not one face doing everything.

Numbers shout. When the most important thing on a screen is a number, the agent makes that number visibly the loudest object. Bigger than the heading. Sometimes by a lot. The eye should land on it first without thinking about it.

Red is reserved. Critical red is for irreversible actions and life-threatening conditions only. Amber for everything else that's "bad but recoverable." This single rule prevents the design from looking like a constant emergency.

Hairlines, not shadows. When in doubt, draw a line. Shadows have become AI design's default decoration; they look fine at first and tired by week two. Hairlines age better.

These rules live in the agent's persistent memory (design-system/notes/preferences.md), which the agent reads at every session start. They were learned by doing, the first attempt at the medcord design system was rejected by me with the words "AI garbage, most AI shit ui design I've ever seen." The second attempt, after the stance discipline was added, got "shit this is goooood." That delta is the value of the rules.

The Shipper's Discipline

The shipper has one hard rule, stated in four separate places in its system prompt because it's the rule the agent most wants to violate:

Never invent design, only translate.

The shipper takes the HTML the designer built and produces a real React component library. It does not improve, embellish, or "modernise" what the HTML shows. If the HTML has six button variants, the React lib has six button variants. If the HTML doesn't show a hover state on the cards, the React lib doesn't add one. If a prop has multiple reasonable shapes (controlled vs uncontrolled, portal vs inline), the shipper surfaces the question, doesn't guess.

The other rule: don't fight the repo. The shipper calibrates against the target codebase before writing anything. It detects the framework (React/Vue/Solid/Svelte), the version, the styling system, the path aliases, the file layout, whether components use named or default exports, where cn is imported from. If the existing convention contradicts the shipper's preference, theirs wins. The new components must look like they belong in the repo, not like they were dropped in from a different project.

This sounds obvious. It's the easiest thing for an AI to violate. Without the discipline, the shipper writes "improved" code that nobody asked for and nobody can review against the spec.

The Six-Act Ship Flow

The shipper runs its own structured flow, with checkpoints that prevent it from running away:

Act 0: Silent reads. Reads the Studio project's foundation CSS, the key HTML scenes, the migration guide. No output.

Act I: Calibrate (read-only). Detects everything about the target repo: framework, version, styling, conventions. Reports findings. Stops. Waits for me to confirm or correct the detected conventions before doing anything else.

Act II: Discovery. About 8 questions, each with a calibration-inferred default. Press enter to accept. Questions cover: component directory, naming, prop conventions, controlled vs uncontrolled defaults, portal preferences.

Act III: Component plan. Writes a structured plan listing all ~28 components grouped by category. Stops. Waits for me to say "go" before writing any code.

Act IV: Generate. In order: tokens (extend globals.css), Tailwind config extension, cn util if missing, then components in checklist order with a checkpoint every 5 components. After each component is generated, it is immediately added to the preview/viewer page with all its props, variants, and states shown.

Act V: Wire up. Asks before any pnpm add or npm install. Writes a migration doc at <target>/docs/<slug>-MIGRATION.md explaining what was added and any follow-up steps.

Act VI: Notes & report. Appends notes/<target-repo-name>/shipped-<date>.md capturing what shipped, what was deferred, and any lessons learned.

The act structure is the safety mechanism. Every act ends with either a checkpoint (waiting for me) or a permission gate (asking before mutating). The shipper cannot run away, there are at least three places where the human is the one who unblocks the next step.

The Incremental Preview Lesson

The most important operational rule in the shipper, learned the hard way:

When building a component library, after building each single component the agent must immediately add it to the preview/viewer page, with all its props, variants, and states shown as samples, then move to the next component.

Not "build all 28 components, then wire all the previews at the end." Per-component preview, sequentially.

The reason: the preview is where I review. A component that isn't in the preview yet is invisible to me. Batching previews to the end leaves a long blind stretch where work piles up unreviewed, and by the time the previews land, I'm reviewing 28 components at once with no ability to course-correct any single one.

The "no sub-agents" qualifier follows from the same logic. Parallelising component generation across agents would re-introduce the blind stretch (I can't watch two threads at once), plus it removes my ability to scroll the main-thread transcript and audit step by step. The constraint is on observability, not on speed. The shipper could go faster with parallel agents. It would also become impossible to trust.

Permission-Gated Mutations

The shipper has explicit guardrails on what it can change without asking:

• Never write a file before I say "go" in Act III. Calibration is read-only.

• Never overwrite an existing file without showing the diff first. This applies to tailwind.config.*, globals.css, package.json, main.tsx. Diff, then ask.

• Never run shell side effects (install, format, test) without asking. Show the exact command, wait for confirmation.

• Never skip git hooks or signing. Even if pre-commit fails, fix the cause; don't bypass.

These exist because the shipper is operating inside my real codebase. A mistake at this layer isn't a bad Figma export, it's a corrupted Tailwind config or a botched component file that breaks the app.

What This Produces

A complete design system shipped to a real React codebase in about two days, end to end:

• ~28 components, all in the same visual stance

• Design tokens wired into the target's Tailwind config

• A preview/viewer page showing every component with every variant and state

• A migration doc explaining how to consume it

• Persistent memory entries in notes/<target-repo-name>/shipped-<date>.md capturing what was built and what was deferred

The components look like a designer made them, because the design discipline lives in the designer agent, the implementation discipline lives in the shipper agent, and neither one is asked to do the other's job.

The full how-to: docs/how-to-use-design-system.md. Both system prompts and the act-by-act flow are open source.

Multi-Agent Orchestration: When to Fork, When Not To

I do not treat sub-agents as the default. The pattern across my work is single-thread + persona swap, not parallel agent swarms except when demanded:

Multi-agent / persona handoff is allowed when

• Work crosses a discipline boundary with a hard artifact at the seam: backend → backend QA → frontend → frontend QA. Each persona produces a structured handoff doc. The handoff is the shared context.

• Long-running unattended creative work (e.g. a batch of demo films). Pre-decided fallback ladders so the agent has authority to keep moving without me.

The nuance: sub-agents are fine when the user is absent and the artifact-at-handoff is well-defined. Sub-agents are forbidden when the user is watching or when shared mutable state (browser session, preview page, live-edited repo) can't survive a fork.

How agents hand off

Three layers, in priority order:

Layer 1: Handoff documents (canonical). Every persona has a templated handoff format. The fullstack persona ships two distinct templates (Frontend QA + Backend QA) plus a Contract Drift Checklist that runs at the seam: Zod schema field names match frontend TS type field names exactly, nullable fields match, pagination shape matches, money fields are integers, dates are ISO 8601 strings, empty arrays are [] not null, error handlers check error.code not error.message.

Layer 2: Persistent memory graph. In Claude Code, ~/.claude/projects/.../memory/ stores cross-linked memory files. Memories named for what triggered them (feedback-ship-preview-incremental, agent-browser-demo-gotchas). I expect the AI to "traverse memory graph-style, not read each file in isolation."

Layer 3: Project guides as a read-order. Project-level agent-handoff.md files are addressed "to the next AI agent... read this once and operate at the same quality bar from the first message" and prescribe a numbered must-read order through the project's docs. Handoff is not a chat, it's a curriculum.

Anti-pattern: plain-text "here's what I was doing" handoffs. Everything is structured. Always.

The browser is the source of truth

The orchestration safety net:

• QA frontend persona never reports PASS without browser verification.

• AI tools lie about success. The agent-browser memory explicitly says: "reports success but the file lands elsewhere." Mitigation: verify state, don't trust default success signals.

• The reload-to-verify-persistence step in the standard QA loop is the circuit breaker. After every mutation, reload and re-read the DOM.

When the AI's report disagrees with the browser, the browser wins.

The Demo Director: AI for Things I'm Bad At

A meta-pattern: I build agents to fix my own weaknesses.

The longest persona in the repo is demo-director.md at ~27KB. It's the persona for the work I don't know how to do, marketing demos and launch films. The persona file is rich because the gap between my native ability and the required output is wide. Personas grow proportional to the gap.

The Demo Director's identity (verbatim):

You are the Demo Director. Your job is to make a product look as good as it actually is, and, when the moment calls for it, to make it look like a launch film. You are a product-marketing-minded frontend engineer with a cinematographer's eye and a motion designer's hands. You do not build features — you reveal them.

Your taste is clean, cinematic, art-directed, honest, and luxurious.

The hard-won rule

The naive approach, drive the live app and agent-browser record it produces a dashcam, not a film: it captures every dead moment while the agent thinks, has no authored pacing, no animations between states, no pointer, no zoom, no callouts, no audio. Do not make films this way. It was tried and it sucked.

Instead, films are rendered deterministically. The renderer is Remotion (React → MP4).

The architecture

agent-browser =  RECON: scrape the real app's markup + computed styles + screenshots + real data

React (Remotion) =  REBUILD the UI faithfully as self-contained components (no cross-tree imports)
                     ANIMATE with Remotion interpolate/spring (+ Framer Motion where its ergonomics help)

Director Kit = reusable primitives: <SceneCard> <Caption> <Pointer> <Spotlight> <ZoomTo> <Reveal>

script.ts = the screenplay: ordered scenes, durations, copy, pointer paths, highlight targets, audio cues

Remotion render = frame-perfect MP4; audio muxed in; then ffmpeg for MP4 = GIF if needed

The three data strategies (always present all, recommend one, ask before building):

1. Use the product's real/built-in data. Most honest path.

2. Mock at the network layer: agent-browser network route "**/api/..." --body '{...}'.

3. Seed real data via the app's own flows/seed scripts, then drive the real UI.

The guardrails:

Films are rendered, never screen-recorded. Honest, always. Dramatization and set dressing allowed; fabricating features is not. Recreate from the real thing, not from memory. Retina or it didn't happen. Stills at scale 2. Films at 2x density / 1080p+. No test test data, ever.

Deeper dive in a future article. The point for now: the persona that codifies the work I'm bad at is the most elaborate persona in the repo. That's the meta-pattern, personas grow proportional to the gap between your ability and the work.

Self-Built Skills: agent-browser, Director Kit

Two skills I built when no existing tool fit.

agent-browser

A CLI tool that exposes a persistent Chromium daemon as bash commands. It's the foundation of the QA frontend agent and the Demo Director's recon step.

Why I rely on a tool of this shape: Playwright, Cypress, and Puppeteer are built for humans writing test files in their DSL. That's the right shape for a regression suite. It's the wrong shape for an AI agent doing exploratory testing in the middle of a conversation.

agent-browser lets the AI agent drive the browser in plain Bash. The agent thinks in shell commands, not in test framework idioms. That made the QA agent's prompts dramatically shorter and meaningfully more reliable — and it doesn't conflict with Playwright at all. The agent uses Playwright for the regression suite it's running, and agent-browser for the exploratory work it's doing on top.

The full reference is in skills/agent-browser.md. The field guide for QA usage is in skills/agent-browser-qa-guide.md.

The Director Kit

A set of React primitives the Demo Director composes into scenes: <SceneCard>, <Caption>, <Pointer> (bezier paths + click pulses), <Spotlight> (dim to focus), <ZoomTo> (camera moves), <Shape>, <AudioCue>, <Reveal>, <BrowserFrame>.

Each primitive composes deterministically against Remotion's frame clock. The Demo Director persona doesn't have to think about animation math; it composes primitives, and the math is correct by construction.

The Director Kit isn't open-sourced separately yet. The patterns it encodes are in the Demo Director persona.

What I'd Build Next Honest gaps in the current system, in order of impact:

1. A landing-page persona. The chain has a hole between Demo Director output and the actual landing page repo. Right now I build landing pages ad hoc. Codifying the pattern (which Director assets go where, what copy structure converts, how the AI-discoverability layer plugs in) would close it.

2. A "fresh repo onboarding" agent persona. "I'm a new agent in a Feranmi project, what do I read in what order", currently project-specific via agent-handoff.md files. A universal version would reduce session-start friction.

The Honest Conclusion The "AI as force multiplier" narrative is real. But it works for me because I've been bitten enough times to know what to encode. It's the practice (bug → rule → spec → next agent inherits it). The files are just where the practice lives.

The files are at github.com/spiderocious/agentic-workflow. Fork it. Edit it. Ignore what doesn't apply. The whole point of the modular structure is to make that easy.

What I hope this two-part series did is show one specific way to use AI seriously in production, not as a toy, not as a magic box, but as a contractor with a reference library of your team's lessons. The reference library is the work. The AI is the means.

The AI doesn't make you a better engineer. It executes the engineer you already are, at higher throughput. Encode the engineer you want to be.

Bye.

I didn't write most of the code. AI agents did. I planned the work with Opus, executed the implementation with Sonnet, ran QA passes with two more agents driving a real browser and a live API. The output was indistinguishable from what I'd write by hand, except faster, and with better test coverage than I usually have the patience for.

It's because the AI is loaded with context before it writes a single line, every bug my team has ever shipped to production, every API convention, every banned pattern, every "we tried this in March and it didn't work." The agent walks into the session already knowing what the senior engineer in the room would have told it.

I've evolved this system across the products I ship — TaxLens, TrustRail, Medcord, Solon, Pracket, WorkSight, Ohlify, and others. It's not a framework or a tool. It's a collection of markdown files and a discipline for using them. It treats the AI agent as a recurring contractor on a maturing codebase, not a one-shot magic box. Each session inherits the accumulated rule set. Each session contributes new rules back when it finds new failure modes.

The result, after about 18 months of iteration:

• Velocity — I ship features end-to-end in hours that used to take days. The bottleneck has moved from typing speed to thinking speed, which is where it should have always been.

• Consistency — code from the AI looks like code I'd write, because the AI is reading the same conventions I follow. Reviewers can't usually tell which lines were mine and which were the agent's.

• Reduced regression rate — recurring bug classes (the 204 .json() parsing bug, API drift, money-as-float, useEffect + fetch races) don't recur. The rules that prevent them are loaded on every session.

• Agentic QA — every feature gets an agent-driven QA pass before I touch it. Browser-driven for the frontend, live API for the backend, with a PASS/FAIL/SKIP/BLOCKED report I read in two minutes.

• Audit trail — every architectural decision is in a markdown file. When the next engineer (human or AI) asks why something is the way it is, the answer is one grep away.

This is Part 1 of two articles on the system. Today: how I plan with AI, how I spec-drive development, how I manage context across long sessions, and how I run code review at scale. Part 2 covers the QA agents, the design system pipeline, and the tools I've built around all of it.

The full system is open source at github.com/spiderocious/agentic-workflow. Every persona, skill, and example I'll reference below is in that repo. Open it in a tab and follow along.

Let's dig in.

Why This Works (and Why the Default Doesn't)

Before showing the mechanics, the foundational claim:

The default AI coding workflow is engineer types a task description, agent generates code, engineer reviews and ships. It works for trivial tasks. For anything non-trivial in a codebase with history, it produces plausible-looking code that violates conventions, repeats fixed bugs, and forces the engineer to spend more time reviewing than they saved by delegating.

The agent isn't wrong because it's bad at coding. It's wrong because it doesn't know what your team knows. It doesn't know that money is stored as bigint kobo, never float. It doesn't know that 204 responses break .json() parsing. It doesn't know that the auth middleware must come before the role-check middleware. It doesn't know that two engineers ago, someone added a route at /api/v1/me that was silently shadowed by /api/v1/:userId and the team spent three days debugging it.

All of that knowledge exists somewhere — in the heads of the engineers, in PR comments, in postmortems, in Slack threads, in git blame. None of it is loaded into the agent's context at the start of a session.

My system is built on a single inversion of that default: encode the lessons in files the agent reads on every session. Make the institutional memory available to the contractor on day one, every day. Everything else in this article is mechanics for doing that well.

The Three-Layer Model

The system has three layers. Each does one thing.

──────────────────────┐
│  LAYER 1: PERSONA                                            │
│  Who the AI is. Identity + invariants + which skills to     │
│  load. Small files (3-30KB).                                                  ──────────────────────┘
                        
            "Before writing code, load these:"
                         ▼
──────────────────────┐
│  LAYER 2: SKILL                                              │
│  HOW to do specific work. Detailed playbooks. Tool          │
│  references, code patterns, lint rules. Reusable across     │
│  multiple personas. Files range from 10KB to 40KB.          │
──────────────────────┘
                          │
                "Reference codebase docs:"
                          ▼
──────────────────────┐
│  LAYER 3: CODEBASE                                           │
│  Your repo. The personas point to your project's docs/      │
│  folder as the source of truth for "what good looks like    │
│  here."                                                       │
──────────────────────┘

A persona is who the AI is — a senior backend engineer, a QA engineer specialising in frontend, a mobile-aware API designer.
A skill is how the AI does specific work — write a service method, drive a real browser for QA, design an API endpoint with mobile consumption in mind.
The codebase is what the AI is working on, with project-specific docs that describe local conventions.

The separation is load-bearing.
Five reasons it matters:

1. Skills are reusable, personas are roles. hard-lessons.md is loaded by 6 different personas — backend, frontend, fullstack, mobile, qa-backend, qa-frontend. If a hard lesson lived inside any single persona file, the other five would drift away from it. Separation enforces single source of truth.

2. Personas can be tiny. The smallest persona in the repo is frontend.md. It's basically: "you are a senior frontend engineer, load these five skills, here are your guardrails." The persona's job is to select and orient, not to redefine.

3. Skills can be large without bloating context. backend-qa-agent.md is 40KB. If that lived inside the QA backend persona file, every "audit my API" invocation would burn 40KB of context. Instead, the persona is small and references the big skill — the agent only loads the heavy file when it actually needs it.

4. QA personas can audit dev personas' work using the same rulebook. qa-backend.md and backend.md both load backend-service-patterns.md. The QA agent greps the codebase for violations of the same rules the dev agent was told to follow. No translation step. No divergence.

5. Personas encode order and tone; skills encode correctness. A persona says "you think in this order: data model → service contract → HTTP surface." That's a working-style claim. A skill says "services return ServiceResult<T>, never throw." That's a rule. Different kinds of content; different files.

The full mental model is written up in docs/how-personas-work.md in the repo.

Specs Are Not Documentation. They're Working Memory.

The single most impactful change in how I work with AI is treating specs as the source of truth that AI agents read, execute against, and update, not as documentation written after the fact.

The operating model:

• Prose lives in a docs folder

• Code lives in the project repo

• AI agents shuttle between them

The docs aren't a description of what the code does. They're a manual addressed to the next AI agent that will work on this project. They include verbatim instructions like "Pattern-match this file before writing any code. Every API path, response unwrap, request body field, icon name, and meemaw pattern is pre-verified here against the actual backend source. Do not guess."

There are five kinds of spec documents, each with a different audience:

There's a real example of each in the repo's examples/ folder — including a sample PRD at the repo root that shows the bare-minimum format.

The Spec

Every MVP spec is a bulleted list of user-story sentences in the exact form "A user can / a user must / a user will be able to ...". Each one is testable, demoable, and pointable-to in a QA report.

From the examples/mvp-spec.md file:

## Module 1 — Upload

- A user can choose between two input paths: Upload a CSV statement or Try with sample data.
- A user must accept the privacy notice before upload becomes available.
- A user can upload a CSV file up to 10MB. Larger files must be rejected with a clear message.
- A user must see a real-time progress indicator while the file uploads and parses.
- A user will be able to see how many transactions were detected immediately after parsing.

Each bullet is one unit of work. The pattern (A user can / must / will be able to) is itself the test contract.

Here's the trick — and this is the part most spec-driven workflows miss:

The MVP features becomes the QA test cases which then becomes the test assertion. Same thing, three lifecycles.

In the MVP:

A user can upload a CSV file up to 10MB.

In the QA handoff (see examples/frontend-qa-handoff.md):

On this screen, the user must be able to upload a CSV file up to 10MB.

In the test script:

await test('A-UP-03', 'Upload rejects files over 10MB', async () => {
  const res = await postFile('/statements/upload', oversizedFile);
  assertStatus(res, 413);
});

One sentence, no translation loss. This is the cheapest way to keep specs and tests in sync. If the MVP says it, the QA tests it, end of debate.

The Pre-Flight Checklist Pattern

MVP specs describe scope. Phase specs front-load gotchas.

A technical documentation phase spec is a pre-verified execution manual that pattern-matches every corners/patterns the agent will hit. The opener tells the agent what kind of document it's reading:

Pattern-match this file before writing any code for any feature in phases 4, 5, or 6. Every API path, response unwrap, request body field, icon name, and meemaw pattern is pre-verified here against the actual backend source. Do not guess.

The structure of a phase spec:

• Mandatory checklist before every feature — 10–15 boxes the agent must tick

• Verified primitives — icon names, EP constants, response shapes — explicitly marked WRONG vs CORRECT

• Cheat tables for every endpoint mapping URL → service return → frontend unwrap

• Banned patterns with wrong/right code pairs

The example phase spec at examples/phase-spec.md shows an API drift table like this:

This is the spec doing AI-prep work: instead of letting the agent re-derive every endpoint, I front-load the drift map so the agent burns zero cycles on solved problems.

It feels excessive when you're writing it. It pays back massively the first time the next agent reads it and avoids three obvious bugs.

Bugs Become Rules

The atomic operation of the whole system is: every bug shipped to production becomes a rule the next agent must follow.

From a sanitized rules-lessons doc:

### 1. Trace the full response chain before writing any hook

Before writing a hook, trace this exact path: 1. Read the route handler — what does ResponseUtil.ok(res, X) pass? 2. Read the service — what does the method return? 3. Know the envelope: ResponseUtil.ok(res, data) → { data }.

Examples from real mistakes: ts* *// Route: ResponseUtil.ok(res, result) where result = { items, total, page, limit, totalPages }* *// WRONG: r.data.data / r.data.meta.total* *// RIGHT: r.data.items / r.data.total* *

Never assume. Read it.

That // Examples from real mistakes: line is the literal moment a bug becomes a permanent agent-facing rule.

The graduation path:

1. Bug ships

2. Engineer fixes it, writes a one-paragraph entry in the project's rules-lessons.md

3. Every future AI session on that project reads rules-lessons.md before writing code

4. If the same bug pattern shows up in a second project, it graduates to the workspace-level skills/hard-lessons.md

5. Every persona that loads hard-lessons.md (six of them) now knows the pattern

This is the loop that makes the system get harder to break with each cycle. The bugs you've already had become the bugs you don't have anymore.

A full example of a project's rules-lessons file is at examples/rules-lessons.md. The workspace-level version is at skills/hard-lessons.md.

Planning with Opus, Executing with Sonnet

Now to the part most people get wrong: context management.

Long sessions degrade. The model gets confused. Earlier decisions get forgotten. Code drifts from the spec. The agent that started crisp ends up making mistakes that the same model in a fresh session would never make.

My pattern, after a lot of trial and error:

Use the most capable model (Opus, currently 4.7 / 4.8) for planning. Use the fastest competent model (latest Sonnet) for execution.

This isn't a cost-saving move. It's a context-management move.

Planning sessions (Opus)

When I start a new feature or a new phase, I open a fresh session with Opus and ask for three deliverables in sequence:

1. High-level plan — "Here's the MVP spec. What are the modules, the order, the dependencies between them?"

2. Detailed plan — "Let's drill into Module 2. What are the API endpoints, the frontend screens, the data model changes? Where are the gotchas?"

3. Tech docs — "Write the phase spec. Include the API drift table, the icon registry, the banned patterns."

Opus is genuinely better at this kind of work — holding many constraints in mind, sensing where the design will break, asking clarifying questions before producing the plan. The output of these three steps is a set of markdown files (high-level-plan.md, phase-2-spec.md, migration-notes.md) that go into the project's docs folder.

Then I close the session. The plan is the deliverable, not the chat history.

Execution sessions (Sonnet)

For implementation, I open a fresh session with the latest Sonnet and point it at the plan:

"Load personas/backend.md and follow it. Read the skills it lists. Then implement Module 2 per the spec in docs/phase-2-spec.md. The relevant rules-lessons are in docs/rules-lessons.md."

Sonnet executes faster, has plenty of context window for the actual implementation work, and produces clean code when the plan is good. The plan does the heavy thinking; Sonnet does the typing.

Clear context between tasks

The single best practice I've adopted: open a new chat for every task. Not "every feature" — every task.

Re-using the same chat across tasks pollutes the context. The agent remembers the previous task's decisions and applies them to the new one even when they don't transfer. Worse, the agent develops a kind of momentum — it stops re-reading the spec because "we already discussed it" — and starts inventing.

A fresh chat per task feels wasteful. It isn't. The cost of re-loading personas and skills (maybe 30 seconds of agent reading) is trivial next to the cost of the agent making a confused decision in turn 47 of a 60-turn chat because it conflated something from turn 12 with the current task.

Run the quality gates between every workflow

Before I hand control back to a fresh session, I run the project's quality gates myself in the previous one:

pnpm typecheck
pnpm lint
pnpm test --changed
pnpm build

All four must pass. If they don't, the new session starts with a broken baseline, and the agent will spend the first 10 minutes trying to figure out why things are red instead of doing the work I'm asking for.

This is the rule the quality-standards.md skill enforces, and it applies to humans too. Don't hand a broken state to the next agent.

Claude Settings That Actually Matter

A few things in my .claude/settings.json that genuinely move the needle:

Permissions allowlist. Default Claude prompts you to approve every Bash command. After the 200th git status, you stop reading the prompts. I add the read-only commands I run constantly to an allowlist so they don't prompt — ls, find, grep, git status, git log, git diff, cat, pnpm typecheck. The prompts that remain are the ones that actually need attention.

Hooks for automation. Claude Code lets you register hooks that run on specific events — SessionStart, PreToolUse, Stop. I use a Stop hook to play a sound when a long-running task finishes so I can context-switch productively. I use SessionStart hooks for project-specific setup ("if you're in this repo, load this persona automatically").

The hard "never" list in CLAUDE.md. Every project has a CLAUDE.md at the root with project-specific rules the agent reads on every session start. Mine includes things like "never bypass git hooks," "never --force push to main," "always run typecheck before claiming done."

The actual settings.json is project-specific, but the doctrine is in the skills/ and commands/ folders — particularly rules.md which captures the universal workspace rules (pnpm only, workspace:* for internal deps, 7-day npm release age, Node 20+, path aliases only).

Why Grep Beats LLM-Only Review at Scale

Now to the second half of the system: code review.

A typical AI code review pattern is "ask the LLM to read every changed file and find issues." This works for small diffs. It does not scale. At any real codebase size, a reviewer that reads every file end-to-end is slow, expensive, and inconsistent — the same code reviewed on Monday and Friday produces different findings.

My reviewer is multi-axis and runs across three persona lenses (backend, frontend, fullstack QA). Each axis has concrete grep recipes and verbatim violation patterns.

The four axes

Logic & correctness — strict TS, no any, no useEffect + fetch, no as casts, money as bigint only.

Security — every route in asyncHandler, auth middleware on protected routes, no z.any(), no real credentials in CI, refresh token reuse detection tested.

Performance — bundle optimization checks, server/client component boundary checks (Next.js), database index audits, N+1 query patterns, append-only ledger violations.

Consistency — pnpm only, workspace:* for internal deps, 7-day release age on deps, path aliases only, no cross-app imports, no Redux/Zustand, icon proxy enforced.

The grep recipes

For each axis, the QA personas have grep recipes that catch the common violations in seconds. From personas/qa-backend.md:

# Services that throw (must return ServiceResult<T>)
grep -rn "throw new\|throw new Error" src/features/ --include="*.service.ts" \
  | grep -v "//\|AppError\|ValidationError"

# req object passed into service calls (HTTP leaking into business logic)
grep -rn "service\.\(.*\)(req\|\.service\.\(.*\)(.*req" src/features/

# res.json() called directly (bypasses ResponseUtil envelope)
grep -rn "res\.json\|res\.send(" src/features/ | grep -v "ResponseUtil"

# Async route handlers without asyncHandler wrapper
grep -rn "router\.\(get\|post\|put\|patch\|delete\)(.*async" src/features/ \
  | grep -v "asyncHandler"

# any type in Zod schemas
grep -rn "z\.any()" src/

# Money stored as number/float (must be bigint)
grep -rn "amount.*: number\|balance.*: number\|price.*: number" src/

From personas/qa-frontend.md:

# Raw && in JSX (must be <Show when={...}>)
grep -rn "{.*&&" src/features/ --include="*.tsx"

# Raw .map() in JSX (must be <Repeat>)
grep -rn "\.map(" src/features/ --include="*.tsx"

# Direct lucide-react imports (must go through icon proxy)
grep -rn "from 'lucide-react'" src/features/

# Raw hex in Tailwind classNames (must use token classes)
grep -rn "bg-\[#\|text-\[#\|border-\[#" src/features/

Each recipe catches a known class of bug in milliseconds. The LLM is reserved for the 20% — semantic review, cross-file architectural sniff tests, "does this approach make sense given the rest of the codebase?"

The pattern: grep catches the patterns; the LLM catches the meaning. Both, never just one.

The slash commands

Built-in Claude Code commands I use constantly:

• /code-review with an effort dial (low / medium / high / max / ultra). Low and medium produce a small number of high-confidence findings. Ultra runs a multi-agent review in the cloud.

• /code-review --comment posts findings as inline PR comments.

• /simplify — equivalent to /code-review --fix. Applies the findings to the working tree.

• /review — review a pull request.

• /security-review — security review of pending changes on the current branch.

• /verify — verify a change actually works by running the app and observing behavior.

Pre-commit Husky hooks enforce the bare minimum (typecheck, lint, format, test on staged files) before commits land. CI fails if coverage of changed files drops below 80%. The reviewer fires both at PR creation and in the local diff.

MCP: Extending the Agent's Reach

Beyond the personas and skills, I use MCP servers (Model Context Protocol) to give the agent access to systems outside the local filesystem.

The four I rely on:

GitHub / GitLab MCP

Lets the agent read PRs, issues, comments, and commit history directly — without me copy-pasting. The pattern: "Read PR #142 and tell me what's still unresolved in the review thread." The agent fetches the PR, reads every comment, identifies which threads are open vs resolved, and produces a summary. The same thing for issues — "What did we decide about pagination in issue #88?"

This sounds small. It compounds. When the agent can read the surrounding context (the PR description, the linked issue, the review comments) before writing code, the code it writes accounts for the discussion.

Atlassian MCP (Jira, Confluence)

The same pattern, applied to ticket systems. "Read JIRA ticket PROJ-2417 and produce the implementation plan." The agent fetches the ticket, the acceptance criteria, any linked design docs in Confluence, and the comment thread. Then it writes the plan against all of that, not just my one-line summary.

I'm cautious about giving the agent write access to Jira — I prefer to keep the human in the loop on ticket transitions. But read access has been transformative.

Figma MCP

For design-driven work. The agent reads the Figma file, extracts the component structure, the design tokens, the spacing, the variants. Then it implements against the actual design, not against my verbal description of it.

This is especially good for design system work (more in Part 2). Combined with the /ship-design-system slash command, the agent can take a Figma file and translate it into a real React component library with high fidelity. The Figma MCP is what makes "the AI implements the design directly" actually feasible.

Video Watcher MCP

Less famous but genuinely useful. Lets the agent watch a video file (a recording, a tutorial, a Loom walkthrough) and produce a transcript-plus-screenshots summary. The pattern: "Here's a 15-minute Loom walkthrough of the bug. Watch it and tell me what's happening." The agent watches, extracts the relevant frames, transcribes the narration, and produces a description that includes the visual context.

This works for design reviews too — "Watch this Figma prototype recording and tell me the user flow." Massively faster than me writing it up.

What I don't use MCP for

I don't use MCP for things that need to happen at scale or in CI. The MCP servers are for interactive work — augmenting the agent's context with information from external systems. The actual code execution, the actual tests, the actual deploys still happen through the standard local tooling. MCP is a context-extension layer, not an execution layer.

Stitch Design and Claude Design

Two more tools that have changed the design-implementation loop:

Stitch Design (AI design generation)

Stitch is an AI design tool by Google that produces production-grade UI mockups from prompts. The trick is that AI design tools work best when given:

1. Screen-by-screen breakdowns — not full page descriptions

2. Extremely detailed specifications — every element, size, color, position

3. Light mode specifications — always specify light/dark mode

4. Exact measurements — pixel values, percentages, spacing units

The Golden Rule: if you haven't explicitly stated it, the AI will guess — and it will probably guess wrong.

I use Stitch as the front of a chain: prompt Stitch with a detailed brief → get a mockup → feed the mockup into Figma → use the Figma MCP to have Claude implement it. The chain converts "I have an idea for a screen" into shipped React code in an afternoon, with quality that would have taken a week the old way.

Claude Design (the design system commands)

The two slash commands in my repo — /design-system-agent and /ship-design-system — are a clean designer/implementer split:

• /design-system-agent (the designer) — picks a stance from a catalog of 25, runs discovery, builds the HTML spec (scenes + foundation CSS + variations)

• /ship-design-system (the shipper) — translates a finished Studio project into a real React component library inside a target repo

The shipper's hard rule, stated in four places in its system prompt: never invent design — only translate. If the HTML doesn't show a state, the shipper doesn't add one. Don't fight the repo (if existing components use default exports, the shipper uses default exports too).

The full workflow is documented in docs/how-to-use-design-system.md. The second part of this article series goes deeper into the design system pipeline — how the two-agent split keeps design and implementation honest.

The Vercel React Skills and the UI Skills

Two more layers that load on every frontend task:

Vercel React skills

A set of three skills from Vercel that I treat as universal frontend canon:

• vercel-react-best-practices — performance optimization guidelines, ~70 rules across categories like async-, bundle-, server-, client-

• vercel-composition-patterns — React composition patterns that scale (compound components, render props, context providers, React 19 API changes)

• vercel-react-view-transitions — guide for native View Transition API implementations

These are not my skills. Vercel built them. They install via Claude Code's skill system (or symlink into ~/.claude/skills/). Together they give the agent a strong default for "what good React looks like in 2026" without me having to encode it.

UI / Web Design Guidelines skill

A general-purpose UI review skill. Useful for catching accessibility regressions, contrast issues, keyboard navigation gaps, the things that should not ship but routinely do because the developer was looking at the happy path on a 32-inch monitor.

These don't replace my frontend-fsd.md and frontend-guide.md — those are the project-specific rules. The Vercel skills are universal patterns; mine are project-specific conventions. Both load.

What This Architecture Gives Up

Honest accounting, because the system isn't free:

Onboarding overhead. A new engineer copying this scaffolding without my scar tissue will encode the wrong things. The lesson is the practice (bug → rule → spec → next agent inherits it), not the specific files. Copying my files without the discipline is cargo-culting.

Doc drift. Specs go stale. The agent reading a stale spec doesn't know the spec is wrong. I don't have a drift detector yet — a weekly job that re-greps the codebase and flags rule drift would keep the specs honest. It's on my "what I'd build next" list.

Grep recipes are codebase-specific. The recipes in qa-backend.md assume Express + service layer + ResponseUtil envelope. If your stack is different (NestJS, Fastify, Go, Rust), the recipes don't transfer directly — you need to rewrite them for your patterns. The methodology transfers; the specific commands don't.

Cross-project promotion of lessons is manual. When a bug pattern appears in two projects, I have to notice it and lift the rule from project-specific rules-lessons.md to workspace-level hard-lessons.md. There's no automation for this. A monthly "lift recurring lessons" review is on the backlog.

It only works because I've been bitten enough times to know what to encode. The system is the externalised memory of an engineer who has seen the failure modes. A junior engineer running this exact scaffolding will encode their first month's mistakes — which are not the same mistakes the system was designed to catch.

Evaluation

After running this system across the products I ship, three measurable properties:

New project starts faster. The universal skills (hard-lessons, quality-standards, rules, frontend-fsd, backend-service-patterns) are already loaded. The agent doesn't need to be told that money is bigint kobo or that services return ServiceResult<T>. It already knows. First-week velocity on a new project is meaningfully higher.

Recurring bug classes don't recur. The 204 .json() parsing bug, the API drift bug, the req-in-service bug, the optimistic update without rollback bug — these used to appear in every project. They don't anymore. They're in the skill files. The agent reads the skills. The bugs don't get written.

QA agents and dev agents grep against the same rulebook. Handoffs don't require translation. The dev agent was told "services return ServiceResult<T>." The QA agent greps for throw new in service files and files violations. Same rule, different lens.

The Closing Frame

The AI is a recurring contractor on a maturing codebase. Each session inherits the accumulated rule set. Each session contributes new rules back when it finds new failure modes.

The persona is who the contractor is. The skill is how the contractor works. The codebase docs are what the contractor needs to know about this specific project.

When you treat AI like a stranger you have to re-explain everything to, you get vacuum-problem output. When you treat AI like a contractor with a reference library of your team's lessons, you get something different.

The reference library is at github.com/spiderocious/agentic-workflow. Fork it. Edit it. Ignore the parts that don't apply. The files are deliberately small and modular so you can take what fits.

The spec is not documentation. It's the executable working memory of the team.

In Part 2: the QA agents, the design system pipeline, the multi-agent orchestration patterns, the self-built skills like agent-browser and the Demo Director persona, and what I'd build next.

This is the story of building WordShot, a real-time multiplayer word game where players race against time to answer categories using words that start with a randomly selected letter. Think Scattergories, but with 10.2 million words in the database, real-time WebSocket synchronization for 2-8 players, and architecture decisions that seemed obvious until they weren't..

It started simple enough. A word game needs words. Categories like Animals, Cities, Food, Names, the basics. I figured I'd grab some public domain word lists, maybe scrape Wikipedia for place names, and call it a day. A weekend project, tops.

Then I remembered: I'm Nigerian. This game would have Nigerian users. That means Yoruba names like "Ọmọkehinde" and "Adébáyọ̀" should be valid. Igbo names like "Chukwuemeka" and "Nneka" too. I couldn't just use American name databases.

So I started collecting.

The Bible Problem

The game has a "Bible" category for biblical references. Simple, right? Just grab some names from the King James Bible and move on.

Except... how many biblical names are there actually?

First attempt: YouVersion API. Found about 800 common names (Abraham, Moses, David). Felt good about myself.

Second attempt: Seminary documents. Found open-source theological databases. YAML files with genealogies and cross-references. Another 1,200 names (Zerubbabel, Mahershalalhashbaz, yes these are real).

Third attempt: Bible JSON projects on GitHub. Multiple repos with structured Bible data. Different translations had different transliterations. Another 1,000 unique spellings.

I wrote a script that parsed all three sources. Recursively extracted names from nested structures. Deduplicated. Normalized Unicode (Hebrew names have diacritics). Final count: about 3,000 unique biblical names.

The Yoruba Names Challenge

This was harder. There's no "official Yoruba name database." It's an oral tradition, passed down through families. Different regions spell names differently. The romanization isn't standardized.

I needed AI.

I built an iterative script that prompted Claude, OpenAI, and Gemini in rounds. The approach: generate letter combinations (aa, ab, ad, ak...) and ask each AI provider for authentic Yoruba names starting with those letters.

Why this worked:

• Each AI provider has different training data

• Rotating providers gave me diverse results

• Letter combos forced systematic coverage

• Incremental saves meant I didn't lose progress if something failed

I let this run overnight. Next morning: about 12,500 unique Yoruba names.

But I wasn't done. I repeated the process for Igbo names, Hausa names, Swahili names. By the end, I had about 105,000 African names that no American word game would ever have.

The Dictionary Breakdown

I found public domain dictionaries online. Massive 50MB text files with words and definitions. Hundreds of thousands of words. But they weren't categorized. I needed to know: is "aardvark" an animal? Is "abacus" a thing?

I wrote a parser that used definition keywords to categorize. Animal keywords: mammal, bird, reptile, fish, insect. Food keywords: edible, fruit, vegetable, dish. Place keywords: city, town, country, location.

This categorization wasn't perfect. "Apple" could be a food or a company. Context matters. But for a first pass, keyword matching got me about 40,000 categorized words.

The Maps Scraping Mission

For the "Place" and "City" categories, I needed real locations. Not just "Paris" and "London", I wanted "Ogbomoso" and "Enugu" and "Zanzibar”, and even niche places like “Ejigbo”, “Iwo”, or “Ikoyi” etc.

I scraped Google Maps (Places API, 1000 requests/day free tier), Apple Maps (browser automation with Puppeteer), and Wikipedia ("List of cities in [country]" pages).

I ran this for every country on Earth. Took 2 days because rate limiting was brutal. Final count: about 115,000 place names.

The Pipeline

Now I had data from multiple sources:

• Bible: 3,000 names

• African names: 8,000

• Dictionary: 40,000 words

• Maps: 15,000 places

But the formats were all different. Some had uppercase, some lowercase. Some had Unicode, some ASCII. Some had duplicates across sources.

I needed a unified pipeline. The logic: normalize Unicode, lowercase everything, deduplicate by word:category key, validate (minimum length, no special chars), extract first letter, find aliases.

I ran this pipeline. Deduped everything. Validated each entry. Final database size: 10.2 million words across 13 categories.

The Alias Problem (Still Ongoing)

Even with 10.2 million words, there's a problem: spelling variations. "Grey" vs "Gray". "Judgement" vs "Judgment". "Theatre" vs "Theater". UK vs US vs EU spellings.

A player types "Grey" but the database has "Gray." They score zero. That's frustrating.

I built a background cron job that runs nightly. It evaluates words per night. For each word: ask AI providers for aliases, scrape dictionary sites for alternate spellings, use logic for UK/US/EU variations (our vs or, re vs er, ise vs ize).

This job processes words per time. The most common words get evaluated first. The long tail can wait.

The Feedback Loop

There's another spawn job that runs in the background. When a player submits an answer that's marked wrong (not in database), the system queues it for re-evaluation.

The process: ask AI if the word is valid for that category, web scraping for verification, combine signals. If valid, add to database and credit the user (future feature).

This means the database grows over time. Players teach the system. If 10 players submit "Oko" for "City" and it's actually a valid Nigerian city, the system learns. Next player who uses "Oko" gets points.

Why This Matters

The word collection wasn't just data entry. It forced every architectural decision I made afterward:

1. 10.2 million records made database indexes mandatory (queries were 150ms without them)

2. Progressive evaluation made background jobs non-blocking (can't freeze gameplay)

3. Spelling variations made the alias system complex (can't just check exact matches)

4. Multiple sources made the data pipeline critical (can't manually merge formats)

5. Continuous growth made the database design support writes during gameplay

If I'd stopped at 100,000 words, I wouldn't have learned these lessons. The scale forced me to build better systems.

Three weeks of word collection. Ten million words. Every architecture decision afterward was shaped by this foundation.

Feature-Sliced Design (The Decision I Got Right From Day One)

I've built systems that turned into spaghetti. I wasn't doing that again.

Before writing a single line of game logic, I knew three things:

1. The game would have multiple modes (single-player, multiplayer, demo)

2. Features would grow independently

3. Folder-by-type (/components, /hooks, /utils) was a trap I'd fallen into before

I chose Feature-Sliced Design from the start. Not because it was trendy, but because I'd seen what happens without it.

The Traditional Hell

On one of my old project, the structure looked like this: everything in /components, /hooks, /utils, /types. 47 components. 23 hooks. 31 utility files. 18 type files.

What happened:

• Want to understand multiplayer? Grep across 4 folders

• Change one feature? Touch files in every folder

• Onboard a new dev? "Good luck understanding how this all connects"

• Remove a feature? Hope you found every related file

It was chaos. Every feature touched every folder. No clear boundaries.

The FSD Approach

This time, I organized by feature. Each feature owns its complete stack: API calls, state management, UI components, types, routing.

The structure:

src/
├── features/
│   ├── game/           (single-player)
│   ├── multiplayer/    (multiplayer)
│   └── demo/           (walkthrough)
└── shared/             (cross-feature)
    ├── services/
    ├── hooks/
    └── ui/

What this gives me:

Clear feature boundaries. Want to understand single-player? Everything is in features/game/. API calls, state management, UI components, types, routing, all in one place.

Parallel development. I built the demo mode while multiplayer was still in progress. Zero conflicts. They don't share code except for shared/.

Easy deletion. When I considered removing the demo feature, I looked at the features/demo/ folder. That's it. No hunting across the codebase.

Feature-level testing. Each feature can be tested in isolation. Mock the API layer, test the provider, verify the UI.

The Demo Mode That Took 2 Days

The clearest proof that FSD worked: I built the demo mode in 2 days.

What is demo mode? Interactive walkthrough for first-time users. Shows how the game works step-by-step. No API calls, no real gameplay, just guided UI.

Why it was fast: Created features/demo/ folder, copied UI components from features/game/, wrote a simple state machine for the walkthrough, hooked it into routing. Done.

No refactoring. No "how do I isolate this from the main game?" questions. FSD already had the answer: it's a separate feature.

If the codebase was folder-by-type, I'd still be untangling dependencies.

The Rule I Follow

Not everything goes in shared/. There's a rule: if code is used by 2+ features, move it to shared/. Otherwise, keep it in the feature.

Examples moved to shared: Button component (used everywhere), sound service (used everywhere), cache service (used by game and multiplayer).

Examples that stayed in features: roulette screen (only single-player), WebSocket provider (only multiplayer), role encoding (multiplayer-specific).

This prevents premature abstraction. Code starts in a feature. If another feature needs it, then we move it to shared/.

The Minimal State Philosophy

React developers love state. I learned to hate it.

Not because state is bad. But because unnecessary state is a bug waiting to happen.

The Previous Project Where State Killed Me

On my last project, we used Redux. Every feature dumped its state into the global store. Why? "Because we might need it elsewhere."

What happened: 37 action creators, 28 reducers, selectors everywhere. No one knew what was in the store at any given time. Debugging meant logging the entire state tree. Updates triggered re-renders across unrelated components.

The final straw: A dev updated game.currentRound and accidentally broke the notification badge because the badge subscribed to the entire game object, not just game.roundsComplete.

I swore off Redux after that project.

The 10.2M Words Problem

With 10.2 million words in the database, I became paranoid about state.

Question: Should I cache the entire word database in Redux?

Math: 10.2M words × 100 bytes each = 1GB. JavaScript heap limit: 1.5GB. Answer: Hell no.

Question: Should I cache the current round's valid words in state?

Math: Player sees 3-5 categories per round. Each category has about 5,000 valid words. 5 categories × 5,000 words × 100 bytes = 2.5MB. Answer: Maybe, but probably overkill.

Question: Should I cache the player's answers in state?

Math: Player submits 3-5 answers per round. 10 rounds max = 50 answers total. 50 answers × 50 bytes = 2.5KB. Answer: Yes, this makes sense.

The scale forced me to be ruthless about what deserved to be in state.

My Decision Matrix

I made a decision matrix before writing any state management code:

For this project:

• 2 features share state (Game and Multiplayer)

• State transitions are simple (Player answers, Validation, Results)

• No time-travel debugging needed

• No middleware needed

Verdict: Context API wins.

The Three-Layer State Architecture

Layer 1: Global State (Minimal). App-level state: error boundary state, sound preference. That's it.

Layer 2: Feature State (Context API). Each feature has its own provider. GameProvider for single-player. MultiplayerProvider for multiplayer.

Layer 3: Component State (Local UI). Everything else is component-local. Input values, modal visibility, selected tabs. This state doesn't need to be global. It's purely UI concern.

The Multiplayer Multi-Provider Hierarchy

Multiplayer has two providers: WebSocketProvider (connection layer) and MultiplayerProvider (game state layer).

Why two providers?

WebSocketProvider handles low-level connection: socket instance, connection status, reconnection attempts, send message wrapper.

MultiplayerProvider handles game logic: room data, player list, game phase, actions (create room, join room, start game).

Why separate? WebSocket can reconnect without resetting game state. Game state can be manipulated independently of connection status. Testing: Mock WebSocket provider, test game logic in isolation.

What I Keep in State vs What I Don't

What's in state: Current game ID, current round number, player answers, multiplayer room data, WebSocket connection status.

What's NOT in state: Word database (way too big), validation results (fetched once from API), game history (stored in localStorage), sound effects (singleton service), UI animations (Framer Motion).

The Rule: Derive State When Possible

If data can be calculated from existing state, don't store it separately.

Bad: Store currentRound, totalRounds, and isLastRound. Now you have to keep isLastRound in sync.

Good: Store currentRound and totalRounds. Calculate isLastRound = currentRound === totalRounds.

One source of truth. No sync bugs.

The ServiceResult Pattern (Why I Stopped Using Exceptions)

Exceptions made sense until I had to debug them in production at 2 AM.

The problem isn't exceptions themselves. It's that exceptions make your code lie. A function signature says it returns User, but secretly it might throw UserNotFoundError or DatabaseConnectionError or ValidationError. You don't know until it happens.

The Production Bug

Backend code, Node.js + Express. User starts a game. Backend throws LetterSelectionError (couldn't find enough valid letters). Caught by the generic catch block. Returns 500 error. Frontend shows "Internal Server Error."

But it's not a server error. It's a validation error. The user selected incompatible categories. But the generic exception handling made everything a 500.

I had to dig through logs to find the real error. 2 AM. Production down.

The Problem With Exceptions

Hidden control flow. Non-local reasoning. Lost type safety. Boilerplate everywhere.

To understand what a function can fail with, you have to read its entire implementation and every function it calls. TypeScript can't tell you what exceptions a function throws. The type system is blind to error paths.

The ServiceResult Pattern

Every service method returns ServiceResult<T>. It's a discriminated union: either { success: true, data: T } or { success: false, error: string }.

Every caller must check .success. TypeScript enforces this. Try to access .data without checking? Compiler error.

Why this works at scale: With 10.2 million words, errors become common. Player types a word not in database. Player selects rare letter with not enough categories. Player submits too fast and hits rate limit. These aren't exceptional. They're normal operation.

With exceptions, you have to know every possible exception. Miss one, app crashes.

With ServiceResult, all error paths funnel through !result.success. One check. No surprises.

Type Safety Across 50+ WebSocket Events

This pattern extends to WebSocket. Room created response: either { success: true, data: Room } or { success: false, message: string }.

Benefits: Discriminated unions enforce success checks. TypeScript provides autocomplete for both paths. No silent failures.

The Pattern That Looked Verbose But Saved Me

Yes, ServiceResult adds lines of code. Before was 1 line. After is 4 lines.

But here's what I gained:

Every error path is visible. No hidden throws. Compiler enforces error handling. Errors are data, not control flow. Consistent response format across all API endpoints.

Measured impact:

Before ServiceResult: 23 unhandled exceptions in production (first month). 7 of those were user-facing crashes. Average debug time: 45 minutes.

After ServiceResult: 0 unhandled exceptions. 0 user-facing crashes from error handling. Average debug time: 5 minutes.

Database Design: The Denormalization Decision

Normalizing 10.2 million words seemed right. It was 98% slower.

This is the section where I learned that database theory and database reality are different things.

The Naive Approach

Initial schema: just word, category, and aliases. No startsWith field. Calculate it on-the-fly with MongoDB's $substr operator.

Query to validate "Apple" in "Food" starting with "A": use $expr with $substr to check first character.

Performance: Full collection scan (COLLSCAN). 10.2 million documents examined. Query time: about 400ms.

Why so slow? MongoDB can't index computed fields. The $substr expression runs on every document. No way to optimize it.

The Denormalization Decision

I added a startsWith field. Just one extra byte per document. Store the first letter explicitly.

Query becomes simpler: match on word, category, and startsWith.

Performance with compound index: Index scan (IXSCAN). About 89 documents examined (only words starting with 'a' in 'food'). Query time: less than 5ms.

Improvement: 98.75% faster.

The Trade-Off Analysis

Cost of denormalization: Extra field, 1 byte per document. 10.2M documents × 1 byte = 10MB. Disk space: Negligible.

Maintenance cost: One pre-save hook to keep startsWith in sync. 3 lines of code.

Benefit: 98% faster queries. No full collection scans. Scales to billions of words.

Verdict: Worth it.

Compound Index Strategy

I needed two indexes:

Index 1: { startsWith: 1, category: 1 } for answer validation (most common query).

Index 2: { category: 1, startsWith: 1 } for cache building (startup).

Why both orders? MongoDB can only use an index if the query matches the prefix of the index. Without both indexes, one query pattern would be slow.

Measured impact: Validation went from 400ms to 5ms. Cache build went from 800ms to 8ms.

Embedded vs Referenced Documents

Another decision: How to store game sessions?

Option 1: Embedded. Everything in one document. Players, rounds, results, all nested.

Option 2: Referenced. Separate collections. Game session has player IDs pointing to Players collection, round IDs pointing to Rounds collection.

Decision matrix: Embedded wins on query complexity (1 query vs 3+), atomicity (single doc update vs multi-collection transaction), and game summary speed (10ms vs 100ms).

Why embedded won: Self-contained games (4-10 rounds, never more). Document size well below 16MB limit. Single query faster. Atomic updates prevent race conditions. Simpler code.

Document size analysis: Worst case 8 players, 10 rounds, 5 categories per round. About 63KB total. Well within 16MB limit.

The Background Jobs That Never Stop

The word collection ended. The word refinement never will.

The Alias Evaluator

Even with 10.2 million words, the alias problem persists. "Grey" vs "Gray". "Judgement" vs "Judgment". UK vs US vs EU spellings.

I built a background cron job that runs nightly. It evaluates 1,000 words per night. For each word: check AI providers for aliases, web scraping for alternate spellings, logic for spelling variations (our/or, re/er, ise/ize).

The job processes 1,000 words per night. At that rate, it'll take 27 years to evaluate all 10.2 million words. But it's fine. The most common words get evaluated first. The long tail can wait.

The Feedback Loop

There's another spawn job. When a player submits an answer that's marked wrong (not in database), the system queues it for re-evaluation.

Process: Ask AI if the word is valid for that category. Web scraping for verification. Combine signals. If valid, add to database.

This means the database grows over time. Players teach the system. If 10 players submit "Oko" for "City" and it's actually a valid Nigerian city, the system learns it. Next player who uses "Oko" gets points.

The Continuous Improvement Pipeline

These background jobs aren't just cleanup. They're the system learning from real usage. Every failed answer is a signal. Every alias discovered is an improvement. The database isn't static. It evolves.

This is only possible because the architecture supports it. ServiceResult pattern makes errors data. Background jobs are non-blocking. Database design supports concurrent writes during gameplay.

The Patterns That Scaled (And the Ones I Refactored)

Not everything I built on day one survived contact with 10.2 million words.

What Held Up

Feature-Sliced Design: Never had to refactor folder structure. Adding multiplayer didn't break single-player. Demo mode took 2 days.

ServiceResult Pattern: Zero unhandled exceptions in production. Every error path is visible and handled.

Minimal State Philosophy: Never hit memory limits. State management stayed simple even as features grew.

Pre-Computed Caches: Game starts in less than 10ms. Letter selection has 0% failure rate. Cache build takes 3 seconds on startup, saves hours of cumulative query time.

What I Refactored

Initial letter selection: Had 2% failure rate. Users couldn't start games. Fixed with pre-validation during selection. Now 0% failures.

Validation flow: Was 150ms per query. Users waited too long. Added compound indexes and two-tier caching. Now less than 5ms.

Room cleanup: Memory leaked 400% daily. Abandoned rooms stayed in cache forever. Added periodic cleanup job and TTL. Now memory stays stable.

What I'd Do Differently

Start with Redis instead of in-memory cache. In-memory cache means single-server deployment. Can't scale horizontally. Redis would allow multi-server setup.

Build admin panel for word moderation earlier. Right now, adding/removing words requires database access. Admin panel would let non-technical team members curate the database.

Test on Nigerian mobile networks from day one. I built on fast Wi-Fi. Real users on MTN 3G had different experience. The three-layer reconnection strategy came from this pain.

The Numbers

Let's be honest about what this architecture achieved.

Performance gains:

• Game start: 300ms to less than 10ms (97% faster)

• Answer validation: 150ms to less than 5ms (97% faster)

• API throughput: 5x increase (400% improvement)

• Memory usage: 35% reduction

• Game failures: 2% to 0% (100% elimination)

Code quality:

• TypeScript coverage: 100% (zero JavaScript files)

• Type safety: Zero any types in source code

• Feature isolation: 3 independent feature folders

• State layers: 3 distinct layers (global, feature, component)

User experience:

• Reconnection success rate: 98% on mobile

• Session recovery: 95% (5% edge cases like cleared storage)

• Error rate: Less than 1% of game sessions encounter errors

The Honest Conclusion

10.2 million words taught me something: scale isn't just about performance. It's about architecture that doesn't collapse when your database grows 100x larger than you planned. It's about minimal state when your data is massive. It's about patterns that assume things will break, so they're built to handle it.

I didn't plan to collect 10.2 million words. But the architecture decisions I made, Feature-Sliced Design, minimal state, ServiceResult pattern, database denormalization, they're the reason the game still works when a player types "Ọmọkehinde" and the system finds it in 4ms, validates it against UK/US/EU spellings, checks aliases, and returns whether it's rare or common.

The word collection was a three-week obsession. The architecture is the reason it didn't become a three-month refactor.

That's the real lesson: Good architecture isn't about planning for scale. It's about making decisions that work at small scale and don't break at large scale. Feature-Sliced Design works with 3 features or 30. ServiceResult works with 10 errors or 10,000. Minimal state works with 100KB of data or 1GB.

The patterns that scale are the patterns that start simple and stay simple as complexity grows. Not because they're clever, but because they refuse to be clever. They just work.

Tech Stack:

• Frontend: React 18, TypeScript 5.6, Vite 6, Tailwind CSS

• Backend: Node.js 18, Express, TypeScript

• Database: MongoDB with Mongoose

• Real-Time: Socket.IO

• Performance: NodeCache, compound indexes, write-behind caching

Metrics:

• 10.2 million words across 13 categories

• 97% performance improvement (300ms to 10ms)

• 98% session recovery rate on mobile

• 0% game initialization failures

• 15,000 lines of code, 3 months part-time

The game works. The architecture held up. The words keep growing. And I learned that sometimes the best architecture decision is the one that lets you obsess over word collection for three weeks without breaking everything else.

Picture this: you're working on a large frontend platform. Multiple teams. Multiple apps. Each team owns their microfrontend slice of the product, deploys it independently, and has the autonomy to make technical decisions within their boundary. It's the microfrontend dream.

Then a user logs in through the shell application. The auth token is refreshed. Three independent micro-apps each running in their own React context, each with their own memory — still hold the old token. One makes an API call. Gets a 401. Shows the user an error they don't understand.

The auth state changed. Nobody was notified. The failure was silent, intermittent, and incredibly annoying to reproduce.

This is not a hypothetical. It's the specific problem that led me to build Connectic.

Let's get cracking,

The Problem with Independent Frontends

Microfrontends solve a real organisational problem: they let large teams work independently on different parts of a product without constant coordination overhead. Each team owns their code, their deployments, their technical choices. The product composes them at runtime.

The catch is that these independent apps still need to share state. They share the user's authentication context. They share user preferences (theme, language, notifications). They share data that one app produces and another needs to display. In a monolith, this is straightforward — everything is in the same memory. In a microfrontend architecture, the memory boundaries are real.

The three naive solutions all have serious problems at scale:

window.postMessage

postMessage works for one-way broadcasts between frames. But there's no contract — you're passing strings or serialized objects with no type safety. If team A changes the shape of a user:updated message, team B's handler silently receives the wrong shape and does something unexpected. The only way to catch it is to have a human who knows about both sides.

At small scale (two apps, one team), this is manageable. At medium scale (eight apps, three teams, rotating engineers), it becomes a source of production bugs that are difficult to attribute.

localStorage with polling

Reading a shared value from localStorage and polling it on an interval. It works. The problems: polling intervals are either too long (stale state for N seconds) or too short (unnecessary CPU and battery drain, especially on mobile). Updates don't propagate instantly — they propagate at the next poll tick. And polling across many components multiplies the overhead.

Custom browser events

document.dispatchEvent(new CustomEvent('auth:updated', { detail: user })) — better than postMessage, but still one-way. There's no request/response primitive. There's no way to ask a question and wait for an answer. If the auth app that holds the canonical user state is slow to initialize and a consumer fires before it's ready, the event is lost with no recovery mechanism.

What Connectic Provides

Connectic is a framework-agnostic communication library for microfrontend architectures. It runs on window.__connectic as a shared coordination singleton — any script loaded on the page can access it, regardless of framework, build tool, or deployment strategy.

Three primitives:

Pub/sub — event-based communication for fire-and-forget notifications
Reactive state — shared state with real-time synchronisation across boundaries Request/response — ask/answer with caching and late-binding support

What makes Connectic useful is that they're implemented together, with a type-safe API, in a way that handles the lifecycle edge cases (late initialization, message replay, provider registration timing) that the naive alternatives don't.

Pub/Sub

// In the auth app — emit after token refresh
connectic.publish('auth:token-refreshed', { token: newToken, expiresAt });

// In any other app — react to the refresh
connectic.subscribe('auth:token-refreshed', ({ token, expiresAt }) => {
  apiClient.setAuthToken(token);
});

The contract is the event name and the payload shape. Both sides agree on what auth:token-refreshed carries. A TypeScript definition shared via a @your-product/events package makes this contractual — the compiler catches shape mismatches before they reach production.

Reactive State

Pub/sub works for events. But some shared values need to be readable at any time, not just when an event fires. A new micro-app initializing doesn't know what events have already fired. It needs to read the current state.

// Auth app sets user state after login
connectic.setState<User>('user', { id, name, role, hospitalId });

// Any app reads current user state on mount
const user = connectic.getState<User>('user');

// Any app subscribes to future changes
connectic.watchState<User>('user', (updatedUser) => {
  updateLocalContext(updatedUser);
});

getState returns the current value synchronously — no wait, no subscription needed if you just want to read the value once. watchState subscribes to subsequent changes. An app that initializes after the state was set can call getState and get the current value immediately.

This eliminates the timing race that plagues event-only architectures: "did I miss the login event because my app loaded after auth already completed?"

Request/Response with Caching

Sometimes a micro-app needs data that another app owns, on-demand. "What are the current user's permissions?" — the permissions are owned by the auth app, but any app might need to check them.

// Auth app registers as the provider
connectic.provide('user:permissions', async () => {
  return fetchCurrentUserPermissions();
});

// Any app requests on-demand
const permissions = await connectic.request<Permission[]>('user:permissions');

The response is cached with a configurable TTL. The second app to call connectic.request('user:permissions') within the cache window gets the cached result without triggering another fetch. This is the pattern that eliminates the "every micro-app calls /me on mount" problem — the user data is fetched once by the app that owns it, and subsequent requests are served from cache.

The Lifecycle Edge Cases

The primitives described above are straightforward. The engineering work is in the edge cases, the situations that only appear in production with real timing.

Late Initialization

A micro-app that subscribes to auth:token-refreshed might initialize after the auth app has already fired that event. In a naive pub/sub system, the subscription is registered too late and the event is missed permanently.

Connectic uses a brief replay buffer for pub/sub events: events fired within the last N milliseconds are replayed to new subscribers. The window is short enough to avoid replaying stale data, and long enough to cover the typical initialization timing gap between apps loaded from a CDN on the same page.

For reactive state, this isn't needed, getState always returns the current value regardless of when the subscriber joined.

Provider Not Yet Ready

For request/response, the provider might not be registered when the first consumer calls connectic.request. The consumer shouldn't fail, it should wait.

connectic.request returns a Promise that resolves when a provider registers and responds. If the provider is already registered, it resolves immediately. If not, the Promise queues the request and resolves when the provider comes online. This makes initialization order irrelevant: consumers can safely call request before providers are ready.

This has a failure case: if the provider never registers (because the auth app crashed, or wasn't loaded), the Promise hangs. Connectic uses a configurable timeout — after N seconds without a provider response, the Promise rejects with a ProviderTimeoutError. The consumer handles this as an outage, not a hang.

Cleanup

Subscriptions and providers must be cleaned up when a micro-app unmounts. A subscription that's never removed will receive events after the subscribing component is gone — in React, this produces the classic "setState on unmounted component" warning. In worse cases, it leaks memory.

Connectic returns cleanup functions from subscribe and provide. In React, this pairs directly with useEffect return values:

useEffect(() => {
  const unsub = connectic.subscribe('auth:token-refreshed', handleTokenRefresh);
  return unsub; // cleanup on unmount
}, []);

The Type Safety Strategy

Cross-app communication without type safety is a liability. The contract between apps is implicit — a developer changing the shape of an event payload doesn't know who's consuming it or whether their change breaks anything.

Connectic's type system works through generics: connectic.publish<T>(event, payload), connectic.request<T>(key), connectic.getState<T>(key). The types are specified at the call site.

The stronger pattern is a shared event catalogue. A @your-product/connectic-types package defines the event names and their payload types:

// @your-product/connectic-types
export interface ConnecticEvents {
  'auth:token-refreshed': { token: string; expiresAt: number };
  'auth:logged-out': { reason: 'timeout' | 'manual' };
  'user:preferences-updated': { theme: 'light' | 'dark'; language: string };
}

export interface ConnecticState {
  user: User | null;
  theme: 'light' | 'dark';
}

Every app that publishes or subscribes imports from this package. Shape changes require a package version bump. Consumers that haven't updated to the new types get TypeScript errors pointing exactly to the changed call sites.

This doesn't fully solve the deployment coordination problem (two apps running different versions of the type package won't catch mismatches at runtime), but it catches mismatches at build time within a CI pipeline that builds all apps together.

Trade-offs

window.__connectic is a global. This is a deliberate choice, it's what makes framework-agnostic communication possible without a shared bundler. The cost: any script on the page can read or write to Connectic's state. This is the same trust model as localStorage or window.postMessage, and it requires the same kind of defense: validate your inputs, don't put secrets in shared state, treat cross-app data as coming from an untrusted source just as you'd treat any cross-origin message.

In-memory state is not durable. A page reload clears Connectic's reactive state. If a micro-app needs to preserve state across page loads, it should persist to localStorage or sessionStorage and hydrate Connectic state from there on initialization. Connectic is a communication bus, not a storage layer.

The pub/sub replay buffer can produce stale re-deliveries. If an event is fired, and a slow-loading app subscribes within the replay window, it will receive the event. This is usually desirable. In cases where the event is "user clicked confirm on this destructive action," replaying to a late subscriber could cause an unintended second effect. The solution is to design events that are idempotent — receiving the same event twice should produce the same result as receiving it once. This is a general distributed systems principle, not a Connectic-specific issue, but it's worth internalizing when designing your event catalogue.

Per-process circuit breakers don't survive horizontal scale. Wait, wrong article. But the in-memory nature of Connectic state is the analogous concern: on a server-rendered microfrontend architecture (where apps are rendered server-side and composed), Connectic's client-side state model doesn't apply cleanly. It's designed for client-side rendered or hydrated microfrontends, not server-rendered shell/fragment compositions.

The request/response pattern is point-to-point, not broadcast. connectic.request('user:permissions') calls the registered provider. If two apps register as providers for the same key (a misconfiguration), Connectic uses the last-registered provider. There's no multi-provider fanout or consensus model — which is intentional simplicity, but it means you need clear conventions about which app owns which request key.

When You Don't Need This

A word on over-engineering, because it's the more common failure mode:

If your "microfrontends" are feature folders in a single Vite project that share the same build output, you don't have cross-boundary communication needs. You have a folder structure problem. The previous article in this series (FSD) handles that case.

Connectic makes sense when:

• Multiple apps are deployed independently with separate CI pipelines

• Different teams own different apps and may be running different framework versions

• The apps genuinely run as separate JavaScript bundles on the same page

• You've been bitten by the auth token / stale state problem described in the opening

If you're not in that situation, a shared React context or a Redux store is the right tool. Connectic is the right tool for genuine cross-bundle, cross-team state coordination — not as a replacement for state management inside a single app.

Evaluation

Connectic has been used in production microfrontend setups across several applications. The properties it provides:

Team independence — Teams can publish events and register state keys without coordinating with every other team. The contract is the event catalogue. Nothing else requires coordination.

Late-binding correctness — Apps that initialize in any order still receive current state and queued requests. Initialization timing is not a source of bugs.

Observable communication — Because all communication flows through window.__connectic, it's possible to instrument it centrally. A connectic.debug() mode logs all published events, state changes, and request/response cycles to the console. Debugging cross-app state issues becomes a matter of opening DevTools, not adding console.log to five different repos.

Framework agnosticism — A Vue app and a React app on the same page communicate through the same Connectic instance without either knowing what framework the other is using. This is the property that module federation and import maps can struggle to provide cleanly.

The Honest Conclusion

Microfrontend state coordination is one of those problems that's easy to underestimate until you've been burned by it. The naive solutions (postMessage, localStorage polling, custom events) each work for simple cases and each fail in specific ways as the number of apps and teams grows.

Connectic exists because I needed the pub/sub + reactive state + request/response combination to work reliably with proper lifecycle handling, in a framework-agnostic way, without requiring all teams to use the same build toolchain.

The 3,000+ npm downloads suggest other people needed the same thing. If you're in the same situation, it's on npm and open source. If you're not, don't add it to a project that doesn't need it.

Use the simplest tool that solves the actual problem. Add complexity when the simpler tool fails.

Note: This article is based on my presentation at DevFest Ibadan 2025, hosted by Google Developer Group Ibadan on November 1, 2025, What started as a 45-minute talk about challenging our framework-first assumptions has been expanded here with additional examples, deeper technical explanations, and code you can actually run. If you were in the audience that day, thank you for the great questions. If you weren't, welcome to the conversation.

But what if I told you that for a significant portion of what we build, we're shipping 120KB of abstraction to solve problems we don't actually have?

Let me be clear upfront: This isn't an anti-framework rant. React, Vue, and Angular exist for excellent reasons, and we'll talk about those reasons honestly. But the pendulum has swung so far toward "framework-first" thinking that we've forgotten to ask a simple question: Do I actually need this?

Today, we're challenging that default assumption. We'll compare vanilla JavaScript and React side-by-side, peek under the hood at what frameworks actually do, and most importantly, learn when each tool makes sense.

And if you're in Nigeria (or anywhere with expensive data and unreliable internet), this conversation isn't academic. Every kilobyte you ship costs your users money and patience.

Let's dig in.

What is "Vanilla" JavaScript Anyway?

The first time I heard "vanilla JavaScript," I was genuinely confused. Is this a different language? A library I missed?

Think of vanilla ice cream. It's the base flavor, no toppings, no mix-ins, just pure ice cream. Other flavors are built on top of it:

• Chocolate = Vanilla + Cocoa

• Strawberry = Vanilla + Strawberries

• Mint Chip = Vanilla + Mint + Chocolate chips

Vanilla JavaScript = JavaScript without any additions. No React. No Vue. No frameworks, no libraries. Just the language as it exists in the browser.

A quick history note: JavaScript was created by Brendan Eich at Netscape in 1995, reportedly in just 10 days. It was originally called Mocha, then LiveScript, before becoming JavaScript. The problem it solved was simple but crucial: websites needed interactivity without full page reloads. Before JavaScript, every filter, every form submission, every tiny interaction required a server round-trip.

JavaScript has three parts:

1. The Language: Syntax, operators, data types, functions, objects, classes

2. The Runtime APIs: Browser APIs (DOM, Fetch, localStorage) or Node.js APIs (fs, http, process)

3. The Ecosystem: npm packages, build tools, developer tools, community

When we talk about "Vanilla JavaScript," we're talking about using parts 1 and 2 without adding layers from part 3.

The Golden Age Before Frameworks

Before React arrived in 2013 (public release in 2015), and before Angular came even earlier, building with vanilla JavaScript had some genuinely beautiful qualities:

1. Tiny Footprint

You didn't need to import anything. Write HTML, add a <script> tag, start coding. Zero bytes of dependencies.

2. Zero Build Time

No webpack. No Babel. No "waiting for the build to finish." You wrote code, hit refresh, and saw results instantly.

3. Simple Deployment

Remember those hosting platforms where you just upload a ZIP file? You'd create index.html, link your CSS and JS files, upload everything, and you were done. No build servers, no CI/CD pipelines, no deployment configurations.

4. No Framework/Vendor Lock-In

Your code was yours. If a new tool came along, you could adopt it gradually. You weren't married to React's release schedule or Vue's breaking changes.

5. Lightweight Dev Environment

These days, dev servers can take 10 minutes to reload on large React apps. You make a change, go get water, come back, and maybe it's finished recompiling. With vanilla JS? Instant feedback. Change file, refresh browser, done.

This sounds like paradise, right?

Why Frameworks Won (And Why That Made Sense)

Frameworks didn't take over because developers are sheep who follow trends. They took over because they solved real, painful problems:

1. Cross-Browser Nightmare

Different browsers implemented JavaScript features differently. Getting user location? Different APIs. CSS animations? Special code for Internet Explorer. Event handling? Safari did it differently than Chrome. You'd write one version for modern browsers, another for IE, and pray it worked on mobile.

Frameworks with bundlers like webpack and Babel would transpile your code to work everywhere. Write once, run anywhere.

2. Manual DOM Hell

Let's say you're building a counter. In vanilla JS, you had to:

function increment() {
    count++;  // Data changed
    document.getElementById('display').innerHTML = count;  // Manually update UI
    document.getElementById('badge').innerHTML = count;    // Manually update UI again
    document.getElementById('sidebar').innerHTML = count;  // And again...
    document.getElementById('btn').disabled = count >= 10; // Don't forget this one!
    // Easy to forget one. Bugs everywhere.
}

Every single place that displays the count needs manual updating. Miss one? Your UI desyncs from your data. This is tedious and error-prone.

3. Harder Reusability / More Complexity for Reuse

Want to reuse a component? In vanilla JS, you'd have to manually structure functions, manage HTML templates, handle initialization. There was no standard component model.

4. State Chaos - Global Variables and Collisions

You'd import different script files, and if two scripts happened to use the same variable name, you were in trouble. No encapsulation meant collision risks everywhere.

React components are enclosed. Everything you define inside a component stays inside it.

5. Untestable Code - Tightly Coupled, Harder to Maintain

Look at this code:

document.getElementById('balance').textContent = patricia.getWalletBalance();

This is tightly coupled to both the HTML (via that specific ID) and the Patricia API. If Patricia shuts down tomorrow (like they did recently), you have to find every single line that references Patricia. If someone changes that balance ID in the HTML, this breaks silently.

Better practice? Write a facade:

function getWalletBalance() {
    return patricia.getWalletBalance();  // Can easily swap to Flutterwave
}

But vanilla JS didn't enforce these patterns. Frameworks did.

What React/Vue/Angular Actually Gave Us

Frameworks earned their dominance by providing five critical improvements:

1. Component Reusability

Write a button component once, use it everywhere. Clear, modular, maintainable.

2. Declarative UI

Instead of saying "find this element, change its text, update this other element," you say "when count is 5, the UI looks like this." You describe what should be rendered, not how to update it.

3. Reactive Data Binding

Change the data, UI updates automatically. No manual syncing.

4. Rich Ecosystems

Thousands of libraries, established patterns, battle-tested solutions. Need routing? There's a library. Need state management? Multiple options.

5. Team Alignment

Everyone knows React. Hiring is easier. Onboarding is faster. "Let's build this in React" is a no-brainer for team coordination.

These are real benefits. Frameworks won for good reasons.

But Everything Has a Cost

Here's the part we don't talk about enough. When you choose a framework, you're not just gaining features. You're accepting trade-offs. And it's not just you as a developer who pays, your users, your team, and your company all bear the costs.

The Trade-offs We Accepted:

1. Bundle Size Bloat
That simple counter app? If you build it with React, you're shipping ~50-120KB of React library code just to count clicks. For users on slow networks or expensive data plans, that's pain.

2. Build Complexity
Most frameworks needs to be compiled, transpiled, bundled. Every change requires a build step, except you use the CDN versions (Content delivery network)

3. Framework Lock-In
If React is sunsetted tomorrow, you're in trouble. Companies literally pay framework maintainers to keep building because they know if development stops, their apps are stuck. Facebook gave React $1.5-2.5 million recently to ensure continued development.

4. Abstraction Layers
React hides how the DOM actually works. If you only know React, you don't know getElementById vs querySelector performance differences, or which DOM APIs are fast vs slow.

5. Easier to "Mess Things Up"
With React, you start importing libraries for everything. Form validation? Import a library. State management? Import Redux. Before you know it, you have 47 dependencies to do things that are built into the browser.

I once saw an engineer spend two days trying to pause background audio when users scrolled away in a TikTok-style app. He was managing Redux state, tracking which audios were playing, dispatching pause actions...

The vanilla solution? document.querySelectorAll('audio').forEach(audio => audio.pause()). Done.

6. Long-Running Servers
With Server-Side Rendering (SSR), Static Site Generation (SSG), and other modern framework features, you now need servers that actively process requests. This is different from just serving static HTML files. Your hosting costs go up.

7. Hosting/Cloud Costs
SSR, incremental regeneration, edge functions, all these cost money. Vercel, Netlify, and others make their money here.

8. Time
Every library you add increases load time. For users in poor network coverage areas, this isn't theoretical—it's the difference between your app loading or not.

9. Trickle-Down Panic When Things Go Wrong
Remember the npm supply chain attacks a few months ago? Libraries got hacked, scripts started reading .env files and uploading secrets to remote servers. If you're using vanilla HTML and CSS, you're not running npm install and you wouldn't have been affected.

Axios had a security vulnerability six months ago that could let attackers manipulate API requests. If you're on an old version and don't know, you're exposed.

10. Cognitive Complexity for New Engineers
You just learned JavaScript. Variables return strings, numbers, functions. Now someone shows you React and you see return <div>Hello</div>. Wait, we're returning HTML? And why is it className instead of class? There's a learning curve just to understand the abstractions.

Feature Showdown: Reactivity & State

Let's get concrete. I'm going to show you the same app built two ways, and we'll compare them across eight dimensions.

The Challenge

Build a car counter app. You're standing by a roadside counting BMWs and Mercedes-Benz cars that pass by. The app needs:

• A button for BMW (increments BMW count)

• A button for Benz (increments Benz count)

• Display total count (sum of both)

• All displays update automatically

Simple, right? Let's see both approaches.

The Vanilla JS Approach

let benzCount = 0;
let totalCount = 0;

function incrementBenzCount() {
    benzCount++;  // Data changed...
    totalCount++; // Another data changed...
    document.querySelector('.benz-count').textContent = benzCount;  // But we manually update UI
    document.querySelector('.total-count').textContent = totalCount;
    // Imagine doing this everywhere...
}

What happens:

1. Increment the benzCount variable

2. Increment the totalCount variable

3. Find the .benz-count element in the DOM

4. Update its text content

5. Find the .total-count element in the DOM

6. Update its text content

Four lines of code inside the function, two variables declared outside. And this is just for one button. The BMW button needs the same treatment.

You can wrap the querySelector calls in a helper function to reduce repetition:

function updateContent(selector, value) {
    document.querySelector(selector).textContent = value;
}

function incrementBenzCount() {
    benzCount++;
    totalCount++;
    updateContent('.benz-count', benzCount);
    updateContent('.total-count', totalCount);
}

Slightly cleaner, but still the same four lines of logic.

The React Approach

const [benzCount, setBenzCount] = useState(0);
const [bmwCount, setBmwCount] = useState(0);
const totalCount = benzCount + bmwCount;  // Derive data automatically

function incrementBenzCount() {
    setBenzCount(benzCount + 1);  // Just update data
}

What happens:

1. Call setBenzCount(benzCount + 1)

2. React handles everything else—UI updates automatically

Notice something crucial: totalCount isn't a separate state. It's derived state, calculated from other state. This is a React best practice. Don't create redundant state; derive it.

Deep Dive: The 8 Dimensions of Comparison

Let's analyze these two approaches across multiple dimensions.

1. Declarative vs Imperative

React (Declarative):

const totalCount = benzCount + bmwCount;  // Declare relationship once
// UI automatically updates when dependencies change. You describe WHAT, not HOW.

Vanilla (Imperative):

benzCount++;
updateContent('.benz-count', benzCount);  // Manual sync
// You explicitly tell the DOM what to do, every single time. Easy to forget steps.

React lets you declare "total count equals the sum of these two values," and it handles keeping the UI in sync. Vanilla requires you to manually execute the sync steps each time.

2. Cognitive Load

React: Lower
You think about state, not DOM manipulation. Mental model = "data flows down." Change the data, React handles the rest.

Vanilla: Higher
You must remember: (1) update variable, (2) find DOM node, (3) update it. Three-step process for every change. Easy to desync if you miss a step.

3. Bug Probability

In programming, more code = more potential bugs. If you write 10 lines, you can introduce up to 10 bugs (one per line). If you write 100 lines, up to 100 bugs.

React:
Fewer steps = fewer bugs. You change state, React handles rendering.

Vanilla:
More steps = more opportunities for errors. Forgot to update one display? Typo in a selector? Wrong element ID? Each is a potential bug.

4. Memory Footprint

React:
~50-120KB (gzipped) for the React library
Virtual DOM (~3x actual DOM size in memory)
Heavy upfront cost

Vanilla:
~0KB overhead. Just your variables. The JavaScript engine is already in the browser—you don't import anything.

The catch: For small apps (<10KB), React's overhead is significant. For large apps (>5MB), React's 120KB becomes negligible as a percentage of total size.

5. Execution Speed (Runtime)

React:
Slower per update. State change → diffing algorithm → batch updates → DOM patch = ~1-5ms per update cycle.

Vanilla:
Faster per update. Direct DOM manipulation = ~0.1ms per update.

The catch: For 1-100 updates, the difference is negligible. For 10,000 updates/second (like a data visualization or game), vanilla wins.

6. What Happens Behind The Hood

React:

1. Triggers re-render

2. React diffs the Virtual DOM against the previous version

3. Batches changes together

4. Updates only the changed DOM nodes

5. Calls useEffect hooks

Vanilla JS:

1. querySelector finds the node

2. Sets textContent directly

3. Done

React does more work, but that work provides benefits: batching prevents multiple repaints, diffing ensures minimal DOM changes.

7. State Consistency

React:
Single source of truth. The state (benzCount) is the source of truth. UI always matches state (eventually). Impossible to desync.

Vanilla:
Dual sources of truth. Is the truth the benzCount variable? Or the DOM? Or both? If you update the variable but forget to update the DOM, they're out of sync.

8. Memory Leaks

React:
Rare. Cleanup happens automatically when components unmount (unless you misuse useEffect by forgetting to return a cleanup function).

Vanilla:
Common. Forgot to remove an event listener? Memory leak. You declared a variable and attached an event listener:

const name = "feranmi";  // Compilation assigns memory block "1101"
document.addEventListener('click', handler);  // Assigns another memory block
// If you never remove this listener, the memory stays occupied forever

When JavaScript compiles your code, it assigns memory addresses to variables. Let's say name gets memory address 1101. That address is marked as "occupied" and stores the value "feranmi".

If you never clean up (by removing event listeners or clearing variables), those memory blocks stay occupied even after you're done with them. The browser's garbage collector can't reclaim them because they're still referenced.

React manages this automatically. When a component unmounts, React cleans up event listeners and state. With vanilla JS, you're responsible for cleanup.

But Wait—You CAN Do Reactivity in Vanilla

Everything I just showed you about React's reactivity? You can build it yourself in vanilla JavaScript in about 10 lines of code.

Meet JavaScript Proxies.

Building Your Own useState

// 1. Create reactive state
function createReactiveState(initialState, callback) {
    return new Proxy(initialState, {
        set(target, property, value) {
            target[property] = value;
            callback();  // Notify on change
            return true;
        }
    });
}

// 2. Use it
const state = createReactiveState(
    { count: 0 },
    () => render()
);

// 3. Render function (template literal)
function render() {
    const { count } = state;
    document.querySelector('#app').innerHTML = `
        <p>Count: ${count}</p>
        <p>Double: ${count * 2}</p>
        <p>Status: ${count > 5 ? 'High' : 'Low'}</p>
        <button onclick="state.count++">+</button>
    `;
}

// Initial render
render();

What happens:

1. State Proxy: Wraps your state object in a Proxy that intercepts changes

2. Usage: When you do state.count++, the Proxy's set trap fires

3. Trigger Rendering: The callback (render()) is called automatically

You've just built React's useState in vanilla JavaScript.

Important Caveat

This isn't production-ready. To truly replicate React, you'd need to add:

• Batching updates (React doesn't re-render 10 times if you change 10 state values; it batches them)

• Diffing algorithm (React only updates changed DOM nodes, not the entire tree)

• Lifecycle hooks (equivalent to useEffect)

• Memory leak prevention (cleanup when components unmount)

But the core concept? You just built it. React isn't magic, it's JavaScript using browser APIs cleverly.

Feature Showdown: Components & Reusability

One of the biggest selling points for frameworks is component reusability. Let's see how both approaches handle this.

The Challenge

Build a <ProductCard> component that displays:

• Product image

• Product name

• Product price

• "Add to Cart" button

The React Way

function ProductCard({ product, onAddToCart }) {
    return (
        <div className="product-card">
            <img src={product.image} alt={product.name} />
            <h3>{product.name}</h3>
            <p className="price">${product.price}</p>
            <button onClick={() => onAddToCart(product)}>
                Add to Cart
            </button>
        </div>
    );
}

// Usage
<ProductCard product={product} onAddToCart={handleAdd} />

Clean, familiar, composable. This only works in React.

The Web Components Way

class ProductCard extends HTMLElement {
    connectedCallback() {
        const product = JSON.parse(this.getAttribute('product'));

        this.innerHTML = `
            <div class="product-card">
                <img src="${product.image}" alt="${product.name}" />
                <h3>${product.name}</h3>
                <p class="price">$${product.price}</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
        `;

        this.querySelector('.add-to-cart').addEventListener('click', () => {
            this.dispatchEvent(new CustomEvent('add-to-cart', {
                detail: product
            }));
        });
    }
}

// Register the component
customElements.define('product-card', ProductCard);

Usage:

<product-card product='{"name":"Phone","price":299,"image":"..."}'></product-card>

<script>
    document.querySelector('product-card')
        .addEventListener('add-to-cart', (e) => {
            console.log('Added:', e.detail);
        });
</script>

What Are Web Components?

Web Components are a set of web platform APIs that let you create new custom, reusable, and encapsulated HTML tags for use in web pages and web applications.

They're based on existing web standards and work across modern browsers, offering a way to extend HTML with new elements that have custom behavior and encapsulated styling.

Key features:

• Custom HTML tags like <product-card>

• Shadow DOM for style encapsulation (styles don't leak out, outside styles don't leak in)

• Works everywhere: React, Vue, Angular, or vanilla JS

• Zero dependencies (browser built-in)

• Perfect for design systems & micro-frontends

The Advantage

React components only work in React.

Web Components work everywhere.

Let's say you're building a design system for a company that has multiple teams using different frameworks. Team A uses React. Team B uses Vue. Team C uses Angular.

If you build components in React, you need to maintain three separate versions. Every time you update a button style, you update it in three places.

If you build with Web Components, you write it once. All teams import the same component. When React 19 comes out with breaking changes, your Web Components still work. When Vue 4 launches, your components still work.

You're not locked to any framework's release schedule.

Feature Showdown: Client-Side Routing

Frameworks like react-router, vue-router, and angular-router make routing seem like magic. But what are they actually doing?

How Framework Routers Work

1. Listen for the popstate event (fires when URL changes via back/forward buttons)

2. Check the routes list (map of paths to components)

3. Render the correct component for the current path

4. Cleanup and wait for the next route change

That's it. The "magic" is just event listeners and conditional rendering.

How to Implement Your Own Router

// 1. Define routes
const routes = {
    '/': renderProductsPage,
    '/cart': renderCartPage,
};

// 2. Router handler
function router() {
    const path = window.location.pathname;
    const render = routes[path] || render404;
    render();
}

// 3. Navigate utility
function navigate(path) {
    history.pushState(null, null, path);
    router();
}

// 4. Handle back/forward
window.addEventListener('popstate', router);

// 5. Intercept clicks
document.addEventListener('click', (e) => {
    if (e.target.matches('a[href^="/"]')) {
        e.preventDefault();
        navigate(e.target.getAttribute('href'));
    }
});

// Initial render
router();

What happens:

1. Routes definition: Map paths to render functions

2. Router handler: Looks at current URL, calls appropriate render function

3. Navigate utility: Programmatically change routes via history.pushState()

4. popstate listener: Handles back/forward button clicks

5. Click interceptor: Catches link clicks and uses navigate() instead of full page reload

You've just built client-side routing in ~20 lines.

Why It's Called "Client-Side"

Routing used to be a server thing. If you visited /products, the server returned a products page. If you visited /cart, the server returned a cart page. Every route change = full page reload.

Client-side routing moves this to the browser. The server sends all the JavaScript once. Then the JavaScript handles routing without talking to the server again.

That's why apps using react-router feel fast—no page reloads, just JavaScript swapping content.

What You Gain By Going Vanilla

When you deeply understand vanilla JavaScript, you gain five things:

1. Deep Platform Understanding

You know how things actually work. You understand getElementById is faster than querySelector. You know which DOM APIs are O(n) vs O(1). You understand browser repaints and reflows.

This makes you a better developer even when using frameworks because you understand what's happening under the abstractions.

2. Zero Framework Churn / Framework Lock-In

No anxiety about React 19 breaking changes. No scrambling when a framework is deprecated. Your skills transfer across tools because you understand the foundation.

3. Performance by Default

The browser is already optimized for JavaScript and DOM manipulation. You get fast performance without needing to "optimize your bundle" or "code-split properly."

4. More Control

You decide exactly what happens, when, and how. No framework making decisions for you.

5. Future-Proof (Work AND Yourself)

Your code will keep working. Browsers are backward-compatible. Code you write today in vanilla JS will work in browsers 10 years from now.

And you are future-proof. In an AI world where tools can generate boilerplate React code, your deep understanding of fundamentals, memory leaks, event loops, DOM performance, reactivity patterns, is what makes you valuable.

The Point (Because We Need to Say It Clearly)

If you take away three things from this article, let them be:

1. Understand the Whole Spectrum

Don't just learn React. Learn JavaScript deeply. Understand what React does under the hood. Know when frameworks add value and when they add bloat.

2. Choose Based on Project Needs

Not every project needs React. A landing page with three buttons? Vanilla JS. A complex dashboard with real-time data and 50 interactive components? React makes sense.

3. Don't Default to React for Everything

Break the reflex. When starting a new project, ask: "Do I actually need a framework for this?" Sometimes the answer is yes. But often, it's no.

When to Actually Use Vanilla JS

Here are five scenarios where vanilla JavaScript is the right choice:

1. Small/Low-Complexity Projects

If your project is under 10-20 components or has minimal interactivity, vanilla JS will be faster to write, faster to load, and easier to maintain.

Example: A personal portfolio site, a documentation page, a simple calculator.

2. Performance Optimization Matters

If you're building for users on slow networks or expensive data plans (hello, Nigeria), every kilobyte matters. Vanilla JS has zero overhead.

Example: A mobile app for emerging markets, an offline-first PWA.

3. Learning Fundamentals

If you're still grasping how JavaScript works, build projects in vanilla first. Understand closures, scope, async/await, DOM manipulation, event delegation. Then learn React.

You'll appreciate what frameworks do because you'll know what problems they solve.

4. You Need More Control

Sometimes you need precise control over rendering timing, event handling, or memory management. Frameworks make decisions for you. Vanilla JS lets you decide.

Example: A data visualization library, a game engine, performance-critical animations.

5. Speed for Light Projects

For throwaway prototypes, internal tools, or quick demos, vanilla JS is faster. No npm install, no build step, no framework decisions. Just code.

The Nigerian Context: Why This REALLY Matters

Let me bring this home.

In Nigeria, where:

• Data costs money (1GB can cost ₦500-1000, and many people are on prepaid)

• Internet can be slow (3G is common, 4G is unreliable, 5G is rare)

• Users are patient only so long (if your app doesn't load in 5 seconds, they'll switch to a competitor)

Every kilobyte matters.

When you ship a React app that's 2MB after "optimization," you're asking Nigerian users to:

1. Pay for that data

2. Wait for it to download over a slow connection

3. Hope their connection doesn't drop mid-download

This isn't hypothetical. I've watched people close apps because "this one is not working" when really it's just... still loading.

A vanilla JS app that's 50KB loads fast, costs less data, and works on terrible connections.

Choose wisely.

Your technical choices have real-world consequences for real people. A smaller bundle isn't just a performance metric—it's respect for your users' constraints.

Final Thoughts: The Balanced Take

Let's bring this full circle with five closing points:

1. Frameworks Exist for Good Reasons

React, Vue, and Angular solved real problems: cross-browser compatibility, manual DOM updates, state management chaos, component reusability. They earned their dominance.

2. But They're Not Always the Answer

For small projects, simple interactions, or performance-critical apps, frameworks are often overkill. The overhead isn't worth it.

3. JavaScript is Powerful on Its Own

With Proxies, Web Components, and modern DOM APIs, vanilla JavaScript can do a lot. You can build reactivity, routing, and components without frameworks.

4. Small Bundles = Happy Users = Successful Businesses

Users on slow networks or expensive data plans will love you for keeping your app lightweight. Happy users stick around. Happy users tell friends. Happy users convert.

5. Understanding Fundamentals Makes You a Better Developer

Whether you end up using React or vanilla JS, understanding how things actually work makes you more effective. You debug faster. You optimize better. You make smarter architectural decisions.

In an era where AI can generate boilerplate framework code, your deep understanding of fundamentals is what makes you irreplaceable.

Skilling Up: Where to Learn More

Want to dive deeper into vanilla JavaScript? Here are the best resources:

Books & Websites:

• O'Reilly Books: "JavaScript: The Definitive Guide," "You Don't Know JS" series

• Web.dev: Google's web development resource with excellent JavaScript guides

• Mozilla Web Docs (MDN): The definitive reference for JavaScript, DOM APIs, Web Components

Courses:

• Frontend Masters: Beginner to advanced JavaScript courses, including deep dives into Proxies, Shadow DOM, and Web APIs

Topics to Master:

• JavaScript Proxies

• Shadow DOM

• Web Components

• DOM APIs (and their performance characteristics)

• Event delegation

• Memory management and garbage collection

Conclusion: The Real Framework is Understanding

I started learning to code by accident. I had an itel phone, installed a random app, and started writing HTML without even knowing it was code. I built a CBT app using link tags and thousands of <br> tags to "jump" between questions.

It was ridiculous. It was clever. It worked.

When I finally learned JavaScript, I didn't start with React. I used alert(), confirm(), and querySelector. Every line of code taught me something about how the web works.

That foundation, understanding the platform deeply, is what makes me effective today. Whether I'm writing React, Angular, or vanilla JavaScript, I know what's happening under the hood.

The best framework isn't React or Vue or Angular.

The best framework is understanding.

So before you type npx create-react-app for your next project, pause. Ask yourself: Do I actually need this?

Sometimes the answer is yes. But often, more often than we admit, the answer is no.

And in those moments, vanilla JavaScript is enough.

**Choose wisely. Every kilobyte matters.**Resources from the Talk

Slides: You can view the original presentation slides from DevFest Ibadan here

Imagine if it’s easy for me to use the same key accross different apps, while still being able to dynamically switch providers in a split second, and validate input and output from the LLMs used, this will make my development of AI-enabled applications super fast!.

The pain points are real:

• Repetitive setup across projects

• Inconsistent error handling patterns

• Manual JSON validation and parsing

• API key management across environments

• No standardized way to handle retries and failures

• Provider-specific code that's hard to switch

Initial Thoughts

The solution seemed obvious: build a unified SDK that abstracts away provider differences while offering consistent developer experience. But the challenge was balancing simplicity with flexibility. Too simple, and it becomes limiting. Too complex, and it defeats the purpose of reducing boilerplate.

I wanted something that felt natural to use, a fluent API that could handle the 80% use case elegantly while still allowing customization for edge cases. The key insight was that most AI interactions follow the same pattern: authenticate, send prompt with variables, get structured response, handle errors.

The Solution Architecture

The SDK centers around two main methods:

Initialize once, use everywhere:

const ai = sdk.initialize({
  auth: {
    type: "embedded" | "fetch",
    url: "https://my-keys-api.com/keys",
    keys: { claude: "key1", openai: "key2" }
  },
  settings: {
    retryOnFail: true,
    maxRetry: 3,
    cachable: true,
    trimPrompt: false
  }
})

Prompt with intelligence:

const result = await ai.prompt('Get weather in {{CITY}}', {
  expectJson: true,
  jsonStructure: { temp: "number", condition: "string" },
  validateJSON: true,
  errorOnInvalidJSON: true
}, { CITY: "San Francisco" })

The authentication system supports both embedded keys and remote fetching, solving the multi-environment deployment challenge. Variable interpolation with required validation prevents runtime errors. JSON structure validation ensures type safety with AI responses.

Decision Matrix

When designing the feature set, I evaluated each potential feature against three criteria:

Impact (how much pain it solves),

Complexity (implementation difficulty), and

Usage Frequency (how often developers need it).

High Impact + Low Complexity + High Usage → V1

• Variable interpolation and validation

• Multi-provider authentication

• JSON response handling and validation

• Basic retry logic and caching

High Impact + High Complexity → V2

• Streaming responses (complex WebSocket/SSE handling)

• Usage tracking and cost estimation (requires pricing data maintenance)

Medium Impact + Medium Complexity → V2

• Template management system

• Advanced middleware and hooks

Low Impact or Very High Complexity → Future/Never

• Complex prompt engineering features

• Built-in fine-tuning capabilities

This matrix helped avoid feature creep while ensuring V1 addresses the most painful developer problems.

Version 1: Core Foundation

V1 focuses on the essential developer experience:

Authentication & Configuration

• Multi-provider support (Claude, OpenAI, extensible to others)

• Flexible auth: embedded keys or remote URL fetching

• Global settings with per-request overrides

Smart Prompting

• {{VARIABLE}} interpolation with validation

• Required variable checking (throws helpful errors)

• Clean variable passing via options object

Response Handling

• Automatic JSON parsing and validation

• Type-safe structure checking against expected schema

• Configurable error handling for invalid responses

Reliability

• Retry logic for failed requests

• Response caching to reduce API calls

• Prompt trimming for token optimization

This gives developers a production-ready foundation that eliminates most AI integration boilerplate while maintaining flexibility.

Version 2: Advanced Features

Once V1 proves the core concept, V2 will add sophistication:

Streaming Support Real-time response streaming for better user experience in chat applications and long-form content generation.

Template Management
Reusable prompt templates with versioning, making it easier to maintain and iterate on prompts across teams.

Usage Analytics Token tracking, cost estimation, and usage limits to help manage AI budgets and optimize performance.

Advanced Middleware Hooks for logging, analytics, custom validation, and request modification, enabling complex workflow integration.

Why This Approach Works

This SDK design succeeds because it follows proven software engineering principles:

Progressive Enhancement: Start simple, add complexity gradually based on real usage patterns.

Separation of Concerns: Authentication, prompting, and response handling are cleanly separated but work together seamlessly.

Developer Experience First: The API feels natural and reduces cognitive load rather than adding abstraction complexity.

Flexibility Without Bloat: Core functionality handles most use cases, while extension points allow customization without forcing complexity on simple users.

I have chosen the name “Ajala AI SDK”, Ajala stood out to me because of the legendary “Ajala, THE TRAVELER” who travelled the entire world on a bicycle, hoping to do that someday, but definitely not with a bicycle 😂😂😂 , Ajala AI SDK in the open, you can follow the development on github. Star the repo to stay updated, open issues for features you need, or reach out if you'd like to contribute code, documentation, or ideas.
Building developer tools is always better as a community effort!

Bye.

In our previous article, we learned that JavaScript has a compilation phase where it scans through your code and sets up variable declarations. But not all variable declarations behave the same way during this process.

Understanding the differences between var, let, and const - and the "Temporal Dead Zone" is important for writing predictable JavaScript and avoiding common bugs.

Definitions

Before we proceed, let's explain a few terms you will come accross:

Temporal Dead Zone (TDZ) - The period between when a variable is hoisted (during compilation) and when it's initialized with a value. During this time, accessing the variable throws a ReferenceError.

Block Scope - A scope created by curly braces {}. Variables declared with let and const are confined to the block where they're declared.

Function Scope - A scope created by functions. Variables declared with var are confined to the function where they're declared (or global if outside any function).

Hoisting - The process during compilation where variable and function declarations are processed before code execution begins.

Initialization - The moment a variable gets its first value assignment.

The Three Variable Declarations

JavaScript gives you three ways to declare variables, each with different scoping and hoisting behavior:

var teacher = "Kyle";     // Function-scoped, undefined when hoisted
let student = "Frank";    // Block-scoped, TDZ when hoisted  
const course = "JS";      // Block-scoped, TDZ when hoisted, immutable

VAR

var declarations are function-scoped and get initialized with undefined during the compilation phase:

console.log(teacher);     // undefined (not an error!)
var teacher = "Kyle";
console.log(teacher);     // "Kyle"

What happens:

1. Compilation: teacher is declared in function scope, initialized with undefined

2. Execution: First console.log prints undefined, then assignment happens

LET and CONST - The Modern Approach

let and const are block-scoped and exist in the Temporal Dead Zone until their declaration line:

console.log(student);     // ReferenceError!
let student = "Frank";
console.log(student);     // "Frank"

What happens:

1. Compilation: student is declared in block scope but NOT initialized

2. Execution: First console.log tries to access uninitialized variable → ReferenceError

Block Scope in Action

Block scope means variables are confined to the nearest set of curly braces:

var globalVar = "I'm global";

if (true) {
    var functionScoped = "I escape the block";
    let blockScoped = "I'm trapped in the block";
    const alsoBlocked = "Me too";
}

console.log(functionScoped);  // "I escape the block"
console.log(blockScoped);     // ReferenceError!
console.log(alsoBlocked);     // ReferenceError!

The difference:

• var ignores block boundaries (function-scoped)

• let and const respect block boundaries (block-scoped)

Temporal Dead Zone (TDZ)

The TDZ is the time between variable hoisting and initialization:

console.log("Before declaration");

console.log(a);  // ReferenceError - TDZ violation
console.log(b);  // undefined - no TDZ for var

let a = "Hello";
var b = "World";

console.log("After declaration");
console.log(a);  // "Hello"  
console.log(b);  // "World"

TDZ Timeline:

1. Compilation: Both a and b are hoisted

2. Execution starts: a is in TDZ, b is undefined

3. Line 3: Accessing a → ReferenceError (TDZ violation)

4. Line 4: Accessing b → undefined (allowed)

5. Line 6: a exits TDZ, gets value "Hello"

6. Line 9: Both variables accessible normally

Practical Implications

Loop Behavior

// var - function scoped, same variable
for (var i = 0; i < 3; i++) {
    setTimeout(() => console.log(i), 100);  // 3, 3, 3
}

// let - block scoped, new variable each iteration  
for (let i = 0; i < 3; i++) {
    setTimeout(() => console.log(i), 100);  // 0, 1, 2
}

Const Immutability

const user = { name: "Kyle" };
user.name = "Frank";        // OK - modifying property
console.log(user.name);     // "Frank"

user = { name: "Suzy" };    // Error - reassigning const

Block Scope Benefits

function processData() {
    if (condition) {
        let tempData = calculateSomething();
        let result = process(tempData);
        return result;
        // tempData and result die here
    }
    // tempData and result not accessible here
}

Common Misconceptions

"let and const aren't hoisted" False. They are hoisted but remain uninitialized in the TDZ.

"const means immutable"
Partially false. The binding is immutable, but object/array contents can change.

"var is always bad" False. var has legitimate use cases, especially for function-scoped variables.

"Block scope is just for loops" False. Any {} creates block scope for let/const.

When to Use Which

Use const by default - Prevents accidental reassignment

const API_URL = "https://api.example.com";
const users = [];  // Can still push to array

Use let when you need reassignment - Clear signal of mutability

let counter = 0;
let currentUser = null;

Use var sparingly - Only when you specifically need function scope

function processItems() {
    for (var i = 0; i < items.length; i++) {
        // var i is function-scoped, accessible after loop
    }
    return i;  // Final value of i
}

Summary: Choose Your Declaration Wisely

Understanding variable declarations is fundamental to JavaScript mastery:

Compilation vs Execution: All declarations are hoisted, but initialized differently TDZ Protection: let/const prevent access before initialization
Scope Boundaries: var ignores blocks, let/const respect them Best Practices: Prefer const, use let for reassignment, avoid var unless necessary

This knowledge sets the foundation for understanding:

• Why certain bugs occur during development

• How closures capture variables correctly

• Module patterns and encapsulation strategies

• Modern JavaScript best practices

Before JavaScript executes a single line of your code, something crucial happens behind the scenes. While most developers think JavaScript executes and runs code line by line(I know I mentioned this in the first series), the reality is more sophisticated and understanding this process is the key to mastering scope, hoisting, and variable behavior. Javascript still executes code line by line, but before that it interprets/compiles the javascript code.
When you write a javascript code, the first thing that happens is what I refer to as “Parsing” also can be referred to as “Compilation” or interpretation.

A relatable example is when you have a syntax error in your code on line 20, but immediately you recompile, you get an error, when infact your code hasn’t executed up to line 20, the reason why this error shows up immediately is because of the first step “Parsing/Compilation”, during this phase, Javascript engines runs through the code, define variables, verify syntaxes, etc.

So, your code is first compiled, then executed, and that brings us to “The Two step process”.

JavaScript's Two-Step Process

Javascript follows a two-step process:

1. Compilation Phase - JavaScript scans through your entire code, setting up scope and preparing for execution

2. Execution Phase - The actual running of your code, line by line

This compilation step is where all the "magic" of hoisting, scope creation, and variable declarations happens.

Definitions

Before we proceed into JavaScript's compilation process, let's explain a few terms you will come accross:

Scope - The accessibility of variables and functions in different parts of your code. It determines where you can use a particular variable.

Lexical Scope - Scope that is determined by where variables and functions are declared in your code (at write-time), not where they are called from (at runtime).

Global Scope - The outermost scope in JavaScript. Variables declared here are accessible from anywhere in your program(more like in the window).

Function Scope - A scope created inside a function. Variables declared here are only accessible within that function.

Block Scope - A scope created by curly braces {} when used with let or const. Variables declared here are only accessible within that block.

Source Reference - When a variable is being read or accessed (appears on the right-hand side of an assignment or in expressions like console.log(variable)).

Target Reference - When a variable is being assigned a value (appears on the left-hand side of an assignment like variable = "value").

Compilation Phase - The first step where JavaScript scans through your code, sets up scope, and prepares variable declarations before any code executes.

Execution Phase - The second step where JavaScript actually runs your code line by line.

Scope Chain - The hierarchy of scopes that JavaScript searches through when looking up a variable, starting from the innermost scope and moving outward.

Hoisting - The behavior where variable and function declarations are processed during the compilation phase, making them available throughout their scope even before their declaration line is reached during execution.

Step 1: Compilation - The Setup Phase

During compilation, JavaScript's engine acts like an organizer, scanning through your code and asking two critical questions about every variable it encounters:

"What scope does this belong to?"
"Is this a source or target reference?"

var teacher = "Kyle";

function otherClass() {
    teacher = "Suzy";
    topic = "React";
    console.log("Welcome!");
}

otherClass();

Let's trace through the compilation phase:

Line 1: var teacher = "Kyle"

• Compiler finds teacher declaration

• Creates teacher in global scope

• Notes: This will be a target reference (receiving a value)

Line 3: function otherClass()

• Compiler creates otherClass function in global scope

• Creates new scope for inside the function

Line 4: teacher = "Suzy"

• Compiler sees teacher reference

• No declaration here, so it's a source reference (looking up existing variable)

• Notes: Will look up scope chain during execution

Line 5: topic = "React"

• Compiler sees topic reference

• No declaration anywhere - this will create an implicit global

Source vs Target References

Understanding the difference between source and target references is crucial:

Target Reference = Left-hand side of assignment (receiving a value)

var student = "Frank";    // student is TARGET
teacher = "Kyle";         // teacher is TARGET

Source Reference = Right-hand side of assignment (providing a value)

console.log(teacher);     // teacher is SOURCE
var message = teacher;    // teacher is SOURCE, message is TARGET

Why This Matters

The engine handles source and target references completely differently:

Target references: Must have a declared variable to assign to Source references: Must find an existing variable to read from

// Compilation phase creates these declarations
var teacher;              // TARGET reference prepared
var student;              // TARGET reference prepared

// Execution phase
teacher = "Kyle";         // TARGET - assigns to existing declaration
console.log(teacher);     // SOURCE - looks up existing value
topic = "React";          // TARGET - no declaration found, creates global
console.log(subject);     // SOURCE - no declaration found, ReferenceError!

Lexical Scope - Where You Write Matters

Lexical scope means scope is determined by where you write your code, not where you call it. The physical placement of your variables and functions determines their scope relationships.

var teacher = "Kyle";

function otherClass() {
    var teacher = "Suzy";

    function ask() {
        console.log(teacher);  // Which teacher?
    }

    ask();
}

otherClass(); // "Suzy"

The ask() function looks for teacher in this order:

1. Local scope (inside ask) - not found

2. Enclosing scope (inside otherClass) - found "Suzy"!

3. Global scope - never reaches here

This lookup happens at compile time based on where you wrote the code, not where you called it.

Scope Chain Resolution

JavaScript creates a scope chain during compilation - a linked list of scopes from innermost to outermost:

var global = "I'm global";

function outer() {
    var outerVar = "I'm in outer";

    function inner() {
        var innerVar = "I'm in inner";
        console.log(innerVar);  // Found in inner scope
        console.log(outerVar);  // Found in outer scope  
        console.log(global);    // Found in global scope
        console.log(missing);   // ReferenceError!
    }

    inner();
}

outer();

Scope chain for inner() function: Inner Scope → Outer Scope → Global Scope

The engine walks up this chain until it finds the variable or reaches the end (ReferenceError).

The Compilation Process in Action

Let's trace through a complete example:

console.log(teacher);        // What happens here?

var teacher = "Kyle";

function ask() {
    console.log(teacher);
}

ask();

Compilation Phase:

1. Line 3: Create teacher declaration in global scope

2. Line 5: Create ask function in global scope

3. Line 6: Create new scope for ask function

4. All source references noted for execution phase

Execution Phase:

1. Line 1: console.log(teacher) - SOURCE reference to teacher

   • teacher exists (from compilation) but value is undefined

   • Output: undefined

2. Line 3: teacher = "Kyle" - TARGET reference

   • Assigns "Kyle" to existing teacher declaration

3. Line 8: ask() - Calls function

4. Line 6: console.log(teacher) - SOURCE reference

   • Looks up teacher in scope chain, finds "Kyle"

   • Output: "Kyle"

Common Scope Misconceptions

"Hoisting moves declarations to the top" False. Nothing physically moves. Compilation creates declarations before execution begins.

"let and const aren't hoisted"
False. They are hoisted but in a "temporal dead zone" until their line is reached.

"Functions create scope" Partially true. Function declarations create scope, but so do blocks with let/const.

"Scope is determined at runtime" False. Lexical scope is determined at compile time by where you write code.

Practical Applications

Understanding compilation and lexical scope helps you:

Debug Variable Access Issues

function broken() {
    console.log(name);  // ReferenceError - not undefined!
    let name = "Frank";
}

Predict Hoisting Behavior

console.log(typeof teacher);  // "undefined" (var hoisting)
console.log(typeof student);  // ReferenceError (let in TDZ)

var teacher = "Kyle";
let student = "Frank";

Understand Closure Creation

function makeCounter() {
    var count = 0;
    return function() {
        return ++count;  // Lexical scope preserves access to count
    };
}

Welcome to JavaScript Deep Dive - a comprehensive series where we'll journey through JavaScript's inner workings, one concept at a time. Over the next several articles, we'll explore everything from basic execution to advanced patterns like closures, promises, and object-oriented programming.

What we'll cover in this series:

• Execution & Memory - How JavaScript reads and stores your code

• Functions & Execution Contexts - The foundation of JavaScript behavior

• Call Stack Fundamentals - Tracking function calls and nested execution

• Stack Overflow & Limits - Understanding JavaScript's boundaries

• Closures & Higher-Order Functions - The DRY principle in action

• Promises & Async Patterns - Managing asynchronous operations

• Event Loop - How JavaScript handles non-blocking operations

• Object-Oriented Programming - The new keyword and beyond

• The this Keyword - Context and binding demystified

• Modern Classes - ES6+ OOP patterns

JavaScript's Sequential Nature

JavaScript operates on a simple principle: one thing happens at a time. Understanding this core concept is essential for writing predictable, debuggable code.

Line-by-Line Execution

JavaScript reads and executes code line by line, in order. When you write a program, JavaScript starts at the top and works its way down, executing each statement before moving to the next.

console.log("First");    // Executes first
console.log("Second");   // Executes second  
console.log("Third");    // Executes third
// Output: First, Second, Third

This sequential execution means that the order you write code matters. Unlike human reading where you might skim or jump around, JavaScript is (and will be) methodical and predictable (in practice).

The Single-Threaded Reality

JavaScript is fundamentally single-threaded (read more about threading here), meaning it can only execute one command at a time. There's no parallel processing happening - each line must complete before the next begins.

This has profound implications:

• Blocking operations stop everything else from running

• User interfaces can freeze if code takes too long

• Predictability is high - you know exactly what order things happen

Memory Storage During Execution

As JavaScript executes code, it stores data in global memory (also called the variable environment). When you declare variables, JavaScript creates space for them and tracks their values.

const num = 3;        // Creates 'num' in memory, stores 3
const string = "hello"; // Creates 'string' in memory, stores "hello"  
let result;           // Creates 'result' in memory, initially undefined in value

Variable Hoisting

JavaScript actually scans through your code before executing it, setting up memory space for variables and functions. This is called hoisting.

javascript

console.log(myVar); // undefined (not an error!)
var myVar = "Hello World";
console.log(myVar); // "Hello World"

What actually happens:

1. JavaScript creates myVar in memory during setup phase

2. myVar initially gets the value undefined

3. First console.log prints undefined

4. Assignment happens: myVar = "Hello World"

5. Second console.log prints "Hello World"

Tracing Execution Step by Step

const num = 3;
const string = "hello";
let result;

// Trace through execution step by step
console.log("Step 1");
result = num + 5;
console.log("Step 2");
console.log(result);

Execution order:

1. Setup Phase (before any code runs):

   • Create num in memory

   • Create string in memory

   • Create result in memory, value undefined

2. Execution Phase (line by line):

   • Line 1: Assign 3 to num

   • Line 2: Assign "hello" to string

   • Line 3: result stays undefined (no assignment yet)

   • Line 5: Execute console.log("Step 1") → outputs "Step 1"

   • Line 6: Calculate num + 5 (3 + 5 = 8), assign to result

   • Line 7: Execute console.log("Step 2") → outputs "Step 2"

   • Line 8: Execute console.log(result) → outputs 8

Common Pitfalls and Misconceptions

"JavaScript runs multiple things at once"

False. JavaScript is strictly single-threaded for code execution. Even asynchronous operations follow specific rules we'll cover in later articles.

"Variables exist before they're declared"

Partially true due to hoisting, but they're undefined until assignment. Understanding the difference between declaration and assignment is crucial.

"Execution order doesn't matter"

False. Order is critical for correct runtime behavior. This becomes even more important with functions and scope.

"Memory management is completely automatic"

Mostly true, but understanding when and how JavaScript manages memory helps you write more efficient code and avoid memory leaks.

Practical Applications: Better Debugging

Understanding execution flow transforms how you debug:

Reading Error Messages

When you see an error like "Cannot read property 'x' of undefined", you can trace back through execution to find exactly when and why a variable became undefined.

Predicting Program Behavior

Before running code, you can mentally trace through the execution steps and predict the output. This skill is invaluable for both development and interviews.

Identifying Performance Issues

When you understand that JavaScript can only do one thing at a time, you start thinking about which operations might block the user interface and how to structure code for better performance.

Summary: Your Mental Execution Model

The key takeaway is developing a mental model of JavaScript as a methodical, step-by-step executor:

1. Setup Phase: JavaScript scans code and sets up memory space

2. Execution Phase: Code runs line by line, in order

3. Memory Management: Variables are stored and tracked throughout

4. Single-threaded: Only one operation at a time

This foundation is crucial for understanding more complex concepts like:

• How functions create their own execution contexts

• Why closures work the way they do

• How asynchronous operations fit into single-threaded execution

• Object creation and the this keyword

Next up: We'll explore how functions create their own execution contexts and why understanding this concept is the key to mastering JavaScript scope, closures, and advanced patterns.

The answer lies in something called threading - and it's one of the most important concepts in computing that affects every single app you use.

What is Threading, Really?

Think of threading as how programs/process organize work. Just like a restaurant needs to decide whether to have one waiter handle all tables or multiple waiters working simultaneously, programs need to decide how to handle multiple tasks.

Threading is essentially the program's strategy for getting things done. It determines whether your app can (oversimplified):

• Download a file while you browse other tabs

• Play music while you text

• Process your photos while you take new ones

• Or forces you to wait for one thing to finish before starting another

Why Your CPU Cares About Threading

Your computer's processor (CPU) is like having multiple workers available, but whether your programs actually use those workers depends on how they're designed.

Modern phones and computers have multiple cores - think of each core as a separate worker. Your iPhone might have 6 cores, your laptop might have 8, and high-end computers can have 16 or more. Having multiple workers doesn't automatically mean your program uses them all.

It's like having a construction site with 8 workers, but if the foreman (your program) only knows how to give instructions to one worker at a time, the other 7 just stand around waiting.

This is why some apps feel snappy and responsive while others feel sluggish, even on the same device/server.

Why Should You Care?

Understanding threading helps you:

• Choose better apps - Multi-threaded apps generally feel more responsive

• Understand performance - Why some tasks are fast vs slow

• Make better decisions - When to close apps, when to wait, when to restart

• Appreciate good software - Recognize when developers have done threading well

Plus, if you're learning to code or working with developers, understanding threading helps you communicate about performance and user experience more effectively.

Think of your CPU as a restaurant kitchen, and each core as a chef (read more about cores here).

Single-Threaded: One Chef, One Order at a Time

// JavaScript - Single-threaded
console.log("Taking order 1");      // Chef takes order
processPayment();                   // Chef processes payment  
cookMeal();                        // Chef cooks meal
serveMeal();                       // Chef serves meal
console.log("Order 1 complete");   // Only now can chef start order 2

What happens: One chef handles everything for one customer before moving to the next. If cooking takes 10 minutes, the entire restaurant waits.

Pros: Simple, predictable, no coordination needed
Cons: Inefficient, blocking operations freeze everything

Multi-Threaded: Multiple Chefs, Parallel Work

// Java - Multi-threaded
public class Restaurant {
    public void handleOrders() {
        // Each thread (chef) works independently
        Thread chef1 = new Thread(() -> processOrder("Table 1"));
        Thread chef2 = new Thread(() -> processOrder("Table 2"));
        Thread chef3 = new Thread(() -> processOrder("Table 3"));

        chef1.start(); // All chefs work simultaneously
        chef2.start();
        chef3.start();
    }
}

What happens: Multiple chefs work on different orders simultaneously. While one chef cooks, another takes orders, and a third serves meals.

Pros: Efficient, non-blocking, better resource utilization
Cons: Complex coordination, potential conflicts (two chefs grabbing the same ingredient)

How This Maps to Your CPU

Your CPU has multiple cores (chefs), and each core can handle threads (tasks):

• Single-core CPU: One chef, must do everything sequentially

• Dual-core CPU: Two chefs, can handle two tasks simultaneously

• Quad-core CPU: Four chefs, even more parallel processing

• Modern CPUs: 8, 16, or more cores with hyper-threading (each chef can juggle 2 tasks)

Real-World Examples

Single-Threaded Languages

JavaScript, Python (GIL), PHP

// Everything waits for this to finish
for(let i = 0; i < 1000000; i++) {
    // Heavy computation blocks everything
}
console.log("Finally done!"); // UI frozen until here

Multi-Threaded Languages

Java, C#, Go, Rust

// Heavy work happens in background
CompletableFuture.runAsync(() -> {
    // Heavy computation on separate thread
    heavyCalculation();
});

// UI stays responsive
System.out.println("UI still works!");

The Trade-offs

When Single-Threading Works Well

• Simple applications where tasks are quick

• I/O heavy applications (like web servers using asynchronous patterns)

• When avoiding complexity is more important than performance

When Multi-Threading Shines

• CPU-intensive tasks (image processing, calculations)

• Applications serving many users simultaneously

• When you can break work into independent pieces

Quick Comparison

Bottom line is, Single-threading is like having one super-efficient chef who never makes mistakes but can only handle one thing at a time.

Multi-threading is like having a full kitchen staff who can serve the whole restaurant simultaneously, but you need a head chef (programmer) who can coordinate them without chaos.

Choose based on your needs: simplicity and predictability vs. performance and resource utilization.

Ever joined a project and spent three days just figuring out how the authentication system works? Or tried to add a simple feature only to discover it breaks two other components in mysterious ways? Or worse - found yourself staring at your own code from six months ago, wondering what past-you was thinking?

The problem isn't your code. The problem is documentation.

Technical implementation documents are either non-existent, outdated, or written like academic papers that only make sense to the person who wrote them. But when done right, they're the difference between a smooth development process and weeks of confusion, debugging, and "why did we build it this way?" conversations.

Let's dive into writing technical implementation documents that actually help people build great software - including future you.

Why Technical Docs Actually Matter (Beyond the Obvious)

Let's be real, most developers treat documentation like that gym membership they never use. "I'll definitely write docs... tomorrow... maybe next sprint... okay, fine, when the project is done."

But here's the thing: great technical implementation documents aren't just nice-to-have paperwork. They're the difference between a smooth development process and spending three weeks debugging why a feature that should have taken two days is mysteriously breaking everything else.

Think about it like this: when you're cooking, you don't just throw ingredients together and hope for the best (well, maybe you do, but your kitchen probably looks like a disaster zone). You plan the meal, understand how each ingredient interacts, and know what steps to take in what order.

Technical implementation documents are your recipe for building software that doesn't fall apart the moment someone else touches it.

The Anatomy of Documents That Actually Work

The "Think Before You Code" Philosophy

The best technical documents start before you write a single line of code. They're born from that crucial thinking phase where you're asking yourself the hard questions:

• What problem are we actually solving?

• What are the different ways to solve this problem?

• What could go wrong, and how do we handle it?

• How does this fit into the bigger picture?

I learned this the hard way when building a notification system that seemed simple on the surface. "Just send notifications when events happen," the requirements said. Easy, right?

Wrong.

Three weeks later, I was debugging race conditions, handling duplicate notifications, dealing with failed deliveries, and wondering why nobody mentioned that notifications needed to work across different time zones, support multiple languages, and gracefully handle users who'd disabled certain notification types.

A proper implementation document would have forced me to think through these scenarios upfront, instead of discovering them at 2 AM when the production system started melting down.

Structure That Makes Sense

Here's the thing about document structure - it should mirror how your brain actually processes information when approaching a new problem.

Start with the "Why" (Context and Problem Statement)

Don't jump straight into technical details. Start by explaining why this feature exists in the first place. What user problem does it solve? What business need does it address?

For example, instead of starting with "Implement user authentication using JWT tokens," start with "Users are frustrated with having to log in repeatedly across different parts of our application, leading to drop-offs and poor user experience."

Then the "What" (Feature Overview)

Now you can describe what you're building, but keep it high-level and user-focused. This section should be readable by non-technical stakeholders who need to understand the scope without getting lost in implementation details.

The "How" (Implementation Strategy)

This is where the technical meat lives, but don't just dump code everywhere. Explain your thinking process:

• Why did you choose this approach over alternatives?

• What are the trade-offs you considered?

• How does this integrate with existing systems?

The "What If" (Edge Cases and Error Handling)

This is where most documents fail spectacularly. They focus on the happy path and completely ignore everything that can (and will) go wrong.

Real users don't follow your perfect user journey. They'll click buttons multiple times, have flaky internet connections, input weird data, and somehow find ways to break your system that you never imagined.

The Language of Clarity

Technical writing doesn't mean you have to sound like a robot having a conversation with a database. Write like you're explaining the system to a smart colleague who's new to the project.

Instead of: "The authentication middleware intercepts incoming requests and validates JWT tokens against the configured secret key before allowing request propagation to downstream handlers."

Try: "When a user makes a request, our authentication system checks their login token to make sure they're allowed to access that feature. If the token is valid, the request continues normally. If not, we send them back to the login page."

Both say the same thing, but one actually helps people understand what's happening and why.

Component Architecture: Beyond the Boxes and Arrows

The "Lego Block" Principle

Good component architecture documentation doesn't just show what components exist - it explains how they fit together and why they're organized that way.

Think of your components like Lego blocks. Each block has a specific purpose, but the magic happens when you understand how they connect to build something bigger.

Instead of just listing components, explain the hierarchy and relationships:

UserDashboard (main orchestrator)
├── ProfileSection (displays user info)
├── NotificationCenter (handles alerts)
│   ├── NotificationItem (individual alerts)
│   └── NotificationSettings (user preferences)
└── ActivityFeed (shows user actions)
    ├── ActivityItem (individual actions)
    └── ActivityFilter (sorting/filtering)

But don't stop there. Explain why this structure makes sense:

"The UserDashboard acts as the main coordinator, fetching user data and passing it down to child components. Each section handles its own specific concerns - ProfileSection manages display logic, NotificationCenter handles alert workflows, and ActivityFeed deals with user action history. This separation means we can update notification logic without touching profile code, and vice versa."

You can read more on seperating concerns and components architecture driven frontends here

State Management Strategy

This is where things get interesting. State management is like organizing your kitchen - there are many ways to do it, but some approaches will drive you (and your teammates) absolutely crazy.

Document not just what state you're tracking, but where it lives and why:

"User authentication state lives in a global context because multiple components across the app need to know if someone is logged in. Notification preferences are stored locally in the NotificationCenter because only that component cares about them. Form data stays in individual form components unless it needs to persist across navigation, in which case it moves to session storage."

API Integration Patterns

API integration is where many projects turn into spaghetti code disasters. Your documentation should explain not just what endpoints you're calling, but how you're handling the inevitable chaos of network requests.

Instead of just listing API endpoints, explain the patterns:

"All API calls go through our apiClient utility, which handles authentication headers, retry logic, and error formatting automatically. For user-facing actions, we use optimistic updates - the UI changes immediately, then we sync with the server in the background. If the server request fails, we roll back the UI change and show an error message."

Real-World Example: Building a Bank Statement Analyzer

Let me walk you through how this looks in practice by documenting a bank statement analyzer app from scratch. By the end of this section, you'll have a complete technical implementation document you could actually hand to a development team.

Let's build this document together, step by step.

Step 1: The Problem Context

Every good technical document starts with understanding why the feature exists. Here's how we'd document our bank statement analyzer:

Bank Statement Analyzer - Problem Context

"Many people struggle to understand their spending patterns and financial health. Traditional banking apps provide transaction lists but lack deeper insights into spending categories, trends, and financial behavior. Users want to upload their bank statements and receive comprehensive financial analysis without sharing sensitive data with third-party services permanently.

Current solutions either require expensive financial advisors, complex spreadsheet analysis, or sharing data with services that store information indefinitely. We need a solution that provides professional-level financial analysis while respecting user privacy through immediate data deletion after processing."

See how we're not jumping into technical details yet? We're establishing the human problem first.

Step 2: The Strategic Approach

Now we explain what we're building and our high-level approach:

Solution Overview

"We're building a client-side web application that allows users to upload CSV bank statements, processes them through AI analysis, and provides comprehensive financial insights. The key differentiator is our privacy-first approach - data is processed and immediately deleted, never stored permanently.

The application follows a linear workflow:

1. Upload Stage: Secure file upload with privacy consent

2. Processing Stage: Real-time analysis progress with Claude AI

3. Results Stage: Interactive financial analysis dashboard

The architecture prioritizes user privacy, clear progress feedback, and comprehensive analysis presentation. Users can test the system with sample data before uploading personal information."

Step 3: Component Architecture & User Flow

Here's where we break down the technical approach:

Application Architecture

The application consists of four main stages, each handling specific user interactions and system processes:

BankStatementAnalyzer (main application)
├── LandingPage (file upload interface)
│   ├── FileUploadDropzone (drag & drop functionality)
│   ├── PrivacyConsentCheckbox (data processing agreement)
│   ├── CSVTemplateDownload (sample data provider)
│   └── FileValidation (CSV format verification)
├── ProcessingPage (analysis progress tracking)
│   ├── ProgressBar (visual progress indicator)
│   ├── ProcessingStatus (real-time status updates)
│   └── AnalysisPreview (partial results display)
├── ResultsPage (comprehensive financial analysis)
│   ├── SpendingCategorization (expense breakdown)
│   ├── TrendAnalysis (spending patterns over time)
│   ├── FinancialHealthScore (overall assessment)  
│   └── ActionableInsights (personalized recommendations)
└── ErrorBoundary (graceful error handling)

Data Flow Architecture:

[User] → [File Upload] → [Client Validation] → [Claude API] → [Analysis] → [Results] → [Data Deletion]

The key architectural decision is processing everything client-side with API calls to Claude, ensuring no server-side data persistence.

Step 4: Detailed Implementation Strategy

Now we get into the technical meat:

Stage 1: Landing Page Implementation

The landing page serves as the entry point and data collection interface. It must handle file validation, privacy consent, and provide testing capabilities.

File Upload Strategy:

• Support drag-and-drop and click-to-browse interfaces

• Validate CSV format and file size (max 10MB) before upload

• Provide real-time feedback on file validation status

• Support multiple common CSV formats (comma, semicolon, tab-separated)

Privacy Consent Implementation:

• Required checkbox: "I consent to my data being processed and deleted immediately after analysis"

• Clear privacy policy explanation

• Prevent upload until consent is given

• Log consent status for audit purposes

CSV Template System:

• Provide downloadable sample CSV with realistic (but fake) transaction data

• Template includes: Date, Description, Amount, Category columns

• Sample data demonstrates various transaction types and spending patterns

• File naming: "sample_bank_statement.csv"

Edge Cases to Handle:

• Invalid file formats (show specific error messages)

• Files larger than size limit (progressive feedback)

• Corrupted or empty CSV files

• Users attempting upload without consent

Stage 2: Processing Page Implementation

The processing page manages the analysis workflow and provides user feedback during potentially lengthy AI processing.

Progress Tracking Strategy:

• Break analysis into logical phases: "Parsing data", "Categorizing transactions", "Analyzing patterns", "Generating insights"

• Show percentage complete for each phase

• Estimated time remaining based on file size

• Real-time status updates via WebSocket or polling

Claude API Integration:

• Chunk large files into manageable segments for API processing

• Implement retry logic with exponential backoff for failed requests

• Handle rate limiting gracefully with user communication

• Process data in stages: categorization → trend analysis → insights generation

User Experience Considerations:

• Prevent page navigation/refresh during processing

• Show preview insights as they become available

• Provide cancel option with confirmation dialog

• Handle browser tab switching (maintain processing state)

Stage 3: Results Page Implementation

The results page presents comprehensive financial analysis in an digestible, interactive format.

Analysis Categories:

• Spending Categorization: Food, Transportation, Entertainment, Bills, etc.

• Trend Analysis: Monthly spending patterns, seasonal variations

• Financial Health Metrics: Income-to-expense ratio, savings rate

• Behavioral Insights: Largest expenses, frequent merchants, unusual transactions

Data Visualization Strategy:

• Interactive charts using Chart.js

• Responsive design for mobile and desktop viewing

• Export capabilities (PDF report, CSV summary)

• Drill-down functionality for detailed transaction analysis

Security Implementation:

• Automatic data deletion after results display (configurable timeout)

• No local storage of sensitive transaction data

• Clear indication when data has been purged

• Option to download results before data deletion

Step 5: Error Handling & Edge Cases

This is where most documentation fails, but it's crucial for real-world applications:

Comprehensive Error Handling Strategy

File Upload Errors:

• Invalid CSV format: "Please upload a valid CSV file with columns: Date, Description, Amount"

• File size exceeded: "File size must be under 10MB. Consider splitting large statements."

• Network failures: Retry mechanism with clear user communication

• Unsupported file types: List supported formats and provide conversion guidance

Processing Errors:

• Claude API failures: Fallback to basic categorization with user notification

• Rate limiting: Queue system with estimated wait times

• Network timeouts: Resume capability from last successful processing stage

• Invalid data formats: Specific guidance on fixing common CSV issues

Privacy & Security Errors:

• Data deletion failures: Multiple deletion attempts with audit logging

• Consent withdrawal: Immediate processing halt and data purge

• Session timeout: Automatic data cleanup with user notification

Browser Compatibility Issues:

• File API not supported: Graceful degradation with upload alternatives

• JavaScript disabled: Server-side processing fallback (if implemented)

• Mobile browser limitations: Responsive design with touch-friendly interfaces

Real-World Scenarios:

• User uploads 2 years of transactions (large file handling)

• Bank CSV has unusual formatting (flexible parser implementation)

• User wants to analyze multiple accounts (batch processing capability)

• Internet connection drops during processing (resume functionality)

Step 6: Technical Implementation Details

API Integration Specifications

Claude API Communication:

// Pseudocode for Claude integration
processTransactions(csvData) {
  // Break data into chunks for processing
  chunks = chunkTransactionData(csvData, 1000) // 1000 transactions per chunk

  results = []
  for each chunk:
    analysis = await claudeAPI.analyze({
      data: chunk,
      analysisType: ['categorization', 'trends', 'insights'],
      responseFormat: 'structured_json'
    })
    results.push(analysis)
    updateProgressBar(chunk.index / chunks.length * 100)

  return combineResults(results)
}

Data Processing Pipeline:

1. CSV Parsing: Convert uploaded file to structured data

2. Data Cleaning: Remove duplicates, handle missing values

3. Transaction Categorization: AI-powered expense categorization

4. Trend Analysis: Time-series analysis of spending patterns

5. Insight Generation: Personalized financial recommendations

6. Result Formatting: Structure data for frontend visualization

Privacy Implementation:

// Data lifecycle management
class DataManager {
  constructor() {
    this.processingData = null
    this.autoDeleteTimer = null
  }

  processFile(file) {
    this.processingData = file
    this.startAutoDeleteTimer(30 * 60 * 1000) // 30 minutes
    // Process data...
  }

  deleteData() {
    this.processingData = null
    clearMemoryReferences()
    logDataDeletion()
  }
}

Step 7: Testing & Validation Strategy

Testing Strategy

Unit Testing Focus:

• CSV parser handles various bank formats correctly

• Transaction categorization accuracy (test with known transaction types)

• Progress tracking updates correctly during processing

• Data deletion mechanisms work reliably

Integration Testing:

• End-to-end upload → processing → results workflow

• Claude API integration under various load conditions

• Error recovery scenarios (network failures, API timeouts)

• Cross-browser compatibility testing

User Acceptance Testing:

• Upload sample CSV and verify analysis accuracy

• Test privacy consent workflow

• Validate results make sense for different spending patterns

• Mobile device usability testing

Performance Testing:

• Large file processing (>5MB CSV files)

• Multiple concurrent users

• API response time optimization

• Memory usage during processing

Your Complete Technical Implementation Document

Congratulations! You've just walked through creating a comprehensive technical implementation document. Let's see what we built:

What We Covered:

✅ Problem Context - Why the feature exists
✅ Solution Overview - High-level approach and key decisions
✅ Component Architecture - How pieces fit together
✅ Implementation Strategy - Detailed technical approach for each stage
✅ Error Handling - Real-world edge cases and recovery strategies
✅ API Integration - Specific technical implementation details
✅ Testing Strategy - How to validate the implementation works

What Makes This Document Effective:

• Starts with user problems, not technical solutions

• Explains architectural decisions and why alternatives were rejected

• Covers edge cases that will definitely happen in production

• Provides specific implementation guidance without being too prescriptive

• Includes testing strategy so teams know how to validate their work

• Considers privacy and security as first-class concerns

This document could be handed to a development team today, and they'd have everything needed to build a production-ready bank statement analyzer. They'd understand not just what to build, but why it's built that way and how to handle the tricky parts.

Common Pitfalls (And How to Avoid Them)

The "Code Dump" Trap

The biggest mistake in technical documentation is treating it like a code dump. Just pasting code blocks with minimal explanation doesn't help anyone understand the system.

Bad example:

function handleSubmit(data) {
  if (!data.partnerId) return false;
  submitSelection(data);
  updateState('success');
  emitCallback({selected: true, partner: data});
}

Better example: "When users submit their partner selection, we first validate that they actually selected someone (users can be sneaky and try to submit empty forms). If validation passes, we send the selection to our API, update the widget to show success state, and notify the parent component about the selection so it can update its own interface accordingly."

The "Everything Is Important" Problem

When everything is highlighted, nothing is highlighted. Not every implementation detail needs to be in your main documentation.

Focus on the decisions that matter:

• Why you chose this architecture over alternatives

• How different components communicate

• What happens when things go wrong

• How the system will handle future changes

Save the nitty-gritty implementation details for code comments and separate technical references.

The "It's Obvious" Assumption

What's obvious to you after spending three weeks building something is definitely not obvious to the developer who's trying to understand it six months later (even if that developer is future you).

Document your assumptions and reasoning. If you decided to use a specific library, explain why. If you structured your state in a particular way, explain the thinking behind it.

Testing and Validation Strategies

Great implementation documents don't just explain how to build something - they explain how to verify that it works correctly.

Testing Philosophy

"Our testing strategy follows the principle of testing behavior, not implementation. We care that users can successfully select partners, not that our internal state management uses a specific pattern.

Component tests focus on user interactions: Can users search for partners? Does selection work correctly? Do error states display appropriate messages? Integration tests verify that the widget communicates correctly with parent components and handles API failures gracefully."

Edge Case Validation

"We systematically test the scenarios that usually break in production:

• Network failures during search and submission

• Rapid user interactions (clicking buttons multiple times)

• Invalid or outdated data from the API

• Keyboard navigation and screen reader accessibility

• Mobile device interactions with touch interfaces"

Maintenance and Evolution

The best technical documents acknowledge that software is a living thing that will change over time.

Future Considerations

"This widget is designed to evolve. The current implementation handles single partner selection, but the architecture supports multiple selections with minimal changes. The search interface can be extended to support filters and sorting without affecting the core widget logic.

Key extension points:

• Additional search criteria can be added to the SearchInput component

• New partner types can be supported by extending the PartnerCard component

• Different selection workflows can be implemented as alternative modal components"

Migration Strategies

"When rolling out this widget to replace existing partner selection implementations:

1. Start with new features to validate the approach

2. Gradually migrate existing screens during their regular update cycles

3. Maintain backward compatibility with existing selection events

4. Provide clear migration guides for teams adopting the widget"

Team Collaboration Through Documentation

Bridging the Communication Gap

Technical implementation documents are often the bridge between different team members with different expertise levels. Your document might be read by:

• Frontend developers implementing the interface

• Backend developers building supporting APIs

• QA engineers creating test cases

• Product managers understanding scope and limitations

• Designers ensuring the implementation matches their vision

Write with this diverse audience in mind. Use clear section headers so people can jump to what's relevant for them. Include diagrams and examples that help visual learners understand the concepts.

Review and Iteration

The best documents are living documents that evolve with the project. Build review and update processes into your development workflow:

"This document will be updated as we learn from user feedback and encounter edge cases in production. Major architectural changes require document updates before implementation. All team members should feel empowered to suggest improvements to unclear sections."

Tools and Techniques

Documentation as Code

Treat your technical documents like code. Use version control, peer reviews, and the same quality standards you apply to your implementation.

Keep documents close to the code they describe. If your widget lives in /components/PartnerSelection/, put the implementation document in /docs/components/PartnerSelection.md. This makes it more likely that documents get updated when code changes.

Diagrams and Visual Aids

Sometimes a simple diagram communicates better than three paragraphs of text. Use tools like Mermaid, Draw.io, or even hand-drawn sketches to illustrate:

• Component hierarchies

• Data flow between components

• User interaction workflows

• State transitions

• API communication patterns

But don't go overboard. Diagrams should clarify, not complicate.

Templates and Consistency

Develop templates for common document types. Having a consistent structure makes it easier for team members to find information and reduces the cognitive load of starting new documents.

A basic implementation document template might include:

• Problem Context

• Solution Overview

• Architecture Decisions

• Component Breakdown

• API Integration

• Error Handling

• Testing Strategy

• Future Considerations

The ROI of Good Documentation

Let's talk about the elephant in the room - time. Writing good technical documentation takes time, and in a world of tight deadlines and feature requests, it often feels like a luxury.

But here's the math that changed my perspective:

A well-documented feature saves every future developer (including future you) about 2-4 hours of ramp-up time. If five people work on or reference that feature over its lifetime, you've saved 10-20 hours of collective time by spending 2-3 hours writing good documentation upfront.

More importantly, good documentation prevents the kinds of misunderstandings that lead to bugs, incorrect implementations, and frustrated team members. The cost of fixing these issues later is always higher than preventing them with clear communication upfront.

Building a Documentation Culture

Making It Part of the Process

The best way to ensure documentation gets written is to make it a natural part of your development process, not an afterthought.

"Definition of Done" should include documentation updates. Code reviews should check that implementation matches documented design. Sprint planning should allocate time for documentation alongside development tasks.

Leading by Example

If you want your team to write better technical documents, start by writing better technical documents yourself. Share examples of documents that helped you understand complex systems. Celebrate when good documentation saves the team time or prevents bugs.

Documentation Debugging

Treat unclear documentation like a bug. When someone asks questions that should be answered in your documentation, that's a sign the documentation needs improvement, not that the person asking is lazy.

Wrapping Up: The Art of Technical Storytelling

At its core, writing technical implementation documents is about storytelling. You're telling the story of how a system works, why it was built that way, and how someone else can successfully work with it.

The best technical documents don't just transfer information - they transfer understanding. They help readers build mental models of how systems work, so they can make good decisions when they need to modify or extend the code.

Remember: every system you build will eventually be maintained by someone else (including future you, who will have forgotten all the clever details). Write documentation that respects their time and intelligence. Explain not just what the code does, but why it does it that way.

Great technical documentation is a gift to your future self and your teammates. It's the difference between inheriting a well-organized kitchen with labeled ingredients and clear recipes, versus walking into a chaotic mess and hoping for the best.

Your code might work perfectly today, but your documentation determines whether it will still be maintainable and understandable six months from now.

A new day, another opportunity to build something well-documented and world-class! 🚀