CL-Architecture CLI

A strict, production-ready backend architecture standard for Node.js/TypeScript.

Installation

npm install -g cl-architecture

Or use directly with npx:

npx cl-architecture init

What is CL-Architecture?

CL-Architecture (Core-Line Architecture) is a backend architecture standard, not a framework. It enforces strict separation of concerns, clear data flow, and production-ready patterns.

Core-Line Request Flow

Request
  → Route (context only)
  → Port (controller)
  → Flow (business logic)
  → Source (DB / external)
  → Flow
  → Response DTO
  → Global response handler
  → Response

No shortcuts. No cross-layer calls. No mixed responsibilities.

CLI Commands

Initialize a New Project

npx cl init
npx cl init --name my-backend
npx cl init -y  # Skip prompts, use defaults

Create a Module

npx cl create module user
npx cl create module auth
npx cl create module product -y  # Skip prompts

Interactive prompts:

• Include validation? (Y/n)
• Include input DTO? (Y/n)
• Include response DTO? (Y/n)
• Include source/repository? (Y/n)
• Include tests? (Y/n)
• Include DI bindings? (Y/n)
• Include logger hooks? (Y/n)

Generated Structure

src/
├── pulse/          # Logger, errors, events
├── orbit/          # Config, env, constants
├── gateway/        # App start, DI wiring, HTTP utilities
├── modules/        # Feature modules
│   └── user/
│       ├── port/   # Controllers, routes
│       ├── flow/   # Business logic
│       ├── source/ # DB, external APIs
│       ├── shape/  # Domain entities
│       ├── bridge/ # DTOs, mappers
│       └── rule/   # Validation
├── framework/      # Express setup
└── test/           # Test utilities

Layers Explained

| Layer | Responsibility | |-------|---------------| | Port | Controllers, input handling | | Flow | Business logic only | | Source | DB, cache, external services | | Shape | Domain models, entities | | Bridge | DTOs, mappers | | Rule | Validation rules | | Pulse | Logger, errors, events | | Orbit | Config, env, constants | | Gateway | App start + DI wiring |

Architecture Rules

Controllers (Port)

• ✅ Read request
• ✅ Call Flow
• ✅ Return standardized response
• ❌ No business logic
• ❌ No DB logic
• ❌ No try/catch (use asyncHandler)

Business Logic (Flow)

• ✅ Business logic only
• ✅ Depends on interfaces
• ❌ No req/res access
• ❌ No concrete class instantiation
• ❌ No direct DB calls

Data Access (Source)

• ✅ DB / external logic only
• ✅ Implements interfaces
• ❌ No business logic
• ❌ No HTTP concerns

DTOs (Bridge)

• Input DTO: Request validation
• Flow DTO: Clean business input
• Response DTO: Safe API output

Flow never touches req.body. Response DTOs are the only API output.

Validation (Rule)

• Validation runs BEFORE Flow
• Flow assumes data is clean
• Uses Zod schemas

Example Generated Code

Controller (Port)

export class UserPort {
  constructor(private readonly userFlow: IUserFlow) {}

  getById = asyncHandler(async (req: Request, res: Response) => {
    const { id } = req.params;
    const result = await this.userFlow.getById(id);
    if (!result) throw new NotFoundError('User');
    return success(res, toUserResponse(result));
  });
}

Business Logic (Flow)

export class UserFlow implements IUserFlow {
  constructor(private readonly userSource: IUserSource) {}

  async create(dto: UserFlowDto): Promise<UserEntity> {
    const entity = createUserEntity(dto);
    return this.userSource.create(entity);
  }
}

Validation (Rule)

export const createUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

export const validate = (type: SchemaType) => {
  return (req, res, next) => {
    const result = schemas[type].safeParse(req.body);
    if (!result.success) throw new ValidationError('Validation failed', errors);
    req.body = result.data;
    next();
  };
};

What CL-Architecture Is NOT

• ❌ Not a framework
• ❌ Not magic decorators
• ❌ Not beginner MVC
• ❌ Not a silver bullet

When to Use

Best for:

• Medium to large projects
• Long-term backends
• Team-based development
• Production systems

Not for:

• Small scripts
• Quick hacks
• One-file APIs

License

MIT