​

UOM Assistant Frontend: System Architecture & Routing Design

​

1. System Topology & Communication Interfaces

​

1.1 Client-Server Boundaries

• Next.js Frontend (localhost:3001): Executed as a Node.js Server providing SSR, Proxy, App Router, Server Functions, etc., bundling assets for the Client’s browser (most of the assistant-ui components run in the browser). It runs the UI layout, holds temporary config values, manages active thread context, and renders stream output.
• Next.js API Passthrough Proxy: Executed on the Next.js server node. It routes requests, injects credentials, and shields sensitive downstream APIs from client visibility.
• LangGraph Agent Server (localhost:2024): Orchestrates the translation steps, runs agent iterations, manages the thread history database (using Postgres and Redis checkpointers), and coordinates with the compilation sandboxes.

​

2. Core Libraries

• Assistant-UI: The frontend uses the assistant-ui library for core chat thread components, message rendering, and the composer input. Custom wrappers and extensions are implemented to integrate with the LangGraph runtime and support the specific translation pipeline steps.
• LangGraph SDK: The frontend uses the @langchain/langgraph-sdk client to communicate with the Next.js API proxy routes, which then forward requests to the LangGraph backend server.
• Shadcn UI & Radix UI & Tailwind CSS: The UI styling is built on top of Shadcn UI components, Radix headless primitives, and Tailwind CSS utilities.

​

3. Next.js API Passthrough Routing & Security

​

3.1 Proxy Implementation & File Mappings

• File Path: frontend/uom-translator-ui/app/api/[..._path]/route.ts
• Runtime: nodejs
• Code Implementation:
  import { initApiPassthrough } from "langgraph-nextjs-api-passthrough";
  
  export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
  	initApiPassthrough({
  		apiUrl: process.env.LANGGRAPH_API_URL,   // E.g., http://localhost:2024
  		apiKey: process.env.LANGSMITH_API_KEY,   // Injected securely on the server
  		runtime: "nodejs",
  	});
  

​

3.2 Routing Mechanics

​

4. Client-Side SDK Initialization

• File Path: frontend/uom-translator-ui/lib/chatApi.ts

​

4.1 Client Factory Implementation

import { Client } from "@langchain/langgraph-sdk";

export const createClient = () => {
	const apiUrl =
		process.env.NEXT_PUBLIC_LANGGRAPH_API_URL ||
		(typeof window !== "undefined"
			? new URL("/api", window.location.href).href
			: "/api");
	return new Client({ apiUrl });
};

• Browser/Server Resolution: If NEXT_PUBLIC_LANGGRAPH_API_URL is not provided, the factory checks if it is running in the client browser (typeof window !== "undefined"). If so, it computes the absolute URL based on the current window host (resolving to /api), directing calls through the proxy route.

​

5. Context & State Propagation Flow

• File Path: frontend/uom-translator-ui/hooks/use-graph-state-context.ts
• File Path: frontend/uom-translator-ui/hooks/use-app-context.ts

​

5.1 State Context Type Signatures

export interface GraphStateContextType {
	graphState: Partial<BackendState>;
	error: { message: string; error?: any } | null;
	setError: (error: { message: string; error?: any } | null) => void;
	runError: { message: string; error?: any } | null;
	setRunError: (error: { message: string; error?: any } | null) => void;
	activeNode: keyof typeof NODE_NAME_MAP | null;
}

export interface AppContext {
	defaultUomGraphContext: Partial<UOMGraphContext>;
}

​

6. UI Style Resolution & Tailwind Integrations

• File Path: frontend/uom-translator-ui/lib/utils.ts

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
	return twMerge(clsx(inputs));
}

• Resolution Process: clsx resolves conditional arrays, key-value classes, and nested string inputs into a unified class string. twMerge then parses the Tailwind classes and overrides redundant or conflicting properties, ensuring the last declared style takes precedence.