Domain Module

A Domain Module is a standardized folder structure that encapsulates all code related to a single domain (e.g., User, Product, Order). It follows Domain-Driven Design principles to organize code around business domains rather than technical concerns.

Domain Module Structure

🎯Goal

The goal is to produce reusable UI components and business logic that can be used in Nest.js backend modules and Next.js frontend pages.

Module Architecture

Domain modules are divided into three categories: Common files (shared), Backend files, and Frontend files. This separation eliminates duplicate code declarations.

Data Flow

Common + Backend → MongoDB Model, Service Logic, Endpoint → Nest.js Module

Common + Frontend → Fetch Client, Flux Store, UI Components → Next.js Component

Category	Files	Output
Common	constant, dictionary, signal	Type definitions, translations, API contracts
Backend	document, service	MongoDB models, business logic
Frontend	store, Template, Unit, View, Zone, Util	State management, UI components

Common Files

Common files are shared between backend and frontend. They must be written in pure JavaScript/TypeScript without platform-specific dependencies.

File	Description
`constant.ts`	Defines data schemas (Input, Object, Light, Full, Insight) and enums using the via() builder pattern.
`dictionary.ts`	Provides multi-language translations for model names, field labels, enum values, API descriptions, and error messages.
`signal.ts`	Defines API endpoints (queries, mutations, subscriptions) and their type contracts between frontend and backend.

Common files cannot import backend-only (mongoose, fs) or frontend-only (window, document) dependencies. Only @akanjs/base and @akanjs/common are allowed. Type imports are safe as they disappear during transpilation.

Backend Files

Backend files create MongoDB models, implement business logic, and are combined to create a Nest.js module.

File	Description
`document.ts`	Creates MongoDB Document/Model from constant schema. Defines database queries, filters, and data processing logic (Redis cache, text search, etc.).
`service.ts`	Implements domain-specific business logic. Handles complex operations, validations, and interactions with other services.

Backend Data Flow

Frontend Files

Frontend files define state management, data fetching, and UI components for the domain.

File	Type	Description
`store.ts`	Client	Global state management with Zustand. Defines domain-related state and actions.
`Template.tsx`	Client	Form components for Create/Update operations with integrated state management.
`Unit.tsx`	Server	Card/list item components for displaying multiple items. Uses LightModel for efficient rendering.
`View.tsx`	Server	Detail view components for single item display. Uses full Model with all properties.
`Zone.tsx`	Client	Page container components that compose Template, Unit, View into complete UI sections.
`Util.tsx`	Client	Specialized utility components for domain-specific features (buttons, badges, etc.).

State Management

store.ts handles domain state and business logic on client.

UI Components

Template, Unit, View provide reusable UI patterns.

Container

Zone composes components into complete pages.

File Naming Convention

Akan.js follows a consistent naming convention to distinguish between different file types:

Pattern	Example	Description
`model.*.ts`	product.constant.ts	Logic files (lowercase)
`Model.*.tsx`	Product.View.tsx	React components (PascalCase)

Complete Module Example

Domain Module Best Practices

1️⃣Keep Common Files Pure

Never import platform-specific code in constant.ts, dictionary.ts, or signal.ts. These files must work in both Node.js and browser environments.

2️⃣Use Appropriate Model Types

Unit.tsx uses LightModel (fewer fields, better performance). View.tsx uses full Model (all fields for detail display).

3️⃣Server vs Client Components

Unit.tsx and View.tsx are Server Components (no 'use client'). Template.tsx, Zone.tsx, and Util.tsx are Client Components (with 'use client').

4️⃣Organize by Domain

Keep all related files in the same folder. This makes it easy to understand and maintain the domain as a whole.

🎉 What You've Learned:

✓ Domain module structure with 11 standardized files
✓ Three categories: Common (shared), Backend, Frontend
✓ Data flow from constant → document → service → signal
✓ Frontend component hierarchy: Zone → Template/Unit/View
✓ Naming conventions: lowercase.ts for logic, PascalCase.tsx for components

File Naming Convention

Domain Module Best Practices

Quick Start

Domain Module

Domain Module Structure

🎯Goal

The goal is to produce reusable UI components and business logic that can be used in Nest.js backend modules and Next.js frontend pages.

Module Architecture

Domain modules are divided into three categories: Common files (shared), Backend files, and Frontend files. This separation eliminates duplicate code declarations.

Data Flow

Common + Backend → MongoDB Model, Service Logic, Endpoint → Nest.js Module

Common + Frontend → Fetch Client, Flux Store, UI Components → Next.js Component

Category	Files	Output
Common	constant, dictionary, signal	Type definitions, translations, API contracts
Backend	document, service	MongoDB models, business logic
Frontend	store, Template, Unit, View, Zone, Util	State management, UI components

Common Files

Common files are shared between backend and frontend. They must be written in pure JavaScript/TypeScript without platform-specific dependencies.

File	Description
`constant.ts`	Defines data schemas (Input, Object, Light, Full, Insight) and enums using the via() builder pattern.
`dictionary.ts`	Provides multi-language translations for model names, field labels, enum values, API descriptions, and error messages.
`signal.ts`	Defines API endpoints (queries, mutations, subscriptions) and their type contracts between frontend and backend.

Backend Files

Backend files create MongoDB models, implement business logic, and are combined to create a Nest.js module.

File	Description
`document.ts`	Creates MongoDB Document/Model from constant schema. Defines database queries, filters, and data processing logic (Redis cache, text search, etc.).
`service.ts`	Implements domain-specific business logic. Handles complex operations, validations, and interactions with other services.

Backend Data Flow

Frontend Files

Frontend files define state management, data fetching, and UI components for the domain.

File	Type	Description
`store.ts`	Client	Global state management with Zustand. Defines domain-related state and actions.
`Template.tsx`	Client	Form components for Create/Update operations with integrated state management.
`Unit.tsx`	Server	Card/list item components for displaying multiple items. Uses LightModel for efficient rendering.
`View.tsx`	Server	Detail view components for single item display. Uses full Model with all properties.
`Zone.tsx`	Client	Page container components that compose Template, Unit, View into complete UI sections.
`Util.tsx`	Client	Specialized utility components for domain-specific features (buttons, badges, etc.).

State Management

store.ts handles domain state and business logic on client.

UI Components

Template, Unit, View provide reusable UI patterns.

Container

Zone composes components into complete pages.

File Naming Convention

Akan.js follows a consistent naming convention to distinguish between different file types:

Pattern	Example	Description
`model.*.ts`	product.constant.ts	Logic files (lowercase)
`Model.*.tsx`	Product.View.tsx	React components (PascalCase)

Complete Module Example

Domain Module Best Practices

1️⃣Keep Common Files Pure

Never import platform-specific code in constant.ts, dictionary.ts, or signal.ts. These files must work in both Node.js and browser environments.

2️⃣Use Appropriate Model Types

Unit.tsx uses LightModel (fewer fields, better performance). View.tsx uses full Model (all fields for detail display).

3️⃣Server vs Client Components

Unit.tsx and View.tsx are Server Components (no 'use client'). Template.tsx, Zone.tsx, and Util.tsx are Client Components (with 'use client').

4️⃣Organize by Domain

Keep all related files in the same folder. This makes it easy to understand and maintain the domain as a whole.

🎉 What You've Learned:

✓ Domain module structure with 11 standardized files
✓ Three categories: Common (shared), Backend, Frontend
✓ Data flow from constant → document → service → signal
✓ Frontend component hierarchy: Zone → Template/Unit/View
✓ Naming conventions: lowercase.ts for logic, PascalCase.tsx for components

File Naming Convention

Domain Module Best Practices