📁 Code Organization

Structuring codebases for navigability and maintainability.

Organization strategies

By feature (recommended)

src/
├── features/
│   ├── auth/
│   ├── billing/
│   └── users/
├── shared/
└── lib/

Everything related to a feature lives together.

By layer (traditional)

src/
├── controllers/
├── services/
├── repositories/
├── models/
└── utils/

Grouped by technical role. Gets unwieldy at scale.

By domain (DDD-inspired)

src/
├── domains/
│   ├── identity/
│   ├── catalog/
│   └── checkout/
├── infrastructure/
└── application/

Naming conventions

Type	Convention	Example
Files	kebab-case	user-service.ts
Classes	PascalCase	UserService
Functions	camelCase	getUserById
Constants	UPPER_SNAKE	MAX_RETRY_COUNT
Types/Interfaces	PascalCase	UserProfile
Directories	kebab-case	user-management/

Module boundaries

• Each module/feature exposes a public API (index.ts barrel file)
• Internal implementation is private
• No circular dependencies between modules
• Shared code goes in shared/ or lib/

File size guidelines

• Keep files under 300 lines
• If a file has more than 5 exports, consider splitting
• One class/component per file
• Group related constants in a dedicated file

Import order

// 1. External packages
import express from 'express'
import { z } from 'zod'

// 2. Internal shared modules
import { logger } from '@/shared/logger'

// 3. Relative imports (same feature)
import { UserRepository } from './user.repository'