DEV Community: Isaac FEI

User Authentication with FastAPI and Next.js

Isaac FEI — Fri, 20 Mar 2026 11:32:46 +0000

This post covers a complete user authentication implementation using FastAPI for the backend and Next.js for the frontend. The system uses JWT tokens, bcrypt password hashing, and HTTP-only cookie management for secure session handling.

I'll walk through the key components and explain the technical decisions behind each part.

Architecture Overview

The authentication system follows Domain-Driven Design (DDD) principles with clear separation between domain logic, application services, and infrastructure concerns:

Backend: FastAPI with PostgreSQL
Frontend: Next.js with React Query and Zustand
Security: JWT tokens with access/refresh token rotation
Session Management: Secure HTTP-only cookies

Backend Implementation

Domain Layer: User Entity and Value Objects

The User entity serves as the core domain object, encapsulating user data and behavior:

# backend/src/aichat/domains/user/domain/entities/user.py
class User(Entity):
    def __init__(
        self,
        *,
        id: UUID,
        created_at: dt.datetime,
        updated_at: dt.datetime,
        name: str,
        email: str,
        password: Password,
        avatar_url: Optional[str] = None,
    ) -> None:
        super().__init__(
            id=id,
            created_at=created_at,
            updated_at=updated_at,
        )
        self.name = name
        self.email = email
        self.password = password
        self.avatar_url = avatar_url

    @classmethod
    def create(
        cls,
        *,
        name: str,
        email: str,
        password: Password,
        avatar_url: Optional[str] = None,
    ) -> Self:
        user = cls(
            id=cls.generate_id(),
            created_at=cls.get_current_datetime(),
            updated_at=cls.get_current_datetime(),
            name=name,
            email=email,
            password=password,
            avatar_url=avatar_url,
        )
        return user

    @property
    def info(self) -> UserInfo:
        return UserInfo(
            user_id=self.id,
            name=self.name,
            email=self.email,
            avatar_url=self.avatar_url,
        )

The create class method handles ID generation and timestamp setting automatically. The info property returns user data without sensitive information like passwords, providing a safe way to share user details across the application.

Secure Password Handling

Password security uses a dedicated Password value object with bcrypt for hashing:

# backend/src/aichat/domains/user/domain/value_objects/password.py
class Password(ValueObject):
    hashed_value: str

    @classmethod
    def from_plaintext(cls, value: str) -> Self:
        return cls(hashed_value=cls._hash(value))

    def check(self, value: str) -> bool:
        return bcrypt.checkpw(
            value.encode(),
            self.hashed_value.encode(),
        )

    @staticmethod
    def _hash(value: str) -> str:
        return bcrypt.hashpw(
            value.encode(),
            bcrypt.gensalt(),
        ).decode()

The from_plaintext method automatically hashes passwords with a unique salt via bcrypt.gensalt(). The check method performs secure password verification without exposing the original password. Bcrypt's computational expense makes brute force attacks impractical.

Authentication Endpoints

The authentication API implements three main endpoints for the complete auth flow:

# backend/src/aichat/presentation/rest/routers/auth.py
@router.post("/signup", response_model=SignupResponse)
@inject
def signup(
    request: SignupRequest,
    signup_command_handler: SignupCommandHandler = Depends(
        Provide[AppDepContainer.signup_command_handler],
    ),
):
    try:
        signup_command = SignupCommand(
            name=request.name,
            email=request.email,
            password=request.password,
        )
        signup_command_handler.handle(signup_command)
        return SignupResponse(
            status_code=status.HTTP_201_CREATED,
            message="User registered successfully",
        )
    except Exception as e:
        return SignupResponse(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            message="Internal server error",
            error=str(e),
        )

@router.post("/login", response_model=LoginResponse)
@inject
def login(
    response: Response,
    request: LoginRequest,
    login_command_handler: LoginCommandHandler = Depends(
        Provide[AppDepContainer.login_command_handler],
    ),
):
    try:
        login_command = LoginCommand(
            email=request.email,
            password=request.password,
        )
        access_token, refresh_token = login_command_handler.handle(login_command)

        # Set secure HTTP-only cookies
        response.set_cookie(
            key=ACCESS_TOKEN_COOKIE_KEY,
            value=access_token,
            httponly=True,
            secure=True,
        )
        response.set_cookie(
            key=REFRESH_TOKEN_COOKIE_KEY,
            value=refresh_token,
            httponly=True,
            secure=True,
        )

        return LoginResponse(
            status_code=status.HTTP_200_OK,
            message="User logged in successfully",
        )
    except Exception as e:
        return LoginResponse(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            message="Internal server error",
            error=str(e),
        )

The response.set_cookie() calls instruct FastAPI to add Set-Cookie headers to the HTTP response. The browser receives these headers and stores the cookies with the specified security attributes.

Cookie settings breakdown:

httponly=True - Prevents JavaScript access, protecting against XSS attacks
secure=True - Ensures cookies only transmit over HTTPS connections
The browser automatically includes these cookies in subsequent requests

After successful login, the browser's developer tools will show two cookies with token values, marked as HttpOnly and Secure:

The complete authentication flow works as follows:

JWT Token Management

The login command handler generates both access and refresh tokens:

# backend/src/aichat/domains/user/application/commands/login_command_handler.py
class LoginCommandHandler:
    def handle(self, command: LoginCommand) -> tuple[str, str]:
        with self._unit_of_work as unit_of_work:
            # Find and validate user
            user_repository: IUserRepository = unit_of_work.get_repository(IUserRepository)
            user = user_repository.find_user_by_email(command.email)

            if user is None:
                raise ValueError(f"User with email {command.email} does not exist")

            if not user.password.check(command.password):
                raise ValueError("Invalid password")

            # Generate tokens
            access_token = self._token_service.create_access_token(
                user_info=user.info,
            )
            refresh_token_value = self._token_service.create_refresh_token(
                user_id=user.id,
            )

            # Store refresh token
            refresh_token = RefreshToken.create(
                user_id=user.id,
                value=refresh_token_value,
            )
            refresh_token_repository: IRefreshTokenRepository = (
                unit_of_work.get_repository(IRefreshTokenRepository)
            )
            refresh_token_repository.save_refresh_token(refresh_token)

        return access_token, refresh_token_value

This design uses two token types: access tokens contain user information with short lifespans (15-30 minutes), while refresh tokens are random strings stored server-side with longer lifespans (7 days).

The dual-token approach balances security and usability. Stolen access tokens expire quickly, while refresh tokens enable seamless token renewal without frequent logins. Server-side refresh token storage allows for immediate revocation when needed.

Authentication Middleware

The authentication dependency extracts and validates tokens from protected route requests:

# backend/src/aichat/presentation/rest/dependencies.py
@inject
def get_current_user_info(
    request: Request,
    token_service: ITokenService = Depends(Provide[AppDepContainer.token_service]),
) -> UserInfoDTO:
    # Check Authorization header first
    access_token = request.headers.get("Authorization")
    if access_token is not None:
        access_token = access_token.removeprefix("Bearer ")
    # Fall back to cookies
    else:
        access_token = request.cookies.get(ACCESS_TOKEN_COOKIE_KEY)
        if access_token is None:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Unauthorized",
            )

    try:
        # Verify token and extract user info
        user_info = token_service.verify_access_token(access_token)
        return UserInfoDTO(
            user_id=user_info.user_id,
            name=user_info.name,
            email=user_info.email,
            avatar_url=user_info.avatar_url,
        )
    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail=f"Unauthorized: {e}",
        )

This implementation supports dual authentication methods: Bearer tokens in Authorization headers (for API clients) and cookie-based authentication (for browsers). The fallback mechanism enables seamless compatibility across different client types.

Frontend Implementation

State Management with Zustand

The frontend uses Zustand for lightweight state management with minimal boilerplate:

// frontend/src/stores/user-info-store.ts
interface State {
  userInfo: UserInfo | null;
  isSignedIn: boolean;
}

interface Action {
  setUserInfo: (userInfo: UserInfo) => void;
  setIsSignedIn: (isSignedIn: boolean) => void;
  clearUserInfo: () => void;
}

const _useUserInfoStore = create<State & Action>()(
  persist(
    (set) => ({
      userInfo: null,
      isSignedIn: false,
      setUserInfo: (userInfo) => set({ userInfo }),
      setIsSignedIn: (isSignedIn) => set({ isSignedIn }),
      clearUserInfo: () => set({ userInfo: null, isSignedIn: false }),
    }),
    {
      name: "user-info-storage",
      // Only persist the isSignedIn state for security
      partialize: (state) => ({ isSignedIn: state.isSignedIn }),
    },
  ),
);

The partialize configuration only persists the isSignedIn boolean to localStorage, excluding sensitive user data. When the app loads with isSignedIn: true, it fetches fresh user data from the server. This approach maintains persistent login state while avoiding security risks from storing sensitive data in localStorage.

API Integration with React Query

Custom hooks handle API integration with automatic data transformation and validation:

// frontend/src/hooks/api/use-login.ts
export const useLogin = () => {
  return useMutation({
    mutationFn: async (loginData: LoginRequest): Promise<LoginResponse> => {
      // Convert camelCase to snake_case for backend
      const backendPayload = convertCamelToSnake(loginData);

      const { data: backendResponse } = await apiClient.post(
        "/api/auth/login",
        backendPayload,
      );

      // Convert and validate response
      const response: LoginResponse = LoginResponseSchema.parse(
        convertSnakeToCamel(backendResponse),
      );

      return response;
    },
  });
};

export const useGetCurrentUserInfo = (options?: UseGetCurrentUserInfoOptions) => {
  return useQuery({
    queryKey: ["current-user-info"],
    queryFn: async () => {
      const { data: backendResponse } = await apiClient.get(
        "/api/auth/current-user",
      );

      const response: GetCurrentUserInfoResponse =
        GetCurrentUserInfoResponseSchema.parse(
          convertSnakeToCamel(backendResponse),
        );

      return response.data;
    },
    enabled: options?.enabled ?? true,
  });
};

The hooks automatically convert between camelCase (frontend) and snake_case (backend) conventions. Zod schemas validate API responses, catching unexpected data structures before they cause runtime errors.

Login Component

The login component demonstrates the integration between UI and authentication logic:

// frontend/src/app/(auth)/login/page.tsx
export default function LoginPage() {
  const router = useRouter();
  const setIsSignedIn = useUserInfoStore.use.setIsSignedIn();
  const loginMutation = useLogin();

  const handleLogin = async (data: LoginData) => {
    try {
      const response = await loginMutation.mutateAsync(data);

      if (response.statusCode === 200) {
        setIsSignedIn(true);
        toast.success("Welcome back! You're now logged in.");
        router.push("/");
      } else {
        const errorMessage = response.error || response.message || "Login failed. Please try again.";
        toast.error(errorMessage);
      }
    } catch (error) {
      console.error("Login error:", error);
      toast.error("Something went wrong. Please check your connection and try again.");
    }
  };

  return (
    <div className="flex min-h-screen items-center justify-center px-4 py-12">
      <div className="w-full max-w-md space-y-8">
        <div className="text-center">
          <h1 className="text-3xl font-bold text-gray-900 dark:text-white">
            Welcome back
          </h1>
          <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
            Sign in to your account to continue
          </p>
        </div>
        <LoginForm onSubmit={handleLogin} isLoading={loginMutation.isPending} />
      </div>
    </div>
  );
}

The handleLogin function manages the complete login flow: API calls, state updates on success, error handling, and user feedback. The loginMutation.isPending state automatically handles form loading states during submission.

Security Features

HTTP-Only Cookies

HTTP-only cookies provide XSS protection by preventing JavaScript access:

# backend/src/aichat/presentation/rest/routers/auth.py
response.set_cookie(
    key=ACCESS_TOKEN_COOKIE_KEY,
    value=access_token,
    httponly=True,    # Prevents JavaScript access
    secure=True,      # HTTPS only
)

The httponly=True flag prevents malicious JavaScript from accessing authentication cookies, even during XSS attacks. The secure=True flag ensures cookies only transmit over HTTPS connections. Browser dev tools display these cookies with security flags indicating proper protection.

Password Security

Bcrypt hashing with automatic salt generation
Password validation happens in the domain layer
No plain text storage anywhere in the system

Token Management

Access tokens for short-term authentication
Refresh tokens stored server-side for revocation control
Dual authentication support (Bearer tokens + cookies)

Conclusion

This authentication system demonstrates several key techniques:

Secure password handling using bcrypt with automatic salt generation
JWT token management with access/refresh token separation for security and usability
Domain-driven architecture with clear separation of concerns
Flexible authentication supporting both API clients and web browsers
Type-safe integration with comprehensive error handling

The modular design supports future extensions like two-factor authentication, social login, or mobile app integration through existing Bearer token support.

Managing Configurations in Python Projects

Isaac FEI — Fri, 20 Mar 2026 11:31:37 +0000

When building a Python project, managing configurations can quickly become a headache. You have different environments like development, testing, and production, each with its own set of configurations. You want to keep things organized, avoid hardcoding sensitive information, and make it easy to switch between environments. In this post, I'll walk you through how I tackled this problem using Pydantic and dotenv files. Let's dive in!

The Problem: Managing Multiple Environments

In any non-trivial project, you'll likely have at least three environments:

Development (dev): Where you write and test your code locally
Testing (test): Where automated tests run
Production (prod): Where your application runs in the real world

Each environment has its own configuration. For example, database credentials, API keys, and file paths might differ between development and production. Hardcoding these values is a no-go—it's error-prone and insecure. Instead, we want to manage these configurations externally, typically using environment variables.

ENV=dev
DEEPSEEK_API_KEY=your_api_key_here
FILE_UPLOAD_DIR=~/uploads
POSTGRES_USER=dev_user
POSTGRES_PASSWORD=dev_password
QDRANT_HTTP_PORT=6333

You should NEVER commit these dotenv files to Git. They often contain sensitive information like API keys and passwords. However, you should include a .env.example file with placeholder values. This way, other developers know what environment variables they need to set up.

Determining the Current Environment

To decide which environment to use, I introduced a special environment variable called ENV. This variable can be set to dev, test, or prod. Based on its value, the application will load the corresponding dotenv file (e.g., .env.dev, .env.test, or .env.prod).

Here's how I implemented this in the find_dotenv.py file:

# project/config/find_dotenv.py

import os
import dotenv

def find_dotenv() -> str:
    # Get the value of ENV from the environment variables
    env = os.getenv("ENV")

    # Default to dev
    if env is None:
        env = "dev"

    # Select different env files based on ENV
    match env:
        case "dev":
            env_filename = ".env.dev"
        case "test":
            env_filename = ".env.test"
        case "prod":
            env_filename = ".env.prod"
        case _:
            raise ValueError(f"unknown env: {env}")

    # Find the dotenv file
    env_filepath = dotenv.find_dotenv(env_filename)

    return env_filepath

This function checks the ENV variable and selects the appropriate dotenv file. If ENV is not set, it defaults to the development environment.

Grouping Configurations with Pydantic

Dotenv files are great, but they don't support nested fields. For example, you can't directly group all PostgreSQL-related configurations under a POSTGRES key. To solve this, I used Pydantic, a powerful library for data validation and settings management.

Pydantic allows you to define configuration classes that can load values from environment variables. Here's how I grouped PostgreSQL configurations:

# project/config/postgres.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class PostgresConfig(BaseSettings):
    user: str
    password: str
    db: str
    port: int
    data_dir: str
    uri: str

    model_config = SettingsConfigDict(
        env_file_encoding="utf-8",
        env_prefix="POSTGRES_",
        extra="ignore",
    )

Notice the env_prefix="POSTGRES_" line. This tells Pydantic to look for environment variables that start with POSTGRES_. For example, POSTGRES_USER, POSTGRES_PASSWORD, etc. This way, you can keep all PostgreSQL-related configurations neatly grouped together.

Similarly, I created a QdrantConfig class for Qdrant-related settings:

# project/config/qdrant.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class QdrantConfig(BaseSettings):
    http_port: int
    grpc_port: int
    uri: str

    model_config = SettingsConfigDict(
        env_file_encoding="utf-8",
        env_prefix="QDRANT_",
        extra="ignore",
    )

Loading the Configuration

Now that we have our configuration classes, we need a way to load them. This is where the load_config function comes in. It loads the appropriate dotenv file based on the ENV variable and initializes the configuration classes.

Here's the load_config function from the config.py file:

# project/config/config.py
def load_config() -> Config:
    # Find the dotenv file based on the ENV
    env_filepath = find_dotenv()

    # Load the qdrant configuration
    qdrant_config = load_qdrant_config()

    # Load the postgres configuration
    postgres_config = load_postgres_config()

    # Load the configuration
    config = Config(
        qdrant=qdrant_config,
        postgres=postgres_config,
        _env_file=env_filepath,
    )

    return config

This function does the following:

Finds the correct dotenv file using the find_dotenv function from python-dotenv package
Loads the Qdrant and PostgreSQL configurations using their respective load_*_config functions
Initializes the main Config class with these configurations

Putting It All Together

Finally, here's the main Config class that ties everything together:

# project/config/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field, field_validator
from pathlib import Path

class Config(BaseSettings):
    env: Env = Field(default=Env.DEV)
    file_upload_dir: Path
    deepseek_api_key: str
    qdrant: QdrantConfig = Field(default_factory=QdrantConfig)
    postgres: PostgresConfig = Field(default_factory=PostgresConfig)

    model_config = SettingsConfigDict(
        env_file_encoding="utf-8",
        extra="ignore",
    )

    @field_validator("file_upload_dir", mode="after")
    @classmethod
    def resolve_path(cls, path: Path) -> Path:
        return path.expanduser().resolve()

This class includes:

A default environment (Env.DEV)
A file_upload_dir field that resolves to an absolute path
Nested configurations for Qdrant and PostgreSQL

Why This Design?

This design has several advantages:

Environment-Specific Configurations: By using the ENV variable, you can easily switch between different environments without changing any code.
Security: Sensitive information is stored in dotenv files, which are not committed to Git.
Organization: Configurations are grouped logically using Pydantic classes, making the code easier to maintain.
Flexibility: You can add more configurations by simply creating new Pydantic classes and adding them to the Config class.

Final Thoughts

By using dotenv files and Pydantic, you can keep your configurations organized, secure, and environment-specific. This approach has worked well for me, and I hope it helps you too!

Qdrant Hybrid Search Combined with SQL Query Results

Isaac FEI — Fri, 20 Mar 2026 11:31:24 +0000

When developing AI-powered search systems, engineers often face a critical challenge: how to combine the contextual understanding of vector search with traditional database filtering. In this guide, we'll explore how Qdrant's hybrid search capabilities can be seamlessly integrated with SQL query results to create powerful constrained similarity searches.

My Favorite Vector Database: Qdrant

Qdrant has emerged as a leading vector database thanks to its:

Native support for both dense and sparse vectors
Efficient hybrid search capabilities
Simple integration with Python ecosystems
Production-ready performance characteristics

Its unique architecture enables simultaneous processing of multiple vector types while maintaining low latency - perfect for real-time applications.

FastEmbed: Lightweight Embedding Powerhouse

Qdrant's FastEmbed library provides optimized model execution with:

Minimal dependencies (no PyTorch/TensorFlow required)
ONNX Runtime backend for hardware acceleration
Support for popular models like all-MiniLM-L6-v2
BM25 implementation for sparse vectors

This combination enables efficient embedding generation without sacrificing performance, crucial when working with large datasets.

