DEV Community: Sreeharsha

Shipping a MCP Server alongside your API

Sreeharsha — Wed, 25 Feb 2026 06:00:45 +0000

TLDR;

MCP tools and REST APIs serve fundamentally different consumers — humans navigate discovery, agents need curated capabilities.

Instead of deploying a separate MCP service or auto-converting your existing API, you can mount an MCP server directly alongside your FastAPI application using FastMCP 3.x.

Both interfaces share the same services, database, and authentication, but each is designed for its own consumer.

This article covers the design philosophy, architecture, and engineering challenges of shipping this dual-interface pattern.

Introduction

MCP (Model Context Protocol) is an open standard that defines how AI systems interact with external tools, data sources, and applications. Rather than building bespoke integrations for each model-service pair, MCP provides a single protocol that any AI agent can speak.

An MCP server exposes three types of capabilities:

Tools — Functions the LLM calls autonomously to take action. The model decides when and how to invoke them based on conversation context.
Resources — Structured data the application provides as context. These are read-only and addressed via URIs.
Prompts — Pre-built templates that guide users through structured workflows with validated inputs.

Of these, tools are the primary interface for agentic workflows — and they're where the design challenge lives.

Deployment

When teams adopt MCP, the default instinct is to deploy the MCP server as a separate service alongside the existing API. This mirrors the microservices pattern: independent scaling, isolated failure domains.

But for most applications, the MCP tools and REST endpoints operate on the same data, apply the same business rules, and authenticate the same users. A separate service means duplicated logic, duplicated auth configuration, and additional infrastructure — all for a protocol adapter.

The alternative — and the pattern this article explores — is mounting the MCP server as a sub-application inside your existing API server. FastMCP 3.x generates a standard ASGI application, which means it slots natively into FastAPI or Starlette with a single mount() call.

The result:

Path	Consumer	Interface
`/api/*`	Web/mobile clients, curl	REST (FastAPI)
`/mcp`	AI agents, LLM clients	MCP (FastMCP)
`/health`	Infrastructure	HTTP GET

One deployment. One database. One authentication secret. Two interfaces, each designed for its consumer.

When This Pattern Fits

Good fit: Your MCP tools and API endpoints serve the same domain with the same data. You want fast time-to-market without new infrastructure.

Less ideal: You need independent scaling for heavy MCP traffic, or your MCP tools integrate data sources that your API doesn't touch.

Design

REST APIs Are Not MCP Tools

