Forem

Next.js 16 Complete Beginner's Guide

Yogesh Chavan — Mon, 20 Apr 2026 07:32:36 +0000

In this article, you will learn everything you need to know about Next.js 16. This is a completely beginner-friendly guide.

So let's get started.

Section 1: Next.js Fundamentals

1. What is Next.js & Why React Developers Should Care

Next.js is a powerful React framework created by Vercel that enables developers to build full-stack web applications with ease. It extends React's capabilities by providing built-in solutions for routing, rendering, data fetching, and optimization. Unlike plain React which only handles the view layer, Next.js provides a complete framework for building production-ready applications.

Before Next.js, React developers had to manually configure webpack, set up routing with React Router, implement server-side rendering, and handle code splitting. Next.js eliminates this complexity by providing sensible defaults while remaining highly customizable. Version 16 brings significant improvements including enhanced performance, better TypeScript support, and improved developer experience.

Why React Developers Should Learn Next.js

As a React developer, learning Next.js is a natural progression that will significantly enhance your capabilities. Here are the key reasons why Next.js has become the go-to framework for React applications:

1. SEO Optimization - Unlike client-side rendered React apps where content is generated in the browser, Next.js can render pages on the server. This means search engine crawlers see fully rendered HTML, dramatically improving your site's visibility in search results.

2. Performance Out of the Box - Next.js automatically optimizes your application with features like automatic code splitting, image optimization, font optimization, and intelligent prefetching.

3. Multiple Rendering Strategies - Choose the best rendering approach for each page: Static Site Generation (SSG), Server-Side Rendering (SSR), Incremental Static Regeneration (ISR), or Client-Side Rendering (CSR).

4. Full-Stack Capabilities - Build API endpoints directly within your Next.js application using Route Handlers. No need for a separate backend server for simple to moderate API needs.

5. File-Based Routing - Create pages and routes simply by adding files to the app directory. No need to configure a router or maintain route definitions separately.

6. Built-in TypeScript Support - Next.js 16 comes with excellent TypeScript integration out of the box, providing better developer experience and catching errors at compile time.

💡 Tip: Next.js is used by major companies including Netflix, TikTok, Twitch, Hulu, Nike, and many more. Learning it opens doors to enterprise-level opportunities.

Key Features at a Glance

Feature	Description	Benefit
App Router	New routing system with RSC	Better performance & DX
Server Components	Components render on server	Smaller bundles
Streaming	Progressive page rendering	Faster perceived load
Route Handlers	API endpoints in Next.js	Full-stack in one project
Image Optimization	Auto image resizing	Faster loading images
Font Optimization	Self-hosted fonts	Better Core Web Vitals

2. Next.js vs CRA vs Vite

Comparing React Development Approaches

When starting a new React project, developers typically choose between three popular options: Create React App (CRA), Vite, or Next.js. Each has its strengths and ideal use cases.

Create React App (CRA)

Create React App was the official way to start React projects for years. It provides a zero-configuration setup for client-side React applications. However, CRA is no longer recommended by the React team.

Pros: Simple setup, good for learning React basics, well-documented

Cons: Client-side only (poor SEO), slow build times, no longer actively recommended

Vite

Vite is a modern build tool that offers lightning-fast development experience. It uses native ES modules and provides instant hot module replacement.

Pros: Extremely fast dev server, quick builds, modern architecture, framework-agnostic

Cons: Client-side focused (needs plugins for SSR), less opinionated, requires more configuration for full-stack

Next.js

Next.js is a full-featured React framework that provides everything you need for production applications out of the box.

Pros: Full-stack capabilities, multiple rendering strategies, built-in optimizations, excellent DX, strong community

Cons: Steeper learning curve, Vercel-centric ecosystem, more opinionated

Feature Comparison

Feature	CRA	Vite	Next.js
Server Rendering	No	Plugin	Built-in
Static Generation	No	Plugin	Built-in
API Routes	No	No	Built-in
File-based Routing	No	No	Built-in
Image Optimization	No	No	Built-in
Dev Server Speed	Slow	Fast	Fast
Production Ready	Basic	Good	Excellent

When to Choose Each Option

Choose CRA if you're learning React basics (though consider alternatives now)
Choose Vite for SPAs, prototypes, or when you need maximum flexibility
Choose Next.js for production apps, SEO-critical sites, or full-stack projects

⚠️ Important: The React team now recommends using a framework like Next.js for new projects instead of Create React App.

3. App Router vs Pages Router (Which One & Why)

Understanding Next.js Routing Systems

Next.js has two routing systems: the older Pages Router (pages/ directory) and the newer App Router (app/ directory). Understanding the differences helps you make the right choice for your project.

Pages Router (Legacy)

The Pages Router has been the standard since Next.js began. Files in the pages/ directory automatically become routes.

pages/
├── index.tsx        -> /
├── about.tsx        -> /about
├── blog/
│   └── [slug].tsx   -> /blog/:slug
└── api/
    └── users.ts     -> /api/users

Key Characteristics:

Uses getServerSideProps, getStaticProps for data fetching
All components are Client Components by default
Layouts require workarounds (_app.tsx, _document.tsx)
Simpler mental model

App Router (Recommended)

The App Router, introduced in Next.js 13 and now stable, uses the app/ directory with React Server Components as the foundation.

app/
├── page.tsx           -> /
├── layout.tsx         -> Shared layout
├── about/
│   └── page.tsx       -> /about
├── blog/
│   └── [slug]/
│       └── page.tsx   -> /blog/:slug
└── api/
    └── users/
        └── route.ts   -> /api/users

Key Characteristics:

React Server Components by default
Native async/await for data fetching
Nested layouts, loading states, error boundaries
Streaming and Suspense support

Key Differences

Feature	Pages Router	App Router
Default Components	Client	Server
Data Fetching	getServerSideProps	async/await
Layouts	_app.tsx workaround	Native nested
Loading States	Manual	loading.tsx
Error Handling	_error.tsx	error.tsx (nested)
Streaming	Limited	Full support

Why Choose the App Router?

For new projects, the App Router is recommended because:

Better Performance - Server Components reduce JavaScript sent to client
Simpler Data Fetching - Use async/await directly in components
Nested Layouts - Share UI between routes without re-rendering
Built-in Loading/Error States - Automatic handling with special files
Future-Proof - All new Next.js features target the App Router

💡 Tip: If you're starting a new project, use the App Router. Only use Pages Router for legacy projects or specific compatibility needs.

4. Setting Up Your First Next.js Project

Prerequisites

Before creating a Next.js project, ensure you have:

Node.js 18.17 or later - Download from nodejs.org
npm, yarn, or pnpm - Package manager (npm comes with Node.js)
Code editor - VS Code recommended with ESLint and Prettier extensions

Creating a New Project

Open your terminal and run:

npx create-next-app@latest my-nextjs-app

You'll be prompted with configuration options:

Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? No
Would you like to use App Router? Yes
Would you like to customize the default import alias? No

Recommended choices for beginners:

TypeScript: Yes (better DX and error catching)
ESLint: Yes (code quality)
Tailwind CSS: Yes (rapid styling)
src/ directory: No (simpler structure)
App Router: Yes (modern approach)

Running the Development Server

Navigate to your project and start the development server:

cd my-nextjs-app
npm run dev

Open http://localhost:3000 in your browser. You should see the Next.js welcome page!

Available Scripts

{
  "scripts": {
    "dev": "next dev",        // Start development server
    "build": "next build",    // Create production build
    "start": "next start",    // Run production server
    "lint": "next lint"       // Run ESLint
  }
}

💡 Tip: Use npm run dev -- -p 3001 to run on a different port if 3000 is already in use.

5. Understanding the Project Structure

Project Directory Overview

After creating a new Next.js project, you'll see this structure:

my-nextjs-app/
+-- app/
|   +-- favicon.ico
|   +-- globals.css
|   +-- layout.tsx
|   +-- page.tsx
+-- public/
|   +-- (static files)
+-- node_modules/
+-- .eslintrc.json
+-- .gitignore
+-- next.config.ts
+-- package.json
+-- postcss.config.mjs
+-- tailwind.config.ts
+-- tsconfig.json

Key Files and Directories

app/ - The main directory for your application code using the App Router.

app/layout.tsx - The root layout component that wraps all pages. Define global UI elements like headers and footers here.

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

app/page.tsx - The home page component, rendered at the root URL (/).

// app/page.tsx
export default function Home() {
  return (
    <main>
      <h1>Welcome to Next.js!</h1>
    </main>
  )
}

public/ - Static assets like images, fonts, and files. Accessible at the root URL.

next.config.ts - Next.js configuration file for customizing build and runtime behavior.

tailwind.config.ts - Tailwind CSS configuration for customizing your design system.

tsconfig.json - TypeScript configuration with Next.js-specific settings.

📝 Note: The globals.css file contains your global styles. When using Tailwind CSS, this file includes the Tailwind directives.

Section 2: Styling & Assets

1. CSS Modules vs Global CSS

Next.js supports multiple styling approaches out of the box: Global CSS, CSS Modules, Tailwind CSS, and CSS-in-JS libraries. Understanding when to use each helps you build maintainable styles.

Global CSS

Global styles apply to your entire application. Import them in your root layout:

/* app/globals.css */
* {
    box-sizing: border-box;
    margin: 0;
    padding: 0;
}

body {
    font-family: system-ui, sans-serif;
    line-height: 1.6;
}

a {
    color: #0070f3;
    text-decoration: none;
}

a:hover {
    text-decoration: underline;
}

// app/layout.tsx
import './globals.css'

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>{children}</body>
        </html>
    )
}

CSS Modules

CSS Modules scope styles to a component, preventing naming conflicts. Create files with .module.css extension:

/* app/components/Button.module.css */
.button {
    padding: 12px 24px;
    border: none;
    border-radius: 8px;
    font-size: 16px;
    cursor: pointer;
    transition: all 0.2s;
}

.primary {
    background: #0070f3;
    color: white;
}

.primary:hover {
    background: #0051a8;
}

.secondary {
    background: #eaeaea;
    color: #333;
}

// app/components/Button.tsx
import styles from './Button.module.css'

type ButtonProps = {
    variant?: 'primary' | 'secondary'
    children: React.ReactNode
}

export function Button({ variant = 'primary', children }: ButtonProps) {
    return (
        <button className={styles.button + ' ' + styles[variant]}>
            {children}
        </button>
    )
}

💡 Tip: CSS Modules automatically generate unique class names like 'Button_primary__x7f3a', ensuring styles never leak between components.

2. Tailwind CSS v4 Setup & Best Practices

What's New in Tailwind CSS v4

Tailwind CSS v4 is a major rewrite with significant improvements: it's up to 10x faster, uses native CSS cascade layers, and has a simplified configuration using CSS instead of JavaScript.

Installing Tailwind CSS v4

# Install Tailwind CSS v4
npm install tailwindcss @tailwindcss/postcss postcss

Configuration with CSS (New in v4)

Tailwind v4 uses CSS-based configuration instead of tailwind.config.js:

/* app/globals.css */
@import "tailwindcss";

/* Custom theme configuration using CSS */
@theme {
    --color-primary: #0070f3;
    --color-secondary: #7928ca;
    --font-sans: "Inter", system-ui, sans-serif;
    --spacing-18: 4.5rem;
}

/* Custom utilities */
@utility container-narrow {
    max-width: 42rem;
    margin-inline: auto;
    padding-inline: 1rem;
}

// postcss.config.mjs
export default {
    plugins: {
        '@tailwindcss/postcss': {}
    }
}

Using Tailwind in Components

// app/components/Card.tsx
export function Card({ title, description, children }) {
    return (
        <div className="rounded-xl border border-gray-200 bg-white p-6
                        shadow-sm hover:shadow-md transition-shadow">
            <h2 className="text-xl font-semibold text-gray-900 mb-2">
                {title}
            </h2>
            <p className="text-gray-600 mb-4">
                {description}
            </p>
            {children}
        </div>
    )
}

Best Practices

Use consistent spacing scale (p-4, p-6, p-8 not p-5, p-7)
Extract repeated patterns into components, not @apply
Use CSS variables for brand colors via @theme
Leverage the new container queries in v4

⚠️ Important: Tailwind v4 no longer requires a tailwind.config.js file. All configuration happens in your CSS using @theme and other directives.

3. Fonts with next/font

Why Use next/font?

next/font automatically optimizes fonts and removes external network requests for improved privacy and performance. It self-hosts font files and eliminates layout shift with automatic font fallbacks.

Using Google Fonts

// app/layout.tsx
import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
    subsets: ['latin'],
    display: 'swap',
    variable: '--font-inter',
})

const robotoMono = Roboto_Mono({
    subsets: ['latin'],
    display: 'swap',
    variable: '--font-roboto-mono',
})

export default function RootLayout({ children }) {
    return (
        <html lang="en" className={inter.variable + ' ' + robotoMono.variable}>
            <body className={inter.className}>
                {children}
            </body>
        </html>
    )
}

Using Local Fonts

// app/layout.tsx
import localFont from 'next/font/local'

const myFont = localFont({
    src: [
        {
            path: '../fonts/MyFont-Regular.woff2',
            weight: '400',
            style: 'normal',
        },
        {
            path: '../fonts/MyFont-Bold.woff2',
            weight: '700',
            style: 'normal',
        },
    ],
    variable: '--font-my-font',
})

export default function RootLayout({ children }) {
    return (
        <html lang="en" className={myFont.variable}>
            <body>{children}</body>
        </html>
    )
}

Using with Tailwind CSS

/* app/globals.css - Tailwind v4 */
@import "tailwindcss";

@theme {
    --font-sans: var(--font-inter), system-ui, sans-serif;
    --font-mono: var(--font-roboto-mono), monospace;
}

💡 Tip: Always use display: 'swap' to prevent invisible text while fonts load. This improves Core Web Vitals scores.

4. Images with next/image

Automatic Image Optimization

The next/image component automatically optimizes images: resizing, converting to modern formats (WebP/AVIF), and lazy loading. It prevents layout shift with automatic dimension handling.

Basic Usage

import Image from 'next/image'

