Instruction file imported from NhanDinhVan/wifi-sentry (.github/instructions/backend.instructions.md). Copyright stays with the author.

Backend Conventions

For the workspace overview, service communication flow, and cross-service rules, see .github/instructions/project.instructions.md.

Tech Stack

Folder Structure

src/
  app.module.ts            # Root module — imports domain modules only
  main.ts                  # Bootstrap entry point

  commons/                 # Shared, framework-agnostic utilities
    constants/             # APP_ENV, route paths, etc.
    enums/
    guards/
    interceptors/
    utils/
    validators/

  configs/                 # Config factory functions, one file per concern
    app.config.ts          # Central config object (reads process.env)
    database.config.ts     # getPostgresDatabaseConfig()
    graphql.config.ts      # getGraphqlConfig()
    index.ts               # Re-exports all configs

  databases/
    postgres/
      datasource.module.ts # TypeORM module wrapper
      datasource.ts        # DataSource for CLI (migrations)
      entities/{feature}/  # One folder per entity
      migrations/          # TypeORM migration files

  modules/
    client/                # "client" domain — all client-facing features
      client.module.ts     # Domain root module
      {feature}/           # One folder per feature
        {feature}.module.ts
        {feature}.resolver.ts
        {feature}.service.ts
        interfaces/
        dtos/requests/
        dtos/responses/
    shared/                # Cross-domain shared providers/services

  providers/               # Infrastructure providers (Redis, BullMQ, etc.)
    redis/index.ts
    bull-queue/index.ts

Naming Conventions

Files

Classes

Modules, Services, and Resolvers must be domain-prefixed:

// ✓ Domain-prefixed — prevents naming conflicts across domains
export class ClientUserModule {}
export class ClientUserService {}
export class ClientUserResolver {}

// ✗ Not allowed — ambiguous across domains
export class UserService {}

• Entities: no domain prefix — UserEntity, TaskEntity
• DTOs: describe the action — CreateUserRequestDto, UserResponseDto
• Interfaces: I-prefixed — ICreateUserInput
• Enums: PascalCase — UserRole, TaskStatus

Variables & Constants

• camelCase for variables and function parameters
• Exported constants use grouped const objects — not flat SCREAMING_SNAKE_CASE:

// ✓ Correct
export const APP_ENV = { LOCAL: 'local', STAGING: 'staging', RELEASE: 'release' }

// ✗ Avoid
export const APP_ENV_LOCAL = 'local'

Database

• Table names: plural snake_case — task_recurrence_rules, workspace_members
• Column names: snake_case (handled automatically by SnakeNamingStrategy)

Code Style (ESLint + Prettier)

Key ESLint rules:

• no-duplicate-imports: error — merge all imports from the same module
• object-shorthand: always — use { foo } not { foo: foo }
• max-depth: 4 — maximum nesting depth of 4
• unused-imports/no-unused-imports: error — prefix unused variables with _
• @typescript-eslint/no-floating-promises: warn — always await or .catch() promises

Module Scope & Boundaries

• Each domain (client, shared) owns its own NestJS module tree. Do not import a feature module from another domain directly.
• Cross-domain shared logic lives in src/modules/shared/ and is exported from SharedModule.
• Infrastructure (Redis, BullMQ) is provided via src/providers/ and imported into the domain module that needs it.
• Direct repository access is not allowed in resolvers — use the feature service.
• Config factory functions must not be called inline inside module files — pass them via useFactory.

TypeORM Entity Auto-Discovery

PostgresDatasourceModule discovers all *.entity.ts files via a glob pattern automatically. Do NOT use TypeOrmModule.forFeature([...]) to register entities manually.

• When creating a new entity, do not modify module imports.
• Use @InjectRepository(EntityClass) in services to inject repositories.

GraphQL Resolver Naming

All @Query and @Mutation names must use action verbs — never bare nouns:

// ✓ Correct
@Query(() => [UserResponseDto])
async getAllUsers(): Promise<UserResponseDto[]> { ... }

// ✗ Not allowed — bare noun
@Query(() => [UserResponseDto])
async users(): Promise<UserResponseDto[]> { ... }

Step-by-Step: Create a New Feature Module

Example: adding devices to the client domain.

1. Create folder structure:

src/modules/client/devices/
  devices.module.ts
  devices.resolver.ts
  devices.service.ts
  interfaces/
    index.ts
    device.interface.ts
  dtos/
    requests/index.ts
    responses/index.ts

2. Scaffold module, service, resolver:

// devices.module.ts
@Module({ providers: [ClientDevicesResolver, ClientDevicesService] })
export class ClientDevicesModule {}