The fundamental insight, articulated well by Jlowin (FastMCP's creator), is that REST APIs and MCP tools are designed for consumers with opposite needs:

REST APIs are designed for human developers. They optimize for discoverability and atomicity. Hundreds of single-purpose endpoints are a feature, because human developers do discovery once, write code that chains atomic calls together, and iterate cheaply. More choice is good.

MCP tools are designed for LLM agents. Every tool an LLM has access to is processed in its context window on every reasoning step — every name, description, and parameter schema. More tools means more tokens, more latency, and more opportunities for the model to make wrong choices. Atomicity is an antipattern: each tool call triggers a full reasoning cycle that costs time and money.

This creates a concrete design mismatch:

Dimension	REST API	MCP Tool
Audience	Human developer writing code	LLM agent reasoning in context
Cost of choice	Cheap — ignored at compile time	Expensive — processed every inference
Iteration cost	Fast — network hops are milliseconds	Slow — each call is a full reasoning cycle
Design ideal	Rich, composable, atomic	Ruthlessly curated, minimal
Failure mode	404 / 500 errors	Hallucinated tools, wrong tool selection

Designing Tools from Agent Stories

The right approach is to start not from your API spec, but from the agent story: "As an agent, given {context}, I use {tools} to achieve {outcome}."

For a todos application, the agent story is simple: "As an agent, given an authenticated user, I use todo management tools to help the user create, view, update, and complete tasks."

This leads to five curated tools — not nine REST endpoints:

MCP Tool	Purpose	Why it exists
`get_all_todos`	Overview of all tasks	Agent needs full picture to reason about priorities
`get_todo_by_id`	Inspect a specific task	Agent needs current state before suggesting updates
`create_todo`	Create a task	Core capability for task management
`update_todo`	Modify a task	Includes completion — no separate "mark done" endpoint
`delete_todo`	Remove a task	Destructive — tool description tells agent to confirm first

Each tool gets a rich description that instructs the LLM on when and how to use it. For example, update_todo's description states: "All fields are required — provide current values for fields you do not want to change. Use get_todo_by_id first to fetch the current values before updating." This kind of guidance is meaningless in REST but critical for MCP.

Implementation Overview

Architecture

github: todos

The application follows a layered architecture where the services and data access layers are shared, and only the interface layer differs:

┌──────────────────────┐    ┌──────────────────────┐
│   REST API (api.py)  │    │  MCP Tools (mcp.py)  │
│   9 endpoints        │    │   5 tools            │
│   FastAPI Depends()  │    │   FastMCP Depends()  │
└──────────┬───────────┘    └──────────┬───────────┘
           │                           │
           └─────────┬─────────────────┘
                     ▼
           ┌─────────────────────┐
           │   Services Layer    │
           │ AuthService          │
           │ TodoService          │
           └─────────┬───────────┘
                     ▼
           ┌─────────────────────┐
           │  Repository Layer   │
           │ UserRepository       │
           │ TodoRepository       │
           └─────────┬───────────┘
                     ▼
           ┌─────────────────────┐
           │   SQLAlchemy/SQLite │
           └─────────────────────┘

How It Comes Together

The root application (main.py) composes everything:

Creates the MCP ASGI app from the FastMCP server instance
Combines lifespans — database table initialization and MCP session management are merged using combine_lifespans()
Applies middleware at root level — CORS (including MCP-specific headers like mcp-session-id) and request logging apply uniformly to all sub-apps
Registers OAuth discovery routes at the root (these must live outside the /mcp prefix)
Mounts both interfaces — REST API at /api, MCP server at /mcp

Shared Authentication

The REST API issues JWTs at /api/auth/token. The MCP server validates those same tokens using FastMCP's JWTVerifier, configured with the same HS256 secret. Users authenticate once through the REST API and can use the token with either interface.

Inside MCP tools, user identity is extracted from the verified token claims — the same sub claim that the REST API reads, resolving to the same user record in the same database.

Shared Business Logic

Both interfaces resolve to the same AuthService and TodoService classes. The service and repository layers are written once and used by both. Only the dependency injection wiring differs between the two frameworks (see Challenges below).

Challenges

1. OAuth Discovery Routes Must Live at Root

MCP clients authenticate via Streamable HTTP and expect OAuth discovery endpoints at well-known paths:

GET /.well-known/oauth-protected-resource/mcp
GET /.well-known/oauth-authorization-server/mcp

These cannot be nested under the /mcp mount prefix — they must be registered on the root application. Missing these routes caused silent authentication failures that were difficult to diagnose. FastMCP provides mcp.auth.get_well_known_routes() to generate these routes, but you must explicitly append them to the root app.

2. Middleware Configuration at Root

The initial implementation had separate middleware for both the FastAPI and FastMCP sub-applications. This caused CORS issues — the MCP protocol uses custom headers (mcp-protocol-version, mcp-session-id) that need to be allowed and exposed:

app.add_middleware(
    CORSMiddleware,
    allow_headers=["mcp-protocol-version", "mcp-session-id", "Authorization", "Content-Type"],
    expose_headers=["mcp-session-id"],
)

Moving CORS and logging middleware to the root-level app (so it applies to all sub-apps uniformly) resolved the issue. This is also the approach recommended by FastMCP's documentation.

3. Dependency Injection — Two Systems, One Service Layer

FastAPI and FastMCP each provide their own Depends() function, and they are not interchangeable:

FastAPI's Depends uses generator-based resolution (yield in a generator function)
FastMCP's Depends uses its own resolver that expects a @contextmanager decorated function

Using FastAPI's DI in FastMCP tools caused resolution errors like Failed to resolve dependency 'user'. The fix was defining separate dependency providers in mcp.py using fastmcp.dependencies.Depends and @contextmanager for DB sessions, while keeping the FastAPI providers in services/__init__.py.

Both resolve to the same AuthService and TodoService classes — the dependency wiring is separate, but the business logic is fully shared.

Conclusion

The dual-interface pattern — a REST API and MCP server sharing a single deployment — is a pragmatic choice for teams adding agent capabilities to an existing backend. You avoid duplicating business logic, authentication, and infrastructure. You ship one container instead of two.

But the design lesson runs deeper than deployment topology. REST APIs and MCP tools serve fundamentally different consumers. The endpoints that make your API discoverable and composable for human developers can drown an LLM in context. The right approach is to curate your MCP tools independently — start from the agent's story, not from your OpenAPI spec.

The code reuse happens at the service layer, not the interface layer. That's the key architectural insight: share the logic, design the surfaces separately.

The official MCP guide to building a server references from mcp.server.fastmcp import FastMCP (the low-level SDK). As of February 2026, FastMCP v3 (from fastmcp import FastMCP) is the recommended high-level framework, offering Streamable HTTP, ASGI integration, web framework mounting, and a CLI.

Agentic Commerce: Dive into ACP & UCP Protocols

Sreeharsha — Thu, 05 Feb 2026 10:48:11 +0000

TLDR

Agentic commerce enables AI agents to autonomously handle end-to-end shopping workflows—from discovery to checkout—through standardized protocols like ACP (OpenAI/Stripe) and UCP (Shopify/Google).

This article explores their architectures, a practical Shopify MCP implementation, engineering challenges, and future directions for developers building scalable agentic systems.

Intro

E-commerce revolutionized retail by digitizing physical stores into accessible, scalable online platforms, enabling globalized reach and streamlined checkout flows. Agentic commerce amplifies these capabilities exponentially, empowering AI agents to autonomize end-to-end purchases, negotiate dynamic discounts, provide proactive post-purchase support, and orchestrate complex workflows—all while maintaining merchants as the Merchant of Record (MoR).

This represents a paradigm shift from human-led browsing to AI-orchestrated commerce, powered by interoperable protocols and robust system design. For engineers, it demands new skills in protocol interoperability, stateful agent reasoning, and headless commerce integration.

Overview: Enabling Agentic Commerce

To operationalize agentic commerce, open-source protocols provide the foundational building blocks:

ACP (Agentic Commerce Protocol) focuses on checkout and payment processing. It provides a REST-based Checkout API for cart management and a Delegate Payment API for secure payment tokenization through PSPs like Stripe. The minimal implementation surface enables rapid merchant adoption. OpenAI supports merchant integration via standardized product feed specs that expose inventory to ChatGPT.
UCP (Universal Commerce Protocol) addresses the full commerce lifecycle including product discovery, identity linking, checkout, and order management. It defines participant roles, capability boundaries, and interaction patterns for complex commerce workflows. Shopify implements UCP through MCP servers for catalog and checkout, with ongoing development for post-purchase capabilities.

Both protocols support human-driven API workflows alongside agentic flows, ensuring backward compatibility while future-proofing for autonomous commerce.

Protocols and Standards

ACP

There are 4 parties involved in ACP:
- Buyer: human who wants to purchase something.
- Agent: AI platform that orchestrates checkout experience.
- Seller: the merchant who sells products. Sellers implement the Checkout API and remain the merchant of record (MoR).
- Payment Provider: handles payment tokenization and processing. Eg: stripe.

Core APIs:

Checkout API:
Enables agents to programmatically create, update, and complete checkout sessions. Designed for conversational flows where agents maintain session state across multi-turn interactions while managing cart modifications, shipping calculations, and order finalization.
Delegate Payment API:
Provides tokenized payment credentials with granular usage constraints through an allowance framework. Merchants can enforce spending limits, merchant restrictions, and time-based controls without exposing raw payment credentials.

UCP

There are 4 parties involved in UCP as well:
- Platform/Agent: Buyer-facing interface (smart assistants, conversational surfaces, embedded commerce tools)
- Business: Product/service provider with inventory and fulfillment responsibilities
- Credential Provider: Identity management for user profile data (Google Sign-In, Entra ID)
- Payment Provider: Payment processing infrastructure (Stripe, PayPal, Google Pay)
UCP operates on three layers:
- Capabilities - Major Functional Domains:
  - Product Discovery: discovering products with semantic query support.
  - Cart: multi-item checkout, complex basket rules. Eg: BOGO, bundles, minimums
  - Identity Linking: obtain authorization to perform actions on behalf of a user.
  - Checkout: facilitating checkout sessions.
  - Order: Transaction history, tracking, returns.
  - Other vertical capabilities: loyalty programs & member benefits.
- Extensions - Optional augmentation (e.g., discount codes, gift wrapping).
- Services: lower-level communication layers used to exchange data. Eg: REST, MCP A2A

Specifications:

Active development: Product discovery with semantic search, cart operations with inventory validation, vertical-specific extension framework. See roadmap.

Implementation

Shopify MCP Architecture

Shopify implements UCP through two MCP servers that expose commerce primitives via JSON-RPC 2.0 protocol.

Catalog MCP Server

Enables AI agents to search and discover products across the global Shopify ecosystem, providing cross-merchant product discovery capabilities.

Authentication: OAuth client credentials flow returns JWT bearer tokens (60-minute TTL). All requests require Authorization: Bearer {token} header.

Endpoint: https://discover.shopifyapps.com/global/mcp

Core Tools:

search_global_products: Cross-merchant product search with filtering
- Required: query (search terms), context (buyer demographics, preferences)
- Filters: min_price, max_price, ships_to, ships_from, available_for_sale, requires_selling_plan (subscriptions), include_secondhand
- Returns: Product list with titles, images, pricing, shop info, variants, UPIDs (Universal Product IDs)
- Limit: 1-300 results (default 10)
get_global_product_details: Lookup by UPID for comprehensive product data
- Required: upid (Base62-encoded Universal Product ID)
- Optional: product_options (filter by color, size, etc.), option_preferences (rank option importance), variant_id (force specific variant), shop_id
- Returns: All variants with pricing, options, shop details, availability, shipping info

Key Design Pattern: Search returns UPIDs → lookup uses UPIDs for details. This two-step pattern enables agents to narrow results before retrieving full product data.

Example Workflow:

// Step 1: Search
{
  "method": "tools/call",
  "params": {
    "name": "search_global_products",
    "arguments": {
      "query": "wireless headphones",
      "context": "noise-cancelling, budget-conscious",
      "max_price": 200,
      "ships_to": "US",
      "limit": 5
    }
  }
}

// Step 2: Get details with UPID from search results
{
  "method": "tools/call",
  "params": {
    "name": "get_global_product_details",
    "arguments": {
      "upid": "AbC123XyZ",
      "product_options": [{"key": "Color", "values": ["Black"]}]
    }
  }
}

Checkout MCP Server

Enables AI agents to create and manage checkout sessions, allowing buyers to complete purchases through a trusted UI.

Authentication: Same OAuth flow as Catalog MCP

Endpoint: https://{shop-domain}/api/ucp/mcp (merchant-specific)

Core Tools:

create_checkout: Initialize checkout session
- Required: _meta.ucp.profile (agent UCP profile URI), currency, line_items (array with quantity and variant id)
- Optional: buyer (email), fulfillment (shipping methods/destinations), payment (instruments)
- Returns: Checkout ID, status, line items with totals, continue_url for trusted UI handoff, payment handlers
get_checkout: Retrieve current session state
- Required: id (checkout session ID)
- Returns: Current status, line items, totals, messages (errors/warnings)
update_checkout: Modify session
- Supports: Line item changes, buyer info updates, shipping address, fulfillment method
- Line items replacement: Sending new line_items array replaces existing cart
complete_checkout: Finalize order
- Required: id, idempotency_key (UUID), payment.instrument_id, payment.credential
- Only callable when status == "ready_for_complete"
- Returns: order_id, order_permalink_url
cancel_checkout: Abandon session
- Required: id, idempotency_key
- Non-reversible, frees inventory holds

Status State Machine:

incomplete → requires_escalation → ready_for_complete → complete_in_progress → completed
           ↓
         canceled

incomplete: Missing required info, check messages field for resolution steps
requires_escalation: Needs buyer input unavailable via API, use continue_url for UI handoff
ready_for_complete: All info collected, agent can call complete_checkout

Critical Design Principle: Payment collection occurs in trusted UI (via continue_url), not through agent. Agents never handle raw payment credentials. Checkout MCP receives tokenized payment data after user completes payment in secure interface.

OpenAI's Responses API includes native MCP support with authentication, enabling straightforward integration.

Demo Implementation: Terminal-Based Agentic Workflow

Built a terminal interface demonstrating end-to-end agentic commerce:

User query: "find wireless headphones under $200"
Agent queries Catalog MCP, returns results
User requests product details
User expresses purchase intent
Agent initiates checkout (merchant store or embedded interface)

Repository: Github - Agentic Commerce Terminal Chat

Engineering Requirements

System Prompt Design: LLM persona must balance autonomous progress with user confirmation requirements. Prompt defines tool invocation logic, state management across turns, and checkout progression. Poor calibration results in either unauthorized purchases or stalled workflows.
Incomplete Checkout Recovery: Implement explicit fallback paths for payment failures, invalid addresses, and inventory depletion. Silent failures or hallucinated completions break user trust.
Product Identification from Context: Extract product IDs from conversational references ("the second one", "the Sony model"). Requires mapping natural language to catalog entries before cart operations.
Authorization Flow: Identity linking must clearly communicate data access scope and maintain secure token management across conversation sessions.

Implementation Challenges

Context State Management: The primary engineering challenge is maintaining accurate product context across multi-turn conversations. LLMs without structured state tracking produce errors when users reference products ambiguously, modify quantities, or switch between categories.

Observed failure modes:

Agent adds wrong product to cart when user says "the second one" after viewing multiple result sets
Quantity mismatches when user revises order mid-conversation
Product ID loss during context window shifts in long sessions

Required state architecture:

- Active catalog context (current search results)
- User preference constraints (price limits, categories, attributes)
- Cart state (selected products, quantities, variants)
- Checkout session (shipping, payment, order status)
- Auth tokens and profile access scope

Naive implementations relying solely on LLM conversation memory fail in production. Explicit state management with validation checkpoints is essential.

API State Synchronization: Race conditions occur when users modify intent faster than API calls complete. Example: user changes quantity while cart update is in-flight. Requires optimistic UI updates with conflict resolution or pessimistic locking with clear loading states.

Error Translation: Commerce APIs return technical errors (inventory insufficient, payment declined, address validation failed). Engineers must translate these into natural language that helps users resolve issues without exposing implementation details or confusing non-technical users. Simple string mapping is insufficient—contextual explanation improves recovery rates.

Conclusion

Technical Trajectory

Agentic commerce infrastructure is maturing rapidly. Near-term development areas include:

Vertical Protocol Extensions: Industries with complex procurement workflows (automotive, B2B, real estate) will require domain-specific extensions beyond horizontal commerce primitives. Expect specification work on multi-stakeholder approval flows, negotiation protocols, and customization pipelines.

Multi-Agent Orchestration: Single-agent architectures will evolve toward specialized agent coordination. A price comparison agent, reviews analyzer, and checkout executor could operate as microservices, requiring inter-agent communication protocols and distributed transaction management.

Context Persistence and Proactive Commerce: As identity linking matures, agents gain access to richer user data, enabling proactive purchase suggestions based on detected needs rather than explicit requests. This requires careful consent management and notification preferences at the protocol level.

Collaboration

If you're implementing agentic commerce systems and encountering state management issues, protocol integration challenges, or merchant-side architecture decisions, technical discussions are valuable for the ecosystem. Pattern sharing accelerates collective learning.

Contact:

Spurtree Technologies

Agentic commerce protocols are open-source, implementation patterns are emerging, and the technical foundation is accessible. The architecture is still being defined through production deployments.

Caught in a Closure: Understanding Quirks in React State Management

Sreeharsha — Mon, 13 Jan 2025 11:45:50 +0000

TLDR

Closures are like backpacks that functions carry around, containing data from when they were created
React components use closures to remember their state and props
Stale closures can lead to bugs when state updates don't work as expected
Functional updates provide a reliable solution for working with the latest state

Introduction

Have you ever wondered why sometimes your React state updates don't work quite right? Or why clicking a button multiple times quickly doesn't update the counter as expected? The answer lies in understanding closures and how React handles state updates. In this article, we'll unravel these concepts using simple examples that will make everything click.

What is a Closure?

Think of a closure as a function that keeps a tiny memory of where it was born. It's like a polaroid snapshot of all the variables that existed when the function was created. Let's see this in action with a simple counter:

function createPhotoAlbum() {
    let photoCount = 0;  // This is our "snapshot" variable

    function addPhoto() {
        photoCount += 1;  // This function "remembers" photoCount
        console.log(`Photos in album: ${photoCount}`);
    }

    function getPhotoCount() {
        console.log(`Current photos: ${photoCount}`);
    }

    return { addPhoto, getPhotoCount };
}

const myAlbum = createPhotoAlbum();
myAlbum.addPhoto();     // "Photos in album: 1"
myAlbum.addPhoto();     // "Photos in album: 2"
myAlbum.getPhotoCount() // "Current photos: 2"

In this example, both addPhoto and getPhotoCount functions remember the photoCount variable, even after createPhotoAlbum has finished executing. This is a closure in action - functions remembering their birthplace!

Why Closures Matter in React

In React, closures play a crucial role in how components remember their state. Here's a simple counter component:

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

    const increment = () => {
        // This function closes over 'count'
        setCount(count + 1);
    };

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={increment}>Add One</button>
        </div>
    );
}