// Local image (automatically gets dimensions)
import profilePic from './profile.jpg'

export function Avatar() {
    return (
        <Image
            src={profilePic}
            alt="Profile picture"
            placeholder="blur" // Shows blurred version while loading
        />
    )
}

// Remote image (must specify dimensions)
export function ProductImage({ src, name }) {
    return (
        <Image
            src={src}
            alt={name}
            width={400}
            height={300}
            priority // Load immediately (above the fold)
        />
    )
}

Responsive Images

// Fill container (responsive)
export function HeroImage() {
    return (
        <div className="relative h-[400px] w-full">
            <Image
                src="/hero.jpg"
                alt="Hero image"
                fill
                style={{ objectFit: 'cover' }}
                sizes="100vw"
                priority
            />
        </div>
    )
}

// Responsive with sizes hint
export function BlogImage({ src, alt }) {
    return (
        <Image
            src={src}
            alt={alt}
            width={800}
            height={400}
            sizes="(max-width: 768px) 100vw, 800px"
            className="rounded-lg"
        />
    )
}

Configuring Remote Images

By default, Next.js blocks remote images for security reasons. The next/image component optimizes images on-demand, which means your server fetches, processes, and caches external images. Without restrictions, malicious users could abuse your server to process images from any URL, potentially causing security vulnerabilities and unexpected costs.

To use remote images, you must explicitly whitelist the domains in your next.config.ts file using the remotePatterns configuration:

// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
    images: {
        remotePatterns: [
            {
                protocol: 'https',
                hostname: 'images.unsplash.com',
            },
            {
                protocol: 'https',
                hostname: '*.cloudinary.com',
            },
        ],
    },
}

export default config

Why This Configuration Matters:

Security - Prevents your server from being used to fetch and process arbitrary external images
Cost Control - Image optimization uses server resources; whitelisting prevents abuse
Performance - Only trusted CDNs and image sources are optimized
Wildcards - Use '.' prefix to allow all subdomains (e.g., '.cloudinary.com')

📝 Note: Use priority prop for Largest Contentful Paint (LCP) images like hero images. This preloads them for better performance.

5. Metadata, SEO & Open Graph Images

Static Metadata

Define metadata in your layout or page files to improve SEO. Next.js automatically generates the appropriate meta tags.

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
    title: {
        default: 'My App',
        template: '%s | My App', // For child pages
    },
    description: 'A Next.js application',
    keywords: ['Next.js', 'React', 'JavaScript'],
    authors: [{ name: 'Your Name' }],
    openGraph: {
        title: 'My App',
        description: 'A Next.js application',
        url: 'https://myapp.com',
        siteName: 'My App',
        images: [
            {
                url: '/og-image.png',
                width: 1200,
                height: 630,
            },
        ],
        locale: 'en_US',
        type: 'website',
    },
    twitter: {
        card: 'summary_large_image',
        title: 'My App',
        description: 'A Next.js application',
        images: ['/og-image.png'],
    },
}

Dynamic Metadata

// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'

type Props = {
    params: Promise<{ slug: string }>
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
    const { slug } = await params
    const post = await getPost(slug)

    return {
        title: post.title,
        description: post.excerpt,
        openGraph: {
            title: post.title,
            description: post.excerpt,
            images: [post.coverImage],
        },
    }
}

Dynamic OG Images

// app/og/route.tsx
import { ImageResponse } from 'next/og'

export async function GET(request: Request) {
    const { searchParams } = new URL(request.url)
    const title = searchParams.get('title') || 'My App'

    return new ImageResponse(
        (
            <div style={{
                display: 'flex',
                fontSize: 60,
                background: 'linear-gradient(to bottom, #1a1a2e, #16213e)',
                color: 'white',
                width: '100%',
                height: '100%',
                alignItems: 'center',
                justifyContent: 'center',
            }}>
                {title}
            </div>
        ),
        { width: 1200, height: 630 }
    )
}

💡 Tip: Use the template pattern in title metadata so child pages automatically append your site name: 'Blog Post Title | My App'

Section 3: Routing in Depth

1. File-Based Routing Explained

Next.js uses a file-system based router where folders define routes. This means the structure of your app/ directory directly maps to your URL structure.

app/
+-- page.tsx           -> /
+-- about/
|   +-- page.tsx       -> /about
+-- blog/
|   +-- page.tsx       -> /blog
+-- contact/
    +-- page.tsx       -> /contact

Creating Your First Routes

Each route requires a page.tsx file inside its folder. The page file exports a React component that renders when users visit that route.

// app/page.tsx - Home page (/)
export default function HomePage() {
    return (
        <main>
            <h1>Welcome to My App</h1>
            <p>This is the home page.</p>
        </main>
    )
}

// app/about/page.tsx - About page (/about)
export default function AboutPage() {
    return (
        <main>
            <h1>About Us</h1>
            <p>Learn more about our company.</p>
        </main>
    )
}

Nested Routes

Create nested folders for nested routes:

app/
+-- blog/
    +-- page.tsx           -> /blog
    +-- posts/
        +-- page.tsx       -> /blog/posts

// app/blog/page.tsx
export default function BlogPage() {
    return <h1>Blog</h1>
}

// app/blog/posts/page.tsx
export default function PostsPage() {
    return <h1>All Blog Posts</h1>
}

Navigation Between Pages

Use the Link component for client-side navigation:

import Link from 'next/link'

export default function Navigation() {
    return (
        <nav>
            <Link href="/">Home</Link>
            <Link href="/about">About</Link>
            <Link href="/blog">Blog</Link>
            <Link href="/contact">Contact</Link>
        </nav>
    )
}

💡 Tip: Always use the Link component instead of anchor tags for internal navigation. Link enables client-side navigation and automatic prefetching for faster page loads.

2. Pages, Layouts & Nested Routes

Understanding Layouts

Layouts wrap pages and preserve state across navigations. They're perfect for shared UI like headers, sidebars, and footers.

// app/layout.tsx - Root Layout (required)
import { Inter } from 'next/font/google'
import './globals.css'

const inter = Inter({ subsets: ['latin'] })

export default function RootLayout({
    children,
}: {
    children: React.ReactNode
}) {
    return (
        <html lang="en">
            <body className={inter.className}>
                <header>
                    <nav>My App</nav>
                </header>
                <main>{children}</main>
                <footer>© 2024</footer>
            </body>
        </html>
    )
}

Nested Layouts

Each route segment can have its own layout that nests inside parent layouts:

app/
+-- layout.tsx              -> Root layout
+-- page.tsx                -> Home page
+-- dashboard/
    +-- layout.tsx          -> Dashboard layout (nested)
    +-- page.tsx            -> /dashboard
    +-- settings/
        +-- page.tsx        -> /dashboard/settings

// app/dashboard/layout.tsx
export default function DashboardLayout({
    children,
}: {
    children: React.ReactNode
}) {
    return (
        <div className="dashboard">
            <aside>
                <nav>
                    <a href="/dashboard">Overview</a>
                    <a href="/dashboard/settings">Settings</a>
                </nav>
            </aside>
            <section>{children}</section>
        </div>
    )
}

Layout Benefits

Preserved State - Layouts don't re-render when navigating between pages they wrap
No Prop Drilling - Fetch data once in layout, available to all children
Partial Rendering - Only the page content updates, not the entire layout

⚠️ Important: The root layout (app/layout.tsx) is required and must contain html and body tags. Nested layouts should NOT include these tags.

3. Dynamic Routes & Catch-All Routes

Dynamic Segments

Use square brackets to create dynamic routes that match variable paths:

app/
+-- blog/
    +-- [slug]/
        +-- page.tsx       -> /blog/hello-world, /blog/my-post

// app/blog/[slug]/page.tsx
type Props = {
    params: Promise<{ slug: string }>
}

export default async function BlogPost({ params }: Props) {
    const { slug } = await params

    return (
        <article>
            <h1>Post: {slug}</h1>
        </article>
    )
}

Multiple Dynamic Segments

app/
+-- shop/
    +-- [category]/
        +-- [product]/
            +-- page.tsx   -> /shop/electronics/iphone

// app/shop/[category]/[product]/page.tsx
type Props = {
    params: Promise<{ category: string; product: string }>
}

export default async function ProductPage({ params }: Props) {
    const { category, product } = await params

    return (
        <div>
            <p>Category: {category}</p>
            <p>Product: {product}</p>
        </div>
    )
}

Catch-All Segments

Use [...slug] to match any number of segments:

app/
+-- docs/
    +-- [...slug]/
        +-- page.tsx       -> /docs/a, /docs/a/b, /docs/a/b/c

// app/docs/[...slug]/page.tsx
type Props = {
    params: Promise<{ slug: string[] }>
}

export default async function DocsPage({ params }: Props) {
    const { slug } = await params
    // slug = ['a', 'b', 'c'] for /docs/a/b/c

    return (
        <div>
            <p>Path: {slug.join(' / ')}</p>
        </div>
    )
}

💡 Tip: Use [...slug] for optional catch-all routes that also match the parent path (/docs).

4. Route Groups & Folder Conventions

What Are Route Groups?

Route groups organize routes without affecting the URL structure. Wrap folder names in parentheses:

app/
+-- (marketing)/
|   +-- layout.tsx         -> Marketing layout
|   +-- page.tsx           -> / (home page)
|   +-- about/
|   |   +-- page.tsx       -> /about
|   +-- pricing/
|       +-- page.tsx       -> /pricing
+-- (app)/
    +-- layout.tsx         -> App layout
    +-- dashboard/
    |   +-- page.tsx       -> /dashboard
    +-- settings/
        +-- page.tsx       -> /settings

Use Cases for Route Groups

1. Different layouts for different sections:

// app/(marketing)/layout.tsx
export default function MarketingLayout({ children }) {
    return (
        <div className="marketing">
            <header>Marketing Header</header>
            {children}
        </div>
    )
}

// app/(app)/layout.tsx
export default function AppLayout({ children }) {
    return (
        <div className="app">
            <Sidebar />
            {children}
        </div>
    )
}

2. Organizing by feature:

app/
+-- (auth)/
|   +-- login/
|   +-- register/
+-- (dashboard)/
    +-- overview/
    +-- analytics/

Private Folders

Prefix with underscore to exclude from routing:

app/
+-- _components/     -> Not a route, just organization
+-- _lib/            -> Not a route, utilities
+-- page.tsx         -> Actual route

📝 Note: Route groups are purely organizational. The parentheses folder name is completely removed from the URL path.

5. Not Found & Error Routes

Custom 404 Page

Create a not-found.tsx file to show when a page doesn't exist:

// app/not-found.tsx
import Link from 'next/link'

export default function NotFound() {
    return (
        <div className="not-found">
            <h1>404 - Page Not Found</h1>
            <p>Sorry, we couldn't find the page you're looking for.</p>
            <Link href="/">Return Home</Link>
        </div>
    )
}

Triggering Not Found

Use the notFound() function to programmatically show the 404 page:

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'

export default async function BlogPost({ params }) {
    const { slug } = await params
    const post = await getPost(slug)

    if (!post) {
        notFound() // Shows the not-found.tsx page
    }

    return <article>{post.content}</article>
}

Error Handling

Create error.tsx to handle runtime errors gracefully:

// app/error.tsx
'use client' // Error boundaries must be Client Components

import { useEffect } from 'react'

export default function Error({
    error,
    reset,
}: {
    error: Error & { digest?: string }
    reset: () => void
}) {
    useEffect(() => {
        console.error(error)
    }, [error])

    return (
        <div className="error">
            <h2>Something went wrong!</h2>
            <button onClick={() => reset()}>Try again</button>
        </div>
    )
}

Nested Error Boundaries

Error files create boundaries at that route segment level. Errors bubble up to the nearest error boundary:

app/
+-- error.tsx              -> Catches all errors
+-- dashboard/
    +-- error.tsx          -> Catches dashboard errors only
    +-- page.tsx

⚠️ Important: error.tsx must be a Client Component (add 'use client' at the top). The reset() function attempts to re-render the segment.

6. Loading UI & Suspense Boundaries

Automatic Loading States

Create a loading.tsx file to show loading UI while a route segment loads:

// app/dashboard/loading.tsx
export default function Loading() {
    return (
        <div className="loading">
            <div className="spinner"></div>
            <p>Loading dashboard...</p>
        </div>
    )
}

How It Works

Next.js automatically wraps your page in a Suspense boundary:

// What Next.js does internally:
<Suspense fallback={<Loading />}>
    <Page />
</Suspense>

Skeleton Components

Create better loading experiences with skeletons:

// app/dashboard/loading.tsx
export default function DashboardLoading() {
    return (
        <div className="dashboard-skeleton">
            <div className="skeleton-header" />
            <div className="skeleton-cards">
                <div className="skeleton-card" />
                <div className="skeleton-card" />
                <div className="skeleton-card" />
            </div>
            <div className="skeleton-table" />
        </div>
    )
}

/* Skeleton animation */
.skeleton-card {
    background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
    background-size: 200% 100%;
    animation: shimmer 1.5s infinite;
}

@keyframes shimmer {
    0% { background-position: 200% 0; }
    100% { background-position: -200% 0; }
}

Manual Suspense Boundaries

Use Suspense directly for more granular control:

import { Suspense } from 'react'

export default function Dashboard() {
    return (
        <div>
            <h1>Dashboard</h1>

            <Suspense fallback={<CardsSkeleton />}>
                <DashboardCards />
            </Suspense>

            <Suspense fallback={<ChartSkeleton />}>
                <RevenueChart />
            </Suspense>
        </div>
    )
}

💡 Tip: Use multiple Suspense boundaries to stream different parts of the page independently. This allows faster content to appear first.

Section 4: Rendering & Data Fetching

1. Rendering Models: CSR, SSR, SSG, ISR

Next.js supports multiple rendering strategies. Choosing the right one depends on your content type and update frequency.

Client-Side Rendering (CSR)

Content is rendered in the browser using JavaScript. The server sends an empty HTML shell.

'use client'

import { useState, useEffect } from 'react'