The Hybrid Search Imperative

When Pure Semantic Search Fails

Consider this search scenario with programming language vs animal ambiguity:

document_contents = [
    # The following contents are related to the Python programming language
    # But the word "Python" is not in the text
    "A versatile scripting language with dynamic typing and indentation-based syntax",
    "The preferred language for machine learning and data analysis",
    "Packages like NumPy and Pandas are essential for scientific computing",
    "Why __init__ and self are key concepts in this programming paradigm",
    "Django and Flask are popular frameworks for web development",
    'def main(): print("Hello, World!")',

    # The following contents are related to python snakes
    "Snakes like the reticulated python can grow over 20 feet long",
    "The reticulated python is the world's longest snake species",
]

A pure semantic search for "Python" using dense vectors might prioritize programming content due to:

Embedding model training bias towards technical content
Semantic similarity clustering in vector space
Lack of explicit keyword signals

This creates a problem for users searching for the animal - the zoologist in our example will get irrelevant programming results via dense vector search:

response = client.query_points(
    collection_name=COLLECTION_NAME,
    query=query_dense_embedding.tolist(),
    using=dense_vector_name,
)

Printing the response.points shows the following

id=5 version=0 score=0.5077583 payload={'sql_record_id': 5, 'content': 'def main(): print("Hello, World!")'} vector=None shard_key=None order_value=None
id=2 version=0 score=0.4901533 payload={'sql_record_id': 2, 'content': 'Packages like NumPy and Pandas are essential for scientific computing'} vector=None shard_key=None order_value=None
id=1 version=0 score=0.38752288 payload={'sql_record_id': 1, 'content': 'The preferred language for machine learning and data analysis'} vector=None shard_key=None order_value=None
id=0 version=0 score=0.36844614 payload={'sql_record_id': 0, 'content': 'A versatile scripting language with dynamic typing and indentation-based syntax'} vector=None shard_key=None order_value=None
id=4 version=0 score=0.35516733 payload={'sql_record_id': 4, 'content': 'Django and Flask are popular frameworks for web development'} vector=None shard_key=None order_value=None
id=7 version=0 score=0.3404391 payload={'sql_record_id': 7, 'content': "The reticulated python is the world's longest snake species"} vector=None shard_key=None order_value=None
id=3 version=0 score=0.29858643 payload={'sql_record_id': 3, 'content': 'Why __init__ and self are key concepts in this programming paradigm'} vector=None shard_key=None order_value=None
id=6 version=0 score=0.2927005 payload={'sql_record_id': 6, 'content': 'Snakes like the reticulated python can grow over 20 feet long'} vector=None shard_key=None order_value=None

BM25: The Keyword Savior

BM25 (Best Match 25) solves this by:

Calculating term frequency-inverse document frequency (TF-IDF)
Prioritizing exact keyword matches
Handling short queries effectively
Working with sparse vector representations

In our example, BM25 would boost documents containing "python" while dense vectors handle semantic matches.

Reciprocal Rank Fusion (RRF): Merging Semantic and Keyword Results

RRF combines results from multiple search methods by:

Getting ranked lists from each search type
Assigning scores based on reciprocal ranks
Merging results using formula: 1/(rank + k)
Producing unified relevance ranking

This fusion preserves keyword matches while maintaining semantic relevance.

Implementing Hybrid Search in Qdrant

Model Configuration

# Configure dense vectors (semantic understanding)
client.set_model(
    embedding_model_name="sentence-transformers/all-MiniLM-L6-v2",
    cache_dir="./fastembed-cache",
)

# Configure sparse vectors (keyword matching)
client.set_sparse_model(
    embedding_model_name="Qdrant/bm25",
    cache_dir="./fastembed-cache",
)

After setting the embedding models in Qdrant, one can get the models later from the name-to-model dictionaries embedding_models and sparse_embedding_models:

from fastembed import TextEmbedding, SparseTextEmbedding

# Get the dense embedding model
dense_embedding_model: TextEmbedding = client.embedding_models[
    "sentence-transformers/all-MiniLM-L6-v2"
]

# Get the sparse embedding model
sparse_embedding_model: SparseTextEmbedding = client.sparse_embedding_models[
    "Qdrant/bm25"
]

Collection Creation

# Get vector configuration parameters
dense_params = client.get_fastembed_vector_params()
sparse_params = client.get_fastembed_sparse_vector_params()

# Create multi-vector collection
client.create_collection(
    collection_name="demo-collection",
    vectors_config=dense_params,
    sparse_vectors_config=sparse_params,
)

Data Insertion Strategy

For demonstration purpose, suppose each document only consists of an ID and a content field:

# The variable `document_contents` is the same as mentioned previously

documents = [
    {"id": index, "content": document_content}
    for index, document_content in enumerate(document_contents)
]

Insert into Qdrant:

# Generate combined embeddings
dense_embeddings = dense_embedding_model.embed(document_contents)
sparse_embeddings = sparse_embedding_model.embed(document_contents)

# Create points with dual vectors
points = [
    models.PointStruct(
        id=doc["id"],
        vector={
            dense_vector_name: dense.tolist(),
            sparse_vector_name: sparse.as_object(),
        },
        payload={
            # Associated the the record in SQL database
            "sql_record_id": doc["id"], 

            # Document content
            "content": doc["content"]
        }
    ) for doc, dense, sparse in zip(documents, dense_embeddings, sparse_embeddings)
]

client.upsert(collection_name="demo-collection", points=points)

Note that calling the methods .tolist() and as_object() is required to convert numpy arrays and SparseEmbedding object to Python data structures so that they can be passed to the Qdrant API.

Hybrid Query Execution

response = client.query_points(
    collection_name="demo-collection",
    prefetch=[
        # Dense vector search
        models.Prefetch(
            query=query_dense_embedding.tolist(),
            using=dense_vector_name,
            limit=10,
        ),

        # Sparse vector search
        models.Prefetch(
            query=query_sparse_embedding.as_object(),
            using=sparse_vector_name,
            limit=10,
        ),
    ],
    query=models.FusionQuery(fusion=models.Fusion.RRF),
)

This returns results combining semantic matches from dense vectors and keyword hits from BM25.

id=7 version=0 score=0.64285713 payload={'sql_record_id': 7, 'content': "The reticulated python is the world's longest snake species"} vector=None shard_key=None order_value=None
id=5 version=0 score=0.5 payload={'sql_record_id': 5, 'content': 'def main(): print("Hello, World!")'} vector=None shard_key=None order_value=None
id=6 version=0 score=0.44444445 payload={'sql_record_id': 6, 'content': 'Snakes like the reticulated python can grow over 20 feet long'} vector=None shard_key=None order_value=None
id=2 version=0 score=0.33333334 payload={'sql_record_id': 2, 'content': 'Packages like NumPy and Pandas are essential for scientific computing'} vector=None shard_key=None order_value=None
id=1 version=0 score=0.25 payload={'sql_record_id': 1, 'content': 'The preferred language for machine learning and data analysis'} vector=None shard_key=None order_value=None
id=0 version=0 score=0.2 payload={'sql_record_id': 0, 'content': 'A versatile scripting language with dynamic typing and indentation-based syntax'} vector=None shard_key=None order_value=None
id=4 version=0 score=0.16666667 payload={'sql_record_id': 4, 'content': 'Django and Flask are popular frameworks for web development'} vector=None shard_key=None order_value=None
id=3 version=0 score=0.125 payload={'sql_record_id': 3, 'content': 'Why __init__ and self are key concepts in this programming paradigm'} vector=None shard_key=None order_value=None

As you can see, the documents related to the python snake make it to the top 3.
The zoologist must be pleased now.

SQL Integration

SQL databases excel at:

Complex conditional filtering
Join operations across datasets
Access control enforcement
Transactional data management

By first filtering records via SQL queries, we create constrained search spaces for vector operations.

Implementation Pattern

SQL Pre-Filtering:

# Get accessible document IDs from SQL
allowed_ids = execute_sql("SELECT id FROM documents WHERE department = 'zoology'")

Constrained Vector Search:

response = client.query_points(
    collection_name="demo-collection",

    # Query filter
    query_filter=models.Filter(
        must=models.FieldCondition(
            key="sql_record_id",
            match=models.MatchAny(any=allowed_ids),
        )
    ),

    # Search settings...
)

Real-World Use Cases

Role-Based Access Control:
- Filter documents based on user permissions
- Maintain security while enabling semantic search
Temporal Filtering:
- Search only within recent documents
- Combine "last 7 days" SQL filter with vector search
Multi-Tenancy:
- Scope search to tenant-specific data
- Maintain single collection architecture

The Ultimate Combination

By merging SQL's filtering power with Qdrant's hybrid search, we create systems that:

Enforce business rules through SQL constraints
Understand user intent via semantic search
Respect keyword matches through BM25
Combine results intelligently via RRF

This architecture supports complex requirements while maintaining search relevance - whether your users are zoologists searching for snakes or developers looking for Python frameworks.

# Final hybrid search with SQL constraints
response = client.query_points(
    collection_name="demo-collection",

    # Query filter to get target documents
    query_filter=models.Filter(
        must=[
            # Only points with sql_record_id of 1, 3, 5, 7 
            # in the payload are considered
            models.FieldCondition(
                key="sql_record_id",
                match=models.MatchAny(any=[1, 3, 5, 7]),
            )
        ]
    ),

    # Hybrid search
    prefetch=[
        models.Prefetch(
            query=query_dense_embedding.tolist(),
            using=dense_vector_name,
            limit=10,
        ),
        models.Prefetch(
            query=query_sparse_embedding.as_object(),
            using=sparse_vector_name,
            limit=10,
        ),
    ],

    # RRF
    query=models.FusionQuery(fusion=models.Fusion.RRF),
)

The result? Precise, secure, and context-aware search experiences that leverage the best of both worlds - structured data management and AI-powered similarity search.

Print the response.points:

id=5 version=0 score=0.8333334 payload={'sql_record_id': 5, 'content': 'def main(): print("Hello, World!")'} vector=None shard_key=None order_value=None
id=7 version=0 score=0.75 payload={'sql_record_id': 7, 'content': "The reticulated python is the world's longest snake species"} vector=None shard_key=None order_value=None
id=1 version=0 score=0.5833334 payload={'sql_record_id': 1, 'content': 'The preferred language for machine learning and data analysis'} vector=None shard_key=None order_value=None
id=3 version=0 score=0.4 payload={'sql_record_id': 3, 'content': 'Why __init__ and self are key concepts in this programming paradigm'} vector=None shard_key=None order_value=None

The Publisher-Subscriber Pattern in React

Isaac FEI — Fri, 20 Mar 2026 11:31:17 +0000

Stopwatch Demo

Consider building a stopwatch component like the one below:

Interactive or embedded content omitted — see the original post: https://isaacfei.com/posts/react-publister-subscriber

🤔 Some thoughts:

The stopwatch should manage the state on its own. We should not lift the state up since it is updating actively. Lifting the state up to its parent would lead to frequent rerendering of the parent component, potentially degrading performance, especially if the parent includes heavy components or complex logic.
We want to start, stop and reset the stopwatch anywhere and anytime as we see fit.
When the stopwatch is started, stopped, reset or when it is ticking, we want to invoke some logic accordingly.
Shall we do this by setting callbacks,
like onStart, onStop, ...?
Or we can do something else?

Gerneral Idea

Define a controller StopwatchController and a compoenent Stopwatch.
The controller will implement methods like start, stop and reset.
The component takes the controller as a prop and provides a visually display of the elapsed time.

// stopwatch/controller.ts

export class StopwatchController {
  #seconds: number = 0;
  #tickInterval: NodeJS.Timeout | null = null;

  constructor() {}

  /**
   * Returns the elapsed seconds since the stopwatch was started.
   */
  get seconds() {
    return this.#seconds;
  }

  start() {
    if (this.#tickInterval) {
      return;
    }

    // Update the elapsed time every 0.01s
    this.#tickInterval = setInterval(() => {
      this.#seconds += 0.01;
    }, 10);
  }

  stop() {
    if (this.#tickInterval) {
      // Clear the tick interval
      clearInterval(this.#tickInterval);

      // Unset the tick interval
      this.#tickInterval = null;
    }
  }

  reset() {
    // Reset the seconds to 0
    this.#seconds = 0;

    // Stop the stopwatch
    this.stop();
  }
}

The Stopwatch component takes props of the following type

interface StopwatchProps {
  className?: string;
  controller: StopwatchController;
}

Stopwatch will maintain a state variable, seconds, using useState to display the elapsed time.

Now, how can the controller notify the component to update the state? One approach is to define callback functions provided by the controller, for example onTick. The Stopwatch component sets this callback to update its state as follows:

useEffect(() => {
    controller.onTick = (seconds) => {
        setSeconds(seconds);
    };
}, []);

However, what if we also need to execute some logic outside the Stopwatch component? For instance, suppose we want to log to the console whenever the stopwatch ticks. Since the onTick callback is already set by the component, we cannot overwrite it to perform additional tasks.

The solution is to dispatch events and, based on that, apply a publisher-subscriber pattern.

Instead of defining callbacks, we will first define custom events such as StartEvent, StopEvent, TickEvent, and so on. We will then dispatch these events at the appropriate locations within the controller, which is referred to as the publisher.

Subsequently, any logic interested in a corresponding event can listen for it. For example, the Stopwatch component will listen to events instead of setting callbacks to update its internal state. The Stopwatch is referred as the subscriber.

useEffect(() => {
    controller.addEventListener("tick", (event) => {
        setSeconds(event.detail.seconds);
    })
}, []);

If we want to log the elapsed seconds outside the component, we simply write another listener to handle the TickEvent.

controller.addEventListener("tick", (event) => {
    console.log(`elapsed seconds: ${event.detail.seconds}`);
})

This logging logic is also a subscriber.

One publisher can have multiple subscribers.

Custom Events

To define our own events, we need to extends the class
CustomEvent.

Events without Extra Data

Definition of a StartEvent for the stopwatch:

class StartEvent extends CustomEvent<null> {
  constructor() {
    super("start");
  }
}

The generic type T in CustomEvent<T>
specifies the type of the detail property.
For the StartEvent, we don't need to attach any extra data.
So, we net the T to null.

Events with Extra Data

Now, consider defining the TickEvent
which is fired whenever the value of the elapsed seconds changes,
and the event accommodates the elapsed seconds since the start of the stopwatch.

class TickEvent extends CustomEvent<number> {
  constructor(seconds: number) {
    super("tick", { detail: seconds });
  }
}

Then the value of the elapsed seconds can be accessed like const seconds = event.detail.

Alternatively, I recommend the following boilerplate for any CustomEvent with a non-null detail, where we treat detail as an object and define its schema. Using this boilerplate, we can handle more complex event data cleanly.

interface TickEventDetail {
  seconds: number;
}

class TickEvent extends CustomEvent<TickEventDetail> {
  constructor(detail: TickEventDetail) {
    super("tick", { detail });
  }
}

The Event Target

To dispatch and add or remove event listeners, we need to use a DOM element as an event target:

element.dispatch(event)
element.addEventListener("xxx", listener)
element.removeEventListener("xxx", listener)

One option is to create a dummy Div element as the event target using const eventTarget = new HTMLDivElement() as a property of the controller.

However, there is actually an EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) class that we can instantiate. By definition, EventTarget is an abstraction of objects that can receive events and may have listeners for them.

// stopwatch/controller.ts

export class StopwatchController {
  #seconds: number = 0;
  #tickInterval: NodeJS.Timeout | null = null;
+  #eventTarget = new EventTarget();

  constructor() {}

  // ...
}

Add/Remove Event Listeners

To add or remove a event listener, we need to specify

type: Event type/name, the unique identifier of this event
listener: (event: Event) => void

eventTarget.addEventListener("start", listener);
eventTarget.removeEventListener("start", listener);

But how can we define add and remove event listener methods for each of our custom events?

Define `addXxxEventListener` and `removeXxxEventListener` for Each `Xxx` Event

Let's first implement addStartEventListener:

addStartEventListener(listener: (event: StartEvent) => void) {
  this.#eventTarget.addEventListener(
    "start",
    listener,
  );
}

If you are using TypeScript, you might encounter a type error because addEventListener does not accept (event: StartEvent) => void as a listener.
But don't worry.
You can use a dirty little trick 👻 with as type casting:

addStartEventListener(listener: (event: StartEvent) => void) {
  this.#eventTarget.addEventListener(
    "start",
    listener as EventListenerOrEventListenerObject,
  );
}

Then, basically COPY and PASTE the same code snippet for other events...

// ...

addStartEventListener(listener: (event: StartEvent) => void) {
  this.#eventTarget.addEventListener(
    "start",
    listener as EventListenerOrEventListenerObject,
  );
}

removeStartEventListener(listener: (event: StartEvent) => void) {
  this.#eventTarget.addEventListener(
    "start",
    listener as EventListenerOrEventListenerObject,
  );
}

addStopEventListener(listener: (event: StopEvent) => void) {
  this.#eventTarget.addEventListener(
    "stop",
    listener as EventListenerOrEventListenerObject,
  );
}

removeStopEventListener(listener: (event: StopEvent) => void) {
  this.#eventTarget.addEventListener(
    "stop",
    listener as EventListenerOrEventListenerObject,
  );
}

// ...

Define a Single Pair of `addEventListener` and `removeEventListener` -- Play around with Types

However, we can do better by playing around with type to eliminate the repetition of the same logic.

First, define a EventMap that maps every event type to the associated custom event class.

interface EventMap {
  start: StartEvent;
  stop: StopEvent;
  reset: ResetEvent;
  tick: TickEvent;
}

Next, leveraging the type tricks
of keyof
and mapped types,
we can only define a single pair of addEventListener and removeEventListener:

addEventListener<K extends keyof EventMap>(
  type: K,
  listener: (event: EventMap[K]) => void,
) {
  this.#eventTarget.addEventListener(
    type,
    listener as EventListenerOrEventListenerObject,
  );
}

removeEventListener<K extends keyof EventMap>(
  type: K,
  listener: (event: EventMap[K]) => void,
) {
  this.#eventTarget.removeEventListener(
    type,
    listener as EventListenerOrEventListenerObject,
  );
}

Summary

Define a new custom event that extends CustomEvent
Modify EventMap
Dispatch the event in the desired place

Implementation

Deploying a Image Recognition Service to AWS Lambda

Isaac FEI — Fri, 20 Mar 2026 11:31:08 +0000

The source code is available in my repository.

Start a New Project

First, create an new virtual environment:

python -m venv ~/pyvenvs/lambda

I used venv for creating the environment, and I named it lambda and placed it in the ~/pyvenvs directory.
You may use any other environment manager and name as you wish.

I will name the project resnet-image-recognition:

mkdir resnet-image-recognition
cd resnet-image-recognition

The Python packages we are going to use are

awslambdaric AWS need this package, the runtime interface client, to manage the interaction betweeen Lambda and our source code. See more details here. It will be used as the entry point of the container, as we will see later.
pydantic My ~go-to~ only choice for defining data models.
fastapi[standard] Framework for building APIs. Use standard feature here to install the fastapi CLI.
mangum An adapter for running ASGI applications in AWS Lambda. It is used to wrap our FastAPI app: Mangum(app).
torch We use PyTorch to define the ResNet50 model.
torchvision We need utilities for transforming images before feeding them into the model.

Project structure:

resnet-image-recognition
├── resnet_image_recognition
│   ├── __init__.py
│   ├── resnet
│   │   ├── __init__.py
│   │   └── ...
│   └── image_recognizer
│       ├── __init__.py
│       ├── image_recognizer.py
│       └── imagenet_classes.py
├── app
│   ├── __init__.py
│   ├── app.py
│   ├── auth
│   │   ├── __init__.py
│   │   └── validate_api_key.py
│   └── handlers
│       ├── __init__.py
│       ├── health_check.py
│       └── recognize_image.py
├── models
│   └── resnet50-0676ba61.pth
├── api-keys.txt
├── Dockerfile
└── .gitignore

Define the ResNet50 Architecture

When I was learning the ResNet, I found the original implementation is not that easy to understand.
So, I implemented the ResNet model using PyTorch from scratch and add a lot of comments.
Hope it will help you.

I put my source code for the ResNet in the sub-package resnet_image_recognition/resnet.
Check it here.
In this project, we will be using ResNet50.

To use the model for inference,
we also need the pretrained weights (.pt or .pth files).
You can download the one provided by PyTorch from here.

Save it under the model directory.

Implement the `ImageRecognizer` using the ResNet50 Model

We are now going to create a simple ImageRecognizer class powered by the ResNet50 model.
It has a recognize method, which takes a PIL image as input and returns the class of that image.

# resnet_image_recognition/image_recognizer/image_recognizer.py

from pathlib import Path
from PIL import Image as im
import torch
from torchvision import transforms
from ..resnet import ResNet50
from .imagenet_classes import IMAGENET_CLASSES

class ImageRecognizer:

    def __init__(self, model_path: Path) -> None:

        # Load the state dict
        state_dict = torch.load(model_path)

        # Create an empty model
        self._model = ResNet50()

        # Set the pretrained weights
        self._model.load_state_dict(state_dict)

        # Set evaluation mode
        self._model.eval()

    def recognize(self, image: im.Image) -> str:
        """
        Recognizes the class of an image.

        Parameters
        ----------
        image : Image
            The input image.

        Returns
        -------
        str
            The name of the class of the given image.
        """

        # Resize the image
        resized_image = transforms.Resize((224, 224))(image)

        # Convert to tensor
        image_tensor = transforms.ToTensor()(resized_image)

        # Add batch dimension
        image_tensor = torch.unsqueeze(image_tensor, 0)

        # Run inference
        # The probabilities for each class are returned
        probs = self._model(image_tensor)

        # Find the class with the highest probability
        class_index = torch.argmax(probs).item()

        # Get the class name
        class_name = IMAGENET_CLASSES[class_index]

        return class_name

The constant IMAGENET_CLASSES is a tuple consiting of 1000 classes from the ImageNet dataset.
You may check its value here in my repository.

Build a FastAPI App -- Deliver the Deep Learning Model as an HTTP Service

The core functionality of the service is done.
To let other users to use our ImageRecognizer, we need create an API that handles users' requests and invokes the ImageRecognizer as a backend service.

Every FastAPI app reqires a global app instance to be defined.

# resnet_image_recognition/app/app.py

from fastapi import FastAPI

# Create an app instance
app = FastAPI()

As a standard procedure, we expose the app instance in the __init__.py:

# resnet_image_recognition/app/__init__.py

from .app import app

__all__ = [
    "app",
]

However, we are not going to use this app (directly) in this project.
But for a general FastAPI project, this is what we need.

For this project, as you will see,
we will wrap the app further with a Mangum adapter in a later section.

Health Check

To get started, first create a health_check API, which simply returns a short message indicating that the server is up and running.

(health_check is the Hello, World API in the backend development.)

# resnet_image_recognition/app/handlers/health_check.py

def health_check():

    return {
        "message": "I am ok",
    }

Function like health_check defined above are oftern referred to as handlers since they handle the incoming requests.

Next, register a route for the health_check:

# resnet_image_recognition/app/app.py

from fastapi import FastAPI
from .handlers import (
    health_check,
)

# Create an app instance
app = FastAPI()

# Register routes
+app.get("/health-check")(health_check)

app.get specifies that the request method is GET.
For POST methods, use app.post.

Recognize Image

# resnet_image_recognition/app/handlers/recognize_image.py

import io
from pathlib import Path
from PIL import Image as im
from pydantic import BaseModel
from fastapi import UploadFile

MODELS_DIR = Path.cwd().joinpath("models")
MODEL_PATH = MODELS_DIR.joinpath("resnet50-0676ba61.pth")

class RecognizeImageResponse(BaseModel):
    class_name: str

async def recognize_image(
    image: UploadFile,
) -> RecognizeImageResponse:

    # Read the image
    image_bytes = await image.read()

    # Create a byte stream from the raw bytes
    image_byte_stream = io.BytesIO(image_bytes)

    # Open the image
    image = im.open(image_byte_stream)

    from resnet_image_recognition import ImageRecognizer

    # Create the image recognizer
    image_recognizer = ImageRecognizer(MODEL_PATH)

    # Recognize
    class_name = image_recognizer.recognize(image)

    return RecognizeImageResponse(class_name=class_name)

# resnet_image_recognition/app/app.py

from fastapi import FastAPI
from .handlers import (
    health_check,
+    recognize_image, 
)

# Create an app instance
app = FastAPI()

# Register routes
app.get("/health-check")(health_check)
+app.post("/recognize-image")(recognize_image)

Final Touch -- Mangum Adapter

Wrap the app instance into the Mangum adapter:

# resnet_image_recognition/app/app.py
from fastapi import FastAPI
from .handlers import (
    health_check,
    recognize_image,
)

# Create an app instance
app = FastAPI()

# Register routes
app.get("/health-check")(health_check)
app.post("/recognize-image")(recognize_image)

+# Wrap the app instance into the Mangum adapter
+handler = Mangum(app)

Expose the variable handler in __init__.py, which will be used as the entrypoint of the container.
The service will be started via app.handler.

# resnet_image_recognition/app/__init__.py

-from .app import app
+from .app import app, handler

__all__ = [
    "app",
+    "handler",
]

Write a Dockerfile for Building the Image

# Base image
FROM --platform=linux/amd64 python:3.11

# Copy files

# Copy the package source
COPY ./resnet_image_recognition ./resnet_image_recognition

# Copy the FastAPI app source
COPY ./app ./app

# Copy model weights
COPY ./models ./models

# Copy API keys
COPY ./api-keys.txt .

# Install dependencies

# Install dependencies
RUN pip install awslambdaric pydantic "fastapi[standard]" mangum

# Install PyTroch for Linux
RUN pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# Set runtime interface client as default command for the container runtime
ENTRYPOINT [ "/usr/local/bin/python", "-m", "awslambdaric" ]

# Pass the name of the function handler as an argument to the runtime
CMD [ "app.handler" ]

You can build and tag the image now if you are familiar with Docker.
Or, you can check the next section for how to build and push the image to AWS ECR.

Build and Push the Docker Image to AWS ECR

ECR (Elastic Container Registry) is an AWS service that
you can store, share and deploy container images.

When deploying an AWS Lambda function using Docker images,
you are prompted to choose an image from the ECR.

Enter the ECR console, you will see the following UI.
Click Create repository and following the instructions.

After that, click the link to the repository you have created and
then click the View push commands button
to see the help messages like the following
for building and pushing Docker images to ECR.

Create a Lambda Function using the Docker Container

Enter the AWS Lambda console and click Create function:

Choose Container image and click Browse image
to select the previously uploaded image from ECR.

Recall that we set the linux/amd64 platform for the container image.
So, here choose the x86_64 architecture.

Then click Create function and wait for it.

Create a Funciton URL

Now, your funciton can only be invoked for authenticated AWS users or
you other AWS services.

To make it accessible for all users via HTTP requests,
you need to generate a function URL.

Set General Configuration

When you invoke the function now,
you will possibly encounter the errors of timeout or out of memeory.
This is because of the limited resources assigned to the cloud function.

You may assign more resources like time limit and memeory usage by
setting the following configuration:

A Simple Web App for Image Generation with Dall-E 3 using Go + HTMX

Isaac FEI — Fri, 20 Mar 2026 11:30:46 +0000

What Will We Build? And My Motivation

In this post, we'll build a single-page web application that generates images using OpenAI's DALL-E 3 API. The app features:

A simple and yet beautiful UI built with Tailwind CSS and DaisyUI
HTMX for frontend interactions without JavaScript
Capability of sending multiple requests to the Dall-E 3 API concurrently

App screenshot:

I've been itching to play around with Go and HTMX 🤩, so I figured, why not build a simple web app with them? Plus, I've been needing to generate AI images every now and then—like for this blog post's cover image. Instead of generating one image at a time and picking through them manually, I thought it'd be way more convenient to build a little app that spits out a bunch of options at once and lets me easily pick the best one.

This is not a step-by-step tutorial. Instead, I will focus on introducing the main ideas and highlighting the key parts of the code. For the complete source code, please refer to my repository gen-img.

See section How to Run for the instructions to run the app.

Introduction to HTMX and Templ

HTMX is a modern library that simplifies building dynamic, interactive web applications using HTML attributes. It enables features like AJAX requests, CSS transitions, and server-side rendering without requiring complex JavaScript. By extending HTML with attributes such as hx-get, hx-post, hx-target, and hx-swap, HTMX allows developers to create seamless user experiences with minimal effort.

When paired with Go and the Go Templ package, HTMX becomes a powerful tool for building server-rendered web applications. The Go Templ package is a templating engine that lets you dynamically generate HTML on the server side. HTMX complements this by handling client-side interactions, enabling smooth DOM updates without full page reloads.

To build UIs with Templ, you write .templ files, which mix HTML and Go code. These files are compiled into normal Go code using the templ generate command (or automatically via live-reloading tools like Air). This approach feels similar to writing TSX in React or using the view! macro in Rust's Leptos framework.

Together, HTMX and Templ leverage the strengths of both technologies: Go's performance and simplicity for server-side logic, and HTMX's lightweight approach to enhancing HTML for dynamic behavior. This combination provides a streamlined workflow for building modern, efficient, and maintainable web applications.

Project Structure

gen-img/
├── cmd/
│   └── web/
│       └── main.go           // Application entry point
├── internal/
│   └── templs/
│       ├── components/       // Reusable UI components
│       ├── layouts/          // Page layouts
│       └── pages/            // Pages
├── pkg/
│   └── genimg/               // Image generation package
│       ├── genimg.go         // Core image generation logic
│       └── genimg_test.go    // Tests
├── .air.toml                 // Air configuration
├── .env.example              // Environment variables template
├── go.mod                    // Go module file
└── go.sum                    // Go dependencies checksum

Setup

Gin

We use Gin as the backend framework.

Add it to your project:

go get github.com/gin-gonic/gin

Templ

Even though this app is simple enough,
you don't want to write every component in a single HTML file.

Templ is a powerful templating engine for Go that allows us to scaffold the app in a modular way.
We'll use it to build our UI components and pages.

Add the templ package:

go get github.com/a-h/templ/cmd/templ@latest

If you are developing in VSCode, you may isntall the extension templ-vscode to get syntax highlighting and autocompletion for .templ files.

Air

Air is a live reload tool for Go applications. It watches your files for changes and automatically rebuilds and restarts your application.

Install Air:

go install github.com/cosmtrek/air@latest

Once installed, you can run the air command in your project directory. By default, Air will look for a .air.toml configuration file in the current directory for any custom settings.

To get started, create a .air.toml file in your project's root directory. Then, as recommended in the documentation, copy the default full configuration into it.

we will modify the following sections with the explanations below:

build.pre_cmd: Prevent generating file pre_cmd.txt
build.cmd: Customize the command to build the main file located at ./cmd/web/main.go
build.post_cmd: Prevent generating file post_cmd.txt
build.include_ext: Watch the .templ files

# .air.toml

# Working directory
# . or absolute path, please note that the directories following must be under root.
root = "."
tmp_dir = "tmp"

[build]
# Array of commands to run before each build
pre_cmd = ["echo 'this is pre cmd'"]
# Just plain old shell command. You could use `make` as well.
cmd = "templ generate && go build -o ./tmp/main ./cmd/web/main.go"
# Array of commands to run after ^C
post_cmd = ["echo 'this is post cmd'"]
# Binary file yields from `cmd`.
bin = "tmp/main"
# Customize binary, can setup environment variables when run your app.
full_bin = "APP_ENV=dev APP_USER=air ./tmp/main"
# Add additional arguments when running binary (bin/full_bin). Will run './tmp/main hello world'.
args_bin = ["hello", "world"]
# Watch these filename extensions.
include_ext = ["go", "tpl", "tmpl", "html", "templ"]
# ...

HTMX

To use HTMX, simply include the CDN link in the HTML head:

// internal/templs/layouts/base_layout.templ

package layouts

templ BaseLayout(title string) {
    <!DOCTYPE html>
    <html lang="en" data-theme="dark">
        <head>
            <meta charset="UTF-8">
            <meta name="viewport" content="width=device-width, initial-scale=1.0">

            <title>{ title }</title>

            // HTMX
            <script src="https://unpkg.com/htmx.org"></script>
        </head>

        <body class="h-screen overflow-clip">
            { children... }
        </body>
    </html>
}

Tailwind CSS v4 + DaisyUI

I usually use Tailwind CSS (now on v4) and Shadcn UI for my frontend projects.
But since this project doesn't use a framework like React or Vue, Shadcn is not applicable.

Instead, I'm going with DaisyUI. It is a nice UI library with ready-to-use components and utilities. The best part? You can just include it via CDN—no setup needed.

Add these to the base layout file:

// internal/templs/layouts/base_layout.templ
package layouts

templ BaseLayout(title string) {
    <!DOCTYPE html>
    <html lang="en" data-theme="dark">
        <head>
            <meta charset="UTF-8">
            <meta name="viewport" content="width=device-width, initial-scale=1.0">

            <title>{ title }</title>

            // HTMX
            <script src="https://unpkg.com/htmx.org"></script>

            // Tailwind CSS v4
            <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

+            // Daisy UI
+            <link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />

+            // Daisy UI Themes
+            <link href="https://cdn.jsdelivr.net/npm/daisyui@5/themes.css" rel="stylesheet" type="text/css" />
        </head>

        <body class="h-screen overflow-clip">
            { children... }
        </body>
    </html>
}

Backend: Send Multiple Requests to OpenAI Concurrently

Send a Single Request

The core functionality starts with the GenerateImage function that sends a single request to the DALL-E 3 API:

// pkg/genimg/genimg.go

func GenerateImage(endpoint string, apiKey string, prompt string, imageSize string) (string, error) {

    // Create the payload
    payload := map[string]any{
        "model":           "dall-e-3",
        "prompt":          prompt,
        "size":            imageSize,
        "response_format": "url",
    }

    // Convert to JSON
    payloadJson, err := json.Marshal(payload)
    if err != nil {
        return "", err
    }

    // Create the request
    req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payloadJson))
    if err != nil {
        return "", err
    }

    // Set the headers
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+apiKey)

    // Send the request
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }

    // Read the response body

    body, err := io.ReadAll(resp.Body)
    defer resp.Body.Close()

    if err != nil {
        return "", err
    }

    // Decode the JSON response into a struct
    var responseData imageGenerationResponseData
    err = json.Unmarshal(body, &responseData)
    if err != nil {
        return "", err
    }

    // Get the image URL

    if len(responseData.Data) == 0 {
        return "", errors.New("data is empty")
    }

    imageUrl := responseData.Data[0].Url

    return imageUrl, nil
}

Send Multiple Requests

You may notice from OpenAI's API documentation that there is a n parameter that allows us to generate multiple images concurrently.
So, why not just send a single request with the n parameter set to the number of images we want to generate?
I tried, but it told me that the model doesn't support it yet 😂.

To generate multiple images efficiently, we use a worker pool pattern with goroutines. This approach allows us to handle concurrent requests to the API without overwhelming it, while still maintaining good performance.
Let's see the code:

// pkg/genimg/genimg.go

func GenerateImages(ctx context.Context, endpoint string, apiKey string, prompt string, imageSize string, numImages int, maxWorkers int) []string {

    // A buffered channel of all image URLs to return
    imageUrlChan := make(chan string, numImages)

    // A buffered channel of all requests to send
    jobChan := make(chan struct{}, numImages)

    // Create a wait goup
    var wg sync.WaitGroup

    for range maxWorkers {

        // Increment the wait group
        wg.Add(1)

        // Start a worker
        go worker(ctx, &wg, endpoint, apiKey, prompt, imageSize, jobChan, imageUrlChan)

    }

    // Send the jobs
    for range numImages {
        jobChan <- struct{}{}
    }

    // Done sending jobs
    close(jobChan)

    go func() {
        // Wait for the wait group to finish
        wg.Wait()

        // Close the channel
        close(imageUrlChan)
    }()

    // Slice of all URLs of generated images
    var imageUrls []string
    for imageUrl := range imageUrlChan {
        imageUrls = append(imageUrls, imageUrl)
    }

    return imageUrls
}

func worker(ctx context.Context, wg *sync.WaitGroup, endpoint string, apiKey string, prompt string, imageSize string, jobChan <-chan struct{}, imageUrlChan chan<- string) {

    // Decrement the wait group counter
    defer wg.Done()

    for range jobChan {
        select {

        case <-ctx.Done():
            return

        default:
            // Generate a single image
            imageUrl, err := GenerateImage(endpoint, apiKey, prompt, imageSize)

            // Collect the image URL
            if err == nil {
                imageUrlChan <- imageUrl
            }

        }
    }

}

Key points of this implementation:

Buffered Channels:
- jobChan is used to distribute jobs (tasks) to workers.
- imageUrlChan collects the results (generated image URLs) from workers.
Worker Pool:
- A configurable number of worker goroutines maxWorkers are spawned to handle jobs concurrently.
Context Handling:
- The ctx.Done() check ensures that workers can gracefully exit if the context is canceled (e.g., due to a timeout).
Asynchronous Result Collection:
- Results are collected in a separate goroutine, allowing the main function to return all generated image URLs once all workers are done.
Wait Group:
- The sync.WaitGroup ensures that the main function waits for all workers to finish before closing the imageUrlChan.

The worker pool pattern is ideal for this use case because:

It limits the number of concurrent requests to the API, preventing overload.
It maximizes efficiency by processing multiple requests in parallel.
It ensures that all results are collected and returned in a structured way.

Set Up the Gin Router

In this section, we configure the Gin router to handle two main routes: / for rendering the home page and /generate for processing form submissions to generate images.

// cmd/web/main.go

package main

import (
    "context"
    "gen-img/internal/templs/components"
    "gen-img/internal/templs/pages"
    "gen-img/pkg/genimg"
    "os"
    "strconv"
    "time"

    "github.com/gin-gonic/gin"
    "github.com/joho/godotenv"
)

const numWorkers = 10

func main() {

    // Load the dotenv
    err := godotenv.Load()
    if err != nil {
        panic(err)
    }

    // Get the API key
    apiKey := os.Getenv("OPENAI_API_KEY")
    if apiKey == "" {
        panic("OPENAI_API_KEY is not set")
    }

    router := gin.Default()

    // Render the home page
    router.GET("/", func(ctx *gin.Context) {
        pages.Home().Render(ctx.Request.Context(), ctx.Writer)
    })

    router.POST("/generate", func(ctx *gin.Context) {

        // Get fields from the submitted form data

        endpoint := ctx.PostForm("endpoint")
        prompt := ctx.PostForm("prompt")
        imageSize := ctx.PostForm("imageSize")

        numImagesAsString := ctx.PostForm("numImages")
        numImages, err := strconv.Atoi(numImagesAsString)
        if err != nil {
            panic(err)
        }

        // Create a context with a timeout
        c, cancel := context.WithTimeout(context.Background(), 60*time.Second)
        defer cancel()

        // Send the request to generate the images
        images := genimg.GenerateImages(c, endpoint, apiKey, prompt, imageSize, numImages, numWorkers)

        // Render the image list
        // HTMX will plug it in under the image list container
        components.ImageList(images).Render(ctx.Request.Context(), ctx.Writer)
    })

    router.Run()
}