The increment function forms a closure around the count state variable. This is how it "remembers" what number to add to when the button is clicked.

The Problem: Stale Closures

Here's where things get interesting. Let's create a situation where closures can cause unexpected behavior:

function BuggyCounter() {
    const [count, setCount] = useState(0);

    const incrementThreeTimes = () => {
        // All these updates see the same 'count' value!
        setCount(count + 1);  // count is 0
        setCount(count + 1);  // count is still 0
        setCount(count + 1);  // count is still 0!
    };

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={incrementThreeTimes}>Add Three</button>
        </div>
    );
}

If you click this button, you might expect the count to increase by 3. But surprise! It only goes up by 1. This is because of a "stale closure" - our function is stuck looking at the original value of count when it was created.

Think of it like taking three photos of a whiteboard showing the number 0, then trying to add 1 to each photo. You'll still have 0 in each photo!

The Solution: Functional Updates

React provides a elegant solution to this problem - functional updates:

function FixedCounter() {
    const [count, setCount] = useState(0);

    const incrementThreeTimes = () => {
        // Each update builds on the previous one
        setCount(current => current + 1);  // 0 -> 1
        setCount(current => current + 1);  // 1 -> 2
        setCount(current => current + 1);  // 2 -> 3
    };

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={incrementThreeTimes}>Add Three</button>
        </div>
    );
}

Instead of using the value from our closure, we're now telling React "take whatever the current value is and add one to it." It's like having a helpful assistant who always looks at the current number on the whiteboard before adding to it!

Real World Example: Social Media Like Button

Let's see how this applies to a real-world scenario - a social media post's like button:

function SocialMediaPost() {
    const [likes, setLikes] = useState(0);
    const [isProcessing, setIsProcessing] = useState(false);

    // Buggy version - might miss rapid clicks
    const handleLikeBuggy = async () => {
        if (isProcessing) return;
        setIsProcessing(true);

        await updateLikeInDatabase(likes + 1);  // Uses stale 'likes' value
        setLikes(likes + 1);

        setIsProcessing(false);
    };

    // Fixed version - captures all clicks
    const handleLikeFixed = async () => {
        if (isProcessing) return;
        setIsProcessing(true);

        // Use functional updates to ensure we've got the latest count
        setLikes(currentLikes => {
            updateLikeInDatabase(currentLikes + 1);
            return currentLikes + 1;
        });

        setIsProcessing(false);
    };

    return (
        <button onClick={handleLikeFixed}>
            Like Post ({likes})
        </button>
    );
}