export default function ClientPage() {
    const [data, setData] = useState(null)

    useEffect(() => {
        fetch('/api/data')
            .then(res => res.json())
            .then(setData)
    }, [])

    if (!data) return <p>Loading...</p>

    return <div>{data.content}</div>
}

Use for: User dashboards, real-time data, personalized content

Server-Side Rendering (SSR)

Content is rendered on the server for each request. Fresh data every time.

// app/products/page.tsx
export const dynamic = 'force-dynamic' // Opt into SSR

export default async function ProductsPage() {
    const products = await fetch('https://api.example.com/products', {
        cache: 'no-store' // Don't cache, always fresh
    }).then(res => res.json())

    return (
        <ul>
            {products.map(p => <li key={p.id}>{p.name}</li>)}
        </ul>
    )
}

Use for: Frequently changing data, user-specific content

Static Site Generation (SSG)

Content is rendered at build time. Fastest performance, cached globally.

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
    const posts = await getPosts()
    return posts.map(post => ({ slug: post.slug }))
}

export default async function BlogPost({ params }) {
    const { slug } = await params
    const post = await getPost(slug)
    return <article>{post.content}</article>
}

Use for: Blog posts, documentation, marketing pages

Incremental Static Regeneration (ISR)

Static pages that revalidate after a time period. Best of both worlds.

// app/products/page.tsx
export const revalidate = 3600 // Revalidate every hour

export default async function ProductsPage() {
    const products = await fetch('https://api.example.com/products')
        .then(res => res.json())

    return (
        <ul>
            {products.map(p => <li key={p.id}>{p.name}</li>)}
        </ul>
    )
}

Use for: E-commerce products, news articles, content that changes periodically

Comparison Table

Strategy	Build Time	Request Time	SEO	Fresh Data
CSR	Fast	Slow	Poor	Yes
SSR	Fast	Slower	Good	Yes
SSG	Slower	Fast	Good	No
ISR	Slower	Fast	Good	Periodic

2. Server Components vs Client Components

Understanding the Difference

In Next.js App Router, components are Server Components by default. They render on the server and send HTML to the client with zero JavaScript.

When to Use Server Components

Server Components Can:

Fetch data directly from databases
Access backend resources and APIs
Keep sensitive data on the server (API keys)

Server Components Cannot:

Use React hooks (useState, useEffect)
Add event listeners (onClick, onChange)
Access browser APIs (localStorage, window)

// Server Component (default) - app/dashboard/page.tsx
async function getData() {
    const res = await fetch('https://api.example.com/data', {
        headers: { 'API-Key': process.env.API_KEY }
    })
    return res.json()
}

export default async function Dashboard() {
    const data = await getData()

    return (
        <div>
            <h1>Dashboard</h1>
            <p>Total users: {data.userCount}</p>
        </div>
    )
}

When to Use Client Components

Use Client Components when you need:

State and lifecycle effects (useState, useEffect)
Event handlers (onClick, onSubmit)
Browser APIs (localStorage, geolocation)

Understanding Hydration

Hydration is the process where React attaches event listeners and makes server-rendered HTML interactive in the browser. When a page loads, the server sends pre-rendered HTML so users see content immediately. Then React 'hydrates' this HTML by attaching JavaScript functionality to make buttons clickable, forms submittable, and state manageable.

How Hydration Works:

Server renders HTML and sends it to the browser (fast initial display)
Browser displays the static HTML immediately (users see content)
JavaScript bundle loads in the background
React hydrates the HTML by attaching event handlers and state
Page becomes fully interactive

Hydration Errors and How to Fix Them

Hydration errors occur when the server-rendered HTML doesn't match what React expects to render on the client. This mismatch confuses React and can cause visual glitches or broken functionality.

Common Causes of Hydration Errors:

Using browser-only APIs like window, localStorage, or document during render
Rendering dates/times that differ between server and client
Using random values or Math.random() during render
Invalid HTML nesting (e.g., div inside p, or p inside p)
Browser extensions modifying the HTML

How to Fix Hydration Errors:

// BAD: Using window during render causes hydration error
export default function BadComponent() {
    const width = window.innerWidth // Error: window is undefined on server
    return <div>Width: {width}</div>
}

// GOOD: Use useEffect for browser-only code
"use client"
import { useState, useEffect } from 'react'

export default function GoodComponent() {
    const [width, setWidth] = useState(0)

    useEffect(() => {
        setWidth(window.innerWidth)
    }, [])

    return <div>Width: {width}</div>
}

// GOOD: Use suppressHydrationWarning for intentional mismatches
export default function TimeDisplay() {
    return (
        <time suppressHydrationWarning>
            {new Date().toLocaleTimeString()}
        </time>
    )
}

// GOOD: Use dynamic import with ssr: false for client-only components
import dynamic from 'next/dynamic'

const ClientOnlyChart = dynamic(() => import('./Chart'), {
    ssr: false,
    loading: () => <p>Loading chart...</p>
})

💡 Tip: Server Components don't hydrate at all - they render only on the server and send pure HTML. This is why they're more performant and can't use hooks or browser APIs.

⚠️ Important: Keep Client Components as leaf nodes in your component tree. Push interactivity down and keep data fetching in Server Components.

3. 'use client' - When & Why to Use It

The Client Boundary

The 'use client' directive marks a file as a Client Component. Place it at the very top of the file, before any imports.

"use client"

import { useState } from 'react'

export default function Counter() {
    const [count, setCount] = useState(0)

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={() => setCount(count + 1)}>
                Increment
            </button>
        </div>
    )
}

Common Patterns

Make small, focused Client Components and compose them within Server Components:

// app/products/page.tsx (Server Component)
import { AddToCartButton } from './AddToCartButton'

async function getProducts() {
    return fetch('https://api.example.com/products').then(r => r.json())
}

export default async function ProductsPage() {
    const products = await getProducts()

    return (
        <div className="products-grid">
            {products.map(product => (
                <div key={product.id}>
                    <h2>{product.name}</h2>
                    <p>${product.price}</p>
                    <AddToCartButton productId={product.id} />
                </div>
            ))}
        </div>
    )
}

// app/products/AddToCartButton.tsx (Client Component)
"use client"

import { useState } from 'react'

export function AddToCartButton({ productId }: { productId: string }) {
    const [added, setAdded] = useState(false)

    return (
        <button
            onClick={() => {
                addToCart(productId)
                setAdded(true)
            }}
        >
            {added ? 'Added!' : 'Add to Cart'}
        </button>
    )
}

💡 Tip: The boundary effect means all components imported into a Client Component also become client components. Design your component tree to minimize the client boundary.

4. Fetching Data in Server Components

Direct Data Fetching

Server Components can fetch data directly using async/await:

// app/posts/page.tsx
async function getPosts() {
    const res = await fetch('https://api.example.com/posts')
    return res.json()
}

export default async function PostsPage() {
    const posts = await getPosts()

    return (
        <ul>
            {posts.map(post => (
                <li key={post.id}>{post.title}</li>
            ))}
        </ul>
    )
}

Database Queries

Query your database directly - no API layer needed:

// app/users/page.tsx
import { db } from '@/lib/db'

export default async function UsersPage() {
    const users = await db.user.findMany({
        orderBy: { createdAt: 'desc' },
        take: 10
    })

    return (
        <ul>
            {users.map(user => (
                <li key={user.id}>{user.name}</li>
            ))}
        </ul>
    )
}

Caching Behavior

Next.js automatically caches fetch requests:

// Cached indefinitely (default)
const data = await fetch('https://api.example.com/data')

// Revalidate every hour
const data = await fetch('https://api.example.com/data', {
    next: { revalidate: 3600 }
})

// No caching - always fresh
const data = await fetch('https://api.example.com/data', {
    cache: 'no-store'
})

⚠️ Important: Sensitive operations like database queries should only happen in Server Components where the code never reaches the client.

5. Parallel & Sequential Data Fetching

Sequential Fetching (Waterfall)

When one fetch depends on another:

// Each fetch waits for the previous one
async function getUser(id: string) {
    const res = await fetch('/api/users/' + id)
    return res.json()
}

async function getUserPosts(userId: string) {
    const res = await fetch('/api/users/' + userId + '/posts')
    return res.json()
}

export default async function UserProfile({ params }) {
    const { id } = await params
    const user = await getUser(id)         // First, get user
    const posts = await getUserPosts(user.id)  // Then, get posts

    return (
        <div>
            <h1>{user.name}</h1>
            <PostsList posts={posts} />
        </div>
    )
}

Parallel Fetching

When fetches are independent, run them simultaneously:

// All fetches start at the same time
async function getUser(id: string) {
    const res = await fetch('/api/users/' + id)
    return res.json()
}

async function getPosts() {
    const res = await fetch('/api/posts')
    return res.json()
}

async function getComments() {
    const res = await fetch('/api/comments')
    return res.json()
}

export default async function Dashboard({ params }) {
    const { id } = await params

    // Start all fetches simultaneously
    const [user, posts, comments] = await Promise.all([
        getUser(id),
        getPosts(),
        getComments()
    ])

    return { user, posts, comments }
}

Practical Example

// app/dashboard/page.tsx
async function getStats() {
    return fetch('https://api.example.com/stats').then(r => r.json())
}

async function getRecentOrders() {
    return fetch('https://api.example.com/orders?limit=5').then(r => r.json())
}

async function getNotifications() {
    return fetch('https://api.example.com/notifications').then(r => r.json())
}

export default async function Dashboard() {
    const [stats, orders, notifications] = await Promise.all([
        getStats(),
        getRecentOrders(),
        getNotifications()
    ])

    return (
        <div>
            <StatsCards stats={stats} />
            <OrdersTable orders={orders} />
            <NotificationsList notifications={notifications} />
        </div>
    )
}

⚠️ Important: Always use Promise.all() / Promise.allSettled() / Promise.race() depending on your requirement when fetching independent data. This can dramatically improve page load times.

Understanding Promise Methods

Promise.all() - Waits for ALL promises to resolve. If any promise rejects, the entire operation fails immediately. Use when you need all data and can't proceed without it.

Promise.allSettled() - Waits for ALL promises to complete (resolve or reject). Never fails early; returns status and value/reason for each. Use when you want partial results even if some requests fail.

Promise.race() - Returns as soon as the FIRST promise settles (resolves or rejects). Use for timeouts or when you only need the fastest response.

// Promise.all - fails if any request fails
const [users, posts] = await Promise.all([getUsers(), getPosts()])

// Promise.allSettled - returns results even if some fail
const results = await Promise.allSettled([getUsers(), getPosts()])
results.forEach(result => {
    if (result.status === 'fulfilled') console.log(result.value)
    if (result.status === 'rejected') console.log(result.reason)
})

// Promise.race - returns first settled promise
const fastest = await Promise.race([fetchFromCDN1(), fetchFromCDN2()])

This article covers the first half of the Next.js 16 Complete Beginner's Guide. For the complete guide including Server Actions, Authentication, Backend APIs, and more, download the full 110-page PDF for FREE.

🚀 Ready to Master Next.js?

Take your skills to the next level by building large-scale, production-ready applications with my comprehensive video course.

👉 Enroll Now.

About Me

I'm a freelancer, mentor, and full-stack developer with 12+ years of experience, working primarily with React, Next.js, and Node.js.

Alongside building real-world web applications, I'm also an Industry/Corporate Trainer, training developers and teams in modern JavaScript, Next.js, and MERN stack technologies with a focus on practical, production-ready skills.

I've also created various courses with 3000+ students enrolled.

My Portfolio: https://yogeshchavan.dev/

The Future: Engineers as AI System Architects

Siddhartha Reddy — Mon, 20 Apr 2026 07:30:00 +0000

AI is not replacing engineers.

It’s redefining what it means to be one.

🚨 The Narrative is Wrong

The common belief:

“AI will replace programmers”

But what’s actually happening is more subtle:

AI is replacing parts of programming not the role of engineers

🧠 What’s Actually Changing

Traditionally, engineers:

Wrote code
Debugged logic
Built features

Now, increasingly, they:

Guide AI systems
Design workflows
Validate outputs

👉 The shift is not from engineer → obsolete

👉 It’s from engineer → architect

⚙️ From Coding to Orchestration

Old workflow:

Write → Debug → Deploy

New workflow:

Define → Generate → Evaluate → Refine → Deploy

Engineers are no longer just writing code.

They are:

Orchestrating systems that produce code

🤖 The Rise of AI Systems

Modern systems include:

LLMs
Tool integrations
Feedback loops
Memory layers

These systems:

Generate solutions
Test them
Improve over time

👉 The intelligence is in the system, not just the model.

🧩 The New Skill Stack

The engineers who will thrive understand:

✅ Systems thinking

How components interact and fail

✅ Data flows

Where inputs come from and how they change

✅ Evaluation

How to measure correctness beyond accuracy

✅ Tooling

How to integrate models into real workflows

✅ Feedback loops

How systems improve over time

❌ What Becomes Less Important

Not irrelevant — but less dominant:

Writing boilerplate code
Memorizing syntax
Manual implementation of standard patterns

👉 These are increasingly handled by AI.

🧑‍💻 What Becomes More Important

Designing robust systems
Handling uncertainty
Managing failure cases
Making trade-offs (speed vs cost vs accuracy)

👉 These cannot be automated easily.

⚠️ The Risk: Shallow Engineers

There’s a danger emerging:

Engineers who can generate code…

but don’t understand systems

This leads to:

Fragile products
Poor debugging ability
Hidden technical debt

👉 AI amplifies both skill and ignorance.

🚀 The Opportunity

The engineers who win won’t be:

The best coders

They’ll be:

The best system designers

🔁 The Future of Software

We’re moving toward systems that:

Generate code
Test themselves
Adapt to new data
Improve continuously

Software becomes:

A living system, not a static artifact

🧠 If You Take One Thing Away

Learn how systems work.

Not just how to write code.

💬 Final Thought

Everyone is learning how to use AI.

Very few are learning how to:

Design AI systems

👉 That gap defines the next generation of engineers.

Launch Day: 7 AI Agents Start Building Startups with $100 Each

Joske Vermeulen — Mon, 20 Apr 2026 07:30:00 +0000