Frontend: Build the UI in `.templ` Files

The UI is built using templ components. The main structure consists of:

A base layout (internal/templs/layouts/base_layout.templ)
A home page (the one and only page) (internal/templs/pages/home.templ)
Reusable components (internal/templs/components/)

This design may seem familiar to you if you have ever used a modern frontend framework.

Base Layout

The base layout provides the common structure for all pages:

// internal/templs/layouts/base_layout.templ

package layouts

templ BaseLayout(title string) {
    <!DOCTYPE html>
    <html lang="en" data-theme="dark">
        <head>
            <meta charset="UTF-8">
            <meta name="viewport" content="width=device-width, initial-scale=1.0">

            <title>{ title }</title>

            // HTMX
            <script src="https://unpkg.com/htmx.org"></script>

            // Tailwind CSS v4
            <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

            // Daisy UI
            <link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />

            // Daisy UI Themes
            <link href="https://cdn.jsdelivr.net/npm/daisyui@5/themes.css" rel="stylesheet" type="text/css" />
        </head>

        <body class="h-screen overflow-clip">
            { children... }
        </body>
    </html>
}

Home Page

The home page includes:

A header with the app title
A request form component that triggers the POST request /generate to the backend
A container for displaying generated images

// internal/templs/pages/home.templ

package pages

import "gen-img/internal/templs/layouts"
import "gen-img/internal/templs/components"

templ Home() {
    @layouts.BaseLayout("gen-img") {
        <main class="flex flex-col h-full gap-8 p-8">
            // Title 
            <header class="flex flex-col justify-center text-2xl font-bold">
                gen-img
            </header>

            <div class="flex flex-row h-full justify-between gap-8">

                <div class="flex flex-row gap-2">
                    // Request Form
                    @components.RequestForm()

                    // Divider
                    <div class="divider divider-horizontal">👉</div>
                </div>

                // Image List Container
                // Its child will be replaced by a image list after the request is finished
                <div id="image-list-container" class="overflow-y-auto h-full">
                </div>
            </div>
        </main>
    }
}

Note we assigned the ID image-list-container to the container element. In the request form component, the hx-target attribute is set to #image-list-container. This means that when the form is submitted, the response will automatically replace the content inside the image-list-container element. Thanks to HTMX, this results in a seamless update of the container without requiring a full page reload.

Request Form Component

The request form component handles user input and HTMX interactions:

// internal/templs/components/request_form.templ

package components

import "gen-img/pkg/genimg"

templ RequestForm() {

    <fieldset class="fieldset w-xs bg-base-200 border border-base-300 p-4 rounded-box">
        <legend class="fieldset-legend">RequestForm</legend>

        <form
            hx-post="/generate"
            hx-target="#image-list-container"
            hx-swap="innerHTML" 
            hx-on="htmx:beforeRequest: this.setAttribute('data-loading', 'true')
                htmx:afterRequest: this.removeAttribute('data-loading')"
        class="flex flex-col gap-4 group"
    >
        // API Endpoint
        <label class="fieldset-label">Endpoint</label>
        <label class="input validator">
            <svg class="h-[1em] opacity-50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><g stroke-linejoin="round" stroke-linecap="round" stroke-width="2.5" fill="none" stroke="currentColor"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></g></svg>
            <input type="url" required placeholder="https://" name="endpoint" value={ genimg.OpenaiImagesApiEndpoint } pattern="^(https?://)?([a-zA-Z0-9]([a-zA-Z0-9\-].*[a-zA-Z0-9])?\.)+[a-zA-Z].*$" title="Must be valid URL"  />
        </label>

        // Prompt
        <label class="fieldset-label">Prompt</label>
        <textarea
            name="prompt" 
            placeholder="Enter your prompt..."
            class="textarea"
        />

        // Image Size
        // Either square 1024x1024 or landscape 1792x1024
        <label class="fieldset-label">Image Size</label>
        <div class=" flex flex-row gap-4">
            <div class="flex flex-row gap-2 items-center">
                <input type="radio" name="imageSize" class="radio-sm" value={ genimg.ImageSizeLandscape } checked />
                <label for="landscape">Landscape</label>
            </div>

            <div class="flex flex-row gap-2 items-center">
                <input type="radio" name="imageSize" class="radio-sm" value={ genimg.ImageSizeSquare } />
                <label for="square">Square</label>
            </div>
        </div>


        // Number of Images
        <label class="fieldset-label">Number of Images</label>
        <input 
            type="number"
            required placeholder="Type a number between 1 to 50" 
            name="numImages" 
            value="1"
            min="1" 
            max="50" 
            title="Must be between be 1 to 50" 
            class="input validator" 
        />

        // Submit Button
        <button 
            type="submit"
            class="btn btn-neutral"
        >
            <span class="animate-spin size-6 group-data-[loading=true]:flex hidden" aria-hidden="true">
                <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M21 12a9 9 0 1 1-6.219-8.56"></path></svg>
            </span>
            Generate
        </button>
    </form>
    </fieldset>
}

Image List Component

The image list component displays the generated images:

// internal/templs/components/image_list.templ

package components

templ ImageList(images []string) {
    <div class="image-list sm:grid flex flex-col md:grid-cols-3 sm:grid-cols-2 lg:grid-cols-4 gap-4">
        for _, image := range(images) {
            <img src={ image }/>
        }
    </div>
}

How to Run

Clone the repository and go to the project directory:

git clone https://github.com/Isaac-Fate/gen-img.git
cd gen-img

Install the dependencies:

go mod download

Create a .env file and add your OpenAI API key:

cp .env.example .env

Fill in the .env file with your OpenAI API key.

Run the application:

go run cmd/web/main.go

Since this ptoject uses Gin framework, you may run it in the realse mode setting the GIN_MODE environment variable to release:

GIN_MODE=release go run cmd/web/main.go

Also, you may also change the default port (8080) by setting the PORT environment variable:

PORT=8081 go run cmd/web/main.go

Visit http://localhost:8080 (or the port you set) in your browser.

A Simple Like System for a Static Blog

Isaac FEI — Fri, 20 Mar 2026 11:30:36 +0000

I noticed my blog gets many daily visitors but very few comments. Maybe readers don't even notice the discussion section at the bottom. Or perhaps it's the friction: Giscus requires GitHub login, and writing a comment takes effort. I wanted a simpler way to get some reactions—a one-click signal that says "I liked this" without accounts or typing.

A like button fits that bill. The system itself is straightforward: one like per visitor per article, stored in a database. The catch: I needed a backend, and I didn't want to spin up a separate project just for this small feature. That's when I remembered I already run a playground project with TanStack Start—a full-stack app on Cloudflare Workers. I could add the like API there.

This post covers the motivation, design choices, and implementation. I use TanStack Start + Neon Postgres because that's what I have; you can use any tech stack. The ideas translate.

Try the button below. It's wired to the real API for this post.

Interactive or embedded content omitted — see the original post: https://isaacfei.com/posts/simple-like-system

Motivation

A static blog is fast and cheap to host, but it often feels one-sided—readers consume, there's little feedback. I wanted a lightweight way for readers to signal appreciation without signing up: anonymous, low stakes (likes don't change content), and resilient enough to work when IP headers are missing (local dev, some proxies).

The goal isn't to prevent all abuse; it's to make casual duplicate-liking annoying enough that most people won't bother, while keeping the experience smooth for everyone else.

The Idea

A floating bar at the bottom of each post: a heart button with a count, plus a shortcut to jump to the comment section. One like per visitor per article. The tricky part: who is a visitor? Without accounts, we need a stable, privacy-preserving identifier.

Design

Visitor Identification

This is the core of the implementation. The system must answer: is this request from (approximately) the same person who liked before? Without that, we can't enforce one like per visitor per article. We have no accounts—only two fallible signals: a client-stored UUID and the request's IP.

Two-tier design. We try the UUID first; if it's absent or invalid, we fall back to IP. Both get hashed before storage, so the DB only ever sees visitor_hash. The key is that the same identifier must always map to the same hash, so repeated requests from the same visitor hit the same row.

Source 1: localStorage UUID. The frontend generates a UUID on first visit, stores it in localStorage, and sends it as X-Likes-Visitor-Id. Same browser, same device → same UUID across requests. Works when IP headers are missing (local dev, some proxies). User-controlled: clearing storage = fresh identity. No fingerprinting.

Source 2: IP fallback. When the header is absent (e.g. localStorage disabled, private mode) or invalid (spoofed), we use the client IP from X-Forwarded-For, CF-Connecting-IP, or similar. The server always has this on real requests. Same IP behind the same NAT → same identifier. IP changes (mobile network, VPN, DHCP) mean the system may treat the same person as "new"—acceptable for a lightweight like system.

Scenario	Identifier used	Result
Normal browser	UUID in header	Same visitor across requests
Private mode (no localStorage)	IP fallback	Same visitor if same IP
Dev/proxy (no IP headers)	UUID	Works when UUID present
All failed (no header, no IP)	—	`400 missing_visitor_id`

Impersonation guard. The visitor ID must be a valid UUID. If the header contains anything else (e.g. someone trying to inject an IP), we ignore it and fall back to the real IP. Prevents one visitor from spoofing another's identity.

Priority	Source	When used
1	`X-Likes-Visitor-Id` (UUID from localStorage)	Header present and valid
2	Client IP from request headers	No header, invalid header, or header spoofed

Hashing & Privacy

Raw IPs and visitor IDs are never stored. Before any DB write, we hash the identifier:

visitor_hash = SHA-256(salt + ":" + identifier)

Salt — From LIKE_SYSTEM_SALT env var. Rotate if compromised.
Output — 64-char hex string. One-way; we can't recover the original.

The article_likes table stores (slug, visitor_hash) with a unique constraint on (slug, visitor_hash)—one like per visitor per article.

Architecture

Frontend: Astro + React. FloatingReactionBar sits at the bottom of each post. Backend: TanStack Start on Cloudflare Workers, CORS configured for the blog domain. Database: Neon Postgres via Drizzle ORM.

API Contract

Method	Endpoint	Headers	Response
GET	`/api/likes/:slug`	`X-Likes-Visitor-Id` (optional)	`{ count, liked }`
POST	`/api/likes/:slug`	`X-Likes-Visitor-Id` (optional)	`{ count, liked }`

Both require a visitor identifier (header or IP). If neither is available, the API returns 400 missing_visitor_id.

CORS

Blog and API live on different origins—the browser blocks cross-origin fetch unless the API returns CORS headers. Allow your frontend domain(s) in Access-Control-Allow-Origin, not mine. Custom headers (Content-Type, X-Likes-Visitor-Id) trigger a preflight OPTIONS; respond with 2xx plus Allow-Headers, Allow-Methods, and optionally Max-Age. My config: allowlist isaacfei.com, isaac-fei.com, localhost; reflect origin when matched.

Implementation

With the design in place, here's how to build it—from database to frontend.

Database Schema

// article_likes table
{
  slug: text,
  visitor_hash: text,  // SHA-256(salt + identifier)
  created_at: timestamptz
}
// UNIQUE(slug, visitor_hash)

One row per (article, visitor). Unlike = delete row.

Visitor ID (Frontend)

// src/lib/likes-visitor-id.ts
const STORAGE_KEY = "likes-visitor-id";

export function getOrCreateLikesVisitorId(): string {
  if (typeof window === "undefined") return "";
  try {
    let id = localStorage.getItem(STORAGE_KEY);
    if (!id) {
      id = crypto.randomUUID();
      localStorage.setItem(STORAGE_KEY, id);
    }
    return id;
  } catch {
    return "";
  }
}

Send it as X-Likes-Visitor-Id on every GET and POST.

Visitor Resolution (Backend)

// Prefer valid UUID from header, else IP
function getVisitorIdentifier(request: Request): string | null {
  const raw = request.headers.get("X-Likes-Visitor-Id")?.trim();
  if (raw && isValidLikesVisitorId(raw)) return raw;
  return getClientIp(request);
}

Validate the UUID format before trusting it.

Hashing

