How to Write Better AI Prompts as a Designer

Here's the truth most AI tutorials skip: the tool is only 30% of the result. Your prompt is the other 70%.

Two designers using the exact same AI tool will get completely different outputs — not because of luck, but because of how they communicate with it. This article teaches you the prompting frameworks that make the difference.

Why Prompting Matters More Than the Tool

AI tools are prediction engines. They predict what output matches your input. A vague input produces a generic, averaged output — the AI's best guess at what most people mean. A precise, contextual input produces something specific, useful, and often remarkable.

Think of prompting the same way you think about design briefs. A bad brief produces bad work. A sharp brief — with context, constraints, and a clear goal — produces sharp work. The same principle applies here.

The Designer's Prompting Framework

Use this 4-part structure for almost any AI prompt in your design workflow:

[Role] + [Context] + [Task] + [Constraints]

Part 1: Role — Tell the AI who it's being

Start by assigning a role. This sets the AI's "perspective" and dramatically improves output quality.

Instead of: "Write a headline for my app"
Try: "You are a senior UX writer specializing in fintech products. Write a headline for..."

Instead of: "Generate a UI layout"
Try: "You are a UI designer focused on accessibility and clean information hierarchy. Design a..."

Role-setting is especially powerful in Claude and ChatGPT, where the AI adapts its reasoning style to match the stated expertise.

Part 2: Context — Give it the full picture

AI has no knowledge of your project unless you share it. The more context, the more relevant the output.

Weak context: "Design a mobile app screen"

Strong context: "This is a mobile app for independent personal trainers in Vietnam, aged 25–40, who are not highly tech-savvy. The app helps them manage client bookings and share workout plans. The design should feel professional but approachable, not clinical."

Context to always consider including:

• Who is the user and what is their situation?
• What is the product and what problem does it solve?
• What is the platform (mobile / web / print)?
• What is the brand tone (playful / minimal / premium / friendly)?

Part 3: Task — Be specific about the deliverable

The task section tells the AI exactly what to produce. Vague tasks produce vague outputs.

Weak task: "Help me with onboarding"
Strong task: "Write 3 different versions of the welcome screen headline and subheadline for the first-time user onboarding flow. Each version should take a different emotional angle: (1) motivational, (2) reassuring, (3) curious/playful."

When asking for visual outputs (in Midjourney, Firefly, Stitch):

Weak task: "A dashboard design"
Strong task: "A clean SaaS analytics dashboard for a mobile app startup. Dark mode. Left sidebar navigation. Key metrics in card format at the top. Line chart showing weekly active users. Minimal, modern, inspired by Linear and Notion."

Part 4: Constraints — Define the boundaries

Constraints are not limitations — they are what transform a generic output into a precise one. This is the most commonly skipped part of prompts, and the one that makes the biggest difference.

Useful constraints to add:

• "Keep it under 15 words" — for UX copy
• "Use only the colors: #1A1A2E, #E8E8E8, #FF6B35" — for visual tools
• "No stock photo look. Original illustration style, not photorealistic" — for Midjourney
• "Output as a numbered list, each item max 2 sentences" — for structured text
• "Avoid jargon. The user is not a designer or developer" — for UX writing tone

Prompt Templates You Can Use Right Now

Copy these and adapt them to your projects:

For UX copy (Claude / ChatGPT):

You are a UX writer specializing in [industry]. Write [number] versions of [element — e.g. empty state message / error message / CTA button label] for [product description]. User profile: [age, context, tech level]. Tone: [tone]. Length constraint: [word limit]. Avoid: [anything to exclude].

For UI generation (Figma Make / Google Stitch):

Design a [screen type] for a [product description]. Target user: [user profile]. Visual style: [adjectives — e.g. minimal, warm, high-contrast, editorial]. Platform: [mobile / desktop / tablet]. Key elements to include: [list]. Reference styles: [tools/apps to reference — e.g. "similar to Notion and Linear"].

For image generation (Midjourney / Adobe Firefly):

[Subject], [environment/setting], [lighting description], [mood/atmosphere], [visual style], [color palette], [camera or composition note]

Example: "A young woman reviewing design work on a large monitor, modern studio office, soft natural light from left, focused and calm atmosphere, editorial photography style, muted earth tones, slight shallow depth of field --ar 16:9 --v6"

For research synthesis (Claude / NotebookLM):

I am going to paste [number] user interview excerpts. Please analyze them and: (1) identify the top 3–5 recurring pain points, (2) highlight any surprising or unexpected insights, (3) list direct quotes that best represent each theme. Format the output as a structured summary with clear headers.

Common Prompting Mistakes to Avoid

Mistake 1: Asking for too many things at onceSplit complex requests into focused steps. "Design the whole app" will always produce worse results than designing one screen at a time with clear intent.

Mistake 2: Accepting the first outputThe first result is a starting point. Follow up: "Keep the same structure but make the tone warmer." / "Regenerate version 2, but this time prioritize information density over white space." Iteration is where the real value is.

Mistake 3: Describing the solution, not the problemInstead of "Make a simpler navigation", try "Users are dropping off because they can't find the settings page. Suggest 3 navigation structures that would make settings easier to discover." Let the AI solve, not just execute.

Mistake 4: Ignoring negative promptsTelling the AI what not to do is just as important. In Midjourney: "--no text, watermarks, blurry". In Claude: "Do not use corporate jargon. Do not open with 'Certainly!' or 'Of course!'"

Building Your Personal Prompt Library

The best designers treat their prompts like design assets — they save, iterate, and refine them over time.

Start a simple document with sections for: Image prompts, UX copy prompts, Research prompts, Client communication prompts. Every time a prompt produces a great result, save it as a template. Over 3 months, you'll have a personal toolkit that makes every project faster than the last.

Final Thought Across All 3 Parts

AI will not replace designers. But designers who use AI fluently will replace those who don't.

The tools in Part 1 give you capability. The workflow in Part 2 gives you structure. The prompting skills in Part 3 give you control. Put all three together and you're not just keeping up with how design is changing — you're ahead of it.

This series was written for UI/UX and Graphic Designers looking to integrate AI practically and confidently into their work. All tools mentioned have been selected based on current real-world usage as of 2025–2026.

How Designers Can Apply AI Across the Design Workflow

Having great AI tools is one thing. Knowing where to use them in your actual day-to-day process is what separates designers who save hours each week from those who play with AI occasionally and call it a day.

This article maps AI tools to each stage of the design process — from research all the way to handoff.

Stage 1: Research & Discovery

Tools: NotebookLM, Perplexity, Claude

Research is one of the most time-consuming parts of design. AI can dramatically compress this phase — not by replacing thinking, but by helping you process information faster.

NotebookLM (by Google) is arguably the most underrated tool in this list. Upload your user interview transcripts, competitor analyses, and brief documents — and NotebookLM turns them into a conversational knowledge base. Ask it "What are the top pain points users mentioned?" and it surfaces patterns from your own data instantly.

Website: notebooklm.google.com · Free

Perplexity functions as an AI-powered search engine that cites every source. Use it for competitive research, industry benchmarks, and quick fact-checking. Unlike Google, it gives synthesized answers — not a list of links to click through.

Website: perplexity.ai · Free · Pro $20/month

Claude (by Anthropic) excels at processing large documents and extracting structured insights. Feed it a 50-page brand guideline and ask: "Summarize the core brand values and list any design constraints mentioned." Done in seconds.

Website: claude.ai · Free · Pro $20/month

Pro tip:
Paste raw user interview notes into Claude and ask it to generate an affinity map grouped by theme. It won't replace your synthesis, but it gives you a first draft to react to — which is always faster than starting from a blank page.

Stage 2: Ideation & Concept Development

Tools: Midjourney, GPT Image 2, Claude, Galileo AI

This is where AI truly shines. Ideation sessions that used to take a full day can now happen in a focused hour.

For visual direction (art-first):
Use Midjourney to generate 10–15 mood board images in different styles before committing to a visual direction. Show clients real imagery, not vague descriptions. This transforms early alignment conversations.

Website: midjourney.com

For conceptual visuals with intent (reasoning-first):
Use GPT Image 2 when you need visuals that communicate why a design works — not just what it looks like. GPT Image 2 is especially strong at translating product goals, UX context, and narrative intent into coherent visual concepts.

It excels at:

• Product hero illustrations tied to user psychology
• Feature explanation visuals
• Early UI concept art grounded in hierarchy and layout logic

If Midjourney helps you explore stylistic possibilities, GPT Image 2 helps you anchor visuals in purpose and meaning.

For UX concepts:
Use Claude to brainstorm user flows, sitemap structures, and feature sets. Prompt it with: "We're designing a mobile app for independent yoga instructors. List 5 different approaches to the onboarding flow, each solving the key friction of getting instructors to publish their first class."

Website: claude.ai · Free · Pro $20/month

Galileo AI specializes in converting concept descriptions directly into UI screens. Describe your app, specify the visual style, and get editable Figma-ready screens in under a minute.

Website: usegalileo.ai · Waitlist / Limited access

Pro tip:
Use AI for divergent thinking (many ideas) and your own judgment for convergent thinking (choosing the right idea). AI generates options — you decide which ones are actually worth pursuing.

Stage 3: Design & Production

Tools: Figma Make, Adobe Firefly, Canva AI, Uizard

This is where most designers first encounter AI — and where it has the clearest time savings.

Figma Make handles UI generation from prompts. Describe a screen and get a working layout that uses your actual design system components. Use it to rapidly produce the first draft of every screen, then refine manually.

Website: figma.com/make

Adobe Firefly removes the most tedious production tasks. Background removal, generative fill for mockup photography, and creating asset variations for different formats — all done in seconds. If you're preparing a presentation with multiple device mockups, Firefly can generate custom background scenes for each one.

Website: firefly.adobe.com

Uizard is excellent for quickly wireframing full user flows. You can upload a rough hand-drawn sketch and it converts it to a digital wireframe. Great for collaborative sessions where not everyone is in Figma yet.

Website: uizard.io · Free · Pro $12/month

Pro tip:
Treat AI-generated UI as a starting point, not a final output. The value is in getting 70% of the way there instantly — your expertise handles the last 30% that actually makes it great.

Stage 4: Content & Copywriting

Tools: Claude, Jasper

Empty wireframes kill presentation quality. AI-generated copy fills them with real, purposeful content from day one.

Claude is the strongest option for UX writing. Give it context: "Write microcopy for an empty state screen in a task management app for remote teams. Tone: friendly, motivating, not condescending. Keep it under 20 words." The results are immediately usable or very close.

Website: claude.ai/new

Jasper is built for marketing-focused copy — product descriptions, landing page headlines, and CTAs. For Graphic Designers creating social media or ad campaigns, Jasper can draft multiple copy directions in the time it takes to open a new document.

Website: jasper.ai · from $49/month

Pro tip:
Always brief the AI with tone of voice, target audience, and word limit. Generic prompts produce generic copy. Specific prompts produce first-draft-ready copy.

Stage 5: Testing & Validation

Tools: UX Pilot, Attention Insight