I just launched an experiment: 7 AI coding agents each get $100 and 12 weeks to build a real startup from scratch. No human coding.

The lineup

Agent	Tool	Model	Cost
🟣 Claude	Claude Code	Sonnet / Haiku	$20/mo
🟢 GPT	Codex CLI	GPT-5.4 / Mini	€23/mo
🔵 Gemini	Gemini CLI	2.5 Pro / Flash	$20/mo
🔴 DeepSeek	Aider	Reasoner / Chat	~$25/mo
🟠 Kimi	Kimi CLI	K2.5	~$19/mo
🟡 Xiaomi	Aider	MiMo V2 Pro	~$25/mo
🟤 GLM	Claude Code	GLM-5.1 / 4.7	$18/mo

Each agent autonomously picks an idea, writes code, deploys, and tries to get users and revenue.

What I learned from 3 test runs

Strategy > code quality. Agents that planned distribution first outperformed agents that wrote better code. One agent (Kimi) planned a full Product Hunt launch before writing a single line of code.

Simple stacks win. HTML + Tailwind deployed in hours. Next.js agents spent days on build errors. The deploy loop is the real bottleneck for AI agents.

Context resets kill progress. Without persistent state between sessions, agents repeat mistakes. I built an orchestrator with structured state files to solve this.

The tech

A bash orchestrator manages everything:

Cron-scheduled 30-minute sessions (2-8 per agent per day)
Automatic git commits with [skip ci] on mid-session commits
Deploy verification via health checks
Loop detection (same action 3x = force alternative)
OpenRouter budget alerts via Discord

All code is public on GitHub.

Follow along

Live Dashboard — real-time progress
Daily Digest — hand-written daily updates
Weekly Recaps — detailed analysis
Full Rules

Also launched on Product Hunt today.

Which agent would you bet on?

What Is LangGraph? A Beginner-Friendly Introduction

ITPrep — Mon, 20 Apr 2026 07:20:45 +0000

What Is LangGraph? A Beginner-Friendly Introduction

As LLM applications become more advanced, developers often need more than a simple prompt-response flow. Many modern AI apps must keep track of state, call tools, make decisions, and loop through multiple steps.

That is where LangGraph becomes useful.

I originally published the full Vietnamese guide here: LangGraph là gì? Hướng dẫn toàn diện cho người mới bắt đầu

What is LangGraph?

LangGraph is a framework for building stateful and agentic applications with large language models. It is especially useful when your workflow needs multiple steps, conditional routing, memory, and tool usage.

In simple terms, LangGraph helps you model an AI workflow as a graph.

The 3 core concepts of LangGraph

1. State

State is the shared data that moves through the workflow. It allows the system to keep track of what has already happened and what should happen next.

2. Nodes

A node represents an action in the workflow. For example, a node can:

call an LLM,
search for information,
process user input,
or evaluate a result.

3. Edges

Edges define how the workflow moves from one node to another. Some transitions are fixed, while others depend on conditions.

Why should developers care?

A normal chatbot often follows a simple pattern: user input goes in, model output comes out.

But real AI applications are more complex. You may need to:

call tools,
retry failed steps,
branch into different flows,
or stop only when the answer is good enough.

This is exactly where LangGraph becomes powerful.

A simple real-world example

Imagine an AI assistant that:

receives a question,
searches for information,
checks whether the answer is sufficient,
searches again if needed,
and then returns the final response.

That kind of multi-step logic is much easier to manage with a graph-based workflow.

When should you learn LangGraph?

LangGraph is worth learning if you want to build:

AI agents,
research assistants,
tool-using chatbots,
multi-step LLM workflows,
or applications that require memory and control flow.

If you only need a basic chatbot, LangChain alone may be enough. But if your application needs more structure and decision-making, LangGraph is a strong next step.

Final thoughts

LangGraph is a valuable tool for developers who want to move from simple LLM demos to more structured and reliable AI systems.

If you want the full roadmap, prerequisites, detailed explanation, and learning guide, I wrote the complete Vietnamese version here:

Read the full guide on ITPrep

FinOps for AI vs Traditional FinOps: Key Differences Explained

Datta Kharad — Mon, 20 Apr 2026 07:18:21 +0000

Cloud cost management has always been a balancing act. But with the rise of AI—especially generative AI—that balance is shifting from predictable arithmetic to something far more dynamic.
Welcome to the evolving world where traditional FinOps meets AI-driven uncertainty.
The Foundation: What is FinOps?
At its core, FinOps (Financial Operations) is a cultural and operational practice that brings together engineering, finance, and business teams to manage cloud spend efficiently.
Traditional FinOps focuses on:
• Cost visibility
• Budget control
• Resource optimization
• Forecasting and accountability
It thrives in environments where workloads are stable, predictable, and measurable.
But AI changes the rules.
The Shift: Why AI Breaks Traditional Cost Models
AI workloads—especially those involving large language models—don’t behave like traditional applications.
They are:
• Compute-intensive
• Data-hungry
• Usage-variable
• Experiment-driven
This introduces a new dimension: cost unpredictability at scale.
FinOps for AI: A New Operating Model
FinOps for AI is not just an extension—it’s a transformation.
It redefines cost management across:
• Model training
• Inference workloads
• Data pipelines
• Experimentation cycles
Here, cost is no longer tied only to infrastructure—it’s tied to intelligence itself.
Key Differences: FinOps for AI vs Traditional FinOps

Cost Structure: Static vs Elastic • Traditional FinOps Predictable costs (VMs, storage, bandwidth) • AI FinOps Highly variable costs driven by: o GPU/TPU usage o Training cycles o Token-based pricing (LLMs) Insight: AI introduces burst economics—short periods of extremely high cost.
Resource Optimization: Right-Sizing vs Right-Thinking • Traditional Optimize instance size, auto-scaling, reserved instances • AI Optimize: o Model size o Training frequency o Inference efficiency Insight: In AI, optimization is not just infrastructure—it’s algorithmic efficiency.
Forecasting: Predictable vs Probabilistic • Traditional Forecast based on historical usage trends • AI Forecast based on: o Experimentation pipelines o Model iterations o User interaction patterns Insight: AI forecasting is closer to probability modeling than budgeting.
Cost Drivers: Infrastructure vs Intelligence • Traditional Servers, storage, network • AI o Data volume o Model complexity o Inference frequency Insight: The cost center shifts from “compute” to “decisions per second.”
Team Collaboration: Finance + Engineering vs Cross-Disciplinary • Traditional Finance + DevOps • AI Finance + DevOps + Data Scientists + ML Engineers Insight: AI FinOps requires multi-layer collaboration.

