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
Clone the Repository
First, navigate to your project directory where the KDS Frontend source code is located.
Install Dependencies
Install the project dependencies using your preferred package manager: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
Configure Environment Variables
Create a You can also copy the example file:
.env.local file in the root directory to configure the API connection:.env.local
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:Drag and Drop Orders
The interface supports intuitive drag-and-drop functionality:- View Orders: Each column displays orders in that status
- Move Orders: Click and drag an order card to a different column
- View Details: Click on any order to see detailed information
- Real-time Updates: Orders automatically sync across all connected clients
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: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 buildandpnpm start
Build for Production
When you’re ready to deploy:Troubleshooting
Application won't start
Application won't start
- 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
Cannot connect to API
Cannot connect to API
- Verify the backend server is running on the configured port
- Check the
NEXT_PUBLIC_API_URLin your.env.localfile - Ensure there are no CORS issues between frontend and backend
WebSocket not connecting
WebSocket not connecting
- Confirm the backend WebSocket server is running
- Check browser console for connection errors
- Verify the API URL includes the correct protocol (http/https)
Orders not updating in real-time
Orders not updating in real-time
- Check the WebSocket connection status in browser DevTools
- Verify the backend is emitting
order.createdandorder.status.updatedevents - Review the orchestrator connection in
contexts/Orders.context.tsx:55