One of the most exciting applications of AI is predicting how users will interact with your designs — before you run a single usability test.

UX Pilot includes predictive heatmaps that simulate where users will focus attention on any screen. Upload your design and get a visual attention map that reveals potential UX issues early. It also has an automated Design Review Bot that catches accessibility contrast issues and layout inconsistencies.

Website: uxpilot.ai · Free · from $12/month

Attention Insight is purpose-built for predictive eye-tracking. Upload any design — web page, app screen, poster, ad — and get a heatmap showing where the eye goes first. Critical for validating visual hierarchy and CTA placement.

Website: attentioninsight.com · Free trial · from $29/month

Pro tip:
Run a predictive heatmap before every client presentation. It lets you speak confidently about design decisions backed by data, not just instinct.

Stage 6: Handoff & Documentation

Tools: Figma AI, Claude

Handoff documentation is often the most neglected part of the design process — and AI makes it significantly less painful.

Use Figma AI to auto-generate design documentation, summarize component behavior, and organize design tokens. Use Claude to convert your design notes into structured developer specs: paste your rough notes and ask it to format them as a clean technical brief.

Pro tip:
Ask Claude to write the "Design Decisions" section of your handoff doc. Describe what you built and why, and it will turn your bullet points into clear, professional documentation your developers will actually read.

The Full Workflow at a Glance

Up next in Part 3: The real skill unlock — how to write better AI prompts as a designer, so you stop getting mediocre outputs and start getting exactly what you need. → https://shiftasia.com/community/p/a43e1385-2e0a-479d-8a1b-eb2c7990c30e/

Popular AI Tools That Help Designers Work Faster and Smarter

The design industry is shifting fast. According to Figma's 2025 AI Report, 78% of designers say AI has noticeably improved their work efficiency. The question is no longer "should I use AI?" — it's "which tools are actually worth my time?"

This article breaks down the most popular AI tools right now, what they're genuinely good at, and how you as a designer can plug them into your workflow starting today.

1. Midjourney — Best for Visual Ideation & Image Generation

Website: midjourney.com

Pricing: Basic $10/month · Standard $30/month

Midjourney remains the gold standard for generating high-quality images from text prompts. Whether you need a mood board, concept art, hero visuals, or brand imagery — Midjourney can produce stunning results in seconds.

Key strengths:

• Exceptional image quality across styles: realism, illustration, editorial, abstract
• Fine-tune with parameters like --ar (aspect ratio), --style, --chaos, --v6
• Large community = tons of public prompts to learn from and remix
• New web app (no more Discord required) — use it straight from your browser

Best for: Graphic Designers needing unique visuals, mood boards, campaign imagery, or brand concept exploration.

Pro tip:
Describe the mood, not just the object. "A minimalist workspace bathed in golden afternoon light, soft shadows, editorial photography" gives far better results than "a desk photo."

GPT Image 2 — Best for Conceptual Image Creation & Visual Reasoning
Website: openai.com
Pricing: Included in ChatGPT Plus / Team / Enterprise

If Midjourney is art-first, GPT Image 2 is reasoning-first.

GPT Image 2 excels at generating images that are grounded in design intent, context, and visual logic — not just aesthetics. It understands hierarchy, layout, narrative, and purpose, making it especially useful at the concept and early exploration stage.

Key strengths:

• Deep understanding of design briefs, UX context, and visual hierarchy
• Generates concept visuals that align with product goals, not just style
• Maintains consistency across iterative prompts and multi-step explorations
• Explains the why behind composition, color, and structure

Best for:
UI/UX Designers, Product Designers, and Visual Designers who need concept imagery with clear reasoning and intent — especially for product storytelling, feature illustrations, and early-stage ideation.

Pro tip:
Prompt GPT Image 2 the way you’d brief a senior designer:

“Create a product hero illustration that communicates speed and trust for a fintech app used by young professionals. Minimal composition, strong focal point, calm color palette.”

✅ If Midjourney shows you what’s possible, GPT Image 2 helps you understand why it works.

2. Adobe Firefly — Best for Designers Already in the Adobe Ecosystem

Website: firefly.adobe.com

Pricing: Included with Adobe Creative Cloud · from $20.99/month

Firefly lives inside Photoshop, Illustrator, and Adobe Express. You don't switch tools — the AI comes to you. The standout feature is Generative Fill: select any area of an image, type what you want, and Photoshop generates it seamlessly.

Key strengths:

• Generative Fill: remove objects, extend backgrounds, add new elements naturally
• Commercially safe outputs — trained on licensed and public domain content
• Mood board generation, layout alternates, and UI component variations
• Tight integration means zero workflow disruption

Best for: UI/UX and Graphic Designers already working in Photoshop or Illustrator who want AI power without changing tools.

Pro tip:
Use Generative Fill to quickly create device mockup backgrounds and lifestyle imagery for your UI presentations — no stock photo subscription needed.

3. Figma AI & Figma Make — Best for UI/UX Designers

Website: figma.com/ai

Pricing: Included in Figma Professional · from $15/month per editor

Figma Make (launched 2025) is a game changer for UI designers. Describe an interface in plain language and it generates complete, editable UI screens — aware of your team's existing design system, components, and tokens.

Key strengths:

• Understands your design system — outputs stay on-brand from the first generation
• Generate UI from text prompts, screenshots, or hand-drawn sketches
• AI suggests UX copy, renames layers, and searches files with natural language
• Exports clean HTML/CSS code for developer handoff

Best for: UI/UX Designers who want to go from idea to working prototype in minutes without leaving Figma.

Pro tip:
Feed Figma Make a competitor's screenshot and ask it to "redesign this in our design system" — it's a fast way to explore UI directions during the early discovery phase.

4. Canva Magic Studio — Best for Graphic Designers Needing Speed

Website: https://www.canva.com/ai

Pricing: Free · Pro $15/month · Teams $10/person/month

Canva's Magic Studio bundles multiple AI features into one familiar interface: Magic Design auto-generates layouts, Magic Write handles copywriting, Magic Edit lets you change image content by describing it, and the Background Remover works with one click.

Key strengths:

• Magic Design: upload a logo or describe your brand → instantly get layout options
• Brand Kit AI: automatically applies your brand colors, fonts, and logo to everything
• Batch-export all social media sizes in one action
• Low learning curve — powerful even for non-technical designers

Best for: Graphic Designers producing high-volume marketing assets — social media content, presentations, event materials.

Pro tip:
Use the "Bulk Create" feature with Magic Write to produce 20 social media variations from a single brief. What used to take a day now takes 20 minutes.

5. Google Stitch — Best New Tool for Rapid UI Prototyping

Website: stitch.withgoogle.com

Pricing: Free (currently in Google Labs beta)

Google Stitch (relaunched March 2026 with a major overhaul) uses Gemini 2.5 Pro to convert text prompts, images, or rough sketches into complete, high-fidelity UI screens. Exports directly to Figma with intact layers. One of the most powerful prompt-to-UI tools available right now.

Key strengths:

• Infinite canvas — mix text descriptions, reference images, and code snippets as inputs
• Two generation modes: Standard (350 screens/month) and Experimental (higher quality, 50 screens/month)
• Figma export preserves layer structure — ready to refine immediately
• Voice input (preview): describe design changes hands-free

Best for: UI/UX Designers who want the fastest possible path from concept to clickable prototype.

Pro tip:
Don't just describe UI — describe the user: "A busy parent checking their child's school app in 30 seconds." The more context you give, the more purposeful the output.

6. Claude Design — Best for Full-Cycle Visual Collaboration ? Just Launched

Website: claude.ai/design

Pricing: Claude Pro $20/month

Launched: April 17, 2026 — Anthropic Labs

If there's one tool that just changed the conversation, it's this one. Anthropic launched Claude Design as an experimental product that lets users create interactive prototypes, slides, wireframes, one-pagers, and marketing collateral entirely through conversation. No template-picking, no manual setup — you brief it like a senior designer and it builds.

What separates Claude Design from every other AI design tool is the reasoning layer underneath. It's powered by Claude Opus 4.7, Anthropic's most capable vision model, and it doesn't just generate visuals — it explains its design decisions, responds to critique, and iterates with you through natural dialogue.

Key strengths:

• Brand-aware from day one: During onboarding, Claude reads your codebase and design files to automatically build your team's design system — colors, typography, components all loaded in before you start
• Conversational refinement: Refine outputs through conversation, inline comments, direct edits, or custom sliders Claude builds specifically for your project
• Full use case coverage: Wireframes and mockups, design explorations, pitch decks, marketing collateral, and frontier design with code-powered prototypes supporting voice, video, shaders, and 3D
• The complete handoff loop: When a design is ready to build, Claude packages everything into a handoff bundle you pass to Claude Code with one instruction — from exploration to production code without leaving the ecosystem
• Export anywhere: Share as internal URL, export to Canva, PDF, PPTX, or standalone HTML

Real-world proof: Datadog's product team compressed what had been a week-long cycle of briefs, mockups, and review rounds into a single conversation. Brilliant (the EdTech company) reported that their most complex pages needed only 2 prompts in Claude Design versus 20+ in competing tools.

Honest take: Claude Design is not a replacement for Figma in production work. Think of it as the most powerful ideation and alignment tool you've ever had — the place where ideas become visible fast enough to get real feedback, before you invest hours of craft in the wrong direction.

Pro tip:
Start every new project brief in Claude Design before opening Figma. Generate 5–8 different visual directions in 30 minutes, pick the strongest one, then move into Figma for precision work. You'll stop second-guessing direction choices because you'll have already seen them side by side.

Quick Reference — Which Tool for What?

Up next in Part 2: How to actually apply these tools across every stage of the design process — from research to final handoff. https://shiftasia.com/community/p/2d4517e9-03e5-4e05-9d83-5c1a9c54d4b0/

The Hidden Foundation That Powers Every Query You Run

When you write SELECT * FROM Users WHERE Id = 42, you probably think about tables, rows, and indexes.

But long before your row reaches the execution engine, the database engine has already performed a crucial step: it read one or more 8 KB (or 16 KB) chunks from disk called pages (or blocks).

These pages are the real physical building blocks of every major relational database. Understanding them is the difference between guessing why a query is slow and knowing exactly why.

What Exactly Is a Page (or Block)?

A page is the smallest unit of data that a database reads from or writes to disk in a single I/O operation.

Think of it like this:

• You ask for one sentence from a book.
• The librarian doesn’t hand you just that sentence.
• She hands you the entire page the sentence lives on.

That’s exactly how databases work.

Anatomy of a Typical Data Page (SQL Server Example)

An 8 KB SQL Server data page looks like this in memory/disk:

+--------------------------------------------------+
| Page Header                  96 bytes           |
+--------------------------------------------------+
| Data Rows                    variable           |
| (actual table records)                           |
+--------------------------------------------------+
| Free Space                   variable           |
+--------------------------------------------------+
| Row Offset Array             2–4 bytes per row  |
| (pointers to start of each row, at end of page) |
+--------------------------------------------------+
Total = exactly 8192 bytes

