Architecture

The KDS Frontend follows a clean architecture pattern with clear separation of concerns across four distinct layers. This architecture ensures maintainability, testability, and scalability of the codebase.

Layered Architecture

The application is organized into the following layers:

Domain Layer

Core business logic and rules

Application Layer

Application services and interfaces

Infrastructure Layer

External integrations (HTTP, WebSocket)

Presentation Layer

UI components and contexts

Directory Structure

source/
├── domain/                    # Domain Layer
│   └── order/
│       ├── order-status.ts
│       └── order-transitions.ts
├── application/               # Application Layer
│   ├── order/
│   │   ├── order-repository.ts
│   │   ├── order-realtime.ts
│   │   └── order-events.ts
│   ├── hook/
│   │   └── use-order-detail.ts
│   └── shared/
│       └── http-client.ts
├── infraestructure/          # Infrastructure Layer
│   ├── http/
│   │   ├── order.repository.ts
│   │   └── axios-http.client.ts
│   └── socket/
│       └── order-realtime.socket.ts
├── orchestrators/            # Orchestration Layer
│   └── order/
│       └── OrderOrchestrator.ts
├── components/               # Presentation Layer
│   ├── Kanban/
│   ├── Column/
│   └── card/
├── contexts/                 # State Management
│   └── Orders.context.tsx
├── dtos/                     # Data Transfer Objects
│   ├── OrderList.dto.ts
│   └── OrderDetails.dto.ts
└── pages/                    # Next.js Pages

Layer Details

Domain Layer
Application Layer
Infrastructure Layer
Orchestration Layer
Presentation Layer

Domain Layer

The domain layer contains pure business logic with no external dependencies. It defines the core rules and types of the application.Location: domain/Key Responsibilities:

Define domain types (e.g., OrderStatus)
Implement business rules (e.g., canTransition)
No dependencies on other layers

Example: Order Status Transitions

domain/order/order-transitions.ts

import { OrderStatus } from "./order-status";

const ALLOWED_TRANSITIONS: Record<OrderStatus, OrderStatus[]> = {
  RECEIVED: ["CONFIRMED", "CANCELLED"],
  CONFIRMED: ["PREPARING", "CANCELLED"],
  PREPARING: ["READY", "CANCELLED"],
  READY: ["PICKED_UP", "CANCELLED"],
  PICKED_UP: ["DELIVERED"],
  DELIVERED: [],
  CANCELLED: [],
};

export function canTransition(from: OrderStatus, to: OrderStatus): boolean {
  return ALLOWED_TRANSITIONS[from].includes(to);
}

The domain layer ensures business rules are enforced consistently across the entire application.

Application Layer

The application layer defines interfaces and contracts for the application’s services. It acts as a bridge between the domain and infrastructure layers.Location: application/Key Responsibilities:

Define repository interfaces
Define service interfaces (e.g., real-time sync)
Define event contracts
Custom React hooks for data fetching

Example: Repository Interface

application/order/order-repository.ts

import { OrderStatus } from "@/domain/order/order-status";
import { OrderDetailDto } from "@/dtos/OrderDetails.dto";
import { OrderListDto } from "@/dtos/OrderList.dto";

export interface OrderRepository {
  listBoard(): Promise<OrderListDto[]>;
  updateStatus(id: string, toStatus: OrderStatus): Promise<void>;
  getDetail(id: string): Promise<OrderDetailDto>;
}

Example: Real-time Interface

application/order/order-realtime.ts

import { OrderEvents } from "./order-events";

export interface OrderRealtime {
  connect(events: OrderEvents): void;
  disconnect(): void;
}

The application layer defines what the application can do, while the infrastructure layer defines how it does it.

Infrastructure Layer

The infrastructure layer implements the interfaces defined in the application layer using specific technologies (HTTP, WebSocket, etc.).Location: infraestructure/Key Responsibilities:

Implement repository interfaces with HTTP clients
Implement real-time sync with WebSocket
Handle external API communication
Transform API responses into DTOs

Example: HTTP Repository Implementation

infraestructure/http/order.repository.ts

export class HttpOrderRepository implements OrderRepository {
  constructor(private readonly http: HttpClient) {}

  async listBoard(): Promise<OrderListDto[]> {
    const { createdFrom, createdTo } = this.getTodayRange();

    const response = await this.http.get<OrdersListResponse>(
      "/api/v1/orders/list",
      {
        params: {
          status: ALL_ORDER_STATUSES.join(","),
          createdFrom,
          createdTo,
        },
      },
    );

    return response.data.orders;
  }

  async updateStatus(id: string, toStatus: OrderStatus): Promise<void> {
    await this.http.patch<UpdateStatusResponse>(
      `/api/v1/orders/${id}/status`,
      { toStatus }
    );
  }
}

Example: WebSocket Implementation

infraestructure/socket/order-realtime.socket.ts

export class SocketOrderRealtime implements OrderRealtime {
  private socket: Socket | null = null;

  constructor(private readonly baseUrl: string) {}

