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