The 96-byte header contains:

• Page number (Page PID)
• Previous/next page pointers (for heap or clustered index)
• Page type (data, index, LOB, IAM, etc.)
• Free space available
• Checksum (if enabled)
• LSN (Log Sequence Number)

Different Types of Pages

Not all pages store regular table rows.

Why Page Size Directly Affects Your Database Design

1. Maximum Row Size

   SQL Server: ~8,060 bytes per row

   → Because a row must fit on a single data page (minus header and offset array).

   → Anything larger → automatically moved to LOB/row-overflow pages.

2. Wide Tables Force More Pages → More I/O

   A table with 10-byte rows can store ~800 rows per page.

   A table with 7,000-byte rows stores only 1 row per page → 800× more I/O.

3. Index Depth

   Smaller page size = more levels in B-tree = slower seeks.

   That’s one reason MySQL InnoDB moved from 8 KB → 16 KB default.

The Dreaded Page Split

Imagine a page that is 98% full. You insert or update a row that no longer fits.

What happens?

1. Database allocates a brand-new page.
2. Roughly half the rows move to the new page.
3. Both pages are now ~50% full.
4. Physical order on disk may now be fragmented.

Result:

• Wasted space (internal fragmentation)
• Slower range scans (external fragmentation)
• Heavy write amplification

This is why DBAs obsess over fillfactor and rebuild/reorganize indexes.

Real-World Performance Examples

How to See Pages in Action

SQL Server

-- See what is actually on a page (undocumented but safe)
DBCC TRACEON(3604);                    -- redirect output to SSMS
DBCC PAGE ('YourDatabase', 1, 12345, 3); -- file 1, page 12345, style 3

PostgreSQL

-- Install and use pageinspect extension
CREATE EXTENSION pageinspect;
SELECT * FROM page_header(get_raw_page('users', 0));

Oracle

-- Dump a block
ALTER SYSTEM DUMP DATAFILE 4 BLOCK 42;

MySQL InnoDB

-- Use innodb_ruby or Percona’s tools
innodb_space -f data/ibdata1 page-dump 100

Best Practice Checklist Based on Page Knowledge

Immutability is a core concept in programming where an object or data structure cannot be modified after it is created. In contrast, mutable objects can be altered post-creation. Immutability plays a pivotal role in writing robust, predictable, and maintainable code, particularly in modern JavaScript applications. This article explores why immutability is important, when to use immutable versus mutable data, and how to implement immutability in JavaScript with practical examples and relevant libraries.

Why is Immutability Important?

Immutability offers several benefits that make it a cornerstone of reliable software design:

1. Thread Safety and Concurrency: Immutable objects are inherently thread-safe because their state cannot change. In JavaScript, which is single-threaded but often handles asynchronous operations (e.g., via promises or async/await), immutability prevents unexpected state changes in shared data across asynchronous tasks.

2. Predictability and Debugging: Immutable data ensures that a value remains consistent throughout its lifecycle. This eliminates side effects, making it easier to reason about code and debug issues. For example, if a function receives an immutable object, you can trust it won’t be modified unexpectedly elsewhere.

3. Functional Programming: Immutability is a key principle in functional programming, enabling pure functions that always produce the same output for the same input. This leads to cleaner, more composable code, as seen in frameworks like React or Redux.

4. Data Integrity: In applications where data consistency is critical (e.g., financial systems or configuration management), immutability prevents accidental or unauthorized changes.

5. Efficient Caching: Since immutable objects don’t change, they can be safely cached or used as keys in hash-based structures (e.g., JavaScript Map or Set) without worrying about state changes affecting their hash.

6. Simplified State Management: In front-end development, immutability simplifies state management in libraries like Redux, where state changes are handled by creating new state objects rather than modifying existing ones.

However, immutability comes with trade-offs. Creating new objects for every change can increase memory usage and impact performance in scenarios requiring frequent updates. Understanding when to use immutable versus mutable data is crucial.

When to Use Immutable vs. Mutable Data

When to Use Immutable Data

• Fixed or Constant Data: Use immutability for data that shouldn’t change, such as configuration settings, user IDs, or API response snapshots.
• Concurrent or Asynchronous Code: Immutability prevents race conditions in asynchronous JavaScript code, such as when handling multiple API calls or event listeners.
• Functional Programming: When writing pure functions or working with libraries like Redux, immutability ensures predictable behavior.
• Hash Map Keys: Immutable objects are ideal as keys in Map or Set because their values (and hash codes) remain constant.
• Shared Data: When passing data between components or modules, immutability prevents unintended modifications.
• Critical Systems: In domains like finance or security, immutability ensures data integrity for records like transactions or audit logs.

When to Use Mutable Data

• Frequent Updates: If an object’s state changes often, mutability avoids the overhead of creating new objects. For example, updating an array in place is faster than creating a new one.
• Performance-Critical Applications: In scenarios where memory or CPU efficiency is critical (e.g., real-time games), mutable objects reduce overhead.
• Modeling Dynamic State: For objects representing real-world entities that change, like a game character’s position or a shopping cart’s contents.
• Temporary Data: Mutable objects are suitable for intermediary or scratchpad data during computations, such as sorting an array.
• Single-Threaded Contexts: In JavaScript’s single-threaded environment, mutability is often safe for local, non-shared data.

Immutability in JavaScript

JavaScript does not enforce immutability by default, but it provides tools and patterns to achieve it. Below, we explore how to implement immutability using native JavaScript features and popular libraries, with practical examples.

Native JavaScript Immutability

JavaScript offers several ways to enforce or simulate immutability:

1. Object.freeze(): Prevents modifications to an object’s properties.
2. const: Prevents reassignment of a variable (though the object’s properties can still be mutated).
3. Spread Operator (...): Creates shallow copies of objects or arrays for non-mutating updates.
4. Array Methods: Methods like map, filter, and slice return new arrays without modifying the original.

Example 1: Using Object.freeze()

const user = Object.freeze({
  id: 1,
  name: "Alice",
  address: { city: "New York" }
});

// Attempting to modify the object throws an error in strict mode
user.name = "Bob"; // Fails silently (or throws in strict mode)
console.log(user.name); // "Alice"

// Note: Object.freeze is shallow; nested objects can still be modified
user.address.city = "Boston"; // Works!
console.log(user.address.city); // "Boston"

// For deep immutability, use a deep freeze function
function deepFreeze(obj) {
  Object.getOwnPropertyNames(obj).forEach(name => {
    const prop = obj[name];
    if (typeof prop === "object" && prop !== null) {
      deepFreeze(prop);
    }
  });
  return Object.freeze(obj);
}

const deepUser = deepFreeze({ id: 2, name: "Charlie", address: { city: "Seattle" } });
deepUser.address.city = "Portland"; // Fails silently (or throws in strict mode)
console.log(deepUser.address.city); // "Seattle"

Example 2: Using the Spread Operator

const cart = { items: ["apple", "banana"], total: 5 };

// Create a new cart with an added item
const updatedCart = {
  ...cart,
  items: [...cart.items, "orange"],
  total: cart.total + 2
};

console.log(cart.items); // ["apple", "banana"]
console.log(updatedCart.items); // ["apple", "banana", "orange"]

Example 3: Immutable Array Operations

const numbers = [1, 2, 3, 4];

// Non-mutating: map creates a new array
const doubled = numbers.map(n => n * 2);
console.log(doubled); // [2, 4, 6, 8]
console.log(numbers); // [1, 2, 3, 4] (original unchanged)

// Mutating: push modifies the original array
numbers.push(5);
console.log(numbers); // [1, 2, 3, 4, 5]

Libraries for Immutability

Several JavaScript libraries simplify working with immutable data, offering robust APIs and performance optimizations. Here are the most popular ones:

1.Immutable.js

• Description: Developed by Facebook, Immutable.js provides persistent immutable data structures like List, Map, and Set. It optimizes memory usage with structural sharing, where unchanged parts of a data structure are reused.
• Use Case: Ideal for complex state management in applications like React or Redux.
• Installation: npm install immutable
• Example:

import { Map, List } from "immutable";

// Create an immutable map
let user = Map({ id: 1, name: "Alice", hobbies: List(["reading", "gaming"]) });

// Update immutably
let updatedUser = user.set("name", "Bob").update("hobbies", hobbies => hobbies.push("coding"));

console.log(user.get("name")); // "Alice"
console.log(updatedUser.get("name")); // "Bob"
console.log(updatedUser.get("hobbies").toArray()); // ["reading", "gaming", "coding"]

2.Immer

• Description: Immer simplifies immutability by allowing you to write “mutative” code that produces immutable results. It uses a draft state that you can modify, and Immer creates a new immutable object behind the scenes.
• Use Case: Great for Redux or React state updates where you want readable, mutative-style code without manual copying.
• Installation: npm install immer
• Example:

 import produce from "immer";

 const state = { user: { name: "Alice", age: 30 }, items: ["apple"] };

 const newState = produce(state, draft => {
   draft.user.name = "Bob"; // Mutate draft safely
   draft.items.push("banana");
 });

 console.log(state.user.name); // "Alice" (original unchanged)
 console.log(newState.user.name); // "Bob"
 console.log(newState.items); // ["apple", "banana"]

3.Seamless-Immutable

• Description: A lightweight library that provides immutable data structures with a simple API. It wraps native JavaScript objects and arrays to prevent mutations.
• Use Case: Suitable for projects needing lightweight immutability without the complexity of Immutable.js.
• Installation: npm install seamless-immutable
• Example:

import SeamlessImmutable from "seamless-immutable";

const state = SeamlessImmutable({ user: { name: "Alice" }, items: ["apple"] });

// Update immutably
const newState = state.merge({ user: { name: "Bob" }, items: [...state.items, "banana"] });

console.log(state.user.name); // "Alice"
console.log(newState.user.name); // "Bob"
console.log(newState.items); // ["apple", "banana"]

4.Mori

• Description: A library that brings Clojure’s persistent data structures to JavaScript. It’s similar to Immutable.js but with a functional programming focus.
• Use Case: Best for functional programming enthusiasts or projects requiring Clojure-style data structures.
• Installation: npm install mori
• Example:

import mori from "mori";

let state = mori.hashMap("user", mori.hashMap("name", "Alice"), "items", mori.vector("apple"));

let newState = mori.assoc(state, "user", mori.assoc(mori.get(state, "user"), "name", "Bob"));
newState = mori.assoc(newState, "items", mori.conj(mori.get(newState, "items"), "banana"));

console.log(mori.get(state, "user").get("name")); // "Alice"
console.log(mori.get(newState, "user").get("name")); // "Bob"
console.log(mori.toJs(mori.get(newState, "items"))); // ["apple", "banana"]

Practical Example: Redux with Immutability

Redux, a popular state management library for React, enforces immutability for predictable state updates. Here’s an example of a Redux reducer using Immer for immutability:

import produce from "immer";

// Initial state
const initialState = {
  todos: [
    { id: 1, text: "Learn JavaScript", completed: false }
  ]
};