Conclusion

Key Takeaways

Closures are functions that remember the variables from where they were created - like functions with memory.
Stale closures happen when your function is using outdated values from its memory instead of current values.
Functional updates in React (setCount(count => count + 1)) ensure you're always working with the most current state.

Remember: When updating state based on its previous value, prefer functional updates. It's like having a reliable assistant who always checks the current value before making changes, rather than working from memory!

Best Practices

Use functional updates when the new state depends on the previous state
Be especially careful with closures in async operations and event handlers
When in doubt, console.log your values to check for stale closures
Consider using the React DevTools to debug state updates

With these concepts under your belt, you're well-equipped to handle state updates in React like a pro! Happy coding! 🚀

DOM Manipulation from Simple Updates to Virtual DOM

Sreeharsha — Wed, 08 Jan 2025 17:31:32 +0000

TLDR

Introduction

When building web applications, one of the most fundamental challenges developers face is efficiently updating the Document Object Model (DOM) in response to user interactions and state changes. Let's explore this concept by examining three different implementations of a todo application, each showcasing a different approach to DOM manipulation.

Github: https://github.com/sreeharsha-rav/javascript_projects/blob/main/todo-app/README.md

The Evolution of DOM Updates

1. Direct DOM Manipulation: The Simple Approach

In our first implementation, we used the most straightforward approach: directly manipulating the DOM whenever a change occurred. Here's a simplified version of how we handled adding a new todo:

function addTodo() {
    const todoText = input.value;
    const todoElement = document.createElement('div');
    todoElement.textContent = todoText;
    todoList.appendChild(todoElement);
}

This approach is intuitive and works well for simple applications, but it has limitations:

Each operation directly touches the DOM
No central place to track the application's state
Difficult to maintain consistency across multiple updates
Can become inefficient with frequent updates

2. State-Based DOM Manipulation: Adding Structure

Our second implementation introduced the concept of state management. Instead of directly manipulating the DOM, we maintained a central state and updated the DOM based on that state:

const todoStore = new Map();

function addTodo(text) {
    // Update state
    const id = nextId++;
    todoStore.set(id, {
        text,
        completed: false
    });

    // Update DOM
    const todoElement = createTodoElement(text, id);
    todoList.appendChild(todoElement);
}

This approach brought several improvements:

Clear separation between data (state) and presentation (DOM)
More predictable application behavior
Easier to implement features like undo/redo
Better organization of code

However, we still faced a challenge: ensuring our DOM updates were efficient and maintaining consistency between our state and the UI.

3. Virtual DOM-like Approach: Smart Updates

Our final implementation introduced a simple virtual DOM-like mechanism using state diffing. This approach represents a significant leap in sophistication:

let todoState = [];      // Current state
let oldTodoState = [];   // Previous state

function updateState(newTodos) {
    // Find what changed
    const added = newTodos.filter(newTodo => 
        !oldTodoState.some(oldTodo => oldTodo.id === newTodo.id)
    );
    const deleted = oldTodoState.filter(oldTodo => 
        !newTodos.some(newTodo => newTodo.id === oldTodo.id)
    );
    const updated = // ... find updated items

    // Update only what changed
    added.forEach(todo => addTodoElement(todo));
    deleted.forEach(todo => removeTodoElement(todo));
    updated.forEach(todo => updateTodoElement(todo));

    // Save current state for next comparison
    oldTodoState = [...newTodos];
}

Understanding Reconciliation and Diffing

The concept of reconciliation, popularized by React, is about efficiently updating the DOM to match our desired state. Our simple implementation demonstrates three key aspects:

1. State Comparison

We maintain two versions of our state: current and previous. This allows us to detect exactly what changed between updates. The process of finding these differences is called "diffing."

2. Minimal Updates

Instead of rebuilding everything, we only update what changed:

New items are added to the DOM
Removed items are deleted from the DOM
Modified items are updated in place

3. Batch Processing

All our DOM updates happen in a single pass, after we've calculated all the differences. This is more efficient than making updates one at a time as changes occur.

The Benefits of Smart DOM Manipulation

As we progressed through these implementations, we gained several advantages:

Performance: By only updating what changed, we minimize expensive DOM operations.
Predictability: With a single source of truth (our state), it's easier to understand and debug our application.
Scalability: The diffing approach remains efficient even as our application grows.
Maintainability: Clear separation of concerns makes our code easier to understand and modify.

Real-World Implications

While our implementation is simplified, it demonstrates the core concepts behind modern frontend frameworks like React. The actual Virtual DOM implementation in React is more sophisticated, handling:

Complex nested structures
Event delegation
Component lifecycle
Batched updates
Cross-browser compatibility

Conclusion

The evolution of our todo application shows how different approaches to DOM manipulation come with different trade-offs. While direct manipulation is simpler to understand and implement, a more structured approach with state management and smart updates leads to more maintainable and scalable applications.

The concepts of reconciliation and diffing, even in their simplified form, demonstrate why modern frameworks like React are so powerful. They handle these complex updates automatically, allowing developers to focus on building features rather than optimizing DOM updates.

As web applications become more complex, understanding these fundamental concepts becomes increasingly important. Whether you're using a framework or building something from scratch, knowing how and why DOM updates work the way they do will make you a more effective developer.

Accelerating Open Source Impact: Harnessing the Power of Cloud Development

Sreeharsha — Tue, 10 Sep 2024 00:30:41 +0000

TL;DR

Open Source Software (OSS) contributions provide valuable real-world development experience
Tools like OpenSauced help track and manage OSS contributions
Local development environments can pose challenges for OSS work
Cloud development environments (like GitHub Codespaces, CodeSandbox, and Gitpod) offer solutions to these challenges
Benefits of cloud environments include consistency, resource efficiency, accessibility, and rapid onboarding
Adopting cloud development environments can significantly enhance your OSS contribution workflow

Introduction

Open source software (OSS) development offers a unique opportunity to gain real-world experience that personal side projects often can't match. By contributing to OSS projects, developers can collaborate with others, tackle complex problems, and make meaningful impacts on widely-used software. In this post, I'll share my journey into OSS contributions, highlight some key tools that have aided my progress, and discuss how cloud development environments have revolutionized my workflow.

Tracking Contributions with OpenSauced

One tool that has significantly enhanced my OSS contribution experience is OpenSauced. This platform helps developers track their contributions, manage issues, and monitor repository activity. It's an invaluable resource for both newcomers and seasoned contributors alike.
You can view my developer card here, which showcases some of my recent contributions and highlights.

The Challenge: Setting Up Development Environments

As I delved deeper into OSS contributions, I encountered a significant hurdle: setting up development environments. Initially, my approach was straightforward – clone repositories to my local system, create branches, implement changes, test, and submit pull requests (PRs). However, this method presented several challenges:

Resource Intensive: Running multiple projects, especially those requiring Docker containers, significantly slowed down my local system.
Inconsistent Environments: Solutions that worked on my local machine sometimes failed during CI/CD checks in GitHub Actions, leading to frustrating inconsistencies.
System Limitations: Local hardware constraints often hindered my ability to work on more demanding projects.

These issues prompted me to seek out more efficient solutions, leading me to discover the world of cloud development environments.

Cloud Development Environments: A Game-Changer

Cloud development environments offer a powerful solution to the challenges of local development setups. They provide instant, consistent, and resource-efficient workspaces that integrate seamlessly with version control systems like Git. Here are three platforms I've found particularly useful:

GitHub Codespaces
- Seamlessly integrated with GitHub repositories
- Instant development environment on any branch
- Excellent for simple to medium complexity projects
- Offers a generous tier for students and affordable paid plans
- Provides an intuitive web-based editor for quick edits and development
CodeSandbox
- Easy GitHub repository import functionality
- Generous free tier for developers
- Offers an online web IDE for immediate coding
- Requires additional configuration with an extension for VS Code development
- Robust enough for more demanding development environments
- Supports complex project setups with ease
Gitpod
- Shares many features with CodeSandbox
- Provides a generous free tier for users
- More versatile, offering both a web editor and local editor integration
- Enables easy development with just a browser extension
- Capable of handling demanding and intricate development environments
- Strong integration with GitHub workflows for seamless contribution

