CKN Framework Overview

CKN Framework is a full-stack JavaScript/TypeScript foundation for building enterprise-grade applications – unifying server, middleware, modules, controllers, UI components and real-time runtime into one opinionated, production-ready stack.

Goal 1

Full-stack Unified

Same concepts across backend and frontend – modules, controllers, middleware – making cross-team collaboration and maintenance easier.

Goal 2

Opinionated but Flexible

Clear conventions for structure and lifecycle while still allowing custom modules, middlewares and UI components.

Goal 3

Production Ready

Designed from real projects – predictable logging, configuration, scalability and integration patterns are built-in from day one.

1. Overview

At a high level, CKN Framework groups responsibilities into three main layers: CKN Technology (utility & runtime helpers), CKN Systems (core platform services), and CKN Solutions (business applications). On top of that, the framework defines a clear server architecture, middleware pipeline, module system, and UI component engine so every service and app follows the same lifecycle.

Unified Runtime

Node.js backend and browser frontend share a common set of helpers exported from @ckn-technology/core. Prototype extensions for string, number, array and date make business rules concise and readable.

Benefit: less glue code and fewer inconsistencies between services and UIs.

Module-oriented Design

Every feature lives in a module folder containing controllers, services, models and UI components. Modules are auto-discovered by middleware and registered at runtime.

Benefit: clear boundaries between domains and easier reuse across projects.

Lifecycle-driven Architecture

Requests flow through a deterministic pipeline: HTTP → Middleware → Module Controller → Business Logic → Response or WebSocket event.

Benefit: debugging and tracing are straightforward because every step has a defined responsibility.

2. Server Architecture

The server side of CKN Framework is built on Node.js with a thin HTTP layer and a strongly structured internal runtime. The focus is on predictable request flow, strict separation of cross-cutting concerns and simple deployment.

HTTP Entry Layer

Routes incoming HTTP requests into the middleware pipeline. It normalizes headers, cookies and body into a single Session object that can be used by all components.

Benefit: future changes to web server / proxy do not affect application code.

Business Execution Layer

Module controllers receive typed requests, call application services, talk to databases via adapters (e.g. MainDatabase), and return standardized responses.

Benefit: complex flows remain testable and easy to reason about.

Integration & Data Layer

Database access, external APIs and internal systems are handled through dedicated adapters that inherit from base classes in CKN Technology/Data.

Benefit: avoids leaking low-level details into business logic and UI components.

3. Middleware Pipeline

Middleware is the backbone of request processing in CKN Framework. Each middleware class has a priority and a clear responsibility. The pipeline runs them in order to transform and validate the request before a controller is executed.

Priority-based Execution

Core middleware (e.g. module discovery, routing, authentication) runs with lower numeric priorities so they always execute first. Custom middlewares can be added before or after them by setting their priority.

Benefit: deterministic order of operations and easier reasoning about performance.

Cross-cutting Concerns

Logging, error handling, CORS, security headers, localization and caching can be implemented once as middlewares and reused by all modules and controllers.

Benefit: no need to duplicate common checks in every endpoint.

Module Middleware

A special middleware scans the modules folder (e.g. dist/modules) to dynamically load controllers and register routes at startup.

Benefit: drop-in modules – add a folder and the framework wires it automatically.

Extendable Pipeline

Teams can plug in custom middleware for tenant resolution, feature flags, rate-limiting or request reshaping without touching existing code.

Benefit: future-proof architecture that can adapt to new business rules.

4. Module System

Modules are the core unit of organization in CKN Framework. Each module represents a bounded context (e.g. Identity, Inventory, TMS, WMS) and contains everything it needs: controllers, business services, models, UI components and configuration.

Self-contained Features

A typical module might expose REST controllers, WebSocket handlers, scheduled jobs and UI components under a single folder, following shared naming conventions.

Benefit: moving or reusing modules between projects is straightforward.

Loose Coupling via Systems

Modules talk to core platform services (Identity, Configuration, Log, Integration) through interfaces provided by CKN Systems, rather than direct references.

Benefit: modules stay focused on business logic, not infrastructure wiring.

Versioning & Rollout

Because modules are isolated, they can be versioned, deployed and rolled back independently, aligned with microservice or monolith-inside-container strategies.

Benefit: safer releases with smaller blast radius per change.

5. Controller System

Controllers are the main entry points for business actions. They receive normalized requests from middleware, coordinate validation and service calls, and return responses in a consistent format (JSON, HTML, file, or WebSocket messages).

HTTP Controllers

Define endpoints for CRUD, queries and workflows using a structured naming convention and clear mapping to modules and domains.