// Reducer with Immer
const todoReducer = produce((draft, action) => {
  switch (action.type) {
    case "ADD_TODO":
      draft.todos.push({ id: action.id, text: action.text, completed: false });
      break;
    case "TOGGLE_TODO":
      const todo = draft.todos.find(t => t.id === action.id);
      if (todo) todo.completed = !todo.completed;
      break;
  }
}, initialState);

// Example usage
const state1 = todoReducer(initialState, { type: "ADD_TODO", id: 2, text: "Learn Immutability" });
console.log(state1.todos); // [{ id: 1, ... }, { id: 2, text: "Learn Immutability", completed: false }]
console.log(initialState.todos); // [{ id: 1, ... }] (original unchanged)

const state2 = todoReducer(state1, { type: "TOGGLE_TODO", id: 1 });
console.log(state2.todos[0].completed); // true

Trade-offs and Best Practices

• Performance: Immutability can increase memory usage due to creating new objects. Libraries like Immutable.js and Immer use structural sharing to mitigate this, but for performance-critical applications, profile memory usage carefully.
• Learning Curve: Libraries like Immutable.js or Mori have a steeper learning curve due to their unique APIs. Immer is more beginner-friendly as it allows mutative-style code.
• Shallow vs. Deep Immutability: Native Object.freeze() is shallow, so nested objects can still be mutated. Use deep-freezing functions or libraries for full immutability.
• Choose the Right Tool: Use native JavaScript (spread operator, Object.freeze) for simple cases. For complex state management, consider Immer or Immutable.js.

Conclusion

Immutability is a powerful concept that enhances code reliability, predictability, and safety, particularly in asynchronous JavaScript applications, functional programming, and state management. By using native features like Object.freeze and the spread operator, or libraries like Immutable.js, Immer, Seamless-Immutable, or Mori, developers can enforce immutability effectively. Choose immutability for fixed data, concurrent systems, or critical applications, and opt for mutability when performance or frequent updates are priorities. Understanding these trade-offs and leveraging the right tools will help you write robust, maintainable JavaScript code.

For further exploration, check out the official documentation:

• Immutable.js
• Immer
• Seamless-Immutable
• Mori

By mastering immutability, you can build more predictable and scalable JavaScript applications, whether you’re managing state in a React app or handling complex data transformations.

When working with databases, writing a query is only half the battle. Understanding how that query actually executes is crucial for optimizing performance and building efficient applications. This is where SQL execution plans come into play—they're your window into the database engine's decision-making process.

What is an Execution Plan?

An execution plan is essentially a roadmap that shows how the database engine processes your SQL query. Think of it like a recipe: it breaks down the query into discrete steps, showing the order of operations, which indexes are used, how tables are joined, and the estimated cost of each operation.

The database query optimizer generates this plan by analyzing multiple possible strategies and selecting what it believes to be the most efficient approach based on statistics about your data, available indexes, and system resources.

Why Execution Plans Matter

Performance issues in database applications often stem from inefficient queries rather than hardware limitations. A query that takes seconds instead of milliseconds can cripple an application's responsiveness. Execution plans help you identify bottlenecks like table scans on large tables, missing indexes, inefficient join strategies, or outdated statistics that lead the optimizer astray.

By examining execution plans, you can transform a query from unusable to lightning-fast, often with minor adjustments to indexes or query structure.

Types of Execution Plans

There are two primary types of execution plans you'll encounter:

Estimated Execution Plans show what the optimizer predicts will happen without actually running the query. These are generated quickly and are useful for examining query structure without the overhead of execution. However, they're based on statistics and assumptions that may not reflect reality.

Actual Execution Plans capture what really happened during query execution. These include actual row counts, execution times, and resource usage. While they require running the query, they provide the truth about performance and can reveal discrepancies between what the optimizer predicted and what actually occurred.

How to View Execution Plans

The method varies by database system, but most provide straightforward ways to access plans:

In SQL Server, you can prefix your query with SET SHOWPLAN_ALL ON or use SQL Server Management Studio's "Display Estimated Execution Plan" and "Include Actual Execution Plan" buttons. These generate graphical representations that are intuitive to read.

PostgreSQL users can add EXPLAIN before any query to see the plan, or EXPLAIN ANALYZE to get the actual execution plan with timing information. The output is text-based but highly detailed.

MySQL offers the EXPLAIN keyword similarly, showing information about table access methods and join types. Oracle provides EXPLAIN PLAN FOR followed by your query, with results viewable through specific system tables.

Reading an Execution Plan

Execution plans can seem overwhelming at first, but they follow logical patterns. Operations are typically displayed hierarchically, either top-to-bottom or left-to-right depending on your tool. The query optimizer processes operations in a specific order, often from the innermost operations outward.

Each operation in the plan includes valuable information: the operation type (like Index Seek, Table Scan, or Hash Join), estimated and actual row counts, estimated cost (usually shown as a percentage of the total query cost), and details about which objects (tables, indexes) are involved.

Common Operations You'll Encounter

Table Scan means the database reads every row in a table sequentially. This is expensive for large tables and often indicates a missing index. While acceptable for small tables, it's a red flag for tables with thousands or millions of rows.

Index Scan reads all entries in an index, which is typically faster than a table scan but still processes more data than necessary. It suggests the index exists but isn't being used optimally.

Index Seek is what you want to see—the database uses an index to jump directly to relevant rows. This is highly efficient and indicates good index utilization.

Nested Loop Join processes one row from the outer table and finds matching rows in the inner table, repeating for each outer row. This works well when the outer table is small or when good indexes exist on the join columns.

Hash Join builds a hash table from one input and probes it with the other. This is efficient for large datasets without suitable indexes.

Merge Join requires both inputs to be sorted on the join keys, then merges them together. This is very efficient when data is already sorted or when indexes provide sorted output.

Key Metrics to Monitor

The cost estimate represents the optimizer's prediction of resource usage. Higher percentages indicate operations consuming more resources relative to the total query. Focus optimization efforts on the highest-cost operations.

Row counts reveal how many rows each operation processes. Large discrepancies between estimated and actual counts suggest outdated statistics, which can lead the optimizer to choose poor strategies.

I/O statistics show how much data is read from disk versus memory. High physical reads indicate the query is hitting disk frequently, suggesting opportunities for better indexing or memory configuration.

Practical Optimization Strategies

When you identify a table scan on a large table, adding an appropriate index often provides dramatic improvement. The index should cover the columns in your WHERE clause, JOIN conditions, and ideally your SELECT columns too.

If the optimizer chooses a plan different from what you expect, updating statistics can help. Statistics become stale as data changes, causing the optimizer to make decisions based on outdated information. Most databases provide commands to update statistics manually or can be configured to update them automatically.

Sometimes rewriting the query itself produces better results. Breaking complex queries into smaller steps with temporary tables, reformulating subqueries as joins, or using common table expressions can all influence the execution plan positively.

Advanced Considerations

Query hints allow you to override the optimizer's decisions when you have specific knowledge it lacks. However, use these sparingly—they can backfire when data patterns change, and they prevent the optimizer from adapting to new conditions.

Parameter sniffing occurs when the optimizer creates a plan based on the first parameter values it sees, which may not be optimal for other values. This can cause the same query to perform differently with different parameters.

Parallelism allows the database to split operations across multiple processors. While this can dramatically speed up large queries, it adds overhead and isn't always beneficial for smaller operations.

Real-World Example

Consider a query that searches for orders from a specific customer in the last month. Without an index, the execution plan might show a table scan reading millions of order records. After adding a composite index on customer ID and order date, the plan changes to an index seek, reading only the relevant hundreds of records—a transformation from seconds to milliseconds.

Best Practices

Make execution plan analysis a regular part of your development workflow. Review plans for all important queries before deploying to production. Monitor production queries and regularly examine the most expensive ones. Keep database statistics current through regular updates or automatic maintenance. Test queries with realistic data volumes, as execution plans can differ dramatically between empty development databases and production systems with millions of rows.

Conclusion

Execution plans are your most powerful tool for understanding and optimizing database query performance. While they can seem complex initially, learning to read them transforms database optimization from guesswork into a systematic process. The investment in understanding execution plans pays dividends in faster applications, lower resource costs, and more scalable systems. Start with simple queries, gradually build your interpretation skills, and you'll soon find yourself instinctively recognizing inefficient patterns and knowing exactly how to fix them.

This blog will introduce an innovative AI approach that combines learning new knowledge and learning before forgetting to help models adapt to new information while discarding outdated or sensitive data. This method is called Knowledge Swapping and together we will explore how it works through the agenda below:

1. Introduction
2. Learning and Unlearning in AI
3. Knowledge Swapping & Architecture
4. Apply to projects
5. Conclusion

I - Introduction

In recent days, AI has been growing rapidly across many fields including chatbots, warning systems, and forecasting applications. Most people expect AI systems to perform well and deliver high accuracy, which requires training on massive datasets that' a critical factor for success. However, this creates a major challenge: AI models tend to retain everything they learn, making it difficult to remove outdated, biased, or sensitive information once it has been absorbed.

1. Privacy data

AI systems must be able to remove sensitive or copyrighted data that they do not have permission to use. This requirement is reinforced by global regulations such as the General Data Protection Regulation (GDPR), which came into effect in Europe in 2018. A real-world example is the lawsuit filed by The New York Times against OpenAI, alleging copyright violations due to training on NYT articles without authorization. These cases highlight the growing need for mechanisms like machine unlearning to ensure compliance and protect both privacy and intellectual property

2. Bias

Most AI models are trained on historical datasets that can quickly become outdated. This lack of timely updates often results in lower model quality and inaccurate forecasts, especially in dynamic fields such as finance, healthcare, and technology. Without effective strategies to refresh or replace obsolete knowledge, AI systems risk making decisions based on stale information.

3. High cost

Because training a state-of-the-art AI model requires substantial resources including millions of dollars and months of computation, retraining a model from scratch every time accuracy drops or data needs to be removed is impractical. Instead, emerging techniques such as machine unlearning and knowledge swapping provide cost-effective solutions to update models without starting over.

Before diving into the details, the diagram below illustrates the relationship between Continual Learning, Machine Unlearning, and Knowledge Swapping.

II - Learning to Unlearn

In this section, we will explore key concepts in Artificial Intelligence (AI) that revolve around how systems learn, adapt, and even forget information.

1. What is Machine Learning (ML)?

Machine learning is an exciting field and a core subset of artificial intelligence. It empowers systems to learn from data and improve over time without being explicitly programmed.
Instead of hardcoding rules, ML algorithms identify patterns and make predictions or decisions based on experience.
You can continue read more about ML here.

2. What is Continuous Learning (CL)?

Opposite with traditional ML, when new data arrives, the model typically needs to be re-trained from scratch or fine-tuned on the updated dataset. CL are designed to learn incrementally from new data without full retraining. Instead of starting over, they update their parameters as new samples arrive. This is often implemented using online learning or incremental learning techniques.

CL is important because of CL will enables models to:

• Adaptability: Learn from new data in real time without full retraining.
• Retention of Information: Avoid catastrophic forgetting by preserving past knowledge.
• Generalization: Stay robust and accurate as environments evolve and data distributions shift.

These are common categories of methods used in CL models:

• Regularization-Based methods: To prevent catastrophic forgetting, a penalty term is added to the loss function during training on the new data.
  Example: Elastic Weight Consolidation (EWC), Synaptic Intelligence (SI), L2 Regularization, ...
• Memory-Based methods: To maintain good performance on old data, memory-based methods store or replay data from previous data in a memory buffer.
  Example: Biased Memory Keeping Protocol (BMKP), ...
• Architecture-Based methods: To expand models and adapt to newly arriving data.
  Example: Progressive Neural Networks, Dynamic Expansion, Parameter Isolation, ...

3. What is Machine Unlearning (MU)?

MU is the process of removing the influence of specific data points such as sensitive or incorrect data from a trained model without retraining from scratch.

The Importance of Machine Unlearning:

• Legal: Organizations must comply with requests to remove personal data from models. Regulations like the General Data Protection Regulation (GDPR) in the European Union grant individuals the “right to be forgotten.”
• Privacy compliance: This establishes a positive image of the organization in the eyes of the public. Building trust and transparency, establishing a positive image of the organization in the eyes of the public.
• Security: This reduces risk from leaked, malicious, or compromised data. Removing certain data points from a trained machine-learning model without needing to retrain the entire model from scratch
• Correctness: helps fix errors efficiently, ensuring models remain accurate and reliable without costly full retraining.

These MU approaches:

• Fine-Tuning: Retrain the model on the remaining data after removing the target samples. here
• Influence Function: Estimate how much a training point influences the model’s parameters or predictions using second-order derivatives.
• NegGrad+: To balance the retention of useful knowledge with the removal of influence from the target data
• L1-Sparse: Use L1 regularization to enforce sparsity when adjusting parameters, minimizing unnecessary changes by driving insignificant weights toward zero.
• Relabeling: Change labels of removed data to neutral or random values before retraining, reducing their influence.

III - Knowledge Swapping

Knowledge Swapping refers to the process of suppressing redundant parameters, selectively retaining crucial parameters, and acquiring new knowledge simultaneously within a pre-trained model. This technique enables models to adapt without full retraining while ensuring compliance with privacy and correctness requirements.

There are three core aims: Forgetting old data, Retaining useful knowledge, Learning new data. And knowledge swapping involves two main processes: learning and forgetting.

• Forget: Remove unwanted or sensitive knowledge from the model.
• Retain: Preserve useful knowledge that is still relevant for future tasks.
• Learn: Introduce new or clean knowledge from a trusted source.

There are two key strategies define the architecture of Knowledge Swapping:

• Forgetting before Learning ( F → L): Forget old data first, then learn new data.
• Learn before Forget (L → F): Learn new data first, then forget old data.

Comparing between F → L and L → F of Knowledge Swapping:

In summary, L → F demonstrates higher parameter stability and achieves nearly complete forgetting (accuracy close to 0%), while F → L often struggles with full forgetting and shows accuracy rebound after learning.

V - Apply to projects

Knowledge Swapping is not just a theoretical concept, it offers practical solutions for real-world AI challenges. Below are key areas where this approach can be applied:

1. Image classification

In computer vision projects, models often need to adapt to new categories or remove outdated ones. For example, an e-commerce platform may need to add new product classes while removing discontinued items. Knowledge Swapping enables this update without retraining the entire model, saving time and cost.

2. Object detection

Autonomous driving systems or surveillance applications frequently encounter changes in object sets (e.g., new traffic signs or removal of obsolete ones). Knowledge Swapping allows models to integrate these changes efficiently while maintaining detection accuracy.

3. Semantic segmentation

Healthcare imaging or geographic mapping projects require precise segmentation of regions. When new labels are introduced or old ones become irrelevant, Knowledge Swapping helps update the segmentation model without catastrophic forgetting, ensuring consistent performance.

VI - Conclusion

To summarize, Knowledge Swapping, as introduced by Mingyu Xing et al., is a significant step toward building robust and adaptive AI models. By prioritizing learning before forgetting, this approach effectively addresses critical challenges in real-world applications without requiring full retraining. This makes Knowledge Swapping a practical and forward-thinking solution for modern AI systems.

Documents

1. Knowledge Swapping via Learning and Unlearning
2. GitHub Knowledge Swapping
3. How to Make AI 'Forget' All the Private Data It Shouldn't Have
4. Learn to Unlearn: A Survey on Machine Unlearning
5. How to Choose and Build the Right Machine Learning Model
6. Fine-tuning vs. Prompt-tuning: When to Use Which

Vector databases and embeddings have become core infrastructure for AI applications–search, RAG, recommendations, anomaly detection, and more. But while building a vector search system is straightforward, measuring its quality is not. Developers often optimize models, indexes, or parameters without proper evaluation, leading to misleading performance and poor user experience.

This article provides a clear framework for evaluating vector search quality, including metrics, datasets, and practical workflows you can apply immediately.

Why Vector Search Needs Proper Evaluation

Traditional keyword search can be tested with precision/recall and simple heuristics, but vector search is different:

• Results depend on embedding models.
• Index configurations affect accuracy vs speed.
• Relevant results may not be strictly "correct" or "incorrect".
• Real-world meaning similarity is subjective.

Without structured evaluation, you might ship a system that feels good in small tests but fails at scale

Key Metrics for Vector Search Quality

1. Recall@K (Most Common)
   Recall@K measures how many of the "true most similar" items are found within the top K results.
   - Recall@10 = proportion of correct neighbors found in the top 10.
   - Higher recall means your yndex retrieves results close to the brute-force (ground truth).
2. Precision@K
   Measures how many of the returned top-K results are actually relevant. This method is useful when you evaluation dataset contains multiple relevant answers instead of exact nearest neighbors.
3. Mean Reciprocal Rank (MRR)
   Focuses on where the first correct result appears.
   - High MRR = relevant items appear very early in the list.
   - Common in question-answer similarity search.
4. Normalized Discounted Cumulative Gain (NDCG)
   NDCG evaluates graded relevance:
   - Works when results are "somewhat relevant", "very relevant", etc.
   - Discounts results based on ranking position.
   Often used in recommendation systems and semantic search.
5. Latency and Throughput Metrics
   Quality is not only accuracy – performance matters.
   - P95/P99 latency
   - Queries per second (QPS)
   - Index build time
   - Memory usage
   A high-recall index is useless if it's too slow for production.

Evaluation workflow

1. Build or collect a ground-truth dataset
2. Generate embeddings
3. Compute brute-force ("gold standard") neighbors
4. Test different vector search configurations
5. Plot accuracy vs speed.

Sample Workflow

1. Install and import dependencies:

pip install chromadb sentence-transformers

from sentence_transformers import SentenceTransformer
import chromadb
import numpy as np

2.   Generate embeddings

model = SentenceTransformer("all-MiniLM-L6-v2")

documents = ["Apple fruit", "Orange fruit", "Carrot vegetable"]
doc_ids = ["doc1", "doc2", "doc3"]

embeddings = model.encode(documents).tolist()

3.   Create a Chroma collection and and documents

client = chromadb.Client()

collection = client.create_collection("fruits_collection")

collection.add(
    ids=doc_ids,
    documents=documents,
    embeddings=embeddings
)

4.   Query the collection

query = "I like fruits"
query_emb = model.encode([query]).tolist()

results = collection.query(
    query_embeddings=query_emb,
    n_results=2
)

print(results)

Example output:

{
    'ids': [["doc1", "doc2"]],
    'documents': [["Apple fruit", "Orange fruit"]],
    'distance': [[0.12, 0.15]]
}

5.   Evaluate Recall@K

ground_truth = [["doc1", "doc2"]]

predicted_ids = results["ids"]
recall = np.mean([len(set(pred) & set(gt))/len(gt)
                  for pred, gt in zip(predicted_ids, ground_truth)])
                
print("Recall@K: ", recall)

6.   Experiment with different settings

• Change embedding models
• Use different collection parameters (e.g., metric="cosine")
• Measure latency and accuracy trade-offs

import time
start = time.time()
collection.query(query_embeddings=query_emb, n_results=2)
print("Query latency: ", time.time() - start, "seconds")

Conclusion

Evaluating vector search quality is not just about picking the best embedding or the fastest index. It's about finding the best balance between:

• Accuracy
• Latency
• Memory
• Real-world relevance

A robust evaluation pipeline will ensure your vector search system stays reliable as your data and traffic scale.

Hey everyone! ? Ever wish you could build beautiful, fast web applications without touching a single line of JavaScript? If you're a Pythonista like me, you know the pain of having to switch context to front-end frameworks like React.

Well, I recently found a game-changer called Reflex (it used to be called Pynecone), and it lets you build your entire full-stack web app—front-end and back-end—all in pure, idiomatic Python. Seriously. It compiles your Python code into a modern React app!

What is Reflex?

Think of Reflex as a framework that gives you the best of both worlds: the simplicity and power of Python combined with the modern speed of a React front-end.

• Python Everywhere: Define your UI, your state, and your back-end logic—all in Python.
• Built-in State Management: Managing component state and events is super easy and intuitive.
• Ready-to-Go Components: It comes with a massive library of ready-made components, so you don't have to style everything from scratch.
• Fast Development: You can go from zero to a live app incredibly quickly.

Let's Build a Quick Demo App

To show you how easy it is to manage data and lists, we'll look at two common app patterns: a simple To-Do List and a basic Student List.

First things first, install Reflex and initialize a new project:

pip install reflex
reflex init

This sets up all the basic files you need.

Now, you define a list of tasks in Python, create an input field and a button, and Reflex takes care of updating everything in the browser when you add a new task. No JavaScript needed for dynamic updates!

What about handling more complex data, like a student list that needs to be loaded from a database? This is where Reflex's state management really shines.

No need to fuss with HTML table structure or CSS styling; you get a clean, professional-looking table right out of the box!

And here's an example of a Student List:

When your Python code starts the data-fetching process (which usually takes a moment), you simply flip a boolean state variable, say State.loading=True. Reflex automatically detects this change and lets you instantly swap the main content for a clean loading screen.

After you write the Python code for these demos, you just run reflex run, and your browser magic begins at http://localhost:3000!

Final Thoughts

Reflex can handle the complexity of the front-end, from state management to UI updates, so you can focus on the business logic in the language you love.

It's fast, fun, and makes the development process feel incredibly streamlined. Go give it a try! You might just find your new favorite way to build web apps.

Happy coding!

If you ask a group of developers: “Hey, have you used :has() before?”
Most of them will look at you like: “Bro, is that even real CSS?”

Yes. It is real. It is powerful. And honestly… it feels a bit illegal because CSS is not supposed to be this smart. But here we are.

Today I want to share this “new old” CSS superpower that can change how you build UI logic — without JavaScript. And trust me, you will feel like a magician.

What Is :has()?

The official definition is something like:

“Select an element if it contains something that matches the selector inside.”