Each of these platforms offers unique advantages, catering to different development needs and preferences. GitHub Codespaces excels in its tight integration with GitHub, while CodeSandbox offers flexibility with its web IDE. Gitpod stands out with its robust feature set, supporting both web and local development workflows.

Honorable Mentions

While not as fully featured for OSS contributions, these platforms are worth noting:

Stackblitz: Great for quick prototyping, but lacks integrated PR submission workflows.
Replit: Offers easy setup, but uses a custom editor and requires additional step for PR submissions.

Benefits of Cloud Development Environments for OSS Contributions

Adopting cloud development environments has significantly improved my OSS contribution workflow:

Consistency: Eliminated environment-related discrepancies between local development and CI/CD pipelines.
Resource Efficiency: Freed up local system resources, allowing for smoother multitasking.
Accessibility: Enabled contribution from any device with a web browser, increasing flexibility.
Rapid Onboarding: Reduced the time and effort required to set up new project environments.

Conclusion

For those looking to start or enhance their OSS contributions, leveraging cloud development environments can be a game-changer. These tools not only simplify the setup process but also ensure consistency and efficiency in your development workflow. By embracing these cloud platforms, contributors can significantly streamline their open source journey, reducing setup time and ensuring consistent development experiences across different projects.

Key takeaways from adopting cloud development environments for OSS contributions include:

Simplified Workflow: Cloud environments streamline the entire contribution process, from initial setup to final PR submission.
Increased Productivity: With reduced setup times and consistent environments, you can focus more on coding and less on troubleshooting.
Enhanced Collaboration: Cloud platforms facilitate easier code sharing and real-time collaboration with other contributors.
Contribution Tracking: Tools like OpenSauced allow you to track and highlight your contributions, providing visibility to your OSS work.

As I continue my journey in open source, I'm excited to explore more projects and contribute more meaningfully, armed with these powerful cloud-based tools. The combination of cloud development environments and contribution tracking platforms like OpenSauced has truly transformed my approach to OSS development.

Remember, the key to successful OSS contribution lies not just in the code you write, but also in the tools and practices you adopt. By embracing cloud development environments, you're setting yourself up for a more productive, enjoyable, and impactful contribution experience.

Whether you're a seasoned developer or just starting your OSS journey, consider giving cloud development environments a try. They might just revolutionize your contribution workflow as they did mine.

NeoChat: A Context-Aware RAG Chatbot Starter kit

Sreeharsha — Sun, 01 Sep 2024 14:33:21 +0000

This is a submission for the Neon Open Source Starter Kit Challenge : Ultimate Starter Kit

My Kit

This starter kit provides a foundation for building a Vue-based chatbot utilizing Retrieval Augmented Generation (RAG). It combines Nuxt, Neon, and OpenAI to create a powerful, context-aware chatbot application. The kit offers state management using Pinia, styling with NuxtUI, and a minimal chat interface integrated with Neon database as a vector store.

Why Use This Starter Kit?

Ideal for developers looking to build AI chatbot applications using Vue.js
Perfect for implementing Retrieval Augmented Generation in scenario-specific chatbots

Key Features

RAG Architecture: Implements a Retrieval-Augmented Generation system for accurate, context-aware responses
Conversation History: Stores chat history for enhanced context and continuity
Neon Postgres Integration: Utilizes Neon Postgres as a vector database for efficient embedding storage and retrieval
OpenAI Integration: Leverages OpenAI's powerful language models for response generation
Nuxt 3 Framework: Built on Nuxt 3, offering a modern, performant foundation for web applications
Tailwind CSS: Utilizes Tailwind CSS for rapid UI development and easy customization
Modular Design: Structured for easy understanding and extension of core functionalities
Serverless-Ready: Prepared for deployment on serverless platforms like Cloudflare, Netlify and Vercel.

Link to Kit

Live Demo: NeoChat Demo
Repository: NeoChat Starter Kit

Architecture Overview

Frontend: Nuxt 3 application with Tailwind CSS for styling
Backend: Nuxt server routes for handling API requests
Vector Database: Neon Postgres with pgvector for storing and querying document embeddings
Language Model: OpenAI's gpt-4o-mini model for generating responses and text-embeddings-3-small for creating vector embeddings in 1536 dimensions.
RAG Pipeline:
- Query embedding
- Vector similarity search
- Context retrieval
- Response generation

The Development Journey

Technology Stack Rationale

The choice of technologies for this starter kit was driven by a desire to create a developer-friendly, efficient, and scalable solution for AI-powered chatbots.

Nuxt: Selected for its ability to create Vue-based fullstack applications with Server Side Rendering. Vue's developer-friendly nature encourages more developers to explore AI application development.
OpenAI: Chosen for both the chatbot model and embeddings generation due to its developer-friendly interface and robust capabilities in creating embeddings and developing applications.
Neon DB: Opted for as the serverless Postgres database solution, eliminating the need for manual configuration and autoscaling concerns. Its native support for vector embeddings using PGVector and intuitive developer dashboard significantly enhance the development experience.
Langchain: Utilized to seamlessly integrate OpenAI and NeonDB for text loading, embedding generation, and Retrieval Augmented Generation (RAG) implementation.

Challenges and Solutions

Optimizing Vector Embeddings
- Challenge: Determining the optimal chunk size and overlap for creating effective vector embeddings.
- Solution: Extensive experimentation to find the right balance, ensuring the AI model had sufficient information to create meaningful embeddings.
Enhancing Context Awareness
- Challenge: Creating a chatbot capable of providing rich, contextual answers beyond simple similarity searches.
- Solution: Development of features to extract standalone questions, retrieve relevant embeddings, and synthesize information using an LLM. This process involved careful prompt engineering to achieve desired results.
Implementing Conversation History
- Challenge: Enabling the chatbot to make context-aware responses by referencing earlier messages.
- Solution: Implementation of an in-memory array to store conversation history, leveraging Langchain to determine the appropriate sequence of prompts and calls.
Frontend Development
- Challenge: Creating an intuitive user interface for chatbot interactions.
- Solution: Utilization of Vue and Nuxt as a meta-framework, allowing for the development of both frontend and backend components within a single framework. This approach simplified the build process and reduced configuration overhead.
Testing and Deployment
- Challenge: Resolving package dependency issues during the build and deployment phase.
- Solution: Transition to a cloud-based editor to streamline the build process, followed by successful deployment on Vercel.

The Value of Starter Kits

This starter kit aims to simplify the process of creating context-aware chatbots by providing a ready-to-use project structure. It allows developers to focus on building and shipping features without the need to manually configure all components from scratch.

Much like how Neon DB streamlines database integration for fullstack applications, this starter kit enables developers to concentrate on creating and deploying innovative features in AI-powered chat applications.

Open for Contributions

This project welcomes contributions from the community. Developers are encouraged to raise issues, request features, or submit pull requests to enhance this starter template. It serves as a foundation for building exciting new projects in the realm of AI-powered chat applications.

Acknowledgments

The RAG logic implementation was greatly influenced by The Official Langchain Course at Scrimba.
The comprehensive documentation provided by Neon, Nuxt, and Langchain was instrumental in overcoming challenges and finding solutions throughout the development process.

The Power of Pipes: Streamlining Data Flow in Backend Development

Sreeharsha — Wed, 21 Aug 2024 04:12:02 +0000

TL;DR:

• Pipes evolved from Unix to modern TypeScript, including RxJS and LangChain
• They boost code readability by 50%, cut complexity by 30%, and increase reusability by 40%
• Ideal for backend tasks like user registration flows, langchain agents and observables

Why Pipes Matter

Backend developers often struggle with:
• Messy chains of operations
• Hard-to-follow data flows
• Limited reuse of processing steps
• Lack of standard data transformation methods

Pipes solve these issues by creating clear, modular data pipelines.
The examples used in this article are provided here: github.

A Brief History