async function hashVisitorIdentifier(identifier: string, salt: string): Promise<string> {
  const input = `${salt}:${identifier}`;
  const data = new TextEncoder().encode(input);
  const hash = await crypto.subtle.digest("SHA-256", data);
  return Array.from(new Uint8Array(hash))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

Toggle Like Logic

A POST toggles like/unlike: if the visitor has already liked, we remove the row (unlike); otherwise we insert (like). The DB enforces one row per (slug, visitor_hash), so the flow is simply: check existence → delete or insert → return updated count and liked state.

Step	Action	Meaning
1	Get identifier	Visitor ID or IP (see Visitor Identification)
2	Hash with salt	`visitor_hash`; same identifier → same hash
3	Check if row exists	`SELECT` where `slug` + `visitor_hash` match
4a	Row exists	User already liked → `DELETE` (unlike)
4b	Row absent	User hasn't liked → `INSERT` (like)
5	Return	`{ count, liked }` for the article

Environment Variables

Variable	Required	Description
`DATABASE_URL`	Yes	Neon Postgres connection string
`LIKE_SYSTEM_SALT`	Yes	32+ char random string for hashing

UI: Fetch, Optimistic Updates, and Shared State

The frontend calls the API on mount and on like, then renders the result. Two approaches—simple and TanStack Query—each with different trade-offs.

Simple Approach

When you have a single like component, a straightforward implementation suffices. On mount, fetch the GET endpoint and store count and liked in state; on click, POST and update optimistically.

Optimistic updates make the UI feel instant: flip the heart and adjust the count immediately, before the server responds. If the request fails, revert in the catch block. The alternative (wait for the round-trip) feels laggy; users expect likes to register at once.

Guarding against rapid clicks matters: a double-tap can fire two POSTs before the first finishes. Use a posting (or inFlight) boolean: set it to true when the request starts, false when it completes. Ignore clicks with if (posting) return, or disable the button. An AbortController can cancel an in-flight request if the user clicks again—optional but useful.

Error handling: show a toast on failure, auto-dismiss after a few seconds. Add select-none on the button to avoid accidental text selection when tapping. This approach works well as long as you have only one like component on the page. Once you add a second (e.g. a demo in the content and a floating bar), you run into sync problems.

TanStack Query (Bonus)

When two or more components display the same like state—e.g. a demo button mid-article and a floating bar at the bottom—three problems appear:

Stale data. Each component fetches independently. User likes via component A; component B still shows the old count until it refetches. Without coordination, the UI is inconsistent.
Mutation signaling. When component A successfully POSTs, how does component B know to refetch? You could dispatch a custom event, lift state, or poll—each adds glue code and complexity.
Shared server state. Both components display the same logical data. They need a single source of truth, not separate copies that can drift.

TanStack Query addresses all three. A shared cache key per (slug, apiBaseUrl) gives you a single source of truth: both components useQuery with the same key and read from the same cache. Mutations use useMutation; on success, setQueryData updates the cache, and every component subscribed to that query re-renders automatically. Optimistic updates go in onMutate; rollback in onError using the previous cache value. No events, no manual refetch signals—the cache is the coordination layer.

Astro islands caveat. Each client:load component is its own React root. A single QueryClientProvider in the layout does not wrap them; React context does not cross roots. The fix: use a shared QueryClient instance—a module-level singleton created once when the first island loads. Each island wraps itself with QueryClientProvider and passes that shared client. They remain separate roots but share the same cache.

Pagination with Shadcn

Isaac FEI — Fri, 20 Mar 2026 11:30:19 +0000

First, you should get familiar with pagination components (e.g., Pagination, PaginationItem, PaginationLink, ...) provided by Shadcn.

Play around with the following pagination bar, and think about how to make it with Shadcn 🤔.

Interactive or embedded content omitted — see the original post: https://isaacfei.com/posts/pagination-with-shadcn

The total number of pagination items is always 7 (including the ellipisis items but excluding the previous and next pagination items). This is to ensure that the pagination bar has a fixed width.

At a first glance, the pagination bar has 3 different UI displays (considering the number of positions of the ellipsis items):

Leading 7 items followed by an ellipsis and the last pagination item. e.g., 1, 2, 3, 4, 5, ..., 100. This happens when the active page number is less than 5.
The active pagination item is at the center surrounded by 2 consecutive pagination items. And the the bar starts with the first item followed by an ellipsis and ends with an ellipsis followed by the last pagination item. e.g., 1, ..., 9, 10, 11, ..., 100 where 10 is the active apge. This happens when the active page number is greater than or equal to 5 and less than n-3 where n is the last page number.
Trailing 7 items preceded by an ellipsis and the first pagination item. e.g., 1, ..., 96, 97, 98, 99, 100. This happens when the active page number is greater than or equal to n-3.

Wait, what if the number of pages is less than or equal to 7? Then there is no need to display any ellipsis items. But how to make sure the width of the bar stays the same?

Yes, there is a fourth case, which I call the enumerated pagination items. And the empty item slots are filled with placeholder items, which are also PaginationItem components to maintain consistent width.

Enumerated pagination items. e.g., 1, 2, 3, placeholder, placeholder, placeholder, placeholder.

Interact with the following examples:

Interactive or embedded content omitted — see the original post: https://isaacfei.com/posts/pagination-with-shadcn

Implementation

The following code snippets are the simplified ones from my actual implementations.
They only illustrate the essential ideas.
You may add more features as you like.

Properties of PaginationBar:

interface PaginationBarProps {
  className?: string;
  numPages: number;
  activePageNumber: number;
  pageNumberToLink?: (pageNumber: number) => string;
}

Build the pagination link:

function buildPaginationLink(props: PaginationBarProps, pageNumber: number) {
  // Check whether this is the active page
  const isActive = pageNumber === props.activePageNumber;

  return (
    <PaginationLink
      className={cn("", {
        // Color of the active page
        "text-accent-foreground": isActive,
      })}
      href={props.pageNumberToLink?.(pageNumber) ?? ""}
      isActive={isActive}
    >
      {pageNumber}
    </PaginationLink>
  );
}

Build leading pagination items with an ellipsis followed by the last pagination item:

function buildLeadingPaginationItems(props: PaginationBarProps) {
  return (
    <>
      {/* Leading pagination items */}
      {[1, 2, 3, 4, 5].map((pageNumber, index) => {
        return (
          <PaginationItem key={index + 1}>
            {buildPaginationLink(props, pageNumber)}
          </PaginationItem>
        );
      })}

      {/* Ellipsis */}
      <PaginationItem key={6}>
        <PaginationEllipsis />
      </PaginationItem>

      {/* Last pagination item */}
      <PaginationItem key={7}>
        {buildPaginationLink(props, props.numPages)}
      </PaginationItem>
    </>
  );
}

Since we know there are always 7 pagination items, the key property for each item can simply be one of 1~7.

Secret Value Manager in Go

Isaac FEI — Fri, 20 Mar 2026 11:30:09 +0000

Core Components

The encryption system consists of three main components:

Passphrase management (digesting and verification)
Secret encryption
Secret decryption

Passphrase Management

The master passphrase is never stored directly. Instead, we store a digest created using PBKDF2:

// Constants for cryptographic operations
const saltLength int = 32        // Length of salt in bytes for key derivation
const secretKeyLength int = 32   // Length of derived key (256 bits for AES-256)
const separator string = "-"     // Separator for components in stored values

func DigestPassphrase(passphrase string) string {
    // Derive a key and get a salt (nil means generate new salt)
    key, salt := deriveKey(passphrase, nil)

    // Store as: <derived_key>-<salt>
    // Both components are hex-encoded for safe storage
    digestedPassphrase := strings.Join(
        []string{hex.EncodeToString(key), hex.EncodeToString(salt)},
        separator,
    )
    return digestedPassphrase
}

The key derivation function uses PBKDF2 with these specific parameters:

SHA-256 as the hash function
100,000 iterations
32-byte output key
32-byte random salt

func deriveKey(passphrase string, salt []byte) ([]byte, []byte) {
    // Generate a random salt if none provided
    if salt == nil {
        salt = make([]byte, saltLength)
        // Use crypto/rand for cryptographically secure random numbers
        rand.Read(salt)
    }

    // Use PBKDF2 to derive a key from the passphrase
    // - passphrase: the input secret
    // - salt: prevents rainbow table attacks
    // - 100000: iteration count for computational cost
    // - secretKeyLength: final key length (32 bytes = 256 bits)
    // - sha256.New: use SHA-256 as the hash function
    key := pbkdf2.Key(
        []byte(passphrase),
        salt,
        100000,
        secretKeyLength,
        sha256.New,
    )
    return key, salt
}

When verifying a passphrase, we:

Split the stored digest to get the original key and salt
Derive a new key using the same salt
Compare the keys

func VerifyPassphrase(passphrase string, digestedPassphrase string) bool {
    // Split stored value into key and salt components
    parts := strings.Split(digestedPassphrase, separator)
    if len(parts) != 2 {
        return false // Invalid format, verification fails
    }

    // Extract the stored key and salt
    groundTruthKey := parts[0]  // The original derived key
    salt, _ := hex.DecodeString(parts[1])  // Decode stored salt from hex

    // Derive a new key using the same salt and passphrase
    key, _ := deriveKey(passphrase, salt)
    // Compare the newly derived key with the stored one
    return hex.EncodeToString(key) == groundTruthKey
}

Secret Encryption

Each secret is encrypted using AES-GCM. The encrypted value format is:
<ciphertext>-<salt>-<iv>

const ivLength int = 12  // 12 bytes is optimal for GCM mode (96 bits)

func Encrypt(passphrase string, value string) (string, error) {
    // For each encryption:
    // 1. Generate a new key using a fresh salt
    // 2. Generate a new IV (nonce) for GCM mode
    key, salt := deriveKey(passphrase, nil)
    iv := make([]byte, ivLength)
    rand.Read(iv)  // Cryptographically secure random IV

    // Create AES cipher in GCM mode:
    // 1. Create AES cipher with our derived key
    // 2. Wrap it in GCM mode for authenticated encryption
    blockCipher, _ := aes.NewCipher(key)
    gcmCipher, _ := cipher.NewGCM(blockCipher)

    // Encrypt and authenticate in one step
    // - nil: no additional authenticated data
    // - iv: nonce for GCM mode
    // - value: the secret to encrypt
    ciphertext := gcmCipher.Seal(nil, iv, []byte(value), nil)

    // Store as: <ciphertext>-<salt>-<iv>
    // All components are hex-encoded for safe storage
    encryptedValue := strings.Join(
        []string{
            hex.EncodeToString(ciphertext),
            hex.EncodeToString(salt),
            hex.EncodeToString(iv),
        },
        separator,
    )
    return encryptedValue, nil
}

Important aspects of the encryption:

Each secret gets a unique salt for key derivation
Each encryption uses a random 12-byte IV
GCM mode provides authenticated encryption
All components are hex-encoded for safe storage

Secret Decryption

To decrypt a secret, we:

Split the encrypted value into its components
Decode from hex
Derive the same key using the stored salt
Decrypt and verify using AES-GCM

func Decrypt(passphrase string, encryptedValue string) (string, error) {
    // Split stored value into its three components
    // Format: <ciphertext>-<salt>-<iv>
    parts := strings.Split(encryptedValue, separator)
    if len(parts) != 3 {
        return "", errors.New("invalid encrypted value format")
    }

    // Decode all components from their hex representation
    ciphertext, _ := hex.DecodeString(parts[0])  // The encrypted secret
    salt, _ := hex.DecodeString(parts[1])        // Salt used for key derivation
    iv, _ := hex.DecodeString(parts[2])          // IV used for encryption

    // Derive the same key using the stored salt
    // This will give us the same key used for encryption
    key, _ := deriveKey(passphrase, salt)

    // Set up decryption:
    // 1. Create AES cipher with the derived key
    // 2. Wrap in GCM mode for authenticated decryption
    blockCipher, _ := aes.NewCipher(key)
    gcmCipher, _ := cipher.NewGCM(blockCipher)

    // Decrypt and verify authenticity in one step
    // If authentication fails, returns an error
    decryptedValue, err := gcmCipher.Open(nil, iv, ciphertext, nil)
    if err != nil {
        return "", err
    }

    return string(decryptedValue), nil
}

Security Properties

This implementation provides:

Key Security
- Unique key for each secret (different salts)
- High-cost key derivation (100,000 iterations)
- No plaintext passphrase storage
Encryption Security
- Authenticated encryption (GCM mode)
- No IV reuse (random generation)
- No padding attacks (GCM is streamlike)
Storage Security
- Safe encoding (hex)
- Clear component separation
- Integrity protection

References

A Simple Next.js File Server

Isaac FEI — Fri, 20 Mar 2026 11:29:54 +0000

Introduction

The complete project repository is available here.

We will be building a simple file server that functions as a web-based file explorer for a specified directory FILE_STORAGE_ROOT_DIR on your server. The key features include:

File Browsing: View files and directories under a given path (of course, it should be under FILE_STORAGE_ROOT_DIR)
File Downloading: Pick and download the files from the server as needed
API Key Authentication: Simple but effective protection

Why I Built This

I am running several microservices on a remote server that continuously generate data and files.
At some point in my life, I need to download these outputs for data analysis
or machine learning projects - whether it's processing logs, training models, or just examining results.

While many file storage and management solutions like Nginx exist,
I always prefer crafting my own tools 💪🛠️.

App Screenshots

Auth page:

File storage page:

After clicking the logs directory, the page will list all the files and directories under the logs directory:

Clicking the abc.log file will download the file.

Setup

Next.js 15 (App Router)
shadcn/ui
pnpm

Project Structure

Other unimportant files are omitted.

file-server-nextjs/
├── src/                              # Primary source code
│   ├── app/                          # Next.js app router
│   │   ├── api/
│   │   │   ├── files/route.ts        # GET /api/files
│   │   │   └── download/[...pathSegments]/route.ts  # Dynamic download endpoint
│   │   ├── storage/[[...pathSegments]]/page.tsx  # File browser UI
│   │   ├── auth/page.tsx             # Authentication page
│   │   └── layout.tsx                # Root layout
│   │
│   ├── components/
│   │   ├── ui/                       # Shadcn UI components
│   │   ├── file-system-entry-view.tsx  # File system entry view
│   │   ├── api-key-input.tsx         # API key input
│   │   └── sign-in-form-data.ts      # Auth form schema
│   │
│   ├── models/                       # Data models
│   │   ├── file-system-entry.ts      # File/directory model
│   │   └── sign-in-form-data.ts      # Auth form schema
│   │
│   └── lib/                          # Business logic
│       ├── services/                  
│       │   ├── list-directory.ts     # Filesystem operations
│       │   └── index.ts              # Service exports
│       ├── auth.ts                   # Authentication logic
│       └── utils.ts                  # Shared utilities
│
├── middleware.ts                     # Edge middleware
├── Dockerfile                        # Production build
├── .dockerignore
├── docker-compose.example.yml        # Example config
├── docker-compose.yml                # Local dev config
├── .env.example                      # Env template
├── .env.local                        # Local development
├── .env.production                   # Production env
├── next.config.ts                    # Next.js config
└── package.json

File Server API

List Files & Directories

First, we define the structure for file/directory entries using Zod:

// src/models/file-system-entry.ts

import { z } from "zod";

export const FileSystemEntrySchema = z.object({
  name: z.string(),
  path: z.string(),
  isDirectory: z.boolean(),
});

export type FileSystemEntry = z.infer<typeof FileSystemEntrySchema>;

This schema ensures each entry contains:

name: File/directory name
path: Relative path from root
isDirectory: Boolean flag for type checking

The business logic is encapsulated in a reusable service.
We will use it both in the API route and the server component src/app/storage/[[...pathSegments]]/page.tsx.

// src/lib/services/list-directory.ts

import type { FileSystemEntry } from "@/models/file-system-entry";
import fs from "fs";
import path from "path";

export async function listDirectory(relativeDirectoryPath: string) {
  // Construct an absolute directory path
  const directoryPath = path.join(
    process.env.FILE_STORAGE_ROOT_DIR!,
    relativeDirectoryPath,
  );

  // Names of the files and directories
  const names = fs.readdirSync(directoryPath);

  const fileSystemEntries: FileSystemEntry[] = names.map((name) => {
    const stats = fs.statSync(path.join(directoryPath, name));
    return {
      name,
      path: path.join(relativeDirectoryPath, name),
      isDirectory: stats.isDirectory(),
    };
  });

  return fileSystemEntries;
}

The following is the implmentation fo the API route.
It is a GET request that takes a path query parameter and returns a list of FileSystemEntry.

In Next.js, we can get the query parameter from the request object like this: request?.nextUrl?.searchParams.get("key").

// src/app/api/files/route.ts

import { NextRequest, NextResponse } from "next/server";
import { listDirectory } from "@/lib/services/list-directory";

export async function GET(request: NextRequest) {
  // Get the path from the query parameters
  const relativeDirectoryPath =
    request?.nextUrl?.searchParams.get("path") || "";

  // Get the file system entries
  const fileSystemEntries = await listDirectory(relativeDirectoryPath);

  return NextResponse.json(fileSystemEntries);
}

Download a File

The simplest way to stream files in Next.js is using Node.js's native readableWebStream() method (official documentation).

// src/app/api/download/[...pathSegments]/route.ts

import { NextRequest, NextResponse } from "next/server";
import fs from "fs";
import path from "path";

export async function GET(
  request: NextRequest,
  {
    params,
  }: {
    params: Promise<{
      pathSegments: string[];
    }>;
  },
) {
  const { pathSegments } = await params;

  // Get file path
  const filePath = path.join(
    process.env.FILE_STORAGE_ROOT_DIR!,
    ...pathSegments,
  );

  // Open the file
  const fileHandle = await fs.promises.open(filePath);

  // Create a readable stream that can be passed to NextResponse
  const stream = fileHandle.readableWebStream({
    type: "bytes",
  }) as ReadableStream<Uint8Array>;

  return new NextResponse(stream);
}

This API uses catch-all route ([...pathSegments]) to support nested directories.
You can get the path segments by defining the params in the function signature.

One more thing to note is that although we didn't use the parameter request here,
we still need to define it in the function signature!
Otherwise, the route handler will not be recognized by Next.js.

Althernative approaches of streaming files are available in the following awesome blog post: How to stream files from Next.js Route Handlers.

Build the UI for Browsing and Downloading Files

A component for displaying both files and directories with appropriate icons and interactions:

// src/app/components/file-system-entry-view.tsx

import type { FileSystemEntry } from "@/models/file-system-entry";
import { FileIcon, FolderIcon } from "lucide-react";

interface FileSystemEntryViewProps extends FileSystemEntry {}

export function FileSystemEntryView({
  name,
  path,
  isDirectory,
}: FileSystemEntryViewProps) {
  const href = isDirectory ? `/storage/${path}` : `/api/download/${path}`;
  const download = isDirectory ? undefined : name;
  const Icon = isDirectory ? FolderIcon : FileIcon;

  return (
    <a
      href={href}
      download={download}
      className="hover:bg-muted flex flex-row items-center justify-between gap-2 rounded-md p-2"
    >
      <div className="flex flex-row items-center gap-2">
        <Icon size={16} className="opacity-60" />
        <span className="line-clamp-1">{name}</span>
      </div>
    </a>
  );
}

If it is a directory, it will link to the storage page (implemented below) with the path segments added.
If it is a file, it will link to the download API route.

Note that I used an anchor tag <a> here instrad of Next.js's Link component.
This is because the Link component does not trigger the download of the file somehow 🤔.
Instead, it will display the file content in a browser tab.

The main storage page uses Next.js's catch-all route to handle nested directory paths:

The main page is grouped under storage (for the ease of middleware matcher later) with dynamic catch-all route [[...pathSegments]].

We will intentionally exclude a dedicated home page (/) to simplify our middleware's route matching logic.
By redirecting the root path directly to /storage, we maintain a single common entry point
for all file storage routes, which should be authenticated.

To do this, in next.config.ts, we can set the redirects option:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
+  redirects: async () => {
+    return [
+      {
+        source: "/",
+        destination: "/storage",
+        permanent: false,
+      },
+    ];
+  },
};

export default nextConfig;

File storage page:

// src/app/storage/[[...pathSegments]]/page.tsx

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { FileSystemEntryView } from "@/components/file-system-entry-view";
import { listDirectory } from "@/lib/services";

export default async function Page({
  params,
}: {
  params: Promise<{ pathSegments?: string[] }>;
}) {
  const pathSegments = (await params).pathSegments ?? [];
  const directoryPath = pathSegments.join("/");
  const fileSystemEntries = await listDirectory(directoryPath);

  return (
    <div className="flex h-full flex-col items-center justify-center p-8">
      <Card className="flex h-full max-h-[40rem] w-full max-w-[40rem] flex-col">
        <CardHeader>
          <CardTitle>File Server</CardTitle>
        </CardHeader>

        <CardContent className="flex h-full flex-col overflow-y-auto">
          {fileSystemEntries.map((fileSystemEntry, index) => (
            <FileSystemEntryView key={index} {...fileSystemEntry} />
          ))}
        </CardContent>
      </Card>
    </div>
  );
}

It is a server component that:

Uses [[...pathSegments]] to handle both root and nested paths
Empty path fallback for root directory
Renders the file system entries using the FileSystemEntryView component with the data obtained from the listDirectory service

Add API Key Authentication

I want to achieve the following:

API Protection
- All API endpoints (/api/files, /api/download) require:
```
Authorization: Bearer <API_KEY>
```
UI Protection
- Middleware redirects unauthenticated users to /auth
- Valid JWT in cookies grants access for a certain period of time, say 8 hours

JWT

We use JWTs in this project to maintain user sessions without requiring repeated API key entry. When users first authenticate with their API key, we generate a time-limited JWT and store it in a cookie. This approach provides the following benefits:

users stay logged in across page visits,
the server can validate sessions without storing sensitive API keys.

The package I chose to handle the JWT generation and decryption is jose instead of jsonwebtoken since the former also works in the Edge runtime.

// src/lib/auth/route.ts

import * as jose from "jose";

export async function createAuthToken() {
  // Encode the JWT secret
  const secret = new TextEncoder().encode(process.env.JWT_SECRET!);

  // Create a JWT token
  const authToken = await new jose.EncryptJWT({
    authorized: true,
  })
    .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
    .setIssuedAt()
    .setExpirationTime(process.env.JWT_EXPIRATION_TIME!)
    .encrypt(secret);

  return authToken;
}

export async function decryptAuthToken(authToken: string) {
  // Encode the JWT secret
  const secret = new TextEncoder().encode(process.env.JWT_SECRET!);

  // Decrypt the auth token
  const { payload } = await jose.jwtDecrypt(authToken, secret, {
    contentEncryptionAlgorithms: ["A256GCM"],
    keyManagementAlgorithms: ["dir"],
  });

  return payload;
}

Note that, in the above implementation, we are actually generating a encrypted JWT.

If the payload does not contain any sensitive information, we can use a plain JWT instead by using jose.SignJWT and jose.jwtVerify.
(In this case, the JWT can be decoded by everyone. It is ok for this project since the payload is just a simple object {authorized: true}.)

Auth API

The logic of the auth API is straightforward.

Verify the API key
Generate a JWT and store it in the cookie

In Next.js we can use the funciton cookies from next/headers to get and set cookies.

// src/app/api/auth/sign-in/route.ts

import { NextRequest, NextResponse } from "next/server";
import { SignInFormDataSchema } from "@/models/sign-in-form-data";
import { cookies } from "next/headers";
import { createAuthToken } from "@/lib/auth";

export async function POST(request: NextRequest) {
  // Parse the request data
  const signInFormData = SignInFormDataSchema.parse(await request.json());

  // Get the API key
  const apiKey = signInFormData.apiKey;

  if (apiKey !== process.env.API_KEY!) {
    return NextResponse.json({ error: "invalid API key" }, { status: 400 });
  }

  // Create a JWT token
  const authToken = await createAuthToken();

  // Put the token into the cookie
  const cookieStore = await cookies();
  cookieStore.set("auth-token", authToken);

  return NextResponse.json({
    authToken,
  });
}

Build the UI: API Key Input, Sign-In Form and Auth Page

When bulding the sign-in form, we follow the suggested steps from Shadcn's React Hook Form:

Define the form data schema (already done)
Use useForm to create the form instance
Use Form to wrap the <form> HTML element
Use FormField to wrap the form field UI (e.g., input, textarea, radio group, etc.)

The schema of the form data is simple, which is just an API key:

// src/models/sign-in-form-data.ts

import { z } from "zod";

export const SignInFormDataSchema = z.object({
  apiKey: z.string().min(1),
});

export type SignInFormData = z.infer<typeof SignInFormDataSchema>;

Next, we create an API key input component in the following.
It is modified from another awesome UI library Origin UI, which is built based on shadcn/ui.

// src/components/api-key-input.tsx

"use client";

import { useState } from "react";

import { Input } from "@/components/ui/input";
import { EyeIcon, EyeOffIcon, KeyRoundIcon } from "lucide-react";
import { cn } from "@/lib/utils";

export function ApiKeyInput(props: React.ComponentProps<"input">) {
  const [isVisible, setIsVisible] = useState<boolean>(false);

  const toggleVisibility = () => setIsVisible((prevState) => !prevState);

  const { className, ...restInputProps } = props;

  return (
    <div className="relative">
      <Input
        className={cn("ps-9 pe-9", className)}
        placeholder="API Key"
        type={isVisible ? "text" : "password"}
        {...restInputProps}
      />

      <div className="text-muted-foreground/80 pointer-events-none absolute inset-y-0 start-0 flex items-center justify-center ps-3 peer-disabled:opacity-50">
        <KeyRoundIcon size={16} />
      </div>

      <button
        className="text-muted-foreground/80 hover:text-foreground focus-visible:border-ring focus-visible:ring-ring/50 absolute inset-y-0 end-0 flex h-full w-9 items-center justify-center rounded-e-md transition-[color,box-shadow] outline-none focus:z-10 focus-visible:ring-[3px] disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50"
        type="button"
        onClick={toggleVisibility}
        aria-label={isVisible ? "Hide API key" : "Show API key"}
        aria-pressed={isVisible}
        aria-controls="apiKey"
      >
        {isVisible ? (
          <EyeOffIcon size={16} aria-hidden="true" />
        ) : (
          <EyeIcon size={16} aria-hidden="true" />
        )}
      </button>
    </div>
  );
}