But in simple language:
:has() is the closest thing we have to a “parent selector” in CSS.

With :has(), you can style a parent based on what the child looks like.

Something like:

.card:has(img) {
  border: 2px solid blue;
}

Boom.
If .card contains an <img>, it becomes blue.
CSS just checked the inside and reacted.

Why It Feels Like CSS With Superpowers

Before :has(), CSS always felt like working with strict Vietnamese parents:

• You can look at your children (descendant selectors)

• But you cannot look at your parents

• No arguments, no exceptions :))

But now :has() says:
“Don’t worry bro, I can look up, I can look down, I can check neighbors— I handle everything.”

Here are some things you can suddenly do:

1. Style a form when an input is invalid

No JS. No event listener. Just CSS.

form:has(input:invalid) {
  border: 2px solid red;
}

Boom. Instant feedback UI.

2. Change button style when a checkbox is checked

Classic “Enable button when user agrees”.

button:has(+ input:checked) {
  background: green;
}

3. Accordion without JavaScript

Yes, you read that right.

.item:has(.content.open) {
  max-height: 200px;
}

A Real Example (Dev-Friendly)

Let’s say you want to highlight a .product-card only when it has .sale-tag.

.product-card:has(.sale-tag) {
  background: #fff7e6;
  border-color: orange;
}

Result:
When the sale tag appears → whole card becomes “on sale mode”.

And you didn’t write even one line of JavaScript.
Feels good right?

Browser Support?

Good news:

• Chrome ✔

• Safari ✔

• Edge ✔

• Firefox ✔

Why Most Devs Don’t Use It Yet

Because:

• They don’t know

• They think it’s not supported

• They heard about it once but forgot

• CSS scares them

• That mindset of "Just use JavaScript, it’s faster."

But once you try :has(), you will realize it’s the missing piece we always wanted.

When Should You Use :has()?

Use it when you want CSS to react to the structure of the HTML.

Great for:

• Forms

• Cards

• Interactions

• Accordions

• Navigation menus

• Any “state” that depends on children

Not great for:

• Complex app logic

• Heavy UI state (JS vẫn làm tốt hơn)

Final Thought

The :has() selector is honestly a game changer.
It’s like the day you learned Flexbox or Grid for the first time — your brain expands a little bit.

With :has() you can:

• Style based on children

• Create UI states without JS

• Make smarter components

• Reduce code complexity

• Make CSS fun again

So next time you code UI, give this selector a try.
Maybe you'll feel like a CSS wizard for 5 minutes.
Worth it.

Where chaos begins turning into order

If the Red zone is where code feels “dangerous” then the Orange zone is where you can finally breathe a little

Even though there is still plenty to improve.

In this state, the code isn’t perfect, but it also doesn’t crush your soul.

This is the transition zone.

The place where cleanup becomes possible without the fear that a tiny change will blow up the whole system.

Renaming variables - a small step, huge impact

Laying the foundation for clarity

You would be surprised how much clarity you gain just by renaming things:

flag → isArchived
temp → initialValue
data → userResponse

It seems simple, almost trivial, but an intentional name removes so much mental guessing.

It saves seconds when reading code, and hours for the whole team over a sprint.

Breaking the story into smaller chapters

You encounter a 40-line function handling multiples different responsibilities.

Instead of rewriting everything, you simply split it out:

validateInput()
calculateDiscount()
saveToDatabase()

We are not changing the logic.

We are just breaking the story into clearer, digestible pieces so the next person doesn’t need to decode everything at once.

Flattening logic whenever possible

The Orange zone is where you start using guard clauses to eliminate deep nesting:

Instead of 4-5 stacked if blocks, you rewrite them as:

if (!user) return
if (!user.isActive) return
if (user.isBlocked) return

Cleaner, flatter, easier to follow.

This reduces cognitive load and prevents the dreaded “nested-if tunnel”.

Eliminating magic numbers

When numbers need real names

if (status === 3)

Replace that mysterious 3 with something meaningful:

STATUS_ARCHIVED

Or change the number 60 to:

SESSION_TIMEOUT

The Orange zone is where you replace hidden meaning with names that everyone understands, even newcomers.

Orange is the launchpad to green

The Orange zone isn’t where we stop, it’s where momentum begins.

It’s the stage where small habits compound:

• clearer names
• smaller functions
• flatter logic
• fewer hidden surprises

These small, consistent improvements gradually push the entire codebase toward the Green zone.

A state of stability, clarity, and long-term maintainability.

References

Martin Fowler - Refactoring
Boy Scout Rule – Uncle Bob

var, let and const are used in JavaScript to declare variables, but they differ significantly in their scope, hoisting, and whether they can be reassigned or redeclared.

1. var is the original way to declare variables in JavaScript. It has largely been superseded by let and const due to its often confusing scoping behavior.

Scope: Function-scoped or globally scoped. Variables declared with var inside a function are only accessible within that function. If declared outside any function, they are global. var ignores block scope (i.e., it is visible outside of if statements or for loops).

Hoisting: Variables declared with var are hoisted (moved to the top of their scope) and initialized with undefined. This means you can use a var variable before its declaration in the code without an error (though it will be undefined).

Reassignment: Can be reassigned (its value can be changed).

Redeclaration: Can be redeclared within the same scope without error.

2. let (Modern, Block-Scoped)
Introduced in ECMAScript 2015 (ES6), let is the preferred way to declare variables that might need to be reassigned.

Scope: Block-scoped. A variable declared with let is only accessible within the block of code (defined by curly braces {}) in which it's declared (e.g., inside an if statement, for loop, or a simple block).

Hoisting: Variables declared with let are hoisted but are not initialized. Accessing a let variable before its declaration results in a ReferenceError (this is known as the Temporal Dead Zone).

Reassignment: Can be reassigned (its value can be changed).

Redeclaration: Cannot be redeclared within the same scope. Doing so results in a SyntaxError.

3. const (Modern, Block-Scoped, Immutable Reference)
Also introduced in ES6, const is used to declare variables whose value should remain constant throughout the program's execution.

Scope: Block-scoped, just like let.

Hoisting: Hoisted, but not initialized, resulting in a Temporal Dead Zone.

Reassignment: Cannot be reassigned (its value cannot be changed after initialization). You must assign a value when declaring it.

Redeclaration: Cannot be redeclared within the same scope.

4. Hoisting

Hoisting is a JavaScript mechanism where variable and function declarations are moved to the top of their containing scope (either the global scope or the function scope) during the compilation phase before the code is executed.

- var variable Hositing

- let Variable Hoisting (with TDZ):

- Function Declaration:

- Function Expression:

5. Temporal Dead Zone (TMZ)

The Temporal Dead Zone (TDZ) is a specific period during the execution of JavaScript code where variables declared with let or const exist but cannot be accessed or assigned a value.

If you attempt to access a let or const variable within its TDZ, the JavaScript engine will immediately throw a ReferenceError.

* How the TDZ Works
The TDZ is directly tied to the concept of hoisting for let and const:

Hoisting Occurs: Like var, variables declared with let and const are hoisted (their creation is moved) to the top of their scope (which is block scope for these keywords).

Uninitialized State: Unlike var (which is initialized to undefined during hoisting), let and const variables are not initialized when they are hoisted. They are put into an uninitialized state.

The TDZ Period: The TDZ is the time period that begins when the scope is entered (e.g., when a { block is started) and ends when the variable's declaration line is executed and the variable is assigned a value (initialized).

Exiting the TDZ: Once the JavaScript interpreter reaches and executes the line of code that declares and initializes the variable (e.g., let x = 10; or const PI = 3.14;), the variable exits the TDZ and becomes fully accessible.

In the rapidly evolving landscape of Large Language Models (LLMs), the ability to establish dependable communication between models and external systems has become a critical necessity. The Model Context Protocol (MCP) has emerged as a pivotal standard designed to define how AI agents obtain, exchange, and act upon contextual data. This article explores the fundamentals of MCP, its significance in the AI ecosystem, and how it is reshaping the future of multi-agent collaboration and system integration.

What Is MCP?

Model Context Protocol is a standardized, transport-agnostic way for AI agents to:

• Discover available tools, data sources, and capabilities
• Request structured context
• Invoke actions safely
• Stream results and intermediate state

It reduces ad‑hoc plugin contracts and replaces brittle prompt stuffing with explicit, typed exchanges.

Core Concepts

• Resources: Read-only contextual objects (files, configs, embeddings).
• Tools: Executable operations with declared input/output schemas.
• Prompts / Templates: Reusable contextual bundles served to models.
• Permissions: Fine-grained gating of tool/resource exposure.

High-Level Flow

1. Client (LLM host) connects to MCP server.
2. Capability negotiation (tools, resources, prompts).
3. Model asks for context (resource listings, prompt retrieval).
4. Model invokes tool with structured arguments.
5. Server streams progress events.
6. Result packaged and appended to conversation context.

Example Interaction

{
  "type": "tool.invoke",
  "tool": "searchLogs",
  "arguments": { "query": "timeout error", "limit": 25 },
  "requestId": "abc123"
}

{
  "type": "tool.result",
  "requestId": "abc123",
  "status": "ok",
  "data": [
    { "timestamp": "...", "line": "TimeoutError: connection lost" }
  ]
}

Common Use Cases

a. Software Development

Developers can use MCP-enabled AI agents to access code repositories, run tests, and deploy applications—all through natural language commands.

b. Data Analysis

Analysts can leverage AI agents that connect to multiple data sources, perform complex queries, and generate insights without writing code.

c. Customer Support

Support systems can use MCP to give AI agents access to knowledge bases, ticket systems, and customer data for more effective problem resolution.

Challenges

a. Versioning of Tool Schemas

When tools evolve (new params, renamed fields, removed outputs), older clients may break or misinterpret results. Silent drift causes hallucinated usage or malformed invocations. Mixing schema versions inside one session amplifies ambiguity (e.g., cached prompt refers to deprecated argument). Without explicit semantic version tags and negotiation, rollback is painful.

b. Latency for Large Resource Hydration

Fetching large codebases, documents, or vector batches can stall the agent’s reasoning loop, leading to timeouts or premature reasoning with incomplete context. Streaming helps, but naive full hydration wastes bandwidth and token budget.

c. Secure Sandboxing of Side-Effect Tools

Tools that mutate state (deploy, write file, trigger pipeline) risk misuse if the model misinterprets instructions or an adversarial prompt causes unintended actions. Overly broad shell or network access turns an MCP server into a lateral movement surface.

d. Coordinating Multiple Concurrent Sessions

Several agents (planner, executor, reviewer) may compete for tool access, creating race conditions (one agent reads stale config another just changed). Without concurrency control, interleaved streams confuse attribution and degrade reasoning quality.

Best Practices

• Keep tools granular and composable.
• Provide lightweight summaries for large resources before full fetch.
• Use streaming for long-running tasks.
• Separate read vs. write capabilities explicitly.
• Log every invocation with correlation IDs.

Conclusion

MCP formalizes how AI agents discover, request, and act on context, enabling secure, interoperable, and reliable integrations. Adopting it early positions teams for multi-agent collaboration and easier backend evolution. Start small: define one resource, one tool, validate the schema, then expand.

Reference documents

• https://modelcontextprotocol.io/docs
• https://www.anthropic.com/engineering/code-execution-with-mcp

One of the first things you learn about Node.js is the Golden Rule: "Node.js is single-threaded."

For 90% of web applications, this is a feature, not a bug. The Event Loop allows Node to handle thousands of concurrent I/O connections (like database queries or API calls) without the overhead of creating threads.

But there is a catch.

Because there is only one thread, if you run a heavy CPU task (like image processing, video compression, or complex implementation of cryptography), you block that single thread. Your entire server freezes. No one else can log in, no APIs respond. The application effectively dies until that calculation finishes.

Enter Worker Threads.

Introduced as a stable feature in Node v12, Worker Threads allow you to break the "Single-Threaded" rule and execute JavaScript in parallel background threads.

The "Chef" Analogy

To understand why we need Workers, let's look at a restaurant kitchen.

1. Standard Node.js (The Main Thread): You have one Chef. This Chef is a master multitasker. He takes an order, puts a pizza in the oven, and immediately takes the next order. He doesn't wait for the pizza to bake (Async I/O). This is fast and efficient.
2. The Problem (CPU Blocking): Suddenly, a customer orders a "Hand-Carved Ice Sculpture." The Chef has to stop taking orders and spend 20 minutes chiseling ice. The restaurant halts. The pizza in the oven burns. Customers leave.
3. The Solution (Worker Threads): You hire a Sous-Chef (a Worker). When the Ice Sculpture order comes in, the Head Chef passes the ticket to the Sous-Chef in the back room. The Head Chef goes back to taking orders instantly, while the Sous-Chef works in parallel.

How Worker Threads Work Under the Hood

Unlike the cluster module (which spawns entirely new Node.js processes), Worker Threads create new threads within the same process.

Here is the architecture:

1. Isolated V8 Engines

Each Worker Thread gets its own instance of the V8 engine and its own Event Loop. This means:

• Variables are not shared automatically. A global variable in the Main Thread does not exist in the Worker Thread.
• If a Worker crashes, it doesn't necessarily kill the Main Thread.

2. Communication via Messaging

Since scopes are isolated, the Main Thread and the Worker communicate by passing messages back and forth, similar to how a frontend talks to a Web Worker.

• Main: "Here is the data. Start working." (worker.postMessage())
• Worker: "I received it. Processing..." (parentPort.on('message'))
• Worker: "I am done. Here is the result." (parentPort.postMessage())

3. Shared Memory (The Superpower)

This is where Workers shine over Child Processes. Workers can share memory using SharedArrayBuffer. This allows the Main Thread and the Worker to read/write to the same chunk of memory without the expensive cost of serializing data (converting objects to text) to send it back and forth.

A Simple Example

Imagine calculating the Fibonacci sequence for a large number. On the main thread, this would freeze your server. Here is how it looks with a Worker.

// main.js
const { Worker } = require('worker_threads');

function runService(workerData) {
  return new Promise((resolve, reject) => {
    // Spin up a new worker
    const worker = new Worker('./worker.js', { workerData });
    
    // Listen for the result
    worker.on('message', resolve);
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) reject(new Error(`Worker stopped with exit code ${code}`));
    });
  });
}