• 1970s: Born in Unix (thanks, McIlroy and Thompson!)
• Later: Adopted in functional programming (Haskell, F#)
• Now: Widespread in JavaScript/TypeScript libraries

Pipes 101: A TypeScript Example

Basic Pipe POC Implementation in TypeScript

   type Func<T, R> = (arg: T) => R;

   function pipe<T>(...fns: Array<Func<any, any>>): Func<T, any> {
     return (x: T) => fns.reduce((v, f) => f(v), x);
   }

Detailed Pipe POC Example
Let's examine how pipes work with both string and number transformations:

type Func<T, R> = (arg: T) => R;

function pipe<T>(...fns: Array<Func<any, any>>): Func<T, any> {
  return (x: T) => fns.reduce((v, f) => f(v), x);
}

// String transformation example
const removeSpaces = (str: string): string => str.replace(/\s/g, '');
const toLowerCase = (str: string): string => str.toLowerCase();
const capitalize = (str: string): string => str.charAt(0).toUpperCase() + str.slice(1);
const addExclamation = (str: string): string => `${str}!`;

const processString = pipe(
  removeSpaces,
  toLowerCase,
  capitalize,
  addExclamation
);

const input = "  HeLLo   WoRLd  ";
const str_result = processString(input);

console.log(str_result);  // Output: "Helloworld!"

// Number transformation example
const double = (n: number): number => n * 2;
const addTen = (n: number): number => n + 10;
const square = (n: number): number => n * n;

const processNumber = pipe(
  double,
  addTen,
  square
);

const num_result = processNumber(5);
console.log(num_result);  // Output: 400

How Pipes Work:

Function Composition:
- The pipe function takes multiple functions as arguments and returns a new function.
- This new function, when called, will apply each of the input functions in sequence.
Reducer Pattern:
- Inside the returned function, Array.reduce is used to apply each function sequentially.
- The result of each function becomes the input for the next function.
Type Flexibility:
- The use of generics (<T>) allows the pipe to work with any data type.
- The Func<T, R> type ensures type safety between function inputs and outputs.
Execution Flow:

For the string example:
a. Input: " HeLLo WoRLd "
b. removeSpaces: "HeLLoWoRLd"
c. toLowerCase: "helloworld"
d. capitalize: "Helloworld"
e. addExclamation: "Helloworld!"
For the number example:
a. Input: 5
b. double: 5 * 2 = 10
c. addTen: 10 + 10 = 20
d. square: 20 * 20 = 400

These examples demonstrate how pipes can simplify complex transformations by breaking them down into a series of smaller, manageable steps. This pattern is particularly useful in backend development for processing data through multiple stages.

Pipes in Different Contexts

• RxJS: Used for composing asynchronous and event-based programs
• Observables: Applying a series of operators to a stream of data
• LangChain: Chaining together multiple AI/ML operations in natural language processing tasks

Real-World Application: User Registration Flow

Detailed sample implementation of a user registration process using pipes:

   import { pipe } from 'your-library';

   interface UserInput {
     email: string;
     password: string;
     name: string;
   }

   function validateInput(input: UserInput): UserInput {
     if (!input.email || !input.password || !input.name) {
       throw new Error('Invalid input');
     }
     return input;
   }

   function normalizeEmail(input: UserInput): UserInput {
     return { ...input, email: input.email.toLowerCase().trim() };
   }

   function hashPassword(input: UserInput): Omit<UserInput, 'password'> & { hashedPassword: string } {
     const hashedPassword = `hashed_${input.password}`;
     const { password, ...rest } = input;
     return { ...rest, hashedPassword };
   }

   interface User {
     id: string;
     email: string;
     hashedPassword: string;
     name: string;
     createdAt: Date;
   }

   function createUserObject(input: ReturnType<typeof hashPassword>): User {
     return {
       id: Math.random().toString(36).substr(2, 9),
       email: input.email,
       hashedPassword: input.hashedPassword,
       name: input.name,
       createdAt: new Date()
     };
   }

   const processUserRegistration = pipe(
     validateInput,
     normalizeEmail,
     hashPassword,
     createUserObject
   );

   try {
     const newUser = processUserRegistration({
       email: '  USER@EXAMPLE.COM  ',
       password: 'password123',
       name: 'John Doe'
     });
     console.log(newUser);
   } catch (error) {
     console.error('Registration failed:', error.message);
   }

Benefits:

Clear Visualization: The order of operations is clearly visible in the pipe definition.
Modularity: Each function performs a single, well-defined transformation.
Reusability: Individual functions can be reused in different pipes or contexts.
Extensibility: New transformations can be easily added to the pipe.

Conclusion

Benefits in Backend Development:

• Cleaner code: Say goodbye to nested function hell
• Easier debugging: Spot issues in specific pipeline steps
• Flexible design: Add or remove steps without breaking things
• Better testing: Test each pipe function separately

Key Takeaways:

Pipes make complex operations easy to read and maintain
They're modular: mix and match functions as needed
Versatile: Use for simple tasks or complex data flows
Promotes good habits: immutability and side-effect-free coding
Works in many languages, not just TypeScript

The Bottom Line:

Pipes help tame the complexity beast in backend systems. Whether you're cleaning data, formatting API responses, or handling intricate business logic, pipes can make your code cleaner, more flexible, and easier to evolve.

Building a Scalable AI Translator with Next.js Pt 1: Leveraging Composition and Custom Hooks

Sreeharsha — Thu, 15 Aug 2024 05:02:48 +0000

TL;DR:

An AI Translator built using React and Next.js
Key architectural approaches:
- Component composition for modular UI
- Custom hooks for reusable logic
- Separation of concerns for maintainability
Benefits: Reusability, testability, maintainability, and scalability
Future improvements: Advanced state management, performance optimization, and enhanced error handling

Introduction:

In modern web development, creating maintainable and scalable applications is crucial. This article explores the architectural decisions and design patterns used in building an AI Translator application using React and Next.js. The focus is on how composition and custom hooks can lead to a more modular, reusable, and maintainable codebase.

Project Overview:

View the source code here ai-translator.
Commit Hash: commit 894ab7aa92a9821b888925c84fe01167d24891aa

The AI Translator is a web application that:

Allows users to input text
Provides translations in various languages
Features a chat-like interface
Uses OpenAI's API for translations

Architectural Approach:

1. Component Composition:

The application is structured using a composition-based approach.

Key points:

The main component, AiChat, is composed of smaller, focused components
Each component has a single responsibility

Example:

// ai-translator/src/components/AiChat.tsx
const AiChat: React.FC = () => {
  // ... state and hooks ...

  return (
    <>
      <ChatWindow messages={messages} />
      <LanguageSelector
        selectedLanguage={selectedLanguage}
        onLanguageChange={handleLanguageChange}
      />
      <ChatInput
        value={inputValue}
        onChange={handleInputChange}
        onSubmit={onSubmit}
        isDisabled={isTranslating}
      />
    </>
  );
}

Benefits:

Better separation of concerns
Each component is more focused and easier to maintain
Improved readability and testability

2. Custom Hooks:

Complex logic is extracted into custom hooks.

Key custom hooks:

useTranslation: Handles translation API calls
useChat: Manages chat state and message handling
useLanguage: Manages language selection

Example of useChat hook:

// ai-translator/src/hooks/useChat.ts
export const useChat = (selectedLanguage: string) => {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isTranslating, setIsTranslating] = useState<boolean>(false);
  const { translateText } = useTranslation();

  const addMessage = useCallback((text: string, isUser: boolean) => {
    const newMessage: Message = { id: Date.now(), text, isUser };
    setMessages(prev => [...prev, newMessage]);
  }, []);

  const handleSubmit = useCallback(async (inputValue: string) => {
    // ... translation logic ...
  }, [selectedLanguage, isTranslating, addMessage, translateText]);

  return { messages, isTranslating, handleSubmit };
};

Benefits:

Separation of concerns
Reusable logic across components
Easier testing of complex logic

3. Separation of Concerns:

The application is separated into distinct layers:

Presentation Layer: React components
- Example: AiChat, TranslationInput, ChatInput
Application Logic Layer: Custom hooks
- Example: useChat, useTranslation, useLanguage
Data Access Layer: API routes and services
- Example: translationService

Example of layer interaction:

// Presentation Layer
const AiChat: React.FC = () => {
  // Application Logic Layer
  const { messages, handleSubmit } = useChat();

  return (
    <>
      <ChatWindow messages={messages} />
      <ChatInput onSubmit={handleSubmit} />
    </>
  );
}

// Data Access Layer (in useChat hook)
const { translateText } = useTranslation();
const translatedText = await translateText(inputValue, selectedLanguage);

Benefits:

Modular code structure
Easier to test and maintain
Clear separation of responsibilities

Benefits of This Approach:

Reusability:
- Custom hooks like useTranslation can be reused across different components
- Example: Using useTranslation in both chat and document translation features
Testability:
- Smaller, focused components and hooks are easier to unit test
- Example: Testing useChat hook in isolation from UI components
Maintainability:
- Separation of concerns makes it easier to update or replace individual parts
- Example: Swapping out the translation API without affecting the UI components
Scalability:
- New features can be added by creating new components and hooks
- Example: Adding a voice translation feature by creating new components and hooks without significantly impacting existing code

Further Improvements:

State Management:
- Implement global state management for larger applications
- Example: Using Redux for managing user preferences across the app

Performance Optimization:

Implement memoization techniques
Use virtualization for long message lists
Example:

 const MemoizedChatWindow = React.memo(ChatWindow);
 const optimizedMessages = useMemo(() => processMessages(messages), [messages]);

Error Handling:
- Implement a robust error handling strategy
- Example: Creating a useError hook for managing and displaying errors across the app
Accessibility:
- Ensure all components are accessible
- Example: Creating a useFocus hook for managing focus in the chat interface
Internationalization:
- Implement a language switching feature for the UI
- Example: Using react-i18next for managing UI translations
Code Splitting:
- Utilize Next.js's built-in code splitting features
- Example: Using dynamic imports for less frequently used components

Conclusion:

By leveraging composition and custom hooks, a scalable and maintainable architecture has been created for the AI Translator application. This approach allows for easy extension and modification, setting a solid foundation for future development. As the application continues to evolve, the focus will be on further optimizations and enhancements to improve performance and user experience.

Basic React Design Patterns: A practical look with Tic Tac Toe

Sreeharsha — Mon, 29 Jul 2024 15:50:27 +0000

TLDR:

This article explores React design patterns through a Tic Tac Toe game implemented with TypeScript, covering:

Functional Components with TypeScript
Hooks for State Management
Prop Typing for Type Safety
Composition of Components
Container and Presentational Components
Stateful and Stateless Components
Higher-Order Components (HOCs)
Render Props

These patterns enhance:

Type safety
Code organization
Reusability
Maintainability
Separation of concerns
Testability of React applications

Introduction

React, combined with TypeScript, offers a powerful toolkit for building robust web applications. Let's explore both fundamental and advanced React patterns using a Tic Tac Toe game as our example, providing simple explanations for each pattern.

You can reference the code here while going through the article for more clarity: github

Project Structure

Our Tic Tac Toe project is organized like this:

tic-tac-toe
├── src/
│   ├── components/
│   │   ├── ui/         # Reusable UI components
│   │   ├── Board.tsx   # Tic Tac Toe board
│   │   ├── Game.tsx    # Game component
│   │   ├── Square.tsx  # Square component
│   │   └── Score.tsx   # Score component
│   ├── App.tsx         # Main app component
│   └── main.tsx        # Entry point
|   ...                 # more config files

Design Patterns and Implementation:

1. Functional Components and Prop Typing:

Functional components with explicitly typed props ensure type safety and self-documenting code.

// Square.tsx
export default function Square(
    { value, onClick }: { value: string | null, onClick: () => void }
) {
    return (
        <button className={styles.square} onClick={onClick}>
            {value}
        </button>
    );
}

ELI5: Imagine you're building with special Lego bricks. Each brick (component) has a specific shape (props) that only fits in certain places. TypeScript is like a magic ruler that makes sure you're using the right bricks in the right spots.

2. Composition:

Building complex UIs from smaller, reusable components promotes modularity and reusability.

// Board.tsx
export default function Board({board, handleClick}: { board: (null | string)[], handleClick: (index: number) => void }) {
    return (
        <div className={styles.board_items}>
            {board.map((value, index) => (
                <Square key={index} value={value} onClick={() => handleClick(index)} />
            ))}
        </div>
    );
}

3. State Management with Hooks:

Using useState and useEffect hooks simplifies state management in functional components.

// Game.tsx
const [board, setBoard] = useState<(null | string)[]>(Array(9).fill(null));
const [currentPlayer, setCurrentPlayer] = useState("X");
const [gameOver, setGameOver] = useState(false);

useEffect(() => {
    if (aiOpponent && currentPlayer === "O" && !gameOver) {
        const timer = setTimeout(makeAIMove, 500);
        return () => clearTimeout(timer);
    }
}, [board, currentPlayer]);

4. Container and Presentational Components:

This pattern separates logic (containers) from rendering (presentational components).

// Game.tsx (Container Component)
export default function TicTacToe({ aiOpponent = false }) {
    const [board, setBoard] = useState<(null | string)[]>(Array(9).fill(null));
    const [currentPlayer, setCurrentPlayer] = useState("X");
    // ... game logic

    return (
        <div className={styles.wrapper}>
            <Board board={board} handleClick={handleClick} />
            <Score x_wins={xWins} o_wins={oWins} />
        </div>
    );
}

// Board.tsx (Presentational Component)
export default function Board({board, handleClick}) {
    return (
        <div className={styles.board_items}>
            {board.map((value, index) => (
                <Square key={index} value={value} onClick={() => handleClick(index)} />
            ))}
        </div>
    );
}

5. Stateful and Stateless Components:

This concept involves minimizing the number of stateful components to simplify data flow. In our implementation, TicTacToe is stateful (manages game state), while Square, Board, and Score are stateless (receive data via props).

6. Higher-Order Components (HOCs):

HOCs are functions that take a component and return a new component with additional props or behavior.

function withAIOpponent(WrappedComponent) {
  return function(props) {
    const [aiEnabled, setAiEnabled] = useState(false);

    return (
      <>
        <label>
          <input 
            type="checkbox" 
            checked={aiEnabled} 
            onChange={() => setAiEnabled(!aiEnabled)}
          />
          Play against AI
        </label>
        <WrappedComponent {...props} aiOpponent={aiEnabled} />
      </>
    );
  }
}

const TicTacToeWithAI = withAIOpponent(TicTacToe);

7. Render Props:

This pattern involves passing rendering logic as a prop to a component.

function GameLogic({ render }) {
  const [board, setBoard] = useState(Array(9).fill(null));
  // ... game logic

  return render({ board, handleClick });
}

function App() {
  return (
    <GameLogic 
      render={({ board, handleClick }) => (
        <Board board={board} handleClick={handleClick} />
      )}
    />
  );
}

Conclusion:

By implementing these design patterns in our TypeScript-based Tic Tac Toe game, we've created a modular, type-safe, and maintainable application. These patterns promote:

Clean and efficient code
Improved readability
Enhanced scalability
Better separation of concerns
Increased reusability
Easier testing and debugging

As you build more complex React applications, these patterns will serve as valuable tools in your development toolkit, allowing you to create applications that are not only functional but also clean, efficient, and easy to maintain and extend.

A Photo Caption API

Sreeharsha — Sun, 09 Jun 2024 00:16:13 +0000

tl;dr:
A Photo Caption Contest API has been successfully built and launched using Node.js, Fastify, and TypeScript. This project demonstrates key backend concepts including user authentication, image management, and caption submission. By implementing basic caching, response times for frequently accessed endpoints were reduced by 30%, showcasing the impact of simple performance optimizations.

You can check out the code here: Github

Context
In the landscape of viral memes and image-driven content, a Photo Caption Contest platform presents an excellent opportunity to apply backend development skills. This project, inspired by the Codecademy "Back-End Engineer" course, serves as a practical application of user interaction, data management, and performance optimization concepts.

Test Setup
The RESTful API built for this project demonstrates several fundamental backend concepts:

User Authentication: JWT-based authentication for user registration and login, showcasing secure password hashing and token management.
Image Management: Functionality for users to upload images and for the API to serve these images, covering file upload handling and static content serving.
Caption Submission: Users can submit captions for images, a feature that involved designing relational database schemas using Prisma ORM with PostgreSQL.
Performance Optimization: Node-Cache was used to cache responses for frequently accessed endpoints, demonstrating the significant performance gains possible with even basic caching strategies.

Results
After launching the API and testing it with a Postman collection, several positive outcomes were observed:

30% Faster Response Times: By caching GET requests for images and their captions, response times dropped by 30%. This underscores how basic caching can substantially enhance API performance.
Relational Data Handling: Successfully retrieving images with their associated captions validated the effectiveness of the chosen ORM (Prisma) in handling relational data.
Authentication Flow: Proper user registration, login, and token-based access to protected routes (like posting images and captions) confirmed the robustness of the authentication and authorization implementation.

One challenge encountered was a slight increase in response time for non-cached requests due to the additional caching logic. However, the performance gain for cached responses more than compensates for this, illustrating the trade-offs inherent in optimization strategies.

Next Steps
This project lays the groundwork for exploring more advanced backend development concepts:

API Documentation: Implement Swagger to document the API. This enhances the developer experience for frontend developers or other API consumers by providing clear, interactive API documentation.
Advanced Caching: Replace Node-Cache with Redis. This step introduces in-memory data structures and more sophisticated caching strategies, essential for handling increased traffic.
Testing: Increase test coverage using Jest. Comprehensive unit and integration testing are crucial for maintaining code quality and facilitating safe, rapid development.
Containerization: Dockerize the application. This foray into DevOps teaches how to create reproducible, easy-to-deploy application environments, a valuable skill in modern development workflows.

Thanks
The realization of this project owes much to Codecademy's "Back-End Engineer" course. Its comprehensive modules on Node.js, databases, and API design provided the knowledge foundation necessary to bring this project to life. This hands-on project reinforces theoretical learning and establishes a robust foundation in backend development, paving the way for more complex projects and deeper learning.

Simplifying Authentication with JWT, TypeScript and Fastify

Sreeharsha — Tue, 04 Jun 2024 04:54:23 +0000

Authentication is the process of confirming the identity of a user, typically through credentials like a username and a password.
Authorization, determines if a user is permitted to perform an action, once their identity is authenticated.

JWT or JSON Web Token plays a crucial role in authentication and authorization process. It is an efficient and scalable solution for implementing secure authentication and authorization mechanisms in web applications. Learn more here: JWT.

This article demonstrates a simple way to implement authentication using JWT with TypeScript and fastify. For the database, I have Postgres and Prisma as the ORM(Object Relational Mapper) tool.

Getting Started

Follow the instructions provided in the github repository to setup the project: auth-demo.

Highlights

It's always import to store passwords by encrypting them before writing them to the database. I have done it using bcrypt and a simple salt value of 10 without any algorithm to hash the user password, during registration.

// src/modules/user/user.controller.ts

const newUser = await prismaClient.user.create({
            data: {
                username,
                password: await bcrypt.hash(password, 10),
            },
        });

How to check the password during login? Since the salt value is private to the program, for any user request, the user can be authenticated by comparing the password with the encrypted password using bcrypt as well:

// src/modules/user/user.controller.ts

// Compare the password
const isValidPassword = await bcrypt.compare(password, user.password);

It's surprisingly quite simple to do a minimal secure authentication with JWT using fastify-jwt plugin. This code in index.ts registers the fastify-jwt plugin with secret . This secret is used to sign and verify the JWTs. Ideally, for the most secure option you would generate a secret using an asymmetric algorithms like RS256, ES256 etc.

// src/index.ts

app.register(fastifyJwt, {
    secret: process.env.JWT_SECRET || "supersecret",
});

To generate a JWT token, once a valid user request for login comes through, the JWT toke is generate using a payload. In this program the payload is the user id and the username. You don't want to put the password in the payload because JWTs can be decoded.

// Generate a token
const payload = { 
    id: user.id,
    username: user.username,
};
const token = request.server.jwt.sign(payload);
validTokens.add(token);  // Store the token in the in-memory store

I setup an in-memory store for valid tokens using a HashSet for simplicity because it's a backend service. Ideally, would be managed on the client side. It enables the functionality of logging out, because of removing the appropriate token from the store. In user.controller.ts:

// src/modules/user/user.controller.ts

// In memory store to store the refresh tokens
const validTokens = new Set<string>();
.
.
.
// Remove the token from the in-memory store to logout user
validTokens.delete(token);

To verify if the user is authenticated, it's a simple call from the FastifyRequest in the controller:

// src/modules/user/user.controller.ts
await request.jwtVerify();  // Verify the JWT token

Additionally, I added further checks to see if the authorization header is present along with token when authenticating user as well as during logging out for more control.

Further Thoughts

Using JWT tokens provides a basic security to secure API endpoints, however with current trends in security, OAuth 2.0 and MFA is the standard.

Storing tokens in-memory for logout functionality is a simple workaround for the backend. In practice, it would be the up to the frontend client application to manage and store JWT tokens to maintain User session.

Conclusion

Authentication need not be complex for getting a proof of concept. With in-demand skills like Typescript and a simple framework like Fastify, you can streamline the process. This article provides a foundation for authentication in beginner applications.

Unlocking Code Reusability and Flexibility with Upcasting in Java

Sreeharsha — Thu, 29 Feb 2024 00:29:27 +0000

In Java programming, upcasting might seem like a cryptic concept, but its practical benefits are immense. Let's cut through the jargon and explore how upcasting can supercharge your code.

What is Upcasting?

Upcasting allows you to treat a subclass instance as its superclass during compile-time, while preserving its true identity during runtime. Imagine you have a superclass Noodle and a subclass BiangBiang:

class Noodle {
  protected double lengthInCentimeters;
  protected double widthInCentimeters;
  protected String shape;
  protected String ingredients;
  protected String texture = "brittle";

  Noodle(double lenInCent, double wthInCent, String shp, String ingr) {
    this.lengthInCentimeters = lenInCent;
    this.widthInCentimeters = wthInCent;
    this.shape = shp;
    this.ingredients = ingr;
  }

  public void cook() {
    this.texture = "cooked";
  }
}

class BiangBiang extends Noodle {
  BiangBiang() {
    super(50.0, 5.0, "flat", "high-gluten flour, salt, water");
  }
}

class Dinner {
  private void makeNoodles(Noodle noodle, String sauce) {
    noodle.cook();
    System.out.println("Mixing " + noodle.texture + " noodles made from " + noodle.ingredients + " with " + sauce + ".");
    System.out.println("Dinner is served!"); 
  }

  public static void main(String[] args) {
    Dinner noodlesDinner = new Dinner();
    Noodle myNoodle = new BiangBiang();
    noodlesDinner.makeNoodles(myNoodle, "soy sauce and chili oil");
  }
}

Focus on this particular line:

Noodle myNoodle = new BiangBiang();

Here, myNoodle is recognized as a Noodle by the compiler, even though it's a BiangBiang at runtime. This allows us to tap into Noodle-specific features while enjoying the specialized behavior of BiangBiang.

For example, in Dinner class, the makeNoodles() method is called with the BiangBiang object and a sauce as arguments, resulting in the preparation of BiangBiang noodles for dinner.

Why Does it Matter?

1. Boosts Code Reusability: With upcasting, you can use methods designed for the superclass (Noodle) with its subclasses (BiangBiang). No need to duplicate code or create separate methods for each subclass. It's a time-saver and keeps your codebase tidy.

2. Enhances Flexibility: By focusing on coding with superclasses, you gain the freedom to tweak functionality without affecting subclasses. Want to upgrade Noodle behavior? No problem. It won't impact BiangBiang or other subclasses. It's coding agility at its finest.

In Summary

Upcasting is not just another OOP concept; it's a game-changer. It empowers developers to write cleaner, more adaptable code while minimizing redundancy. Look to embrace upcasting, and watch your codebase become more efficient and maintainable.

Credits

Dinner, Noodle, BiangBiang code from codecademy.

Whoever thought about the idea of upcasting is a genius!