Finally, the sign-in form:

// src/components/sign-in-form.tsx

"use client";

import {
  type SignInFormData,
  SignInFormDataSchema,
} from "@/models/sign-in-form-data";

import { LockIcon, LockOpenIcon } from "lucide-react";
import { Card, CardContent } from "@/components/ui/card";
import { Form, FormControl, FormField, FormItem } from "@/components/ui/form";
import { ApiKeyInput } from "@/components/api-key-input";
import { Button } from "@/components/ui/button";

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import axios from "axios";
import { useRouter } from "next/navigation";

export function SignInForm() {
  const form = useForm<SignInFormData>({
    resolver: zodResolver(SignInFormDataSchema),
    defaultValues: {
      apiKey: "",
    },
  });

  const router = useRouter();

  const submitFormData = async (formData: SignInFormData) => {
    // Clear the form
    form.reset();

    // Send the request
    try {
      // Send the request to sign in
      await axios.post("/api/auth/sign-in", formData);

      // Redirect to the home page
      router.push("/");
    } catch (e) {
      alert(e);
    }
  };

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(submitFormData)}>
        <Card>
          <CardContent className="flex flex-col items-center justify-center gap-6">
            <LockIcon className="text-muted-foreground size-24" />

            <div className="flex flex-col gap-4">
              <FormField
                name="apiKey"
                render={({ field }) => (
                  <FormItem>
                    <FormControl>
                      <ApiKeyInput {...field} />
                    </FormControl>
                  </FormItem>
                )}
              />

              <Button type="submit">
                <LockOpenIcon
                  className="-ms-1 opacity-60"
                  size={16}
                  aria-hidden="true"
                />
                Unlock
              </Button>
            </div>
          </CardContent>
        </Card>
      </form>
    </Form>
  );
}

The auth page is just a simple page that contains the SignInForm component.

// src/app/auth/page.tsx

import { SignInForm } from "@/components/sign-in-form";

export default function Page() {
  return (
    <div className="flex h-full flex-col items-center justify-center">
      <SignInForm />
    </div>
  );
}

Middleware

// src/middleware.ts

import { NextRequest, NextResponse } from "next/server";
import { cookies } from "next/headers";
import { decryptAuthToken } from "@/lib/auth";

export async function middleware(request: NextRequest) {
  // Get the auth header
  const authHeader = request.headers.get("authorization");

  if (authHeader !== null) {
    // Get the API key from the bearer token
    const apiKey = authHeader.replace("Bearer ", "");

    if (apiKey === process.env.API_KEY!) {
      return NextResponse.next();
    } else {
      return NextResponse.json({ error: "invalid API key" }, { status: 400 });
    }
  }

  // Get the cookies
  const cookieStore = await cookies();

  // Get the auth token
  const authToken = cookieStore.get("auth-token")?.value;

  if (authToken === undefined) {
    return NextResponse.redirect(new URL("/auth", request.url));
  }

  try {
    // Decrypt the auth token
    const { payload } = await decryptAuthToken(authToken);

    // We don't need to do anything with the payload though
  } catch (e) {
    console.error(`failed to verify the auth token: ${e}`);
    return NextResponse.redirect(new URL("/auth", request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/storage/:path*", "/api/((?!auth\\b).*)"],
};

This middleware handles authentication for protected routes using two distinct methods:

The middleware activates for:

All paths beginning with /storage/ (using the :path* wildcard to match nested paths)
All API endpoints except /api/auth (using the regex (?!auth\\b) to exclude the auth route specifically)

The authentication process is as follows:

API Key Verification
- The middleware first checks for an Authorization header
- If present, it validates the API key against your environment variable
- Valid keys proceed to the route handler
- Invalid keys receive a 400 error response
Session Cookie Fallback
- When no API key is provided, the middleware checks for an auth-token cookie
- Missing tokens trigger an immediate redirect to the authentication page
- Existing tokens are decrypted and validated
- Failed validation also redirects to the auth page

Flow diagram:

Request → [Has API Key?] → Yes → [Valid?] → Yes → Proceed
                     ↓ No
                     [Has Auth Token?] → No → Redirect to /auth
                     ↓ Yes
                     [Valid Token?] → No → Redirect to /auth
                     ↓ Yes
                     Proceed

Dockerize the app

To containerize this app, copy Next.js's official Dockerfile into the project root.
No modifications are needed.
But ensure next.config.ts enables output: "standalone" for optimized deployment, alongside your existing redirect rules.

// next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
+  output: "standalone",
  redirects: async () => {
    return [
      {
        source: "/",
        destination: "/storage",
        permanent: false,
      },
    ];
  },
};

export default nextConfig;

Environment Variables

We have seen from previous code snippets,
this application requires several environment variables for authentication, security, and file storage configuration.
Below is an example .env.example file, which serves as a template for setting up your environment:

# .env.example

# API key for accessing the file server
API_KEY=

# 256-bit JWT encryption key
JWT_SECRET=

# JWT expiration time
JWT_EXPIRATION_TIME=8h

# File storage directory
FILE_STORAGE_ROOT_DIR=

For Development
Copy .env.example to .env.local and fill in test values.
Set the JWT_EXPIRATION_TIME to a shorter time, e.g., 1min for the ease of development.
Remember to ignore .env.local in .gitignore.
For Production
Create .env.production with real credentials.
Also remember to ignore .env.production in .gitignore.
Fill in the missing environment variables.
Ensure FILE_STORAGE_ROOT_DIR exists and has proper read/write permissions.

Write a Docker Compose File

The following is the example of the docker-compose.yml file:

// docker-compose.example.yml

version: "3.8"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - NODE_ENV=production
    env_file: .env.production
    ports:
      - ${HOST_PORT}:3000
    volumes:
      # Mount host file storage directory as read-only volume
      - ${HOST_FILE_STORAGE_DIR}:/app/file-storage:ro

The Docker image uses /app as its working directory (review the Dockerfile). Within this, /app/file-storage serves as the container's storage path - this directory is automatically created during container initialization and mounts to your designated host directory without requiring manual creation.

The ro flag ensures read-only access from the container for security.

Note from the Dockerfile that the project root inside the image is /app.
The virtual file storage directory will be designe as /app/file-storage. (file-storage needs not to be created beforehand. it will be mounted to the specified directory on the host machine.)

For production, copy the docker-compose.example.yml to docker-compose.yml and

Replace ${HOST_PORT} with your desired port (e.g., 8080).
Replace ${FILE_STORAGE_ROOT_DIR} with the path to the directory on the host machine.

Then, you may build the image and run the container on your local machine via command:

docker-compose up -d

Bonus: Multi-Platform Build

As I'm developing this project on my M2 Mac (which uses ARM64 architecture),
when I built my container locally, pushed to Docker Hub,
and then tried pulling and running it on my production server (which uses AMD64 architecture), I got those frustrating exec format error messages.
Of course this happened - the architectures were completely incompatible.

The solution is to build the image for both ARM64 and AMD64 architectures.

If you have never run a multi-platform build before, you need to create a builder instance first by running:

docker buildx create \
  --name multi-platform \
  --use \
  --platform linux/amd64,linux/arm64 \
  --driver docker-container

--name multi-platform
- Gives your builder a descriptive label (e.g., multi-platform).
- Helpful if you manage multiple builders (e.g., for different projects).
--use
- Immediately sets this builder as the default for all docker buildx operations.
- Without this, you’d need to manually specify the builder each time.
--platform linux/amd64,linux/arm64
- Specifies the platforms you want to build for.
--driver docker-container
- Uses an isolated container runtime (instead of your local Docker daemon).
- Enables QEMU emulation, allowing your machine to build ARM images on Intel hardware (and vice versa).

After that, you can build the image for both architectures by running:

docker buildx build -t isaacfei/file-server-nextjs:0.1.0 --platform linux/amd64,linux/arm64 --push .

-t isaacfei/file-server-nextjs:0.1.0
- Tag flag (names your image)
- Format: [username]/[repository]:[version]
- Example breaks down to:
- isaacfei = Your Docker Hub username
- file-server-nextjs = Repository name
- 0.1.0 = Semantic version tag
--platform linux/amd64,linux/arm64
- Builds two separate images in parallel:
- linux/amd64: For Intel/AMD processors (most cloud servers)
- linux/arm64: For Apple Silicon (M1/M2) and ARM servers
- Creates a manifest list that automatically serves the correct image
--push
- Immediately pushes both images + manifest to Docker Hub
- Without this, images only exist locally (useful for testing)
.
- The build context (where your Dockerfile lives)
- Docker includes all files in this directory by default

Installation

Build from Source

Clone the repository:

git clone https://github.com/Isaac-Fate/file-server-nextjs.git

Check out the specific tag:

git checkout v0.1.0

Set the environment variables in .env.production:

cp .env.example .env.production

Fill in the missing environment variables.

Create docker-compose.yml file:

cp docker-compose.example.yml docker-compose.yml

Fill in the host port and the host file storage directory you want to use.

Build the image and run the container:

docker-compose up -d

Use the Pre-Built Docker Image from Docker Hub

The pre-built Docker image isaacfei/file-server-nextjs:0.1.0 is available on Docker Hub. To use it:

Modify the docker-compose.yml:

Remove the build section
Add the image specification

# docker-compose.yml

version: "3.8"

services:
  app:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      args:
-        - NODE_ENV=production
+    image: isaacfei/file-server-nextjs:0.1.0

All other configurations remain unchanged.
Set the environment variables in .env.production and run docker-compose up -d as usual.

API Reference

Authentication

Include in headers:

Authorization: Bearer <API_KEY>

Endpoints

Method	Endpoint	Description
GET	`/api/files?path=<DIR>`	List directory contents
GET	`/api/download/<PATH>`	Download a file

List files and directories under a given subdirectory path:

GET /api/files?path=<DIRECTORY_PATH> HTTP/1.1
Host: <HOST_NAME>:<HOST_PORT>
Authorization: Bearer <API_KEY>

Download a file:

GET /api/download/<DIRECTORY_PATH>/<FILE_NAME> HTTP/1.1
Host: <HOST_NAME>:<HOST_PORT>
Authorization: Bearer <API_KEY>

Examples

Suppose that I am running the container on my local machine and the host name is localhost and the port is 3000.
And suppose that the tree view of my file storage root directory data is like this:

data/
├── hello.txt
└── logs/
    └── abc.log

To download the file hello.txt, I can send the following request:

GET /api/download/hello.txt HTTP/1.1
Host: localhost:3000
Authorization: Bearer <API_KEY>

To download the file logs/abc.log:

GET /api/download/logs/abc.log HTTP/1.1
Host: localhost:3000
Authorization: Bearer <API_KEY>

To list files and directories under data, I can send the following request:

GET /api/files HTTP/1.1
Host: localhost:3000
Authorization: Bearer <API_KEY>

GET /api/files?path=/ HTTP/1.1
Host: localhost:3000
Authorization: Bearer <API_KEY>

To list files and directories under the subdirectory logs:

GET /api/files?path=logs HTTP/1.1
Host: localhost:3000
Authorization: Bearer <API_KEY>

Building AI Apps with Go: A Practical Guide with LangChainGo and LangGraphGo

Isaac FEI — Fri, 20 Mar 2026 04:44:44 +0000

I've been experimenting with building AI-powered applications in Go using langchaingo and langgraphgo. This post is a brain dump of everything I learned — from the simplest LLM call to designing full agent and workflow systems. I'll walk through the code, share my mental model for choosing between agent-based and workflow-based designs, and leave you with quick-reference cheat sheets.

All demo code lives in my gotryai repository. A huge shout-out to the langgraphgo examples directory — it has 85+ examples covering everything from basic graphs to RAG pipelines, MCP agents, and multi-agent swarms. That's where I learned most of what I know about using langgraphgo, and it's the best place to go when you want to explore beyond what this post covers.

Calling an LLM

The absolute minimum. No agents, no tools — just send a prompt to an LLM and get a response.

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/joho/godotenv"
    "github.com/tmc/langchaingo/llms/openai"
)

func main() {
    godotenv.Load()

    llm, err := openai.New(
        openai.WithBaseURL("https://api.deepseek.com"),
        openai.WithToken(os.Getenv("DEEPSEEK_API_KEY")),
        openai.WithModel("deepseek-chat"),
    )
    if err != nil {
        panic(err)
    }

    ctx := context.Background()

    resp, err := llm.Call(ctx, "Who are you?")
    if err != nil {
        panic(err)
    }

    fmt.Println(resp)
}

A few things to note:

langchaingo uses the OpenAI-compatible interface. Since DeepSeek (and many other providers) expose an OpenAI-compatible API, you just swap the base URL and token. The openai.New(...) constructor is the universal entry point — don't be confused by the package name.
llm.Call(ctx, prompt) is the simplest invocation. One string in, one string out.
Environment variables are loaded from a .env file via godotenv. Keep your API keys out of source code.

Running this:

┌─────────────────────────────────────────────────────────────
│ LLM Response
└─────────────────────────────────────────────────────────────

你好！我是DeepSeek，由深度求索公司创造的AI助手！😊
...

One string in, one string out. This is the foundation. Everything else builds on top of this.

Structured Output

Sometimes you don't want free-form text — you want the LLM to return parseable JSON that matches a specific schema. This is useful when LLM output feeds directly into downstream code.

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "os"

    "github.com/invopop/jsonschema"
    "github.com/joho/godotenv"
    "github.com/tmc/langchaingo/llms/openai"
    "github.com/tmc/langchaingo/prompts"
)

func main() {
    godotenv.Load()

    reflector := jsonschema.Reflector{DoNotReference: true}
    schema := reflector.Reflect(&[]TodoItem{})

    b, _ := json.MarshalIndent(schema, "", "  ")
    schemaString := string(b)

    llm, err := openai.New(
        openai.WithBaseURL("https://api.deepseek.com"),
        openai.WithToken(os.Getenv("DEEPSEEK_API_KEY")),
        openai.WithModel("deepseek-chat"),
        openai.WithResponseFormat(openai.ResponseFormatJSON),
    )
    if err != nil {
        panic(err)
    }

    ctx := context.Background()

    promptTemplate := prompts.NewPromptTemplate(`{{.input}}
    You must return a JSON object that matches the following schema:
    {{ .schema }}
    `, []string{"input", "schema"})

    prompt, _ := promptTemplate.Format(map[string]any{
        "input":  "Need to buy a cup of coffee and then learn langchaingo package. After that, watch a movie if there is time.",
        "schema": schemaString,
    })

    resp, err := llm.Call(ctx, prompt)
    if err != nil {
        panic(err)
    }

    todoItems := []TodoItem{}
    json.Unmarshal([]byte(resp), &todoItems)

    for i, item := range todoItems {
        fmt.Printf("%d. %s (priority: %s)\n", i+1, item.Title, item.Priority)
    }
}

type TodoItem struct {
    Title       string           `json:"title"`
    Description string           `json:"description,omitempty"`
    Priority    TodoItemPriority `json:"priority" jsonschema:"enum=low,enum=normal,enum=high,default=normal"`
}

type TodoItemPriority string

const (
    TodoItemPriorityLow    TodoItemPriority = "low"
    TodoItemPriorityNormal TodoItemPriority = "normal"
    TodoItemPriorityHigh   TodoItemPriority = "high"
)

Running this produces structured, typed output:

┌─────────────────────────────────────────────────────────────
│ Structured output (Todo items)
└─────────────────────────────────────────────────────────────

  📋 Todo items:
    1. Buy a cup of coffee
       Purchase coffee to drink
       priority: high
    2. Learn langchaingo package
       Study the langchaingo programming package
       priority: normal
    3. Watch a movie
       Watch a movie if there is time available
       priority: low

The LLM returned valid JSON matching our schema, and we parsed it directly into Go structs. The key pieces:

openai.WithResponseFormat(openai.ResponseFormatJSON) — tells the LLM to respond in JSON mode.
JSON Schema in the prompt — use jsonschema.Reflector to generate a JSON Schema from your Go struct, then embed it in the prompt. The LLM uses this schema as a contract for its output format.
json.Unmarshal — parse the LLM response directly into your Go struct. If the schema and prompt are right, this just works.
jsonschema struct tags — use tags like jsonschema:"enum=low,enum=normal,enum=high" to constrain the LLM's output to valid values.

This pattern — "define a struct, reflect its schema, embed in prompt, parse the response" — is one you'll use constantly.

The `invopop/jsonschema` Package

The invopop/jsonschema package is quietly one of the most useful dependencies in this entire stack. It does one thing well: reflect a Go struct into a JSON Schema object. You'll reach for it in two places:

Structured output — embed the schema in a prompt so the LLM knows what JSON shape to produce (as shown above).
Tool input schemas — return the schema from ToolWithSchema.Schema() so the LLM knows what arguments a tool expects (covered in the next section).

The core API is two lines:

reflector := jsonschema.Reflector{DoNotReference: true}
schema := reflector.Reflect(&MyStruct{})

Reflect walks your struct's fields and builds a *jsonschema.Schema from the json tags (field names, omitempty) and jsonschema tags (constraints). The most useful jsonschema struct tags:

Tag	Effect	Example
`enum=a,enum=b,enum=c`	Restricts to allowed values	`jsonschema:"enum=low,enum=normal,enum=high"`
`default=x`	Sets a default value	`jsonschema:"default=normal"`
`description=...`	Adds a field description	`jsonschema:"description=Due date in ISO 8601"`

Two reflector options matter:

DoNotReference: true — inlines all types instead of using $ref. Useful for structured output prompts where you want the LLM to see the full schema in one shot.
ExpandedStruct: true — inlines the root struct's fields so the top-level schema is {"type":"object","properties":{...}} instead of {"$ref":"#/$defs/MyStruct"}. Required for tool schemas because LLM APIs expect type: "object" at the root.

You can also implement the jsonschema.JSONSchema() interface on custom types to control their schema representation — like FlexibleDate returning {"type":"string","format":"date-time"} instead of whatever the reflector would guess.

Invoking an Agent

An "agent" in langgraphgo is a loop: the LLM decides whether to respond or call a tool, tools execute, results go back to the LLM, repeat until done. Even without tools, the agent pattern gives you message-based conversation (instead of raw string in/out).

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/joho/godotenv"
    "github.com/smallnest/langgraphgo/prebuilt"
    "github.com/tmc/langchaingo/llms"
    "github.com/tmc/langchaingo/llms/openai"
    "github.com/tmc/langchaingo/tools"
)

func main() {
    godotenv.Load()

    llm, err := openai.New(
        openai.WithBaseURL("https://api.deepseek.com"),
        openai.WithToken(os.Getenv("DEEPSEEK_API_KEY")),
        openai.WithModel("deepseek-chat"),
    )
    if err != nil {
        panic(err)
    }

    inputTools := []tools.Tool{}

    runnable, err := prebuilt.CreateAgentMap(llm, inputTools, 10)
    if err != nil {
        panic(err)
    }

    ctx := context.Background()

    initialState := map[string]any{
        "messages": []llms.MessageContent{
            llms.TextParts(llms.ChatMessageTypeHuman, "Who are you?"),
        },
    }

    resp, err := runnable.Invoke(ctx, initialState)
    if err != nil {
        panic(err)
    }

    fmt.Printf("%+v\n", resp)
}

Output:

┌─────────────────────────────────────────────────────────────
│ Agent completed in 1 iteration(s)
└─────────────────────────────────────────────────────────────