async function run() {
  console.log("Main thread is free to do other things...");
  const result = await runService(40); // Calculate Fib(40)
  console.log("Result from worker:", result);
}

run();

// worker.js
const { workerData, parentPort } = require('worker_threads');

// A CPU-heavy function
function fibonacci(n) {
  if (n < 2) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

// Do the work
const result = fibonacci(workerData);

// Send result back to main thread
parentPort.postMessage(result);

When to Use Workers

It is tempting to throw everything into a Worker Thread to make it "faster," but that often backfires. Creating a Worker is expensive (it has to boot up a V8 instance).

❌ Do NOT use Workers for I/O

Don't use Workers for database queries, HTTP requests, or file reading.

• Why? Node.js already does this efficiently in the background using C++ threads (via libuv). Wrapping an async DB call in a Worker Thread just adds overhead for no gain.

✅ DO use Workers for CPU Tasks

Use Workers when you have to process data synchronously.

• Image Processing: Resizing, cropping, or filtering images (e.g., sharp library).
• Video Compression: Transcoding video files.
• Cryptography: Generating massive RSA keys or hashing thousands of passwords.
• Data Parsing: Parsing a 500MB JSON or CSV file.

Conclusion

Node.js is no longer "just" single-threaded.

While the Event Loop remains the heart of Node.js for handling high-concurrency I/O, Worker Threads give you the muscle to handle heavy computation.

By offloading heavy math and parsing to background threads, you ensure your Main Thread stays where it belongs: handling incoming requests at lightning speed.

References

• https://nodesource.com/blog/worker-threads-nodejs
• https://medium.com/@manikmudholkar831995/worker-threads-multitasking-in-nodejs-6028cdf35e9d
• https://www.scaler.com/topics/nodejs/worker-threads-in-node-js/

After mastering how to design search APIs (see the previous article), it’s time to dive into the family of “write” APIs — create, update, and delete. These APIs directly affect system data, so their design must be careful and rule-driven.

Structure of Detailed Design for Create, Update, Delete APIs

1. API Name

As with search APIs, naming for write APIs should be concise, consistent, and clear. Avoid verbose names like “API to add a new product” or “API to delete a user.” Use these conventions:

• Standard create: [Entity] + Create/Add
  Example: `userCreate` — Create a new user
• Standard update: [Entity] + Update/Edit
  Example: `productUpdate` — Update product information
• Standard delete: [Entity] + Delete
  Example: `orderDelete` — Delete an order
• Partial update: [Entity] + [Action]
  Examples:
     - `orderUpdateStatus` — Update order status
     - `userUnblock` — Unblock a user
• Create/update/delete by a foreign key (parent ID)
  Example: `productUpdateByShopId` — Update product by shop ID (often includes constraints)
• Bulk create multiple records: [Entity] + BulkCreate
  Example: `shopBulkCreate` — Create multiple shops at once

With this convention, the team can infer functionality from the API name alone — no extra explanation needed.

2. HTTP Method

Write APIs typically use these methods:

Why these methods and not others?

Technically, nothing stops you from using POST to update or PATCH to create. However, choosing the method that matches the intent makes your API easier to manage, read, maintain, and it adheres to RESTful conventions. Each method carries meaning, helping readers of docs or code understand the API’s purpose without extra commentary. When the team sticks to these rules, collaboration and development go much smoother.

Method breakdown

• POST:
   - Used to create a new resource. The client sends data in the request body; the server creates the record and returns it (usually with an ID). → Hence POST is typically for creation because it generates a new resource.
   - Can be used for single or bulk creation, or to create a child resource under a parent (e.g., create a product for a shop).
   - Some systems use POST for partial updates, but this is discouraged because it’s confusing.
• PUT:
   - Used to replace a record entirely. The client usually sends all fields, including unchanged ones.
   - PUT is “replace” semantics — missing fields may be removed or set to default (system-dependent).
   - Use PUT when you want the record’s state to match exactly what’s sent.
• PATCH:
   - Used to update part of a record — only fields sent are changed; others remain.
   - Good for flexible updates, e.g., changing status or tweaking one field without sending the full payload.
   - Helps save bandwidth and avoids unintended overwrites.
• DELETE:
   - Used to remove a record. The client typically sends the record identifier (ID).
   - Some systems implement soft delete, marking records as deleted rather than physically removing them. The DELETE endpoint remains, but the deletion logic must be documented.

Practical notes

• If deletion requires confirmation (e.g., `confirm=true`), document it clearly
• For multi-record updates, you can use PUT/PATCH with an array of IDs or a dedicated endpoint like `/products/bulk-update`.
• Don’t overuse POST for all write operations — follow REST to keep your API extensible, maintainable, and compatible with tooling and documentation.
• Legacy or third-party integrations may force POST for update/delete. If so, document the reason clearly to avoid confusion.

In short, picking the right HTTP method is not just theoretical — it improves development, maintenance, testing, and integration. If you have exceptions, note them clearly in the design so everyone aligns.

3. URI

URI design for create, update, delete is similar to search APIs. If needed, revisit the previous article’s URI principles. Here are practical tips for this group:

• For operations on a specific resource (e.g., update or delete a product), place the resource ID in the URI path. It should be immediately clear what you’re doing and to which ID.
  Examples:
     - `PUT /products/123` — Update product with ID 123
     - `DELETE /products/123` — Delete product with ID 123
• For child resources scoped by a parent foreign key, include the parent ID in the path to clarify the context. This makes documentation readable and the business flow easier to grasp.
  Example: `POST /shops/{shop_id}/products` → `POST /shops/5/products` — Create/update/delete a product for shop ID 5
• For bulk operations (bulk update, bulk delete), don’t cram IDs into the path. Long, comma-separated or special-character-separated lists make the URI unwieldy and parsing error-prone. Instead, send the list via query parameters or the request body. It’s cleaner, more extensible, and safer for backend parsing.
• A common pattern is to share the same URI for read, update, and delete — differing only by HTTP method. This is normal and increases consistency.
  Examples:
     - `GET /products/{product_id}` — Get product details
     - `PUT /products/{product_id}` — Update product details
     - `DELETE /products/{product_id}` — Delete product

Design URIs so that, at a glance, you know what the API does, on which resource, and within what scope. Don’t hesitate to reuse search API URI examples — the core principles are clarity, consistency, and ease of team communication.

4. Authentication and Authorization

This was covered in detail previously, so revisit that article if needed.

One extremely important point for write APIs that you must never gloss over: Insecure Direct Object Reference (IDOR). In search or read-only APIs, IDOR primarily leaks data — users can view others’ information. In create/update/delete, the consequences are much more severe: attackers can modify, delete, or even take over others’ data simply by changing IDs in requests.

For example, if an API allows order status updates and only checks the order ID provided by the client, user A might update user B’s order by swapping IDs. This leads to unintended modifications/deletions and damages trust. Always check ownership and permissions rigorously — never trust IDs from the client alone.

5. Input Parameters

Unlike search APIs, create/update/delete APIs usually have fewer complex URI or query parameters. These typically just identify the resource to operate on (e.g., product ID, user ID).

Most of the data needed to create, update, or delete is sent via the request body. Why?

• First, request body is more secure, especially for sensitive fields (passwords, personal info). URLs are easily logged by proxies, browsers, or intermediaries.
• Second, payloads are often large and structured — query strings have length limits (often ~2048 chars) and can be truncated.
• Third, the body supports various data types, such as images, audio, CSV, Excel. Query parameters cannot do this. For file upload or binary payloads, only the body (`multipart/form-data` or binary) suffices. This is crucial for create/update APIs involving attachments.
• Fourth, body data makes backend validation and extensibility easier. You can define a body schema (JSON Schema, Joi, Yup, etc.), declare validation rules, and let the framework enforce them before business logic. Adding fields later is simple — update the schema without changing the path or query string.

◆ Common request body types

Below are the typical body formats for write APIs:

• application/json: The most common for structured create/update operations.
  Example:

POST /products
Content-Type: application/json
{
  "name": "iPhone 17 Pro Max 512GB",
  "price": 40000000,
  "description": "Apple’s latest product",
  "in_stock": true
}

• multipart/form-data: Used when sending files (images, audio, documents) alongside text fields. Each part is separate; backend receives both file(s) and metadata.
  Example:

POST /products
Content-Type: multipart/form-data
name: iPhone 15
price: 25000000
image: [image file]

• application/x-www-form-urlencoded: Common for simple forms; data is key=value. Suitable for endpoints with few fields and no files.
  Example:

POST /login
Content-Type: application/x-www-form-urlencoded
username=abc&password=xy

The above are the three most common ways to send data; there are also less common types such as:

• text/plain: Plain text payloads for very simple data.
• application/xml: XML payloads for legacy systems or specific partner integrations.
• application/octet-stream: Binary data such as zip/exe or specially encoded content.
• application/pdf, image/png, image/jpeg, audio/mpeg, video/mp4...: Direct file uploads where the payload itself is the file.
• application/csv, application/vnd.ms-excel: Tabular data uploads for bulk import.

◆ Why not use `multipart/form-data` for everything?

You might wonder: “Why not always use `multipart/form-data` since it handles files and text?” Sounds convenient, but it’s not ideal:

• If the API only receives text/JSON, `multipart/form-data` complicates things:
   - Modern frameworks provide strong schema/type/value validation for JSON. With multipart, you lose these conveniences and must manually parse and validate fields.
   - Frontend can send JSON with a simple function call; multipart requires building `FormData`, appending fields, handling files.
   - Backend must parse parts and cannot leverage JSON validators effectively.
• `multipart/form-data` adds boundaries, headers, and encoding, making requests heavier than plain JSON. If you’re sending only text, JSON saves bandwidth and reduces server load.
• Documentation/testing tools (Swagger/OpenAPI, CI/CD integrations) default to application/json for write APIs. Using multipart everywhere complicates docs and automation and confuses teams.

Practical examples:

• Create product with image: use `multipart/form-data` for file + metadata.
• Create product without files: use `application/json` — simpler and more robust.

Bottom line: choose the body type that fits the API’s purpose. Use multipart for file uploads; use JSON for text-only payloads. This improves validation, maintainability, performance, and integration.

6. Data Validation

Unlike search APIs, write APIs must enforce multiple layers of validation — tightly — to protect the system from attacks and business errors. For search, validation mainly prevents resource abuse (e.g., huge limits). For write, validation is the “security fence” guarding data from corruption, loss, and exploitation.

◆ Mandatory validations for write APIs

◇ Security hardening:

• Block SQL Injection: Always sanitize client inputs. Disallow dangerous characters/patterns like single/double quotes, semicolons, SQL comments (`--`), or keywords like SELECT/INSERT/DROP/UNION. Prefer parameterized queries/ORMs; never string-concatenate SQL.
• Block XSS: Strip dangerous HTML/script patterns such as `<script>`, `javascript:`, `onload`, `onerror` in all user-provided fields, especially descriptions/notes. Use sanitize libraries or escape HTML before storing/rendering.
• Blacklist attack patterns: Maintain known-dangerous patterns (command strings, malware payloads, special characters) and reject inputs that match. Use security libraries or custom rules.
• Validate uploaded files: Check MIME type, extension, and actual content. Allow only safe types (jpg/png/pdf...), reject dangerous types (.exe/.js/.bat/.sh...). Also verify file size and enforce limits to prevent resource exhaustion.

◇ Authorization checks: Define exactly which user roles may perform which actions under which business states. Rule of thumb: only allow the right user, right role, right state to perform the right action; reject everything else.

Example for order status updates:
- Sales staff can set status to “awaiting payment confirmation”.
- Warehouse staff can set to “shipped from warehouse” or “returned to warehouse”.
- Accounting can set to “payment confirmed”.
- Customer can set to “order canceled”.
- Admin may have broader permissions (if business permits).
- Any mismatch (e.g., warehouse confirming payment) must be rejected.

◇ Required fields: Fields that are non-nullable/required in the database must be required by create/update APIs as well. Required means the client must send the field, it must have a value, and it must not be an empty string ''.

• Create APIs: If the database has no default, the API must require the field and reject empty ''. If the database has a default and you want to always store that default when creating, do not accept the field from the client (even if sent). This avoids security holes, e.g., creating an order with initial status set to cancel.
• Update APIs: Data already exists. If a field may be edited, accept it; otherwise block it. Do not allow updating fields to empty ''.

◇ Type validation: Every field must match its declared type (integer, float/decimal, string, boolean, array, object, date, enum…) and this must align with the database schema. If the type is wrong, return an error — do not auto-coerce or ignore.

• Integer: Only integers; no floats, strings, or special characters.
  Examples:
     - 1, 100, -5 are valid
     - 1.5, "abc" are invalid
• Float/double/decimal: Accept floats or integers.
  Examples:
     - 1.5, 100.0, -3 are valid
     - "abc" are invalid
• String: Only character strings.
  Examples:
     - "iPhone", "abc123" are valid
     - 123 are invalid
• Boolean: Accept true/false or 1/0 depending on the system.
  Examples:
     - true, false, 1, 0 are valid
     - "yes", "no" are invalid
• Date/datetime/timestamp: Strings in a valid format (ISO 8601, yyyy-MM-dd, yyyy-MM-dd HH:mm:ss...).
  Examples:
     - "2025-10-14", "2025-10-14T10:00:00Z" are valid
     - "2025/10/14", "14/10/2025", "abc" are invalid
• Enum: Values must be within the allowed set.
  Examples:
     - Order status: only "pending", "confirmed", "cancel"
     - Others are invalid.
• Array: Must be a list of elements of consistent types; validate count and element types.
  Examples:
     - [1,2,3], ["a","b"] are valid
     - "1,2,3", null are invalid
• Object: Must match the designed structure; nested fields must also be valid.
  Examples:
     - {"name":"A","price":100} is valid
     - "{name:A}", null are invalid

◇ Value validation:

• Examples:
     - Quantity must be between 1 and 100; <=0 or >100 is invalid.
     - Date must be today or future; past dates are invalid.

◇ Length, pattern, format:

• Examples: product name <= 255 chars, email format valid, phone number matches pattern.
• Don’t forget file checks: if API allows file uploads, validate type, count, and size. Clarify whether limits apply per request, per resource ID, or per file.

◇ Uniqueness checks:

• Examples: email, username, product code must be unique and not duplicate existing records.
• Consider whether to include soft-deleted records in uniqueness checks. Some systems ignore soft-deleted records — e.g., if an account with username "test" was soft-deleted, creating a new account with "test" may be allowed.

◇ Business logic validation: e.g., order status may only transition from "pending" to "confirmed", not backwards.

◆ Why is validation critical for write APIs?

If you skip or loosen validation for write endpoints, you risk:

• Security vulnerabilities: SQLi, XSS, malicious uploads.
  Examples:
   - Without input sanitization, a client could set product name to `'; DROP TABLE products; --` and attempt SQL injection, wiping the table.
   - Without script blocking, a client could set a description to `<script>alert('XSS')</script>`, attacking users viewing it on the web UI.
   - Without file type checks, attackers could upload `.exe` or scripts, potentially compromising the server.
• Unauthorized actions: users performing operations beyond their roles.
  Example: warehouse staff setting order status to “paid”.
• Bad data and broken business processes.
  Example: if types aren’t checked, sending price as "abc" may crash the system or corrupt the DB.
• Duplicates and inconsistency, hard to audit and maintain.
  Examples:
   - Multiple users with the same email/username breaks login, notifications, and role assignments.
   - Duplicate product codes cause confusion in inventory, invoicing, or external integrations.
   - Invalid status transitions or unsynchronized multi-table writes lead to retrieval/reporting errors.

In short, validation for write APIs is not "nice-to-have" — it’s mandatory. Invest in designing, enforcing, and documenting validation rules to protect your system, data, and product reputation.

7. Data Persistence

This is the heart of create/update/delete APIs. Bad or incomplete writes cause bad data and downstream pain. Document thoroughly:

• Which tables/columns to insert/update/delete.
• For create/update:
   - Specify stored values (omit when using DB defaults).
   - If branching logic results in different storage semantics, document each branch clearly.
   - If files are uploaded, specify storage location, naming conventions, and any file metadata to persist (original name, size…).
   - For date/time/datetime, state the timezone explicitly.
   - Don’t forget related tables! If writing to `orders`, should you also write to `order_details`? If writing to `products`, do you also write to `product_suppliers`?
• For delete:
   - Hard delete or soft delete?
   - Whether to delete dependent records (foreign-key-bound tables).
   - If records have files stored elsewhere, whether to delete corresponding files.

8. Output Parameters

Unlike search APIs, write APIs focus on writing, so output guidelines are simpler:

• Return the minimal information necessary. Typically `id` (and optionally `version`/ETag) so the client can confirm and proceed. For detailed views, call the corresponding GET. Returning full objects from multiple endpoints leads to divergent contracts and higher maintenance costs.
• Standardize HTTP status codes for each case so frontend messaging is consistent. For example: `201 Created` for create, `204 No Content` for update/delete when no body is needed.

Sample Create/Update/Delete APIs Detailed Design

You can view and download the template (API Blueprint) to use as a standard frame for writing detailed designs for search APIs [here](https://github.com/sa-violetdang/advanced-api-documentation).

Conclusion

From naming, HTTP methods, URIs, security, validation, to storage and responses — you now have a solid framework to design clean, extensible, low-tech-debt write APIs.

The key to write APIs isn’t a verbose response but discipline: perform the write correctly, respond minimally, and use standard status codes so the client understands immediately without extra ceremony. The less extraneous data you return, the more stable the contract and the lower the maintenance cost.

Key Takeaways

1. Start minimal, expand when needed: Prefer `204 No Content` for update/delete and return only `id` on create. If required, add minimal `version`/ETag or `links.self` — avoid returning full objects.
2. Consistent contracts: Names, URIs, methods reflect semantics; status codes clear (`201/204/400/404/409`). Use stable time/id formats to simplify integration and testing.
3. Validation is the safety fence: Security (SQLi/XSS/files), authorization, types, uniqueness, and business rules. Document once and enforce across the team.
4. Principled persistence: Transactions, write order, hard/soft delete, table relations, file handling. Document semantics to avoid bad data and painful rollbacks.
5. Advanced features when needed: Add idempotency for POST, concurrency via `ETag/If-Match`, observability with `requestId`/timestamp, and support bulk/async with clear contracts (partial success, `202 Accepted`).

Above all, remember: good design reduces guesswork for API consumers (FE/BE). Every line in your docs should cut communication errors and speed development. Keep responses lean and contracts clear — reads belong to GET — that’s how your system stays robust over time.