// devices.service.ts
@Injectable()
export class ClientDevicesService {}

// devices.resolver.ts
@Resolver()
export class ClientDevicesResolver {
    constructor(private readonly devicesService: ClientDevicesService) {}
}

3. Register in domain root module:

// client.module.ts
@Module({ imports: [ClientUserModule, ClientDevicesModule] })
export class ClientModule {}

4. Create entity (if DB table needed):

• File: src/databases/postgres/entities/device/device.entity.ts
• No module registration needed — auto-discovered via glob.

5. Generate and run migration:

pnpm migration:generate CreateDevicesTable
pnpm migration:run

6. Add barrel exports to every interfaces/index.ts, dtos/requests/index.ts, dtos/responses/index.ts.

Step-by-Step: Add Config or Provider

New config section (e.g., caching):

1. Create src/configs/cache.config.ts exporting a factory function
2. Re-export from src/configs/index.ts
3. Add raw env values to src/configs/app.config.ts with sensible defaults — never let values be undefined

New infrastructure provider (e.g., queue):

1. Create src/providers/<name>/index.ts exporting a DynamicModule or provider array
2. Import it into the domain module that needs it — not into AppModule
3. Never instantiate Redis/BullMQ clients directly in feature services

TypeScript Conventions

Strict Mode

• No implicit any — every parameter and return value must be typed when TypeScript cannot infer precisely
• No non-null assertion (!) — use guard clauses or optional chaining instead
• as casts — allowed only when TypeScript cannot infer the type; add an inline comment explaining why
• Floating promises — always await or .catch() async calls

// ✗ Unsafe
const name = user!.name

// ✓ Safe guard
if (!user) throw new Error('User not found')
const name = user.name

// ✓ Justified cast — AuthGuard validates payload shape upstream
const userId = (req.user as JwtPayload).sub

Naming

interface vs type

Use interface for object shapes passed as inputs (especially 4+ fields) and anything that may be extended. Use type for unions, intersections, conditional types, and utility-derived types.

// ✓ interface — service input contract
export interface ICreateDeviceInput {
    name: string
    macAddress: string
    networkId: string
    notes?: string
}

// ✓ type — union
type SortDirection = 'ASC' | 'DESC'

Enums

Always use string enums — numeric enums are fragile when serialized:

export enum DeviceStatus {
    ONLINE = 'ONLINE',
    OFFLINE = 'OFFLINE',
    SUSPICIOUS = 'SUSPICIOUS',
}

Place shared enums in src/commons/enums/; feature-local enums in the feature's interfaces/ file.

Function Parameters and Return Types

• ≤3 parameters: positional arguments are fine

• 3 parameters: use a single named input object typed via an interface

• Always declare explicit return types on public class methods
• All async methods must explicitly declare Promise<T> — no inferred wrappers
• "Not found" returns use T | null, not T | undefined

// ✓
async findById(id: string): Promise<UserEntity | null> { ... }
async createDevice(input: ICreateDeviceInput): Promise<DeviceEntity> { ... }

Migration Conventions

For the complete reference with SQL format examples, see backend/.github/instructions/migration.instructions.md.

File Naming

Pattern: {timestamp}-{kebab-case-description}.ts

1777461999633-create-uuid-extension.ts
1777738982218-create-users-table.ts

Generate: pnpm migration:generate <PascalCaseName> Create stub: pnpm migration:create <PascalCaseName>

A migration file must never be renamed or edited after being applied to any environment.

Class Format

import { MigrationInterface, QueryRunner } from 'typeorm'

export class CreateDevicesTable1234567890123 implements MigrationInterface {
    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`-- SQL statement`)
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`-- reversal SQL`)
    }
}

• Only import: { MigrationInterface, QueryRunner } from 'typeorm' — no project imports
• Each queryRunner.query() must contain exactly one SQL statement

Standard Columns

Every new table must include, in this order: id first, then business columns, then created_at and updated_at last.

The uuid-ossp extension is already enabled — do not create it again.

Constraint Naming

Always use the full table name — never abbreviations.

Foreign Key Actions

ON DELETE must always be declared explicitly. Omit ON UPDATE for UUID primary keys.

General Authoring Rules

• One migration = one logical change (one table, one index group, one column addition)
• Migrations contain raw SQL only — never import TypeORM entity or repository methods
• synchronize: true must never be used as a substitute for migrations
• down() must fully and precisely reverse everything in up()
• Use IF NOT EXISTS on CREATE TABLE, DROP TABLE, CREATE INDEX, DROP INDEX
• Do not use IF NOT EXISTS on ALTER TABLE ADD COLUMN — failure there indicates a real inconsistency