  connect(events: OrderEvents): void {
    if (!this.socket) {
      this.socket = io(this.baseUrl, {
        transports: ["websocket"],
        reconnection: true,
        reconnectionAttempts: 5,
        reconnectionDelay: 2000,
      });
    }

    this.socket.on("order.created", (order: OrderListDto) => {
      events.onCreated?.(order);
    });

    this.socket.on("order.status.updated", (order: OrderListDto) => {
      events.onUpdated?.(order);
    });
  }
}

Orchestration Layer

The orchestration layer coordinates between the repository and real-time services, providing a unified API for the presentation layer.Location: orchestrators/Key Responsibilities:

Coordinate repository and real-time services
Provide a single entry point for order operations
Delegate to appropriate services

Example: Order Orchestrator

orchestrators/order/OrderOrchestrator.ts

export class OrderOrchestrator {
  constructor(
    private readonly repository: OrderRepository,
    private readonly realtime: OrderRealtime,
  ) {}

  connect(events: OrderEvents): void {
    this.realtime.connect(events);
  }

  disconnect(): void {
    this.realtime.disconnect();
  }

  async listBoard(): Promise<OrderListDto[]> {
    return this.repository.listBoard();
  }

  async getOrderDetail(id: string): Promise<OrderDetailDto> {
    return this.repository.getDetail(id);
  }

  async updateOrderState(id: string, toStatus: OrderStatus): Promise<void> {
    await this.repository.updateStatus(id, toStatus);
  }
}

The orchestrator simplifies the presentation layer by providing a single API that handles both HTTP requests and real-time updates.

Presentation Layer

The presentation layer contains UI components, React contexts, and pages that users interact with.Location: components/, contexts/, pages/Key Responsibilities:

Render UI components
Manage local UI state
Handle user interactions
Subscribe to real-time updates

Example: Orders Context

contexts/Orders.context.tsx

export const OrdersProvider = ({ children }: { children: React.ReactNode }) => {
  const [orders, setOrders] = useState<OrderListDto[]>([]);

  const upsert = (incoming: OrderListDto) => {
    setOrders((prev) => {
      const idx = prev.findIndex((o) => o.id === incoming.id);
      if (idx === -1) return [incoming, ...prev];

      const next = [...prev];
      next[idx] = incoming;
      return next;
    });
  };

  useEffect(() => {
    const loadInitial = async () => {
      const initial = await orderOrchestrator.listBoard();
      setOrders(initial);
    };

    loadInitial();

    orderOrchestrator.connect({
      onCreated: upsert,
      onUpdated: upsert,
    });

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

  const updateOrderStatus = async (id: string, status: OrderStatus) => {
    // Optimistic update
    setOrders((curr) => curr.map((o) => (o.id === id ? { ...o, status } : o)));

    try {
      await orderOrchestrator.updateOrderState(id, status);
    } catch (e) {
      // Rollback on error
    }
  };

  return (
    <OrdersContext.Provider value={{ orders, updateOrderStatus }}>
      {children}
    </OrdersContext.Provider>
  );
};

Data Flow

User Interaction

User drags an order card to a new column in the Kanban board

Domain Validation

The canTransition function validates if the status change is allowed

if (!canTransition(current.status, targetStatus)) return;

Orchestrator Coordination

The context calls the orchestrator to update the order status

await orderOrchestrator.updateOrderState(id, status);

Infrastructure Execution

The HTTP repository sends a PATCH request to the backend API

await this.http.patch(`/api/v1/orders/${id}/status`, { toStatus });

Real-time Broadcast

The backend broadcasts the update via WebSocket to all connected clients

UI Update

The socket handler triggers the onUpdated event, and the context updates the UI

this.socket.on("order.status.updated", (order: OrderListDto) => {
  events.onUpdated?.(order);
});

Benefits of This Architecture

Testability

Each layer can be tested in isolation with mocked dependencies

Maintainability

Clear separation makes it easy to locate and modify code

Flexibility

Swap implementations (e.g., replace HTTP with GraphQL) without changing business logic

Scalability

Add new features by following established patterns

Next Steps

Order Status

Learn about order status types and transition rules

Real-time Sync

Understand how WebSocket synchronization works

Get Started

Core Concepts

Components

Development

Layered Architecture

Domain Layer

Application Layer

Infrastructure Layer

Presentation Layer

Directory Structure

Layer Details

Domain Layer

Application Layer

Infrastructure Layer

Orchestration Layer

Presentation Layer

Data Flow

Benefits of This Architecture

Testability

Maintainability

Flexibility

Scalability

Next Steps

Order Status

Real-time Sync

Build docs developers (and LLMs) love

Get Started

Core Concepts

Components

Development

​Layered Architecture

Domain Layer

Application Layer

Infrastructure Layer

Presentation Layer

​Directory Structure

​Layer Details

​Domain Layer

​Application Layer

​Infrastructure Layer

​Orchestration Layer

​Presentation Layer

​Data Flow

​Benefits of This Architecture

Testability

Maintainability

Flexibility

Scalability

​Next Steps

Order Status

Real-time Sync

Build docs developers (and LLMs) love

Layered Architecture

Directory Structure

Layer Details

Domain Layer

Application Layer

Infrastructure Layer

Orchestration Layer

Presentation Layer

Data Flow

Benefits of This Architecture

Next Steps