▸ [1] Human
    Who are you?

▸ [2] AI
    你好！我是DeepSeek，由深度求索公司创造的AI助手！😊
    ...

With no tools and a single question, the agent completed in 1 iteration — it's essentially a raw LLM call wrapped in the agent protocol. Key differences from llm.Call():

prebuilt.CreateAgentMap(llm, tools, maxIterations) builds the agent loop. The third argument caps how many LLM↔tool round-trips can happen before it stops.
State is a map[string]any with a "messages" key holding the conversation as []llms.MessageContent. This is the standard state shape for the prebuilt agent.
runnable.Invoke(ctx, state) runs the agent loop and returns the final state (including all messages from the conversation).
Even with an empty tools slice, the agent still works — it just can't call any tools, so it behaves like a single LLM call wrapped in the agent protocol.

Defining a Simple Tool

Tools are how you give the LLM the ability to do things — query a database, call an API, roll dice, whatever. The simplest tool implements three methods: Name(), Description(), and Call().

type RollDiceTool struct{}

func (t *RollDiceTool) Name() string {
    return "roll_dice"
}

func (t *RollDiceTool) Description() string {
    return "Roll a 6-sided dice and return the result."
}

func (t *RollDiceTool) Call(ctx context.Context, input string) (string, error) {
    return strconv.Itoa(rand.Intn(6) + 1), nil
}

That's it. The tools.Tool interface is just those three methods. When you register this tool with an agent, the LLM sees its name and description, decides when to call it, and the agent framework routes the call to your Call() method.

To use it with an agent:

inputTools := []tools.Tool{&RollDiceTool{}}

runnable, err := prebuilt.CreateAgentMap(llm, inputTools, 10)
if err != nil {
    panic(err)
}

initialState := map[string]any{
    "messages": []llms.MessageContent{
        llms.TextParts(
            llms.ChatMessageTypeHuman,
            "Roll a dice for 3 times and tell me the result.",
        ),
    },
}

resp, err := runnable.Invoke(ctx, initialState)

Here's what happens when we ask the agent to roll 3 times:

┌─────────────────────────────────────────────────────────────
│ Agent completed in 2 iteration(s)
└─────────────────────────────────────────────────────────────

▸ [1] Human
    Roll a dice for 3 times and tell me the result.

▸ [2] AI
    I'll roll a dice for you 3 times and show you the results.
    → tool: roll_dice({"input": "First roll"})
    → tool: roll_dice({"input": "Second roll"})
    → tool: roll_dice({"input": "Third roll"})

▸ [3] Tool
    ← roll_dice: 3

▸ [4] Tool
    ← roll_dice: 6

▸ [5] Tool
    ← roll_dice: 5

▸ [6] AI
    Here are the results of rolling a 6-sided dice 3 times:

    1. First roll: **3**
    2. Second roll: **6**
    3. Third roll: **5**

Notice the agent loop: iteration 1 — the LLM decides to call roll_dice three times in parallel (messages 2–5); iteration 2 — the LLM sees all the tool results and produces a final answer (message 6). Two iterations total. Also notice the {"input": "First roll"} arguments — that's the default schema at work. The LLM sends {"input":"..."} and the framework extracts the string before passing it to Call().

When you don't implement ToolWithSchema, the framework generates a default schema: {"type":"object","properties":{"input":{"type":"string"}}}. This is fine for tools that take a single string (or no meaningful input at all, like our dice roller).

Tools with Custom Input Schema

Real-world tools often need structured input — not just a single string. For example, a "save todo items" tool needs an array of objects with titles, priorities, and due dates. This is where ToolWithSchema comes in.

The interface adds one method on top of tools.Tool:

type ToolWithSchema interface {
    tools.Tool
    Schema() map[string]any
}

Here's a full example — a tool that extracts and saves todo items from an email:

type SaveTodoItemsInput struct {
    TodoItems []TodoItem `json:"todo_items"`
}

type TodoItem struct {
    Title       string           `json:"title"`
    Description string           `json:"description,omitempty"`
    Priority    TodoItemPriority `json:"priority" jsonschema:"enum=low,enum=normal,enum=high,default=normal"`
    DueDate     *FlexibleDate    `json:"due_date,omitempty" jsonschema:"description=Due date (YYYY-MM-DD or ISO 8601)"`
}

type SaveTodoItemsTool struct{}

func (t *SaveTodoItemsTool) Name() string        { return "save_todo_items" }
func (t *SaveTodoItemsTool) Description() string { return "Save the todo items to the database." }

func (t *SaveTodoItemsTool) Schema() map[string]any {
    r := &jsonschema.Reflector{ExpandedStruct: true}
    schema := r.Reflect(&SaveTodoItemsInput{})
    data, _ := json.Marshal(schema)
    var schemaMap map[string]any
    _ = json.Unmarshal(data, &schemaMap)
    return schemaMap
}

func (t *SaveTodoItemsTool) Call(ctx context.Context, input string) (string, error) {
    var req SaveTodoItemsInput
    if err := json.Unmarshal([]byte(input), &req); err != nil {
        return "", err
    }
    for _, item := range req.TodoItems {
        fmt.Printf("Saved: %s (priority: %s)\n", item.Title, item.Priority)
    }
    return "Todo items saved successfully.", nil
}

When paired with an agent that reads an email and extracts action items, the full output looks like this:

┌─────────────────────────────────────────────────────────────
│ Schema for save_todo_items (Parameters sent to LLM)
└─────────────────────────────────────────────────────────────
{
  "properties": {
    "todo_items": {
      "items": { "$ref": "#/$defs/TodoItem" },
      "type": "array"
    }
  },
  "required": ["todo_items"],
  "type": "object",
  "$defs": {
    "TodoItem": {
      "properties": {
        "title":       { "type": "string" },
        "description": { "type": "string" },
        "priority":    { "type": "string", "enum": ["low","normal","high"], "default": "normal" },
        "due_date":    { "type": "string", "format": "date-time" }
      },
      "required": ["title", "priority"],
      "type": "object"
    }
  }
}

  Saved:
    • Review and sign off on API documentation (priority: high due 2026-03-14)
    • Coordinate with DevOps team on staging environment setup (priority: high due 2026-03-18)
    • Update runbook with new monitoring alerts (priority: normal)

┌─────────────────────────────────────────────────────────────
│ Agent completed in 3 iteration(s)
└─────────────────────────────────────────────────────────────

▸ [1] Human
    Extract todo items from the email below and save them using
    the save_todo_items tool. Call get_current_date_time first.
    ...

▸ [2] AI
    → tool: get_current_date_time({"input": "Get current date and time"})

▸ [3] Tool
    ← get_current_date_time: 2026-03-15T21:51:22+08:00

▸ [4] AI
    → tool: save_todo_items({"todo_items": [{"title": "Review and sign off on API documentation", ...}]})

▸ [5] Tool
    ← save_todo_items: Todo items saved successfully.

▸ [6] AI
    Perfect! I've successfully extracted and saved 3 todo items from the email.

A few things to notice from the output:

The schema printed at the top is exactly what gets sent to the LLM as FunctionDefinition.Parameters. The LLM uses this to know the expected JSON shape.
The agent took 3 iterations: (1) call get_current_date_time, (2) call save_todo_items with structured input, (3) produce a final summary.
The get_current_date_time tool uses the default schema ({"input": "..."}) while save_todo_items uses a custom schema — both work seamlessly in the same agent.

How `Schema()` Is Wired Under the Hood

To understand what's really happening, let's trace through the langgraphgo source code. The journey of a tool schema touches three files in the prebuilt package: tool_executor.go, create_agent.go, and the langchaingo tools/tool.go.

Step 1: The tools.Tool interface (langchaingo)

The foundation is langchaingo's tools.Tool — just three methods:

// github.com/tmc/langchaingo/tools/tool.go
type Tool interface {
    Name() string
    Description() string
    Call(ctx context.Context, input string) (string, error)
}

Note that Call always takes a plain string. This is important — whether your tool has structured input or not, the framework ultimately passes a string to Call().

Step 2: ToolWithSchema (langgraphgo)

langgraphgo extends this with an optional interface in tool_executor.go:

// github.com/smallnest/langgraphgo/prebuilt/tool_executor.go
type ToolWithSchema interface {
    Schema() map[string]any
}

It's not embedded in tools.Tool — it's a separate interface that tools may implement. The framework uses Go's interface type assertion to check at runtime.

Step 3: getToolSchema — the branching point

Also in tool_executor.go, this function decides which schema to use:

// github.com/smallnest/langgraphgo/prebuilt/tool_executor.go
func getToolSchema(tool tools.Tool) map[string]any {
    if st, ok := tool.(ToolWithSchema); ok {
        return st.Schema()
    }
    return map[string]any{
        "type": "object",
        "properties": map[string]any{
            "input": map[string]any{
                "type":        "string",
                "description": "The input query for the tool",
            },
        },
        "required":             []string{"input"},
        "additionalProperties": false,
    }
}

If your tool implements ToolWithSchema, it calls Schema() and uses whatever you return. Otherwise, it produces a default schema with a single input string field. This is the default that simple tools (like our dice roller) get automatically.

Step 4: Agent node — building tool definitions for the LLM

In create_agent.go, the agent node builds llms.Tool definitions and passes them to the LLM:

// github.com/smallnest/langgraphgo/prebuilt/create_agent.go (agent node)
var toolDefs []llms.Tool
for _, t := range allTools {
    toolDefs = append(toolDefs, llms.Tool{
        Type: "function",
        Function: &llms.FunctionDefinition{
            Name:        t.Name(),
            Description: t.Description(),
            Parameters:  getToolSchema(t),  // <-- your Schema() lands here
        },
    })
}

resp, err := model.GenerateContent(ctx, msgsToSend, llms.WithTools(toolDefs))

The llms.FunctionDefinition (from langchaingo) has a Parameters any field — it accepts any JSON-serializable value, which is exactly what getToolSchema returns. This gets serialized and sent to the LLM API as the function's parameter specification.

Step 5: Tools node — dispatching tool calls back to your code

When the LLM responds with tool calls, the tools node in create_agent.go handles the dispatch. This is where the ToolWithSchema check matters again:

// github.com/smallnest/langgraphgo/prebuilt/create_agent.go (tools node)
tool, hasTool := toolExecutor.Tools[tc.FunctionCall.Name]

var inputVal string
if hasTool {
    if _, hasCustomSchema := tool.(ToolWithSchema); hasCustomSchema {
        // Tool has custom schema — pass raw JSON arguments directly
        inputVal = tc.FunctionCall.Arguments
    } else {
        // Default schema — extract the "input" field
        var args map[string]any
        _ = json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args)
        if val, ok := args["input"].(string); ok {
            inputVal = val
        } else {
            inputVal = tc.FunctionCall.Arguments
        }
    }
}

res, err := toolExecutor.Execute(ctx, ToolInvocation{Tool: tc.FunctionCall.Name, ToolInput: inputVal})

Two paths:

With ToolWithSchema: the LLM's Arguments JSON (e.g. {"todo_items":[...]}) is passed as-is to Call(). You unmarshal it yourself.
Without ToolWithSchema: the framework assumes the LLM sent {"input":"some string"} (because that's the default schema it told the LLM to use), extracts the "input" field, and passes just that string to Call().

Here's the full flow as a diagram:

This design is clean: the same interface check (ToolWithSchema) gates both schema generation and argument dispatch, keeping the two sides consistent.

One practical gotcha: LLMs are sloppy with dates. They often return "2025-03-14T23:59:59" (no timezone), which fails time.Time's strict RFC3339 parsing. The FlexibleDate type in the example handles this by trying multiple layouts:

type FlexibleDate time.Time

func (f *FlexibleDate) UnmarshalJSON(b []byte) error {
    var s string
    if err := json.Unmarshal(b, &s); err != nil {
        return err
    }
    for _, layout := range []string{
        time.RFC3339,
        "2006-01-02T15:04:05Z",
        "2006-01-02T15:04:05",
        "2006-01-02",
    } {
        if t, err := time.Parse(layout, s); err == nil {
            *f = FlexibleDate(t)
            return nil
        }
    }
    return fmt.Errorf("invalid date: %q", s)
}

It also implements jsonschema.JSONSchema() so the generated schema tells the LLM to use "format": "date-time".

Steps to define a tool (cheat sheet)

Define your input struct with json tags and jsonschema tags for enums/descriptions.
Create a tool struct implementing Name(), Description(), Call(), and Schema().
In Schema(), use jsonschema.Reflector{ExpandedStruct: true} to generate the schema (must be ExpandedStruct: true so the root is type: "object", not a $ref).
In Call(), unmarshal the raw JSON input into your input struct.
Register the tool: inputTools := []tools.Tool{&MyTool{}}.

Two Philosophies: Workflow vs. Agent

When you're building an AI-powered application, you'll face a fundamental design decision: do you want a fixed workflow where you control the execution path, or do you want an agent that decides what to do on its own?

This is not just a langchaingo/langgraphgo distinction — it's a general architectural question that applies to any AI application framework.

Workflow: Fixed Graph of LLM-Powered Steps

A workflow is a directed graph where you define the nodes (steps) and edges (transitions). Each node can use an LLM, but the overall execution path is predetermined. Think of it as a state machine where some states happen to call an LLM.

Here's an example: given an email, first summarize it, then extract todo items from the summary.

g := graph.NewListenableStateGraph[MyState]()

g.AddNode(
    "summarize_email",
    "Summarize the email",
    func(ctx context.Context, state MyState) (MyState, error) {
        promptTemplate := prompts.NewPromptTemplate(`
        You are a helpful assistant that summarizes emails.
        The email is: {{.email}}
        Your summary is:
        `, []string{"email"})

        prompt, _ := promptTemplate.Format(map[string]any{"email": email})
        resp, err := llm.Call(ctx, prompt)
        if err != nil {
            return state, err
        }

        state["summary"] = resp
        return state, nil
    },
)

g.AddNode(
    "extract_todo_items",
    "Extract todo items from the summary",
    func(ctx context.Context, state MyState) (MyState, error) {
        // Uses llmStructured (JSON mode) to extract todo items
        // from the summary produced by the previous node
        // ...
        state["todo_items"] = result.TodoItems
        return state, nil
    },
)

g.AddEdge("summarize_email", "extract_todo_items")
g.AddEdge("extract_todo_items", graph.END)
g.SetEntryPoint("summarize_email")

The graph state (MyState, which is just map[string]any) flows through each node. Each node reads what it needs from the state, does its work (often involving an LLM call), and writes its results back to the state.

Here's the actual output when streaming this graph:

[22:37:27.943] 🚀 Chain started
[22:37:27.943] ▶️  Node 'summarize_email' started
[22:37:32.848] ✅ Node 'summarize_email' completed
  state:
    {
      "summary": "Sarah requests John to: 1) Review and sign off on the
       API documentation by March 14th. 2) Coordinate with DevOps on
       staging environment setup by March 18th. 3) Update the runbook
       with new monitoring alerts (no hard deadline)."
    }
[22:37:32.848] ▶️  Node 'extract_todo_items' started
[22:37:40.533] ✅ Node 'extract_todo_items' completed
  state:
    {
      "summary": "...",
      "todo_items": [
        { "title": "Review and sign off on the API documentation",
          "due_date": "2026-03-14T23:59:59+08:00" },
        { "title": "Coordinate with DevOps on staging environment setup",
          "due_date": "2026-03-18T23:59:59+08:00" },
        { "title": "Update the runbook with new monitoring alerts",
          "description": "Emma from SRE can assist" }
      ]
    }
[22:37:40.533] 🏁 Chain ended

You can see the state accumulating as it flows through nodes: summarize_email writes "summary", then extract_todo_items reads it and writes "todo_items". The entire pipeline took about 12 seconds (two LLM calls back to back).

Streaming — graph.NewStreamingStateGraph lets you compile with CompileListenable() and call Stream() to get a channel of events (chain start/end, node start/complete/error) as they happen:

runnable, _ := g.CompileListenable()
events := runnable.Stream(ctx, initialState)
for event := range events {
    // EventChainStart, NodeEventStart, NodeEventComplete, EventChainEnd, etc.
}