I Built and Shipped a $39 macOS App in One Day (Here's How)

hiyoyo — Mon, 20 Apr 2026 07:16:09 +0000

Yesterday I had an idea. Today it's on Gumroad making money.
Here's exactly how I shipped HiyokoBar — a menu bar HUD for engineers — in a single day.

The Idea
I was constantly alt-tabbing to check Docker status, GitHub PRs, server health.
I wanted something that pushes information to me, not something I have to pull from.
Raycast is great but it's Pull-type. You invoke it when you need it.
I wanted a HUD that's always there — like a cockpit instrument panel for my Mac.

The Unfair Advantage: Code Reuse
I didn't start from zero. I have a portfolio of macOS utility apps built with Rust + Tauri 2.0, and I ruthlessly reused everything I could:
ComponentSourceMenu bar skeletonHiyokoHelper (internal app)Keychain storageHiyokoKitGumroad license authHiyokoShotParallel executionHiyokoAutoSyncGemini AI integrationHiyokoLogcat
The menu bar app architecture — tray icon, click to show/hide, window positioning — was already battle-tested. I just dropped in new features.
This is why building a product suite matters more than one-off apps.

Timeline
Morning

Copied HiyokoHelper as the base
Replaced window positioning with tauri-plugin-positioner
Got the HUD dropping down from the menu bar icon

Midday

Built the shell script execution engine in Rust
Card UI in React with Framer Motion animations
Polling with random jitter to avoid CPU spikes

Afternoon

Gemini AI error analysis (ported from HiyokoLogcat)
GUI settings editor — no JSON required
Drag & drop card reordering
Real-time countdown timers

Evening

Gumroad license auth (ported from HiyokoShot)
macOS Keychain for API key storage
OWASP security audit (caught a critical A02 bug — API keys were stored in plain JSON instead of Keychain)
i18n (Japanese / English)
Gumroad listing, README, pricing

Total: ~8 hours

The Security Audit Saved Me
Before shipping, I ran through OWASP Top 10 for native apps.
Found a critical bug: despite the design doc saying "store in Keychain," the actual implementation was saving API keys in plain JSON.
A quick audit before shipping caught what code review missed.
Always check OWASP before you ship. Even for "simple" apps.

Pricing: $39 One-Time
I originally planned $29. Looked at what I built and charged $39.
The target is senior engineers. They don't blink at $39 for a tool they'll use every day. Underpricing signals low quality to this audience.

What's Next

Product Hunt launch this week
v3.0 ideas: community recipe store, macOS notifications, multi-AI support

Try It

HiyokoBar: https://hiyokoko.gumroad.com/l/hiyokobar

🇯🇵 日本語版: https://hiyokoko.gumroad.com/l/hiyokobar_jp

🐤 Launched on Product Hunt today — would love your support!
https://www.producthunt.com/products/hiyokobar

X: @hiyoyoko

AI-Native Workflow: The Operating Manual for Your Agent

idavidov13 — Mon, 20 Apr 2026 07:15:53 +0000

Imagine your first day on a new team. The codebase is well organized, the docs are written, the linter is configured.

Nobody, however, tells you how this team actually works. Which channel for what, when to ask before pushing, when the senior dev expects to review.

That's exactly what a new engineer faces when they first open the scaffold we've been building across this series. The folders are clean, CLAUDE.md is loaded, the skills are sitting in .claude/skills/.

Then you open the chat, type your first prompt, and... what are you supposed to say?

The previous six articles built the scaffold. The first gave it structure, the second explained what makes an agent different from a chatbot, and the third gave the agent its rules.

The fourth gave it deep expertise. The fifth gave it eyes. The sixth showed all of those parts working together on a real task.

But none of that tells you how to drive the machine. That's what this article is about, and it kicks off a new sub-series inside Agentic QA called Working With the Agent.

🗺️ The Operating Manual: What ai-native-workflow Is

ai-native-workflow is the meta skill that ties every other skill together. Where the deep skills tell the agent how to write a page object or an API test, the meta skill tells the agent how to behave on this scaffold. It's the operating manual for the machine you've been handed.

Think of the system as three layers, each loaded at a different time.

Layer	What it is	When it loads
L1: Orchestrator	`CLAUDE.md` - the constitution, the workflow, the skills index	Always
L2: Specialized skills	`.claude/skills/{name}/SKILL.md` - deep rules, phased instructions	Triggered by your wording
L3: Code conventions	The actual TypeScript - fixtures, page objects, enums, factories	Read on demand from the repo

You usually don't think about which skill loads. You describe the work in plain language and the meta skill routes the request to the right specialist. The orchestrator is the table of contents, the skills are the brain, the code is the truth.

🤝 The Conversation Contract

This is the single most important habit to internalize. Every non-trivial task on the scaffold follows the same five-step loop, called audit-then-edit.

You state the goal in plain language.
The agent loads the relevant skill and proposes scope - what will change, in which files, why, with trade-offs.
You approve, modify, or reject.
The agent applies the change.
The agent reports what landed and asks whether to commit.

For one-line fixes and obvious typos there's a faster path called direct mode - the agent just does it. You can opt into direct mode for a whole session by saying "just do it" once.

The contract has hard stops baked in. The agent must stop and ask whenever a path, an enum value, a message, or an endpoint is unknown. It must refuse to ship guessed selectors, hardcoded credentials, suppressed test failures, any types, XPath, or page.waitForTimeout(...). These aren't preferences. They're refusals.

Audit-then-edit is the difference between an agent that helps you and an agent that surprises you.

🧭 How the Right Skill Loads Itself

You don't pick the skill. The way you phrase the task picks it for you. This is the full routing table the meta skill uses to dispatch work.

You say...	First skill that loads	Then chains to
"Add tests for `POST /api/...`"	`api-testing`	`data-strategy`, `enums`, `type-safety`, `debugging`
"Add a page object for the settings page"	`page-objects`	`selectors`, `playwright-cli`, `enums`, `fixtures`
"How do I add Y? / Generate the prompt for X"	`common-tasks`	the matching specialized skill
"Test is failing / behaving unexpectedly"	`debugging`	`api-testing`, `selectors`, `fixtures`, `refactor-values`
"Rename this enum value / change a static-data row"	`refactor-values`	`enums` or `data-strategy`, then `debugging`
"Create a new factory"	`data-strategy`	`type-safety`, `api-testing`
"Add a helper / fixture"	`helpers` or `fixtures`	`api-testing` Phase 8 (promotion criteria)
"Add an env var / config / utility URL"	`config`	`enums`, `type-safety`
"Add an enum / endpoint / message"	`enums`	`playwright-cli` for live-text verification
"Refactor a Zod schema / `any` to typed"	`type-safety`	`api-testing`
"Add a new spec file / tagging question"	`test-standards`	`data-strategy`, `api-testing`, `page-objects`

If nothing matches, the agent defaults to common-tasks or asks you. The lesson: describe the work, don't name the skill. Naming a skill is a fallback for when the agent loaded the wrong one.

🔄 The 7-Phase Rhythm of Every Task

Once a skill loads, the work moves through the same seven phases. The rhythm is the same whether you're adding a test, refactoring an enum, or hunting a flaky failure.

Identify the work category. New artifact, edit, refactor, debug, or investigation.
Explore before generating. playwright-cli for UI, OpenAPI for API, ls pages/ and ls enums/ for repo conventions. If exploration is impossible, the agent stops and notifies you.
Propose scope. What, where, why. You approve before any file changes.
Apply the critical rules from each loaded skill. These are hard stops, not suggestions.
Verify against the skill's checklist - the api-testing coverage matrix, the page-objects fixture registration, the refactor-values tsc + eslint + targeted tests gate.
Run the affected tests. npx playwright test <file>, never the full suite. On red, the debugging skill loads.
Commit with a why message. Title imperative and specific, body lists substantive changes, one logical change per commit.

Notice that exploration is phase two, not phase four. The scaffold treats "look before you build" as non-negotiable.

🧱 Five Principles That Make the Scaffold AI-Native

Underneath all the skills and phases, five principles do the heavy lifting. They exist so the agent never has to guess.

Single source of truth per value class. URLs and credentials live in process.env.*. Endpoint paths and UI messages live in enums/{area}/. Universal invalid values live in test-data/static/util/invalid-values.ts. Dynamic happy-path data comes from Faker factories in test-data/factories/{area}/. There is exactly one right place for every kind of value.
Hard-stop forbidden patterns. Every Critical block in every skill has a list of NEVER rules with concrete anti-examples. They trigger refusal, not warnings.
Mandatory exploration discipline. playwright-cli for UI, OpenAPI or docs first for API. No guessing selectors. No inventing endpoints.
Strict folder discipline. Every artifact has exactly one home. The folder layout maps cleanly to skill names so keyword routing works.
Phased instructions inside skills. You don't invent a workflow per task. You follow the phases the skill already defined.

The result is consistency. The same prompt, given on a Monday or a Friday, produces the same shape of output.

🎬 A Worked Example: From Prompt to Commit

Say you ask: "Add API tests for POST /api/products."

CLAUDE.md is already loaded. The wording routes through common-tasks to api-testing. The agent confirms an OpenAPI spec exists for /api/products, then runs ls fixtures/api/schemas/, ls tests/, and ls enums/ to ground itself in the conventions.

It proposes scope: schema name and location, factory name and location, spec structure, the full status-code coverage matrix, the validation tiers. You approve.

It applies the change using z.strictObject() from type-safety, expect(Schema.parse(body)).toBeTruthy() from api-testing, the ApiEndpoints.PRODUCTS enum from enums, and a Faker factory from data-strategy. It tags the spec with @api per test-standards. It verifies against the api-testing Phase 5 coverage matrix.

It runs npx playwright test tests/{area}/api/products.spec.ts. Green. It commits with the message Add POST /api/products tests with full coverage matrix and asks whether to continue.

That's the whole loop. Seven phases, three skills, one approval point.

🚧 Common Gotchas And How to Steer Out of Them

A few things go sideways often enough to be worth naming.

The agent generates something off-convention. It loaded the wrong skill. Name the skill in your next prompt: "use the api-testing skill". Then ask it to redo.
The agent invents a folder, an enum value, or an env var. Reject it. Require re-verification with ls, the OpenAPI spec, or playwright-cli. The fix is exploration, not regeneration.
The agent suppresses a failing test with .skip, raised timeouts, or weakened assertions. Reject the suppression. Require the debugging skill's root-cause phases instead.
Cursor and Claude Code give different answers. The .claude/skills/ directory is the canonical source. The mirrors in .cursor/skills/ and .github/instructions/ may lag. When in doubt, defer to .claude/.

The pattern in all four: when the agent goes off the rails, the fix is to push it back into the workflow, not to do the work yourself.

🚀 Get Started

You have everything you need to start working with the agent on a real task.

You can find the public README for the scaffold on GitHub: Playwright Scaffold.

You can get access to the private GitHub repository here: Get Access.

🙏🏻 Thank you for reading! This article opens the Working With the Agent sub-series inside Agentic QA. The next ones will go deeper into the daily moments of working with an AI agent on the scaffold, one habit at a time.

The Snapshot That Travels

Vivian Voss — Mon, 20 Apr 2026 07:15:33 +0000

The Unix Way — Episode 13

At three in the morning, on a production cluster with state measured in terabytes, the question is not which backup tool you have. It is whether any of them will finish before breakfast.

The usual answer involves three tools: one for backup, one for replication, one for versioning. Each excellent in isolation, and architecturally in each other's way once state crosses the point where tarballs and rsync stop being a reasonable proposition. FreeBSD's answer has been sitting there since FreeBSD 7.0 (2008). ZFS treats snapshots, replication, and copy-on-write as properties of the filesystem itself. Three workflows become three uses of the same primitive.

A Short History

ZFS began at Sun Microsystems in 2001 and was released under the CDDL in 2005 as part of OpenSolaris. Paweł Jakub Dawidek ported it to FreeBSD in 2007; FreeBSD 7.0 shipped it as a proper filesystem option, and FreeBSD 8.0 (2009) made it a first-class citizen. When Oracle acquired Sun in 2010 and quietly discontinued the open development of Solaris, the future of ZFS outside Oracle's walls was in doubt. The illumos community forked OpenSolaris to preserve it; in 2013 the OpenZFS project was founded to unify development across FreeBSD, illumos, and (eventually) Linux and macOS. In 2020, OpenZFS 2.0 merged the Linux and BSD codebases into a single source. Since FreeBSD 13.0 (2021), FreeBSD has shipped the unified OpenZFS 2 codebase.

The interesting consequence: ZFS is no longer "the Solaris filesystem ported to FreeBSD". It is a platform-independent filesystem maintained by a community that includes everyone who depends on it. The most architecturally committed user remains FreeBSD, where ZFS has been the installer default for over a decade.

Local Snapshots

zfs snapshot tank/data@before-i-try-something-clever

That is the entire command including a proper commit message. Atomic, takes milliseconds on active datasets, no locks, no files copied. The snapshot is an immutable view of every block at that instant. A snapshot is not a copy; it is a reference to the blocks as they were. Writing to the live dataset allocates new blocks; the snapshot continues to point to the old ones. This is copy-on-write at the filesystem layer, not bolted on top of it.

Linux has btrfs, which offers similar subvolume snapshots. It is, in fairness, the only serious counterpart. Alas, btrfs RAID 5/6 is still marked "strongly discouraged for production" in 2026, which one does find a trifle awkward for a system meant to hold long-term state. Btrfs has its strengths: it ships with mainline Linux, it is well-integrated into Ubuntu and Fedora, and its single-disk and mirrored-RAID configurations are perfectly serviceable. It is not, however, what one chooses for a 40 TB production cluster with parity RAID.

Across a Cluster

zfs send tank/data@A | ssh standby zfs receive tank/data
zfs send -i tank/data@A tank/data@B | ssh standby zfs receive tank/data

Block-level, not file-level. The first command ships the entire dataset as a stream. The second ships only the delta between snapshots A and B. For a 40 TB dataset with small deltas, the incremental transfer is seconds, not hours. Published benchmarks put full-send rates at 100 to 300 MB/s and incremental sends at around 60 MB/s on commodity hardware; the real surprise is how small the deltas become. A 1 TB dataset with a 1% daily change rate ships roughly 10 GB per replication cycle. A 512 MB benchmark dataset where only metadata changed: 33 KB incremental. Once the initial full send is done, ongoing replication is close to free for stable workloads.

This is how disaster-recovery standbys are kept in sync, how clusters replicate read replicas, how staging is rebuilt from production in the time it takes to boil a kettle. The automation ecosystem around this primitive is mature: Sanoid handles policy-driven snapshot scheduling, Syncoid orchestrates incremental sends via cron, zrepl runs as a long-lived daemon with TLS and bandwidth limiting for links that matter. Each sits on top of the same five or six subcommands.

Btrfs send/receive exists. It (alas) requires the source subvolume to be made read-only before the send, which is a trifle inconvenient for continuously active state, and its automation ecosystem has not reached the same maturity.

Something Rather Like Git

If one insists on the metaphor: every snapshot is an immutable commit, every clone a branch.

zfs clone tank/data@A tank/branch-experiment

The clone costs no disk space until it diverges. Reads still come from the shared baseline. This is Git's copy-on-write semantics applied to the entire filesystem, except it works on blocks rather than files, and it does not care whether the content is source code, a PostgreSQL data directory, or 40 TB of scientific observations.

One can spin up fifty clones of a multi-terabyte database for fifty engineers, each with their own writable branch, for the price of the blocks they actually change. AWS has productised exactly this pattern in FSx for OpenZFS: Oracle databases at near-petabyte scale, cloned in seconds, zero additional capacity consumed until divergence. The same pattern is used in CI pipelines to give every test run its own writable snapshot of the production dataset, torn down when the run completes.

zfs diff reports changes at file level between two snapshots. zfs rollback returns a dataset to a prior snapshot, undoing every write since. zfs promote swaps a clone with its origin, turning the branch into the main line. Replication via send is effectively git push. The filesystem is the version control.

Btrfs offers subvolume snapshots and clones. Its RAID 5/6 is officially not production-ready, its dedup is offline-only (batch, not inline), and its quota accounting has historically slowed noticeably with many snapshots. One would prefer rather more predictable ground under the version-control layer of one's infrastructure.

The Point

On FreeBSD, ZFS is the installer default. The snapshot-as-stream philosophy is not a backup strategy bolted on top. It is the filesystem. There is no separate "backup layer", "replication layer", or "branching layer". There is the pool, the dataset, the snapshot, and the stream. Everything else is a composition of those four primitives.

This is the Unix philosophy applied to storage: small, orthogonal operations that compose. The value is not in any one of the commands. It is in the fact that snapshot, send, receive, clone, diff, rollback, and promote are variations on the same model.

Backup, replication, and branching are not three tools. They are three uses of the same primitive.

Read the full article on vivianvoss.net →

By Vivian Voss — System Architect & Software Developer. Follow me on LinkedIn for daily technical writing.

Personal token factory: OpenClaw in AWS but Nvidia GB10 at home

Piotr Pabis — Mon, 20 Apr 2026 07:14:17 +0000

Even though Nemotron 3 Super is still free on OpenRouter, the agreement is that you donate all your exchanges to Nvidia for training. A paid version is available also quite cheaply ($0.10/M input, $0.50/M output.) I still decided to utilize my ASUS GX10 (aka DGX Spark aka GB10) as the token source for my agent hosted at AWS. But the trick here is the following: I don't want to open my home network to the outside Internet! Another rule: I don't want to pay for any public IPv4 address to AWS. Will I be able to achieve that? That's actually simple! Let me guide you today how I achieved that setup.

Above you can see that I plan to tunnel both home and AWS networks using Wireguard. I could potentially make this site-to-site but to make it simpler and safer for my home devices, I will only connect to Wireguard server (listener) on AWS side with DGX Spark as a client. I will do it over IPv6. At the bottom you can see that my home devices have normal connectivity to both IPv6 and IPv4 Internet but on AWS side I am relying solely on IPv6 (although internally VPC still uses private IPv4 range). There will be some issues with that but we will fix them later.

Companion GitHub repo: github.com/ppabis/wireguard-openclaw-dgx

Setting up VPC and Wireguard server

I have created a simple VPC using a module with range 10.189.80.0/21 with IPv6 enabled. It has Internet Gateway in public subnets and egress only Internet Gateway for IPv6 outbound connectivity. I disabled NAT gateway on purpose, we will cover this issue later. Instances in public subnet will be reachable over IPv6 from the outside - this is where we will place our Wireguard server. OpenClaw will remain inside the private subnet.

data "aws_availability_zones" "available" {
  state = "available"
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 6.6.0"

  name = "my-vpc"
  cidr = "10.189.80.0/21"

  azs             = slice(data.aws_availability_zones.available.names, 0, 3)
  public_subnets  = ["10.189.80.0/24", "10.189.81.0/24", "10.189.82.0/24"]
  private_subnets = ["10.189.83.0/24", "10.189.84.0/24", "10.189.85.0/24"]

  enable_dns_hostnames = true
  enable_dns_support   = true
  enable_nat_gateway   = false

  enable_ipv6                                    = true
  public_subnet_assign_ipv6_address_on_creation  = true
  private_subnet_assign_ipv6_address_on_creation = true
  public_subnet_ipv6_prefixes                    = [0, 1, 2]
  private_subnet_ipv6_prefixes                   = [3, 4, 5]

  private_subnet_tags = { type = "private" }
  public_subnet_tags  = { type = "public" }
}

Creating Wireguard server instance

First of all, I will create an EC2 instance with latest Amazon Linux 2023. It includes WireGuard already in the repositories and the update servers work over IPv6. I will run my WireGuard server on port 51280 so that's what I will open on the security group. All egress should also be open. I will attach am IAM role to it as well, no permissions but it will come handy later. First, define all the smaller components.

data "aws_ssm_parameter" "al2023_arm64" {
  name = "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-arm64"
}

resource "aws_security_group" "wireguard" {
  name_prefix = "wireguard-sg"
  vpc_id      = module.vpc.vpc_id

  ingress {
    from_port        = 51280
    to_port          = 51280
    protocol         = "udp"
    ipv6_cidr_blocks = ["::/0"]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

data "aws_iam_policy_document" "wireguard_assume_role_policy" {
  statement {
    actions = ["sts:AssumeRole"]
    principals {
      type        = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "wireguard" {
  name               = "wg-ec2-role"
  assume_role_policy = data.aws_iam_policy_document.wireguard_assume_role_policy.json
}

resource "aws_iam_instance_profile" "wireguard" {
  name = "wg-ec2-profile"
  role = aws_iam_role.wireguard.name
}

And finally we can define the EC2 instance. It will be the cheapest and smallest possible one I can find, which is t4g.nano. AMI ID is pulled from publicly shared SSM parameter (easier than AMI data source in Terraform). From networking I'm disabling public IPv4 assignment, forcing at least one IPv6 and disabling source destination check (more on that later). I didn't define any SSH connectivity, nor EC2 Instance Connect or Session Manager. The cheapest option here would be to define a key pair and open 22 on IPv6 to your subnet if you need debugging.

resource "aws_instance" "wireguard" {
  ami                         = data.aws_ssm_parameter.al2023_arm64.value
  instance_type               = "t4g.nano"
  iam_instance_profile        = aws_iam_instance_profile.wireguard.name
  subnet_id                   = module.vpc.public_subnets[0]
  vpc_security_group_ids      = [aws_security_group.wireguard.id]
  associate_public_ip_address = false
  ipv6_address_count          = 1
  source_dest_check           = false

  user_data = local.user_data

  tags = { Name = "Wireguard" }
  lifecycle { ignore_changes = [ami] }
}

output "ipv6" {
  value = aws_instance.wireguard.ipv6_addresses[0]
}

Installing and configuring Wireguard on the server

How would we install the server if we have no SSH or any other shell access to the instance? As you see above, I have defined user data. This is a script that runs on first instance boot... if you just use pure Bash. For our use case, we want to be able to control instance contents dynamically. For that we will use cloud-init, which allows for more flexibility regarding user data contents. We will start with the draft defining "attachments" with both cloud-init's cloud-config (YAML) as well as standard Bash script that starts on boot. I'm writing this in a new file called user-data.yaml (although it's not a valid YAML file).

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0

--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"

#cloud-config
package_update: true

--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"

#!/bin/bash
echo "Configuring WireGuard..."
--//--

Side note

If you know cloud-init, you might wonder why I want to use also user data. For some reason runcmd doesn't always execute when I want it to and bootcmd happens too early.

As you see we have two sections in this file. First, we have defined cloud-config that will just update packages on startup. Second script will also execute on first boot and just echo a message. Now what we can do is to configure each module to run on every restart. In cloud-config add this (insert between boundaries):

#cloud-config
package_update: true
cloud_final_modules:
  - [scripts-user, always]

cloud_config_modules:
  - [write_files, always]
  - [package_update_upgrade_install, always]

Now all the sections (that we define soon) will run on every instance reboot. This will give us some flexibility in changing the configuration (although requiring reboot but how often do you plan to change this 😄). Let us install required packages: Wireguard itself, iptables for routing capabilities and for convenience if you need to debug, tmux and htop can come in handy.

packages:
  - wireguard-tools
  - iptables-nft
  - htop
  - tmux

Now let's proceed with Wireguard configuration. As previously stated, I want to use 10.155.222.0/24 as the subnet and listen on port 51280. The private key will be a placeholder for safety reasons. When the tunnel is brought up, we are going to enable IP forwarding in the kernel and allow forwards between wg0 Wireguard's interface and ens5 (primary network card in AL2023 at least). The router address (sever) will be the first one in the subnet 10.155.222.1.

write_files:
  - path: /etc/wireguard/wg0.conf
    content: |-
      [Interface]
      Address    = 10.155.222.1/24
      ListenPort = 51280
      PrivateKey = _PRIVATE_KEY_

      # Enable routing + NAT for WG clients to reach VPC
      PostUp   = sysctl -w net.ipv4.ip_forward=1
      PostUp   = iptables -A FORWARD -i wg0 -o ens5 -j ACCEPT
      PostUp   = iptables -A FORWARD -i ens5 -o wg0 -j ACCEPT

      PostDown = iptables -D FORWARD -i wg0 -o ens5 -j ACCEPT
      PostDown = iptables -D FORWARD -i ens5 -o wg0 -j ACCEPT
      # End of file

This configuration is not yet usable until we create another part of the user data attachment. In the Bash script that is going to run on every machine startup, we are going to generate Wireguard's key pair, if it doesn't exist, and if it does, we will just replace the _PRIVATE_KEY_ placeholder with sed. But that's not all! We also need the public key of the server after all to connect. As I don't want to need any SSH-like connectivity to this server, it will export the public key to AWS Systems Manager Parameter Store.

--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"

#!/bin/bash
set -eo pipefail

echo "Configuring WireGuard..."
# If there's no private key, generate the private key into a file and derive
# the public one also into a file.
if [ ! -f /etc/wireguard/private.key ]; then
  wg genkey | tee /etc/wireguard/private.key | wg pubkey > /etc/wireguard/public.key
fi

# Replace the private key placeholder if it exists in wg0.conf
sed -i "s#_PRIVATE_KEY_#$(cat /etc/wireguard/private.key)#g" /etc/wireguard/wg0.conf

# Export the public key to SSM Parameter Store. Use IPv6 endpoint.
echo "Public key: $(cat /etc/wireguard/public.key)"
export AWS_USE_DUALSTACK_ENDPOINT=true
aws ssm put-parameter --type "String" --overwrite \
 --name "/wireguard/public-key" \
 --value "$(cat /etc/wireguard/public.key)"

# Start the tunnel.
wg-quick up wg0

--//--

Currently if you run the script, the machine will not be able to write into Parameter Store because the IAM role doesn't have such permissions. Add the following policy to the previously defined role.

data "aws_caller_identity" "X" {}
data "aws_region" "X" {}

data "aws_iam_policy_document" "wireguard_ssm_policy" {
  statement {
    actions   = ["ssm:PutParameter"]
    resources = ["arn:aws:ssm:${data.aws_region.X.region}:${data.aws_caller_identity.X.account_id}:parameter/wireguard/public-key"]
  }
}

resource "aws_iam_role_policy" "wireguard_ssm_policy" {
  name   = "wg-ssm-policy"
  role   = aws_iam_role.wireguard.id
  policy = data.aws_iam_policy_document.wireguard_ssm_policy.json
}

As the last part, add the user data local variable. I will use templatefile because we are going to do some dynamic things later, so it will come in handy.

locals {
  user_data = templatefile("${path.module}/user-data.yaml", {})
}

When you now deploy this infrastructure, after some minutes you should get a public key in SSM Parameter Store under wireguard/public-key. You can use it to configure the client connections. You can also use the following command to get the public key value.

aws ssm get-parameter \
 --name /wireguard/public-key \
 --query Parameter.Value \
 --output text

Setting up client

On the client side, so my DGX Spark, I will now SSH and also install Wireguard. I am using default Ubuntu installation. We are going to generate a new private key, get the public key and save the configuration. You need to run the following commands under root.

apt -y install wireguard wireguard-tools

Define some variables that are public key from SSM Parameter store and output with IPv6 from Terraform. Also configure the path where you want to keep the configuration. I will use wg1 interface.

WG_SERVER_KEY="sJQTQ7sytRuLBK74Y24TNtXrHqrmpRb+ZsT9olMfXQ4=" # Key from SSM
WG_SERVER_IP="2a05:d012:e21:2345:6789:01ab:cdef:9dd7" # IPv6 from AWS
mkdir -p /etc/wireguard/
WG_CONFIG=/etc/wireguard/wg1.conf
WG_PRIVATE_KEY=$(wg genkey)
WG_PUBLIC_KEY=$(echo $WG_PRIVATE_KEY | wg pubkey)
echo "Public key = $WG_PUBLIC_KEY"

Then generate the configuration. In case you have some firewall, select a port that you want to use for listening on incoming VPN traffic. Choose a unique address from the VPN subnet pool. Optionally set the DNS resolver to the AWS VPC one (second address of subnet's CIDR). AllowedIPs is an unfortunate name but these are the routes that should go through the VPN - I set them to VPC CIDR and VPN's internal subnet.

cat > $WG_CONFIG <<EOF
[Interface]
PrivateKey = $WG_PRIVATE_KEY
# Public Key: $WG_PUBLIC_KEY
Address = 10.155.222.3/32
DNS = 10.189.80.2    # Optional
ListenPort = 62910   # You can skip this if you don't have firewall

[Peer]
PublicKey = $WG_SERVER_KEY
AllowedIPs = 10.189.80.0/21, 10.155.222.0/24 # Connectivity to VPC and VPN
PersistentKeepalive = 25
Endpoint = [$WG_SERVER_IP]:51280

EOF

Allowing new client on the Wireguard server

As you get the new public key for your home client, we need to now enable it on the Wireguard server. As you remember we used templatefile to load the user data. This will come useful now as we will be able to configure multiple clients. Let's revisit the write_files section. Modify the end of file, after iptables commands.

write_files:
  - path: /etc/wireguard/wg0.conf
    content: |-
      [Interface]
      Address    = 10.155.222.1/24
      ListenPort = 51280
      PrivateKey = _PRIVATE_KEY_

      # Enable routing + NAT for WG clients to reach VPC
      PostUp   = sysctl -w net.ipv4.ip_forward=1
      PostUp   = iptables -A FORWARD -i wg0 -o ens5 -j ACCEPT
      PostUp   = iptables -A FORWARD -i ens5 -o wg0 -j ACCEPT

      PostDown = iptables -D FORWARD -i wg0 -o ens5 -j ACCEPT
      PostDown = iptables -D FORWARD -i ens5 -o wg0 -j ACCEPT

      %{~ for peer in peers ~}
      [Peer]
      PublicKey = ${peer.public_key}
      AllowedIPs = ${peer.address}/32
      %{~ endfor ~}

      # End of file

The above for loop will generate multiple clients on the Wireguard server. Now in the template variables you have to set peers map with public_key and address keys. Revisit the locals in EC2 instance. Applying this will reboot the instance.

locals {
  user_data = templatefile("user-data.yaml", {
    peers = [
      {
        address    = "10.155.222.3", # the IP you selected for the client
        public_key = "bxmMoVvXlVVRg7uaTnxI6Vf7wxeI0XWj5d6zREqDkzk=" # the public key of the client
      }
    ]
  })
}

Now if you bring up the there should be a status about latest handshake and some data that is received.

$ sudo wg-quick up wg1
[#] ip link add wg1 type wireguard
[#] wg setconf wg1 /dev/fd/63
[#] ip -4 address add 10.155.222.3/32 dev wg1
[#] ip link set mtu 1420 up dev wg1
[#] ip -4 route add 10.155.222.0/24 dev wg1
[#] ip -4 route add 10.189.80.0/21 dev wg1

$ sudo wg
interface: wg1
  public key: bxmMoVvXlVVRg7uaTnxI6Vf7wxeI0XWj5d6zREqDkzk=
  private key: (hidden)
  listening port: 62910

peer: sJQTQ7sytRuLBK74Y24TNtXrHqrmpRb+ZsT9olMfXQ4=
  endpoint: [2a05:d012:e21:2345:6789:01ab:cdef:9dd7]:51280
  allowed ips: 10.189.80.0/21, 10.155.222.0/24
  latest handshake: 22 seconds ago
  transfer: 92 B received, 180 B sent
  persistent keepalive: every 25 seconds

I have created a test internal application load balancer. It will listen for CIDR 10.155.222.0 (not VPC CIDR!) on port 80. But before this can be used you also have to define routes for Wireguard's subnet. This is the reason for turning off source-destination check on the network card of the EC2 instance. Without that feature, packets destined for Wireguard (whether requests or responses) will be accepted by the EC2 instance even if the destination isn't any of the instance's IPs.

resource "aws_route" "wireguard_tunnel_prefix" {
  for_each = toset(
    concat(
      module.vpc.private_route_table_ids,
      module.vpc.public_route_table_ids
    )
  )

  route_table_id         = each.value
  destination_cidr_block = "10.155.222.0/24"
  network_interface_id   = aws_instance.wireguard.primary_network_interface_id
}

Afterwards I tested with cURL and the connectivity was established! The test IPs are private range as you see below. I even tried DNS and it was also functional through the Wireguard interface - that way we can later set up some private domains or use Cloud Map.

$ curl http://internal-mytest-alb-1234567890.eu-west-3.elb.amazonaws.com
hello world

$ dig +short internal-mytest-alb-1234567890.eu-west-3.elb.amazonaws.com
10.189.83.70
10.189.85.144

$ resolvectl query internal-mytest-alb-1234567890.eu-west-3.elb.amazonaws.com
internal-mytest-alb-1234567890.eu-west-3.elb.amazonaws.com: 10.189.83.70 -- link: wg1
                                                            10.189.85.144 -- link: wg1

Installing LLM server

Now we need to install and configure Ollama. Just follow the instructions on ollama.com to install it, or you can use any other LLM server you wish. Be sure that it is listening on all addresses and not just local host. Create the following override in SystemD (on Ubuntu).

sudo cat > /etc/systemd/system/ollama.service.d/override.conf <<EOF
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_CONTEXT_LENGTH=212000"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"
Environment="OLLAMA_KEEP_ALIVE=2400"
EOF
sudo systemctl enable --now ollama
sudo systemctl restart ollama

You can alternatively run it in Docker. It should be supported on DGX Spark out of the box to use it with the GPU. Choose only one or the other because they occupy the same port in the command below!

docker run -d \
 --gpus=all \
 -v ollama:/root/.ollama \
 -p 11434:11434 \
 --name ollama \
 --restart=unless-stopped \
 ollama/ollama

For direct installations, you can just use ollama pull <model> to download the model in advance. I will use Nvidia's Nemotron 3 Super which was one of the best medium-sized models when I started writing this post. However, Gemma 4 and Qwen 3.6 were also released so you can experiment with that.

ollama pull nemotron-3-super:120b-a12b-q4_K_M

Connecting from an EC2 instance

I will create another EC2 instance which will be used for OpenClaw or any other system as you want such as Hermes or just a web app for chatting. I will prepare the instance first, will use Ubuntu 24.04 and t4g.medium instance. I will also create a new user data script that will bootstrap some of the required packages. As we have IPv6 outbound connectivity from private subnet, APT repositories should work without issues. I will also enable SSH access from Wireguard's inner subnet so that I can SSH to the instance, but you can alternatively use IPv6 when moving to public subnet or via SSM Systems Manager if you configure it, it's up to you.

data "aws_ssm_parameter" "ubuntu_2404" {
  name = "/aws/service/canonical/ubuntu/server/24.04/stable/current/arm64/hvm/ebs-gp3/ami-id"
}

resource "aws_security_group" "agent" {
  name        = "openclaw-agent-sg"
  vpc_id      = data.aws_subnet.agent.vpc_id

  ingress {
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = ["10.155.222.0/24"]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

resource "aws_instance" "agent" {
  ami           = data.aws_ssm_parameter.ubuntu_2404.value
  instance_type = "t4g.medium"
  user_data     = file("openclaw.yaml")
  tags          = { Name = "openclaw-agent" }

  subnet_id                   = module.vpc.private_subnets[0]
  vpc_security_group_ids      = [aws_security_group.agent.id]
  associate_public_ip_address = false
  ipv6_address_count          = 1

  metadata_options {
    http_endpoint = "enabled"
    http_tokens   = "required"
  }

  root_block_device {
    volume_size           = 20
    volume_type           = "gp3"
    encrypted             = true
    delete_on_termination = true
  }

  lifecycle { ignore_changes = [ami] }
}

output "private_ip" {
  value = aws_instance.agent.private_ip
}

From the system config I will do the following:

add Node.js APT repository of version 24,
install Node.js and unattended upgrades,
enable unattended upgrades,
enable AWS SSM (optional but useful).

I will also create a separate user for OpenClaw so that it can have its own home directory and permissions. It is also very important to create the default user as this will allow you to SSH to the instance to onboard OpenClaw. If you wish you can also specify SSH keys in here or via AWS key pairs.

#cloud-config
cloud_final_modules:
  - [scripts-user, always]

cloud_config_modules:
  - [write_files, always]
  - [apt_configure, always]
  - [package_update_upgrade_install, always]

hostname: openclaw-agent
create_hostname_file: true

apt:
  sources:
    nodejs:
      keyid: 2F59B5F99B1BE0B4
      keyserver: keyserver.ubuntu.com
      source: deb [signed-by=$KEY_FILE] https://deb.nodesource.com/node_24.x nodistro main

package_update: true
package_upgrade: true
packages:
  - nodejs
  - unattended-upgrades

users:
  - default
  - name: openclaw
    uid: 2200

ssh_authorized_keys:
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPgVNNOeuUqMgobgeIIkndXXYekOmC/e5bqty3f0UXDa my-ssh-key

write_files:
  - path: /etc/apt/apt.conf.d/20auto-upgrades
    permissions: "0644"
    owner: root:root
    content: |
      APT::Periodic::Update-Package-Lists "1";
      APT::Periodic::Unattended-Upgrade "1";

runcmd:
  - systemctl enable --now unattended-upgrades || true
  - loginctl enable-linger openclaw || true # Enable SystemD on openclaw's user

Installing OpenClaw - with a caveat 😳

I SSH'd into the instance and Nodejs should already be there based on the provided user data. So I switched user to the new openclaw one I defined and started installation with NPM.

ssh ubuntu@$(tofu output -raw private_ip) # replace with your private IP

The authenticity of host '10.189.83.247 (10.189.83.247)' can't be established.
ED25519 key fingerprint is: SHA256:iMfJBU8iSEc5ikspbNKGD8jCAlLGwrOs28lbI4aPw2Q
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

# Inside the machine
sudo su openclaw -l -s /bin/bash
npm install openclaw@latest

...
4564 error A git connection error occurred
4565 error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
4566 error ssh: connect to host github.com port 22: Connection timed out
4566 error fatal: Could not read from remote repository.

This timeout happens because we don't have public IPv4 connectivity! There are two standard solutions - public IP for the instance or NAT Gateway or...

Hosting tinyproxy on DGX Spark

As we already have connection to other VPN places we can simply use one of the machines on the network as the exit to IPv4 internet. As a bonus we retain our residential IP! So let's spin it up in a Docker but for that we need to make some configuration first in Dockerfile and tinyproxy.conf.

FROM alpine:latest

RUN apk add tinyproxy
COPY tinyproxy.conf /etc/tinyproxy/tinyproxy.conf
EXPOSE 8888
ENTRYPOINT ["/usr/bin/tinyproxy"]
CMD ["-d"]

Port 8888
Timeout 600
MaxClients 100
ViaProxyName "tinyproxy"

User nobody
Group nobody

DefaultErrorFile "/usr/share/tinyproxy/default.html"
StatFile "/usr/share/tinyproxy/stats.html"
LogLevel Info

Allow 127.0.0.1
Allow ::1
Allow 10.155.222.0/24
Allow 10.189.80.0/21

From that config we can easily build the new image for Tinyproxy and set it up so that it starts on boot. Of course then all this connectivity will rely on our local machine being up, so it's only usable for some of IPv4 requirements such as GitHub.

docker build -t local-tinyproxy:latest .
docker run -d \
 --name tinyproxy \
 --restart=unless-stopped \
 -p 8989:8888 \
 local-tinyproxy:latest

Now we can easily direct the proxy to the new service within Wireguard's network. However, in order to do this, we need to open the port 8989 (and 11434 for Ollama) on Wireguard's instance. You might ask why is that? So any packet sent from OpenClaw's instance in that direction will look like this:

source address: 10.189.83.247 (example),
destination address: 10.155.222.3,
source port: 59123 (example),
destination port: 8989.

Filtering on AWS security group level cares about source address and destination port rather than anything else. Destination address is taken care by "source-destination" check of the network interface - the feature we just disabled. Let's update our security group.

resource "aws_security_group" "wireguard" {
  name_prefix = "wireguard-sg"
  vpc_id      = module.vpc.vpc_id

  ingress {
    from_port        = 51280
    to_port          = 51280
    protocol         = "udp"
    ipv6_cidr_blocks = ["::/0"]
  }

  ingress {
    from_port        = 11434
    to_port          = 11434
    protocol         = "tcp"
    security_groups  = [aws_security_group.agent]
  }

  ingress {
    from_port        = 8989
    to_port          = 8989
    protocol         = "tcp"
    security_groups  = [aws_security_group.agent]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

Now you can configure NPM and Git to use the proxy and OpenClaw should be able to install with no issues. You can also test the connectivity with cURL even, if it responds with 500, this is fine; if 403, this might be a problem with tinyproxy.conf. If this cURL command shows timeout or "couldn't connect to server", this can be security groups, routes or other firewall.

curl http://10.155.222.3:8989 -X CONNECT | grep title
# Test results
# <title>500 Unable to connect</title>
npm set https-proxy=http://10.155.222.3:8989
npm set proxy=http://10.155.222.3:8989
git config --global http.proxy http://10.155.222.3:8989
git config --global https.proxy http://10.155.222.3:8989
npm install openclaw@latest

OpenClaw - Onboard!

And we are almost done! The only thing we now need is to follow the onboarding process. Use Ollama provider in local mode, set the correct DGX's IP over Wireguard and choose the model from the list!

export XDG_RUNTIME_DIR=/run/user/$(id -u) # for systemd support
npx openclaw onboard

I will demonstrate usage via TUI rather than any instant messenger here. The first load time for the latest build of OpenClaw took around 1:30 minutes with Nemotron 3 Super (q4). After resetting the session, first message took around 20 seconds (to load 12k context), so most of the time was loading the model into VRAM. Keeping model in memory is controllable on Ollama's side. For each subsequent message, there's some more time needed.

npx openclaw tui

To have some performance comparison, I decided to also try running the agent on latest Qwen 3.6 35B (qwen3.6:35b-a3b-q8_0). The startup took around 30 seconds and each message takes maybe 10.

Power usages

I decided to also order a meter that provided how much power the DGX machine draws in different situations. When it's completely idle, it takes around 30W, with the model loaded to memory but unused it's around 40W and during response generation it oscillates around 170W. Let's do some assumptions - when you sleep you don't use OpenClaw at all but you keep DGX Spark on, so it takes 30W for 7 hours. You are a very heavy user, writing to OpenClaw all day, scheduling a lot of tasks basically treating it as a thinking extension which totals to 8 hours of pure generative work. For all the other time it just sits idle but loaded to memory.

7 h * 30 W = 210 Wh
8 h * 170 W = 1360 Wh
9 h * 40 W = 360 Wh
in total it is about 2 kWh
assuming price in Germany is 0.5€ for a kilowatt-hour, it is 1€ per day, 30€ per month, just for pure token generation.

Obviously you also have to consider costs for AWS EC2 Instance. For the VPN server, if you commit for a year to EC2 saving plans, you will pay around 25€, for the agent instance, if it's online all year round this is 200€ (but note that OpenClaw is especially heavy compared to other harnesses).

If you use small model like Qwen 35B in Q8, you will still have space in VRAM for some image generator like Z-Image-Turbo, a small TTS model or Whisper Turbo for speech recognition. I managed to easily fit image generation and VibeVoice ASR along with the chatbot model in 100 gigs of RAM.

Cons of this setup

Of course each of such setups comes with a tradeoff. You keep your privacy, you maybe pay less for inference (that's debatable) but that's about it. The best setup is to have GB10 as the primary model provider and fall back on something small on OpenRouter. There's always a possibility to mix multiple models and providers using subagents. For example you want to perform a coding task, you use Sonnet 4.6 but you keep local Qwen 3.6 for orchestration. Such setup is far from highly available. Not only can the machine break, you can have blackout or Internet can be down in your flat. Another tradeoff is speed - most of the medium sized models from OpenAI or Anthropic will nevertheless run faster than any decent model on DGX Spark.

The prefill (loading context) speed is 500 tokens per second for Nemotron 3 Super and token generation is 20 tokens per second. Assuming that in each 15 minute window we have to load 200k context, we can generate 10k tokens, that makes it (within 8 hour daily generation) 6.4 M tokens input and 0.32 M tokens output. Prompt prefill accounts for around 40% of the time spent so from a daily spend, 40 cents will go to input tokens and 60 cents to output tokens. Normalized this is around 0.06€ per million input tokens and 1.88€ per million output tokens.

For Qwen 3.6 the speeds look different: 1150 tokens/s prefill and 39 tokens/s generation. Then in 15 minute window (200k input context) the prefill will account for 20% of the generation time. 80% of the time left will be for token generation and this will produce 28k tokens. So within a day we get 6.4 M input and 0.896 M output tokens, normalized this makes it 0.03€/Mtok input and 0.89€/Mtok output.

Is any of these competitive? It highly depends on your use case and usage patterns; whatever I did above is just napkin maths. Gemma 4 31B over OpenRouter is just $0.13/$0.38 in/out but GPT-5.4 Nano is $0.20/$1.25.

🌍 Plantera — Plant Trees on a Living Earth

Anupam Thakur — Mon, 20 Apr 2026 07:13:39 +0000

This is a submission for Weekend Challenge: Earth Day Edition

🌱 What I Built

Plantera is an interactive Earth where users can plant virtual trees on real-world locations and contribute to a global, community-driven green map.

Users can:

🌍 Plant trees anywhere on Earth
📍 Choose real-world locations using latitude & longitude
🖼️ Upload images of their plants
💬 Add quotes or messages
🌳 Watch the Earth become greener as more people plant

The idea is simple:
Turn environmental awareness into an interactive experience.

Instead of just talking about planting trees, Plantera lets users visually contribute to a greener planet.

🚀 Demo

🌐 Live Demo: https://plantera-phi.vercel.app
🎥 Video Demo: workin on it

💻 Code

GitHub Repository: https://github.com/anupamthakur-dev/plantera

🧠 How I Built It

🌍 Interactive Globe

Plantera uses a 3D interactive globe where users can plant trees across the Earth.

Each planted tree stores:

Location (lat/lng)
Plant type
User information
Images
Quote/message

To maintain performance, I used:

Plant type grouping instead of unique models per plant
Lazy rendering of markers
Optimized rendering logic for large datasets

This allows Plantera to scale to thousands of trees smoothly.

🌱 Planting System

Users can plant trees through a bottom floating action bar:

"Plant a Sapling 🌱" CTA
Bottom-sheet modal
Smooth slide animations
Blur background overlay

The modal system is built as a state machine architecture allowing future expansion without breaking UI.

🖼️ Image Upload System

Users can upload multiple images when planting.

Features:

Multiple image uploads
Secure storage using Supabase Storage
Image cleanup if upload fails
Optimized upload flow

🗂️ Backend & Database

I used Supabase for:

Authentication
Database
Storage
Row Level Security

Database structure:

users
plants_planted
plant_images

This allows scalable, secure plant posts.

⚡ Performance Decisions

To keep Plantera fast:

Lazy loaded modals
Plant type grouping
Optimized globe rendering
Minimal 3D model usage
Efficient database queries

These decisions help Plantera scale to global-level usage.

🎯 Why Plantera

Earth Day is about taking action, not just awareness.

Plantera turns planting into:

Interactive
Visual
Community-driven

Every planted tree becomes a digital footprint of environmental action.

🏆 Prize Categories

🥇 Best Use of GitHub Copilot

I used GitHub Copilot extensively to:

Design scalable architecture
Build modal state machine
Structure services layer
Optimize performance logic
Generate clean TypeScript interfaces

Copilot helped accelerate development and maintain clean, scalable code.

🌍 Future Plans

Real tree partnerships
Gamification
Community challenges
Tree growth animations
Environmental impact stats

🌱 Final Thoughts

Plantera is more than an app.
It's a living, growing Earth powered by community.

Plant a tree.
Watch the world grow greener.

Thanks for reading 🌍

Docker Kubernetes: What They Really Changed (It's Not What You Think)

Harrison Guo — Mon, 20 Apr 2026 07:13:19 +0000

"A Docker container is basically a lightweight VM, right?" No. That sentence alone causes more architectural misunderstandings than any other in modern backend engineering. A VM virtualizes hardware. A container is a set of Linux kernel features — namespaces, cgroups, overlay filesystems — wrapped in a nicer CLI. Same host kernel, same memory space, same attack surface if the kernel has a bug. The marketing that says otherwise has cost teams real money in misconfigured production.

Kubernetes gets the same treatment. "It's a tool for running containers." Also not really. Kubernetes is a distributed scheduler, service mesh, declarative control plane, and reconciliation engine. Containers are one of the things it happens to run. Treating Kubernetes as "container orchestration" produces systems that break in predictable, frustrating ways — because the team never learned that the reconciliation loop, not the container, is the thing that actually matters.

This is a working engineer's re-read of what Docker and Kubernetes actually changed. Not the marketing story. The underneath-the-hood story that tells you when to reach for them and when they're overkill.

tl;dr — Docker didn't invent Linux namespaces, cgroups, or filesystem layering; it packaged them into a developer-friendly workflow. That workflow is what changed. Kubernetes didn't invent distributed scheduling, service discovery, or rolling deployments; it standardized the declarative, reconciliation-loop pattern for all of them. That pattern is what changed. Understanding these primitives (namespaces + cgroups + reconciliation loops) tells you when to reach for the tools and when the tools are overkill.

What Docker Actually Is

Docker is a set of Linux kernel features wrapped in a nice CLI and an image format. The features existed before Docker; they just weren't accessible.

Linux namespaces — process, mount, network, IPC, UTS, user, cgroup. Each namespace gives a process its own view of that resource. When your container thinks it has PID 1, it really thinks so; inside its PID namespace, the host's init is invisible.
cgroups (v1/v2) — resource accounting and limits. How much CPU, memory, I/O bandwidth a group of processes can use. This is why a misconfigured container can eat a host's memory and take everything else down.
Union / overlay filesystems — the thing that lets you stack "base image" + "layer 1" + "layer 2" without copying. OverlayFS on modern kernels.
Image format (OCI) — a standard way to package a root filesystem plus metadata into something reproducible.

Docker's innovation was not inventing any of this. It was making them accessible. docker run -p 8080:80 nginx hides a beautiful horror of namespace creation, iptables rules, virtual ethernet pairs, overlay mounts, and cgroup assignment. Before Docker, you'd have spent a week reading unshare(2) and ip netns add to reproduce this. After Docker, you did it in a workshop afternoon.

What actually changed: deployments became reproducible. The image you built on your laptop contained everything needed to run — OS libraries, Python version, environment. "Works on my machine" stopped being a coping mechanism and started being a legitimate development artifact. That's the Docker revolution. Not containers. Reproducible, portable environments.

The thing that is not true, despite the marketing: Docker containers are not VMs. They share the host kernel. A kernel exploit in one container can reach the host and other containers. Containers are a soft isolation — good enough for most production multi-tenant workloads, not good enough for hostile tenants.

What Kubernetes Actually Is

Kubernetes is a declarative control plane built on the reconciliation loop pattern. This is the single most important idea to internalize.

You write a manifest describing the desired state: "three replicas of this deployment, exposed through this service, attached to this config."
You hand the manifest to the control plane: "make it so."
Kubernetes runs an unending loop: observe the current state, compare to desired, take actions to close the gap.

Everything Kubernetes does follows this pattern:

Deployment controllers watch the pod count, scale up if low, scale down if high.
ReplicaSet controllers ensure N identical pods exist.
Service controllers maintain the iptables / IPVS / eBPF rules that route virtual IPs.
Ingress controllers watch Ingress resources and configure the edge proxy.
The scheduler watches for unscheduled pods and binds them to nodes.
Node controller watches node health and evicts pods from unhealthy nodes.

Your application is just the data in the reconciliation loop. The loops run forever, closing gaps. That's Kubernetes.

Every Kubernetes feature — Deployments, Services, Ingresses, HPAs, CronJobs, StatefulSets — is some controller running this exact pattern. Once you see it, the platform stops being magic.

What actually changed because of this: the operational model became shared across companies. Before Kubernetes, every engineering team had a bespoke orchestration system: a collection of Chef/Puppet/Ansible recipes, some custom scripts, a deploy button, and a few senior engineers who knew which knobs to turn during incidents. Different at every company. Opaque to new hires. Sensitive to key-person risk.

Kubernetes is many things, but the single biggest thing it did was replace a hundred bespoke orchestration glues with one standard. It's not the best tool for every problem — Nomad is simpler, ECS is more managed, Cloud Run hides the thing entirely — but it's the standard, and "it's the standard" has real value: hires know it, vendors build for it, books exist, the job market is liquid.

The Mental Model Most People Miss

Once you see "reconciliation loop," you stop asking questions Kubernetes doesn't answer.

"How do I deploy?" You don't. You update a manifest. A controller observes the change and reconciles.

"How do I roll back?" You don't. You update the manifest back. A controller observes the change and reconciles in the other direction.

"Why did my pod get killed?" Because a controller decided the current state (this pod is here, on this node) didn't match the desired state (node is draining, or pod is over its memory limit, or a replica count decreased). It closed the gap.

"Why can't I SSH in and hand-edit things?" Because the next reconcile loop will undo your edit. The manifest is the source of truth. If you want to change behavior, change the manifest.

This is a shift from imperative ops ("run these commands to deploy") to declarative ops ("the system should look like this; make it so"). Git becomes the history of what your infrastructure should be. Time travel works. Change review works. Disaster recovery becomes "re-apply the manifests to a new cluster." When it clicks, you stop fighting the platform.

Until it clicks, the platform feels maddening. "I just want to run a container" — yes, but the platform doesn't care what you want to do once. It cares about the continuous state. Every action through kubectl apply is a statement of desired state, not an imperative command.

What Changed in Practice

Concretely, what looks different on a team that's moved from "SSH into the box and systemctl restart" to a reconciled-state model:

Deployment became a git push

Before: log into the bastion, pull the latest build, restart the service, watch the log.
After: merge to main, CI pushes image to registry, ArgoCD/Flux observes the manifest change, the Deployment controller updates the ReplicaSet, pods roll gradually.

Benefits: change review, audit trail, rollback by git revert, consistent deploys across teams.
Costs: debugging a broken deploy requires understanding the CD pipeline, the manifest, and the controller that's reconciling. The failure mode surface is wider.

Scaling became a number in a file

Before: write a script that watches metrics, calls the cloud API, hopes for the best.
After: replicas: 10 in a manifest, or an HPA (Horizontal Pod Autoscaler) that watches metrics and adjusts the Deployment.

Benefits: declarative, versioned, reproducible.
Costs: HPA behavior is subtle — wrong thresholds cause thrashing, wrong metrics cause over/underscaling. Many teams never invest in tuning.

Service discovery became DNS

Before: register in Consul, read from Consul, have a catalog. Or hardcode IPs. Or service registry.
After: my-service.my-namespace.svc.cluster.local resolves to a stable virtual IP. Kube-proxy or CNI load-balances to healthy pods.

Benefits: services don't need to know how other services run. Standard DNS.
Costs: the DNS / networking layer is one of the hardest parts of Kubernetes to debug. When service discovery breaks, you're reading iptables or eBPF maps, not a Consul dashboard.

Configuration became a manifest

Before: environment variables, .env files, maybe Consul KV.
After: ConfigMaps and Secrets, mounted as env vars or volumes.

Benefits: versioned, reviewed, separate from code.
Costs: changing a ConfigMap doesn't automatically restart pods. You have to annotate the Deployment or use something like reloader. New users get bitten by this constantly.

When Kubernetes Is Overkill

I'll say it directly: most teams adopting Kubernetes for the first time don't need it.

Rules of thumb:

Two or three services, one team: you don't need Kubernetes. ECS, Nomad, Cloud Run, or even systemd + Ansible will do. The operational overhead of Kubernetes exceeds its benefit at this scale.
Ten to twenty services, small team: Kubernetes starts breaking even if you pick a managed service (EKS, GKE, AKS). Don't run your own control plane.
Fifty+ services, multiple teams, serious release engineering needs: Kubernetes is probably the right call. The cost of complexity is amortized over the benefits of a shared declarative platform.

The dangerous zone is 5-15 services on a small team. At that scale, Kubernetes often wins the resume-driven-development vote and loses the actual-outcomes vote. Pick a simpler tool.

When Kubernetes Is the Right Answer

The jobs where Kubernetes genuinely shines:

Multi-service, multi-team engineering orgs where consistency matters more than per-service optimality.
Scale-out workloads with heterogeneous shapes — web apps, job runners, ML batch jobs, stateful databases, all on one platform.
Teams that want declarative infrastructure — GitOps via ArgoCD/Flux, infra PRs reviewed like code.
Workloads with nontrivial scheduling — affinity rules, taints, GPU allocation, spot instances.
Operators ecosystem — Kubernetes operators (Prometheus operator, cert-manager, etc.) let you extend the same reconciliation model to application-specific concerns.

Notice the pattern: Kubernetes wins when you want the platform's primitives — declarative state, reconciliation, operators — beyond just container scheduling. If you only want "run my container," you're buying a jumbo jet to fly to the next town.

What I'd Tell a Team Starting Fresh

Two concrete takeaways I'd hand to engineers thinking about Docker and Kubernetes.

For Docker: the image isn't the point. Reproducibility is. An image built on your laptop that runs unchanged in CI and production — that's the contract you got. Break it (say, by mutating state inside the running container) and you lose the value. The container is a delivery mechanism for a reproducible environment.

For Kubernetes: the manifest is the source of truth. Every piece of your infrastructure — deployments, services, secrets, ingresses, policies — lives in git. Every change is a git change. Every rollback is a git revert. If you find yourself running kubectl edit on production, something is wrong with your workflow, not with Kubernetes.

Both tools won because they codified patterns that were already emerging in sophisticated shops. They didn't invent the patterns. They made them accessible, portable, and standard. That's the fifteen-year revolution. Not containers. Not YAML. The standardization of patterns that used to require a senior infrastructure team to implement from scratch at every company.

When you work with the grain of the pattern — reproducible environments for Docker, reconciled declarative state for Kubernetes — both tools get out of the way. When you fight the grain, they fight back.

Why Go Handles Millions of Connections — Linux primitives that Docker is built on, seen from the language side.
Observability and Cost Attribution: Why One Pipeline Isn't Enough — what happens to operational complexity when you have dozens of services.
Scale-Up vs Scale-Out: Why Every Language Wins Somewhere — the architectural decision that drives whether you need Kubernetes at all.

5 Architecture Decisions That Kill AI Projects Before They Launch

Aashir As — Mon, 20 Apr 2026 07:13:19 +0000

$684 billion was invested in AI initiatives in 2025. More than $547 billion of that failed to deliver value (RAND Corporation). That's not a model problem. That's mostly an architecture problem.

I've been on the failing side of this. Here are the five architectural decisions that caused the most damage, across 50+ AI projects we've built at Afnexis.

1. Building the Model Before Validating the Data

I learned this the hard way on a fraud detection project. The client had 18 months of transaction data. We built a beautiful gradient boosting classifier. Precision: 91%. We were proud of it.

Then we discovered their fraud labels were generated by their old rules engine, not by human review. The rules engine had a known flaw that mislabeled certain transaction types. We'd trained a model to replicate a broken system at 91% accuracy.

The fix cost four weeks. The root cause took four minutes to identify.

The decision that killed it: Starting model development before auditing label quality. We now treat data auditing as a non-negotiable gate before writing model code. Every project. No exceptions.

What to check before you write a line of code:

Are labels generated by humans, rules, or another model?
What's the label error rate? (Use Cleanlab or manual spot-checking)
What's the class balance? How were rare events captured?
Is there data leakage between train and test splits?

2. Treating Inference as an Afterthought

Most ML tutorials end at model accuracy. Production starts at inference.

A client needed real-time credit decisions. We trained a beautiful model with strong AUC scores. Then we tested serving latency. P95 response time: 2.3 seconds. Their requirement: under 200ms.

The model used 340 features, 20 of which required live API calls at inference time. We'd designed for accuracy, not for serving. Rebuilding the inference architecture added five weeks.

What we do now: Define the serving constraints before training. Before a single model runs:

What's the maximum acceptable latency? (P95, not average)
What features are available at inference time, with no latency penalty?
Is the serving environment CPU, GPU, or edge?
What's the expected RPS (requests per second)?

These constraints shape model architecture, feature selection, and serving infrastructure. Define them first.

3. One Monolithic Model for Everything

I once built a single model for a healthcare client that was supposed to classify 14 different document types. It worked okay on 9 of them and poorly on 5. When we pushed updates to improve the poor performers, we sometimes degraded the good ones.

The model was trying to do too much. Different document types have different data distributions, different error costs, and different update frequencies. Treating them as one problem made the engineering worse, not simpler.

What we do now: Ensemble-first architecture. Start by asking: can this problem be decomposed into smaller problems with clearer boundaries? For My Medical Records AI, we ended up with separate specialist models for lab reports, discharge summaries, prescriptions, and referral letters. Each could be updated independently. Each had its own monitoring. Accuracy improved on every category.

Monolithic models feel simpler at first. They're not.

4. No Feedback Loop from Production

Models degrade. That's not a hypothesis. MIT research found 91% of ML models see accuracy decline over time without active monitoring. The question isn't whether your model will drift. It's whether you'll know before your users do.

We shipped a churn prediction model for a SaaS client. Six months later, the business had launched two new product lines. User behavior patterns had shifted significantly. The model's precision dropped from 78% to 61%. Nobody noticed for eight weeks. The sales team was acting on stale predictions the whole time.

What we do now: Every model ships with a feedback loop. Specifically:

Outcome tracking: Did the predicted thing actually happen? Link predictions to outcomes.
Distribution monitoring: Are the features at inference time still distributed like the training data?
Confidence tracking: Is average confidence dropping? That's usually the first signal of drift.
Ground truth sampling: Regularly label a random sample of recent predictions. Compare to model output.

If you can't close the loop between model output and real-world outcomes, you're flying blind.

5. Hard-Coding the LLM Provider

This feels like a minor architectural decision until you get a surprise pricing change or a model deprecation notice.

We built a document analysis system for a fintech client using GPT-4 directly. Six months later, GPT-4 was deprecated in favor of GPT-4o with a different API signature. Migration cost: two weeks and a small bug in production that nobody caught immediately.

What we do now: Abstract the LLM provider behind an interface from day one. The calling code doesn't know if it's talking to OpenAI, Anthropic, or a self-hosted Llama model. Provider configuration lives in environment variables, not in code. Switching providers is a config change, not a refactor.

This also lets you run cost experiments: route 10% of traffic to a cheaper model and measure if quality degrades. You can't do that if your provider is hard-coded.

The Pattern

Every one of these failures came from building for the demo, not for production. Models are trained on clean test data. Production has messy data, time pressure, and users who break assumptions.

The best architectural advice I have: write down your production constraints before your first model run. Latency, labels, feedback loops, serving environment, provider flexibility. One page. It'll save you weeks.

More on what kills AI projects in production: Why AI Projects Fail — and What To Do Instead

Aashir Tariq is the CEO of Afnexis. We've shipped 50+ production AI systems across healthcare, fintech, and real estate. If your AI project is stuck between POC and production, that's what we fix.