Benefit: easy to discover endpoints and navigate codebase by URL patterns.

Socket Controllers

For real-time scenarios, controllers can publish events over WebSocket channels to update UI or external systems as state changes.

Benefit: same mental model for REST and WebSocket based flows.

Validation & Policies

Controllers are the ideal place to enforce access policies and validate inputs before deeper services are called, using shared helpers and middlewares.

Benefit: single layer for security checks instead of scattered if conditions.

6. UI Component Engine

The CKN UI component engine provides a lightweight component model designed to work well with Bootstrap/Tailwind layouts, plus CKN’s own design systems (e.g. CKN UI 1 for desktop dashboards and CKN UI 2 for mobile/driver flows).

Component Class Model

Components extend a base Component class and implement lifecycle hooks such as template building and event wiring.

Benefit: shared patterns across login forms, dashboards, detail pages and real-time panels.

Stateful UI

Internal state (loading, error messages, filters) is encapsulated and mapped to DOM updates, making UI logic easier to manage than ad-hoc scripts.

Benefit: less fragile DOM manipulation and clearer UI flows.

Design System Friendly

Components are intentionally unopinionated about CSS frameworks – they can be styled with Bootstrap, Tailwind or internal CKN themes.

Benefit: consistent brand identity while still using flexible technology stack.

7. WebSocket Runtime

Real-time capabilities are provided via a dedicated WebSocket runtime, pairing server-side event publishing with client-side helpers like Socket from @ckn-technology/core.

Channel-based Events

Shipments, queues, AGV status, dashboards and monitoring pages can subscribe to dedicated channels and receive updates only for relevant entities.

Benefit: efficient, scalable real-time updates without polling.

Queue & Retry Options

On the client, Socket supports optional message queueing and reconnect logic, ensuring data is processed in order when connections are unstable.

Benefit: smoother UX for mobile or field users on weak networks.

8. Folder Structure

CKN Framework encourages a predictable folder structure so developers can quickly locate modules, controllers, middleware and infrastructure code.

Typical Service Layout


project-root/
├─ src/
│  ├─ core/              # shared core classes (Middleware, Controller, etc.)
│  ├─ middleware/        # global middlewares
│  ├─ modules/           # feature modules
│  │  ├─ identity/
│  │  ├─ inventory/
│  │  └─ tms/
│  ├─ ui/                # UI components (if same repo)
│  └─ main.ts            # server bootstrap
├─ dist/                 # compiled output
├─ config/               # environment & system configs
└─ docker/               # deployment & runtime scripts

Benefits

  • New developers can navigate by domain name instead of technical layers.
  • Refactoring a whole module does not impact others if interfaces are stable.
  • Deployment, logging and monitoring configs stay separate from business code.

9. Lifecycle Flow

Every request in CKN Framework passes through a well-defined lifecycle. Understanding this flow helps teams debug, monitor and extend the platform.

  1. Request Ingress – HTTP or WebSocket request hits the server entry.
  2. Session Creation – headers, cookies, query, body are normalized into a Session object.
  3. Middleware Pipeline – authentication, logging, routing, module resolution and other cross-cutting concerns are executed in priority order.
  4. Controller Dispatch – resolved controller and action receive the request and run business logic.
  5. Service & Data Access – controllers call services which talk to databases, queues or external systems via adapters.
  6. Response or Event – results are returned as HTTP response or published to WebSocket channels.
  7. Post-processing – additional middleware can log metrics, trace IDs or clean up resources.

10. Best Practices

To get the most out of CKN Framework, teams are encouraged to follow these practical guidelines:

  • One domain per module – avoid mixing unrelated features in the same module.
  • Keep controllers thin – move complex logic into dedicated services or use cases.
  • Use middleware for cross-cutting concerns – authentication, tenant resolution, audit logging, not in business code.
  • Align UI with modules – structure pages and components to mirror backend modules for easier navigation.
  • Leverage core utilities – use number/string/array/date helpers to minimize ad-hoc implementations.
  • Standardize logging – include correlation IDs and domain prefixes for all logs.
  • Document module contracts – describe input/output models and side-effects for each controller.

Next Steps

This overview page gives a high-level picture of the CKN Framework architecture and runtime. The next documentation pages can dive deeper into:

  • CKN Technology – detailed utilities and prototype extensions.
  • CKN Systems – identity, configuration, logging and integration services.
  • CKN Solutions – functional coverage of each business application (TMS, WMS, Inventory, Financial, etc.).
  • Deployment Guides – Docker, Cloud Run, CI/CD pipelines and environment setup.

Use the left navigation to move between sections, or wire this page into your own documentation portal as the primary entry point to CKN Framework.