Listeners — graph.NewListenableStateGraph gives you a listener pattern. You can attach global listeners (see all node events) or per-node listeners (see only that node's events):

g.AddGlobalListener(&EventLogger{})
extractNode.AddListener(&TodoItemReporter{})

runnable, _ := g.CompileListenable()
result, _ := runnable.Invoke(ctx, initialState)

Listeners implement OnNodeEvent(ctx, event, nodeName, state, err) and are great for decoupling concerns like logging, metrics, persistence, or triggering side effects from the node logic itself.

When to use a workflow:

The steps are known and fixed — you know exactly what needs to happen and in what order.
You want explicit control over the execution flow.
Different steps may need different LLM configurations (e.g., one node uses JSON mode, another uses free-form text).
You want to observe and react to individual step completions (via listeners or streaming).

The workflow approach is essentially: "I know the recipe, I just need an LLM to help me execute some of the steps."

Agent: Let the LLM Decide

The agent approach is fundamentally different. Instead of you defining the execution path, you define tools and let the LLM decide which tools to call, in what order, and when to stop.

Internally, prebuilt.CreateAgentMap builds a simple 2-node graph:

The agent node sends the conversation to the LLM. If the LLM responds with tool calls, the tools node executes them and feeds the results back. If the LLM responds with a final answer (no tool calls), execution ends.

inputTools := []tools.Tool{
    &GetCurrentDateTimeTool{},
    &SaveTodoItemsTool{},
}

runnable, _ := prebuilt.CreateAgentMap(llm, inputTools, 10,
    prebuilt.WithSystemMessage(
        "You must call get_current_date_time first to get the current date, "+
        "then extract todo items and save them.",
    ),
)

initialState := map[string]any{
    "messages": []llms.MessageContent{
        llms.TextParts(
            llms.ChatMessageTypeHuman,
            "Extract todo items from the email below and save them.\n\n"+email,
        ),
    },
}

resp, _ := runnable.Invoke(ctx, initialState)

The LLM autonomously decides: "First I'll call get_current_date_time to know what today is, then I'll analyze the email and call save_todo_items with the extracted items." You didn't hardcode this sequence — the LLM figured it out.

When to use an agent:

The execution path is dynamic — it depends on the input, intermediate results, or external state.
You want the LLM to reason about what to do, not just execute a step.
The problem is naturally described as: "here are the capabilities (tools), figure out how to accomplish the goal."

My Practical Experience

After building with both approaches, here's my mental model:

Workflows are for when you know the "what" but need help with the "how." You know you need to summarize, then extract, then save. The LLM helps with the summarization and extraction (the "how"), but you control the pipeline (the "what" and "when"). This is great when the process is well-understood and you want predictability and debuggability. The graph structure makes it easy to reason about what happens when, and listeners let you observe each step.

Agents are for when you want to replace if-else logic with language-based reasoning. This is the insight that clicked for me. Traditionally, when we write business logic, we translate real-world decision-making into code: if conditionA { doX() } else if conditionB { doY() }. An agent flips this — instead of us translating the decision tree into code, we describe the available actions (tools) and the context (in natural language), and the LLM figures out the branching. It's replacing hard-coded control flow with language-based control flow.

This is powerful when:

The decision logic is complex and hard to enumerate in code.
The branching depends on understanding natural language context.
You want to add new capabilities (tools) without rewriting control flow.

But it comes with trade-offs:

Less predictable — the LLM might not always choose the optimal tool sequence.
Harder to debug — "why did it call tool X before tool Y?" requires inspecting the LLM's reasoning.
More expensive — each decision point is an LLM call.

In practice, I find myself using workflows for structured pipelines (ETL-like processes, multi-step content processing) and agents for open-ended tasks (chatbots with capabilities, email triage, anything where the "right" sequence depends on the input).

My Takeaways

After spending time with these libraries, here are the things I wish I'd known upfront:

1. langchaingo's openai package is a universal OpenAI-compatible client. Don't think of it as "only for OpenAI." Any provider with an OpenAI-compatible API (DeepSeek, Azure OpenAI, local models via Ollama/LiteLLM) works by swapping the base URL.

2. The tools.Tool → ToolWithSchema progression is natural. Start with simple tools (just Name/Description/Call), and only add Schema() when you need structured input. The default schema ({"input":"string"}) is fine for many tools.

3. JSON Schema is your contract with the LLM. Whether it's structured output via ResponseFormatJSON or tool input via ToolWithSchema, the pattern is the same: define a Go struct, reflect it into a JSON Schema, and let the LLM conform to it. The invopop/jsonschema package with struct tags (jsonschema:"enum=...") is your friend here.

4. LLMs are sloppy with types. Dates without timezones, numbers as strings, etc. Build defensive unmarshaling (like FlexibleDate) rather than expecting perfect output.

5. ExpandedStruct: true is critical for tool schemas. Without it, jsonschema.Reflector produces $ref-based schemas that LLM APIs don't understand. Always use ExpandedStruct: true when generating schemas for tool definitions.

6. System messages guide agent behavior. Use prebuilt.WithSystemMessage(...) to tell the agent how to approach the task. This is especially important when tools have a natural ordering (e.g., "get the current date first").

7. Workflow graphs are state machines. Think of each node as a state transition: it reads from the shared state, does work, writes results back. The graph edges define the transition sequence. This mental model makes complex workflows easy to reason about.

8. Listeners decouple concerns. Don't put logging, metrics, or side effects inside your node functions. Use listeners. Global listeners for cross-cutting concerns, node-specific listeners for targeted reactions.

Quick Reference

Calling an LLM

llm, _ := openai.New(
    openai.WithBaseURL("https://api.deepseek.com"),
    openai.WithToken(os.Getenv("DEEPSEEK_API_KEY")),
    openai.WithModel("deepseek-chat"),
)
resp, _ := llm.Call(ctx, "your prompt")

Structured Output

llm, _ := openai.New(
    // ...
    openai.WithResponseFormat(openai.ResponseFormatJSON),
)
// Include JSON schema in prompt, then json.Unmarshal(resp, &myStruct)

Defining a Simple Tool

type MyTool struct{}
func (t *MyTool) Name() string                                      { return "my_tool" }
func (t *MyTool) Description() string                               { return "Does something." }
func (t *MyTool) Call(ctx context.Context, input string) (string, error) { return "result", nil }

Defining a Tool with Schema

type MyTool struct{}
func (t *MyTool) Name() string        { return "my_tool" }
func (t *MyTool) Description() string { return "Does something structured." }
func (t *MyTool) Schema() map[string]any {
    r := &jsonschema.Reflector{ExpandedStruct: true}
    schema := r.Reflect(&MyInput{})
    data, _ := json.Marshal(schema)
    var m map[string]any
    json.Unmarshal(data, &m)
    return m
}
func (t *MyTool) Call(ctx context.Context, input string) (string, error) {
    var req MyInput
    json.Unmarshal([]byte(input), &req)
    return "result", nil
}

Creating an Agent

runnable, _ := prebuilt.CreateAgentMap(llm, tools, maxIterations,
    prebuilt.WithSystemMessage("instructions"),
)
state := map[string]any{
    "messages": []llms.MessageContent{
        llms.TextParts(llms.ChatMessageTypeHuman, "user input"),
    },
}
resp, _ := runnable.Invoke(ctx, state)

Building a Workflow Graph

g := graph.NewListenableStateGraph[map[string]any]()
g.AddNode("step1", "description", func(ctx context.Context, s map[string]any) (map[string]any, error) {
    // use LLM, update state
    return s, nil
})
g.AddNode("step2", "description", stepTwoFunc)
g.AddEdge("step1", "step2")
g.AddEdge("step2", graph.END)
g.SetEntryPoint("step1")
runnable, _ := g.CompileListenable()
result, _ := runnable.Invoke(ctx, initialState)

Making Your Astro Blog AI-Readable with llms.txt

Isaac FEI — Fri, 20 Mar 2026 04:35:43 +0000

I've been noticing something shift over the past year or so. The readers of my blog posts, documentation pages, and personal sites are no longer just humans scrolling through a browser. More and more, the "readers" are AI models 🤖 — Claude, ChatGPT, Gemini — ingesting content on behalf of a developer who asked a question. When someone types "how do I deploy TanStack Start to Cloudflare" into an AI assistant, the answer might come from my blog. But the AI never sees my carefully styled page. It sees whatever raw text it can scrape, often garbled with navigation markup, SVG icons, and JavaScript artifacts.

There's a strange irony in this. I write a blog post, an AI reads it, digests it, and serves it back to another person — who might then ask a different AI to help them write their blog post based on it. The whole loop is increasingly AI-to-AI, with humans as the initiators but not necessarily the readers anymore. Documentation sites are being consumed not by developers reading them top-to-bottom, but by coding assistants pulling in context on-the-fly. The audience has changed, and it changed quietly.

I'd be a hypocrite if I pretended this bothers me in some principled way. Most of the posts on this blog were drafted or polished with AI assistance. 😅 That's just the reality of writing these days — AI helps me organize thoughts, smooth out rough prose, and catch things I'd miss on a second pass. The line between "I wrote this" and "AI wrote this" has become genuinely blurry, and I think most honest writers would admit the same.

What does strike me, though, is the downstream effect. When AI creates more content, and AI consumes more content, the proportion of genuinely human-originated thought in the loop gets smaller. I'm not saying that's catastrophic — the ideas are still human, the intent is still human — but it's worth pausing to notice. We're building an infrastructure where machines write for machines to read, and the humans are somewhere in the margins, prompting and approving.

I don't have a grand conclusion about this. It's just the world we're in now. And if that's the case, the pragmatic thing to do is make sure the content I do put out there — however it was drafted — is as accessible as possible to both audiences.

That's exactly what llms.txt is for. It's a simple, emerging standard — a Markdown file at /llms.txt that acts as a site map for language models, pointing them to clean, structured content they can actually parse. Think of it as robots.txt, but instead of telling crawlers what not to index, it tells AI models what to read.

So here's what I did: I made my blog speak both languages. A styled, human-friendly site for browsers, and a clean Markdown feed for AI. Below is how I integrated it into my Astro blog.

The plan

The implementation has three pieces:

/llms.txt — an index file listing every post with a link to its Markdown version.
/llms-full.txt — all posts concatenated into a single file, for when an AI model wants the full context.
/posts/{slug}.md — a per-post clean Markdown endpoint, so individual articles can be fetched without the HTML wrapper.

All three are prerendered as static files at build time, so there's zero runtime cost.

Step 1: MDX to clean Markdown

My posts are written in MDX — Markdown with JSX components, imports, and expressions sprinkled in. An AI model doesn't need any of that. It needs plain Markdown with the code blocks intact.

I used the unified ecosystem — specifically remark-parse, remark-mdx, remark-stringify, and unist-util-visit — to build a small processing pipeline:

// src/lib/llms-txt.ts
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkMdx from "remark-mdx";
import remarkStringify from "remark-stringify";
import type { Root } from "mdast";
import { visit, SKIP } from "unist-util-visit";

function remarkStripMdx() {
  return (tree: Root) => {
    visit(tree, (node, index, parent) => {
      if (index === undefined || !parent) return;
      if (
        node.type === "mdxjsEsm" ||
        node.type === "mdxJsxFlowElement" ||
        node.type === "mdxJsxTextElement" ||
        node.type === "mdxFlowExpression" ||
        node.type === "mdxTextExpression"
      ) {
        parent.children.splice(index, 1);
        return [SKIP, index];
      }
    });
  };
}

const processor = unified()
  .use(remarkParse)
  .use(remarkMdx)
  .use(remarkStripMdx)
  .use(remarkStringify, { bullet: "-", fences: true, listItemIndent: "one" });

export async function mdxToMarkdown(mdx: string): Promise<string> {
  const stripped = mdx.replace(/^---\n[\s\S]*?\n---\n?/, "");
  return String(await processor.process(stripped)).trim();
}

// ... shared helpers (getSortedPosts, formatPost, etc.) shown below ...

The pipeline: remark-parse parses the Markdown, remark-mdx understands the MDX syntax, a custom remarkStripMdx plugin walks the AST with unist-util-visit and removes every MDX-specific node (imports, exports, JSX components, JS expressions), and remark-stringify serializes what's left back to clean Markdown.

This is significantly more robust than regex. The AST approach correctly handles edge cases like JSX components nested inside lists, or code blocks that happen to contain import-like syntax.

Step 2: The three endpoints

With the processor in place, the endpoints are minimal. Still in the same src/lib/llms-txt.ts file, I added a few shared helpers using Astro's Content Collections API to keep things DRY:

// src/lib/llms-txt.ts
// ... imports, remarkStripMdx plugin, processor, mdxToMarkdown shown above ...

import { getCollection } from "astro:content";

export interface PostMeta {
  title: string;
  description: string;
  date: Date;
  tags: string[];
  body: string;
  slug: string;
}

export async function formatPost(post: PostMeta, baseUrl: string): Promise<string> {
  const md = await mdxToMarkdown(post.body);
  const date = post.date.toISOString().split("T")[0];
  const tags = post.tags.length ? `- **Tags:** ${post.tags.join(", ")}\n` : "";

  return `# ${post.title}\n\n- **URL:** ${baseUrl}/posts/${post.slug}\n- **Date:** ${date}\n${tags}- **Description:** ${post.description}\n\n---\n\n${md}`;
}

export async function getSortedPosts() {
  const posts = await getCollection("blogPost", ({ data }) => !data.draft);
  return posts.sort((a, b) => b.data.date.getTime() - a.data.date.getTime());
}

export function resolveBaseUrl(site: URL | undefined): string {
  return site?.toString().replace(/\/$/, "") ?? "https://example.com";
}

Then each Astro endpoint becomes a thin wrapper:

`/llms.txt` — the index

// src/pages/llms.txt.ts
import type { APIRoute } from "astro";
import { getSortedPosts, resolveBaseUrl } from "@/lib/llms-txt";

export const prerender = true;

export const GET: APIRoute = async ({ site }) => {
  const baseUrl = resolveBaseUrl(site);
  const posts = await getSortedPosts();

  const lines = [
    "# My Blog",
    "",
    "> A short description of your site.",
    "",
    "## Blog Posts",
    "",
    ...posts.map(
      (p) => `- [${p.data.title}](${baseUrl}/posts/${p.id}.md): ${p.data.description}`
    ),
    "",
    "## Optional",
    "",
    `- [Full blog content](${baseUrl}/llms-full.txt): All posts in one file`,
  ];

  return new Response(lines.join("\n"), {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
};

`/llms-full.txt` — everything in one file

// src/pages/llms-full.txt.ts
import type { APIRoute } from "astro";
import { getSortedPosts, resolveBaseUrl, toPostMeta, formatPost } from "@/lib/llms-txt";

export const prerender = true;

export const GET: APIRoute = async ({ site }) => {
  const baseUrl = resolveBaseUrl(site);
  const posts = await getSortedPosts();
  const sections = await Promise.all(
    posts.map((p) => formatPost(toPostMeta(p), baseUrl))
  );

  return new Response(
    ["# Full Blog Content", "", sections.join("\n\n---\n\n")].join("\n\n"),
    { headers: { "Content-Type": "text/plain; charset=utf-8" } }
  );
};

`/posts/{slug}.md` — per-post Markdown

// src/pages/posts/[...slug].md.ts
import type { APIRoute } from "astro";
import { getSortedPosts, resolveBaseUrl, toPostMeta, formatPost } from "@/lib/llms-txt";

export const prerender = true;

export async function getStaticPaths() {
  const posts = await getSortedPosts();
  return posts.map((post) => ({
    params: { slug: post.id },
    props: { post },
  }));
}

export const GET: APIRoute = async ({ site, props }) => {
  const { post } = props as { post: Awaited<ReturnType<typeof getSortedPosts>>[number] };

  return new Response(await formatPost(toPostMeta(post), resolveBaseUrl(site)), {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
};

That's it for the backend. Three files, each under 20 lines of actual logic.

Step 3: A "Copy for AI" button

To make this discoverable to human visitors too, I added a small React component that fetches the Markdown endpoint and copies it to the clipboard. One component handles two modes: a simple inline button for blog list tiles, and a dropdown menu in the global header (copy this page, copy full blog, view llms.txt). I keep the dropdown only in the header — not duplicated on each post page — to avoid clutter.

// src/components/copy-for-ai.tsx
"use client";

import { useState } from "react";

export function CopyForAI({ postSlug }: { postSlug?: string }) {
  const [status, setStatus] = useState<"idle" | "copying" | "copied">("idle");

  const url = postSlug ? `/posts/${postSlug}.md` : "/llms-full.txt";

  const handleCopy = async () => {
    setStatus("copying");
    try {
      const res = await fetch(url);
      await navigator.clipboard.writeText(await res.text());
      setStatus("copied");
      setTimeout(() => setStatus("idle"), 2000);
    } catch {
      setStatus("idle");
    }
  };

  return (
    <button onClick={handleCopy}>
      {status === "copied" ? "Copied!" : "Copy for AI"}
    </button>
  );
}

Pass a postSlug and it copies that single post. Omit it and it copies the entire blog. The dropdown lives in the global header so visitors can quickly grab AI-friendly content from anywhere on the site.

A discoverability gotcha: links must be in the HTML

Here's a subtle but important concern. If the "View llms.txt" link lives only inside a dropdown that's rendered conditionally (e.g. {open && (...)} in React), it won't exist in the DOM until the user clicks. AI crawlers that parse the initial HTML won't find it — they don't execute JavaScript or simulate clicks. So if someone tells an AI "read this person's blog," the AI might crawl the page, extract links from the HTML, and never see the llms.txt URL.

Primary discovery is convention-based: the llms.txt spec puts the file at a well-known path (https://yoursite.com/llms.txt), like robots.txt. AI systems that know the spec can fetch it directly without needing a link. But for crawlers that discover content by following links, you need the URL to appear in the HTML from the start.

What to do:

<link> in <head> — Add a machine-readable hint so parsers that read link tags can find llms.txt:

<link rel="alternate" type="text/plain" href="https://yoursite.com/llms.txt" title="llms.txt - AI-readable site index" />

Visible static link — Put a plain anchor somewhere that's always rendered (e.g. in your RSS/feeds section or footer). No JavaScript, no dropdown. The link must be in the initial server-rendered HTML.
robots.txt — Create one at the site root if you don't have it. You can add a comment pointing to llms.txt for crawlers that look for it.
Per-post link — On each blog post page, add a simple dedicated link to that post's .md version. Don't duplicate the full CopyForAI dropdown (it's already in the header). Use a minimal Astro component that renders a static <a href="/posts/{slug}.md"> — always in the HTML, so crawlers can discover individual post markdown from any article page.

<!-- src/components/PostMarkdownLink.astro -->
---
interface Props { slug: string; className?: string; }
const { slug, className = "" } = Astro.props;
---
<a href={`/posts/${slug}.md`} class={className} title="View markdown version for AI">
  Markdown for AI
</a>

This keeps the header dropdown for human convenience (copy to clipboard, view full blog) while ensuring every post page has a crawlable link to its AI-readable version.

Takeaways

The whole implementation is about 200 lines across 6 files. The key dependencies are unified, remark-parse, remark-mdx, and remark-stringify — battle-tested libraries that handle the MDX-to-Markdown conversion properly through AST manipulation rather than fragile regex.

The technical part was honestly the easy part. What lingers is the feeling behind it. We spent years perfecting responsive layouts, dark mode, typography, and scroll animations — all for human eyes. Now we're adding a second output format for an audience that doesn't care about any of that. An audience that wants raw text, clear structure, and nothing else.

And maybe that's fine. Maybe the future of a personal blog isn't just a place for humans to read — it's also a node in a larger knowledge graph that AI systems draw from. If my writing helps someone solve a problem, does it matter whether they read it directly or whether an AI summarized it for them? I'm honestly not sure. 🤷

What I am sure of is that this shift is happening whether we like it or not. The pragmatic move is to meet it halfway — keep writing for humans, but make it easy for machines too. That's all llms.txt really is: a small act of acknowledging who your readers actually are right now.

DEV Community: Isaac FEI

User Authentication with FastAPI and Next.js

Architecture Overview

Backend Implementation

Domain Layer: User Entity and Value Objects

Secure Password Handling

Authentication Endpoints

JWT Token Management

Authentication Middleware

Frontend Implementation

State Management with Zustand

API Integration with React Query

Login Component

Security Features

HTTP-Only Cookies

Password Security

Token Management

Conclusion

Managing Configurations in Python Projects

The Problem: Managing Multiple Environments

Determining the Current Environment

Grouping Configurations with Pydantic

Loading the Configuration

Putting It All Together

Why This Design?

Final Thoughts

Qdrant Hybrid Search Combined with SQL Query Results

My Favorite Vector Database: Qdrant

FastEmbed: Lightweight Embedding Powerhouse

The Hybrid Search Imperative

When Pure Semantic Search Fails

BM25: The Keyword Savior

Reciprocal Rank Fusion (RRF): Merging Semantic and Keyword Results

Implementing Hybrid Search in Qdrant

Model Configuration

Collection Creation

Data Insertion Strategy

Hybrid Query Execution

SQL Integration

Implementation Pattern

Real-World Use Cases

The Ultimate Combination

The Publisher-Subscriber Pattern in React

Stopwatch Demo

Gerneral Idea

Custom Events

Events without Extra Data

Events with Extra Data

The Event Target

Add/Remove Event Listeners

Define addXxxEventListener and removeXxxEventListener for Each Xxx Event

Define a Single Pair of addEventListener and removeEventListener -- Play around with Types

Summary

Implementation

Deploying a Image Recognition Service to AWS Lambda

Start a New Project

Define the ResNet50 Architecture

Implement the ImageRecognizer using the ResNet50 Model

Build a FastAPI App -- Deliver the Deep Learning Model as an HTTP Service

Health Check

Recognize Image

Final Touch -- Mangum Adapter

Write a Dockerfile for Building the Image

Build and Push the Docker Image to AWS ECR

Create a Lambda Function using the Docker Container

Create a Funciton URL

Set General Configuration

A Simple Web App for Image Generation with Dall-E 3 using Go + HTMX

What Will We Build? And My Motivation

Introduction to HTMX and Templ

Project Structure

Setup

Gin

Templ

Air

HTMX

Tailwind CSS v4 + DaisyUI

Backend: Send Multiple Requests to OpenAI Concurrently

Send a Single Request

Send Multiple Requests

Define `addXxxEventListener` and `removeXxxEventListener` for Each `Xxx` Event

Define a Single Pair of `addEventListener` and `removeEventListener` -- Play around with Types

Implement the `ImageRecognizer` using the ResNet50 Model

Frontend: Build the UI in `.templ` Files

The `invopop/jsonschema` Package

How `Schema()` Is Wired Under the Hood