Skip to main content

Welcome to KDS Frontend

KDS (Krazy Display Service) is a modern Kitchen Display System built with Next.js and TypeScript. This guide will help you set up and run the application quickly.
Before you begin, ensure you have Node.js 18+ installed and either pnpm, npm, or yarn available on your system.

Installation

1

Clone the Repository

First, navigate to your project directory where the KDS Frontend source code is located.
cd path/to/kds-frontend
2

Install Dependencies

Install the project dependencies using your preferred package manager:
pnpm install
The project includes the following key dependencies:
  • Next.js 14 - React framework for production
  • @dnd-kit - Modern drag-and-drop toolkit
  • Socket.io-client - Real-time WebSocket communication
  • Axios - HTTP client for API requests
3

Configure Environment Variables

Create a .env.local file in the root directory to configure the API connection:
.env.local
NEXT_PUBLIC_API_URL=http://localhost:3004
The NEXT_PUBLIC_API_URL variable is required for the application to communicate with the backend API. Make sure your backend server is running on the specified port.
You can also copy the example file:
cp .env.example .env.local
4

Start the Development Server

Run the development server:
pnpm dev
The application will start on port 3000.
5

Access the Application

Open your browser and navigate to:
http://localhost:3000
You should see the KDS Kanban board interface with order columns.

Quick Usage Example

Once the application is running, you can start managing orders through the Kanban board interface.

Understanding the Order Flow

The KDS system manages orders through seven status columns:
type OrderStatus =
  | "RECEIVED"    // New orders from customers
  | "CONFIRMED"   // Orders confirmed by kitchen
  | "PREPARING"   // Orders being prepared
  | "READY"       // Orders ready for pickup
  | "PICKED_UP"   // Orders picked up by courier
  | "DELIVERED"   // Orders delivered to customer
  | "CANCELLED";  // Cancelled orders

Drag and Drop Orders

The interface supports intuitive drag-and-drop functionality:
  1. View Orders: Each column displays orders in that status
  2. Move Orders: Click and drag an order card to a different column
  3. View Details: Click on any order to see detailed information
  4. Real-time Updates: Orders automatically sync across all connected clients
// Example: The Kanban component from components/Kanban/Kanban.tsx:29
import { useOrders } from "@/contexts/Orders.context";

export default function Kanban() {
  const { ordersByStatus, updateOrderStatus } = useOrders();
  
  // Orders are automatically organized by status
  // and updates are synced in real-time via WebSocket
}

Order Transitions

The system enforces business rules for valid order transitions. Not all status changes are allowed:
Order transitions are validated both in the domain layer (domain/order/order-transitions.ts) and at the UI level for optimal user experience.

Real-time Synchronization

The application maintains real-time synchronization through WebSocket connections:
// Example: Orders context from contexts/Orders.context.tsx:55
useEffect(() => {
  // Load initial orders via HTTP
  const initial = await orderOrchestrator.listBoard();
  setOrders(initial);

  // Connect WebSocket for real-time updates
  orderOrchestrator.connect({
    onCreated: upsert,  // Handle new orders
    onUpdated: upsert,  // Handle order updates
  });

  return () => {
    orderOrchestrator.disconnect();
  };
}, []);

Architecture

Learn about the layered architecture and design principles

Components

Explore the UI components and their usage

Order Status

Understand order statuses and transitions

Real-time Sync

Connect to backend services and WebSocket events

Next Steps

Now that you have the application running, you can:
  • Customize the theme - Toggle between light and dark modes using the theme switch
  • Configure order rules - Modify transition logic in domain/order/order-transitions.ts
  • Extend the UI - Add new components or customize existing ones
  • Deploy to production - Build and deploy using pnpm build and pnpm start

Build for Production

When you’re ready to deploy:
pnpm build
pnpm start
The production build will be optimized for performance and ready to deploy to your hosting platform of choice.

Troubleshooting

  • Verify Node.js version is 18 or higher: node --version
  • Ensure all dependencies are installed: pnpm install
  • Check if port 3000 is already in use
  • Verify the backend server is running on the configured port
  • Check the NEXT_PUBLIC_API_URL in your .env.local file
  • Ensure there are no CORS issues between frontend and backend
  • Confirm the backend WebSocket server is running
  • Check browser console for connection errors
  • Verify the API URL includes the correct protocol (http/https)
  • Check the WebSocket connection status in browser DevTools
  • Verify the backend is emitting order.created and order.status.updated events
  • Review the orchestrator connection in contexts/Orders.context.tsx:55
If you encounter persistent issues, check the browser console and terminal for error messages. The application includes comprehensive error handling throughout the codebase.

Build docs developers (and LLMs) love