Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ronaldjdev/forge/llms.txt

Use this file to discover all available pages before exploring further.

Consistent naming is not cosmetic in a Forge-governed system — it is functional. The armorer module identifies ownership by scanning file suffixes and directory paths. The inspect audit uses suffixes to detect orphaned components, misplaced domain artifacts, and R13 violations (domain files in platform/). The quench validator checks naming conventions as a dedicated scoring category. If a file is named incorrectly, Forge cannot classify it, and an unclassified file is treated as an orphan in the ownership report. Every name in a Forge project is a machine-readable signal.

​
File and Directory Naming

ElementFormatExample
Directorieskebab-case/credit-card/, event-bus/, user-profile/
Files (artifacts)<PascalCase>.<artifact>.tsUser.entity.ts, CreateUser.uc.ts
InterfacesI<PascalCase>.<artifact>.tsIUser.repository.ts, IPayment.port.ts
Ports (domain)<Name>.port.tsPaymentPort.port.ts, EmailPort.port.ts
Use cases<Action>.uc.tsCreateUser.uc.ts, GetOrder.uc.ts
Barrel filesindex.tsNamed exports only — no export default

​
Class and Function Naming

ElementFormatExample
ClassesPascalCaseUserController, DatabaseConfig, LoggerService
FunctionscamelCaseformatDate, calculateTotal, buildQuery
ConstantsUPPER_SNAKE_CASEMAX_RETRIES, DEFAULT_PAGE_SIZE, MAX_RETRY_COUNT
Types / pure interfacesPascalCaseUserPayload, PaginatedResult, OrderStatus
EnumsPascalCaseUserRole, OrderStatus, PaymentMethod
VariablescamelCaseuserService, prismaClient, requestId

​
Artifact Suffixes

These suffixes are the vocabulary Forge uses to classify every file in your project. Files without a recognized suffix are flagged as orphans in the ownership report.
SuffixArtifact TypeBelongs In
.entity.tsDomain entityfeatures/<name>/domain/entities/
.repository.tsRepository implementation (concrete)features/<name>/adapters/out/persistence/
.uc.tsUse casefeatures/<name>/application/use-cases/
.mapper.tsDomain mapperfeatures/<name>/application/mappers/
.controller.tsHTTP controllerfeatures/<name>/adapters/in/http/
.routes.tsRoute definitionsfeatures/<name>/adapters/in/http/
.schema.tsDatabase schemafeatures/<name>/adapters/out/persistence/
.error.tsDomain-specific errorfeatures/<name>/domain/errors/
.event.tsDomain eventfeatures/<name>/domain/events/
.service.tsPlatform / infrastructure serviceplatform/<module>/ or infra/<provider>/
.port.tsDomain port (interface)features/<name>/domain/repositories/
.config.tsConfiguration moduleplatform/config/
The armorer step in the boot sequence and the inspect command both rely on these suffixes to detect ownership violations. Any file with a .entity.ts, .uc.ts, .mapper.ts, .port.ts, or .repository.ts suffix inside src/platform/ triggers R13 CRITICAL regardless of its contents. A .uc.ts file outside of a features/ directory is flagged as a misplaced component.

​
Interface and Port Naming

Interfaces for repository ports follow the I<Name>.repository.ts pattern. General domain ports (adapters to external services) use <Name>.port.ts: 
src/features/users/domain/repositories/
├── IUser.repository.ts          ← repository port interface
└── IUserCache.port.ts           ← cache port interface (optional)

src/features/payments/domain/repositories/
├── IPayment.repository.ts
└── IPaymentGateway.port.ts      ← external payment service port

​
Domain Event Naming

Domain events always use past tense to reflect a fact that has already occurred: 
src/features/users/domain/events/
├── UserCreated.event.ts         ✅ past tense
├── UserUpdated.event.ts         ✅
└── UserDeleted.event.ts         ✅

# Never imperative:
# CreateUser.event.ts            ❌ imperative
# OnUserCreate.event.ts          ❌ handler-style name

​
Feature Structure Example

The following shows a complete users feature with every file named according to Forge conventions: 
src/features/users/
├── domain/
│   ├── entities/
│   │   └── User.entity.ts                    ← .entity.ts
│   ├── repositories/
│   │   └── IUser.repository.ts               ← I<Name>.repository.ts
│   ├── errors/
│   │   ├── UserNotFound.error.ts             ← .error.ts
│   │   └── UserAlreadyExists.error.ts
│   └── events/
│       ├── UserCreated.event.ts              ← .event.ts (past tense)
│       └── UserDeleted.event.ts
├── application/
│   ├── use-cases/
│   │   ├── CreateUser.uc.ts                  ← <Action>.uc.ts
│   │   ├── GetUser.uc.ts
│   │   ├── ListUsers.uc.ts
│   │   ├── UpdateUser.uc.ts
│   │   └── DeleteUser.uc.ts
│   └── mappers/
│       └── User.mapper.ts                    ← .mapper.ts
└── adapters/
    ├── in/http/
    │   ├── User.controller.ts               ← .controller.ts
    │   └── User.routes.ts                   ← .routes.ts
    └── out/persistence/
        ├── User.repository.ts               ← .repository.ts (concrete impl)
        └── User.schema.ts                   ← .schema.ts
The corresponding class names follow the same pattern: 
// User.entity.ts
export class UserEntity { ... }

// IUser.repository.ts
export interface IUserRepository { ... }

// CreateUser.uc.ts
export class CreateUserUseCase { ... }

// User.mapper.ts
export class UserMapper { ... }

// User.controller.ts
export class UserController { ... }

// User.repository.ts (concrete)
export class UserRepository implements IUserRepository { ... }

​
Platform Layer Naming

Platform files follow the same <PascalCase>.<artifact>.ts pattern but scoped to technical concerns: 
src/platform/
├── config/
│   ├── App.config.ts             ← .config.ts
│   └── Env.config.ts
├── server/
│   └── Server.ts                 ← plain PascalCase (no artifact suffix for top-level modules)
├── logger/
│   ├── Logger.config.ts
│   └── Logger.service.ts         ← .service.ts
├── security/
│   ├── Auth.middleware.ts        ← .middleware.ts
│   └── Encryption.service.ts
└── di/
    ├── Container.ts
    └── Tokens.ts

​
Shared Layer Naming

Shared uses slightly different conventions for each of its four sub-directories: 
src/shared/
├── errors/
│   ├── NotFoundError.ts          ← <Name>Error.ts  (no dot-suffix)
│   ├── ValidationError.ts
│   └── ConflictError.ts
├── contracts/
│   └── IPaginatedResponse.ts     ← I<Name>.ts
├── types/
│   └── api.types.ts              ← <domain>.types.ts  (all lowercase)
└── utils/
    ├── formatDate.ts             ← camelCase.ts
    └── pagination.ts
Run forge quench to validate naming conventions across the entire project. The Naming category contributes 10 points to the inspect score. Use forge quench --fix to auto-correct violations where Forge can infer the correct name from the file’s contents and location.

Build docs developers (and LLMs) love

Get started for freeTalk to us