AGENTS.md - Agentic Coding Guide

Instructions for AI coding agents working in this pnpm monorepo.

Project Structure

```
apps/backend
```
- NestJS 11 API (TypeORM, PostgreSQL, Auth0, Stripe)
```
apps/frontend
```
- Next.js 14 (React 19, Tailwind CSS 4, React Query)
```
apps/backend-e2e
```
- E2E tests for backend API
```
libs/project-setup
```
- Project initialization utilities

Build/Lint/Test Commands

Root Level

pnpm run build          # Build all packages (excludes backend-e2e, frontend)
pnpm run test           # Run tests across all packages
pnpm run lint           # Lint all packages
pnpm run mill:dev       # Start local dev (docker + backend + frontend)
pnpm run knip           # Check for unused code/dependencies

Backend (

apps/backend

)

pnpm run build          # Build the backend
pnpm run start          # Start in watch mode (development)
pnpm run lint           # Lint with auto-fix
pnpm run test           # Run all tests (Vitest)
pnpm run up             # Start Docker services (PostgreSQL, Redis)
pnpm run down           # Stop Docker services
pnpm run db:run         # Run database migrations
pnpm run db:gen         # Generate new migration

Running a Single Test

# Backend - run specific test file (Vitest)
cd apps/backend && pnpm run test src/course-files/services/file-scrambler.service.test.ts

# Backend - run tests matching pattern
cd apps/backend && pnpm run test --testNamePattern="partition"

# Backend E2E tests
cd apps/backend-e2e && pnpm run test:e

# Project setup tests (Vitest)
cd libs/project-setup && pnpm run test

Frontend (

apps/frontend

)

pnpm run build          # Build for production
pnpm run start          # Start development server
pnpm run lint           # Run Next.js linting

Code Style Guidelines

Formatting (Prettier)

Tab width: 4 spaces (no tabs), Semicolons: Always, Quotes: Double quotes only

TypeScript Strictness

All strict checks enabled:

strict

noImplicitAny

strictNullChecks

strictPropertyInitialization

noUnusedLocals

noImplicitReturns

ESM Module System

This project uses ESM (

"type": "module"

). Use

.js

extensions for local imports:

import { MyService } from "./my-service.js"; // Correct
import { MyService } from "./my-service"; // Incorrect

File Naming Conventions

Type	Pattern	Example
Entities	`kebab-case.entity.ts`	`org-github-user.entity.ts`
DTOs	`kebab-case.dto.ts`	`create-user.dto.ts`
Services	`kebab-case.service.ts`	`user-onboarding.service.ts`
Controllers	`kebab-case.controller.ts`	`payments.controller.ts`
Modules	`kebab-case.module.ts`	`payments.module.ts`
Unit tests	`*.test.ts`	`file-scrambler.service.test.ts`
E2E tests	`*.e2e-spec.ts`	`basic-security.e2e-spec.ts`
React components	`PascalCase.tsx`	`UserProfile.tsx`
React hooks	`useCamelCase.ts`	`useAuth.ts`

Code Naming Conventions

Classes/Types/Interfaces:
```
PascalCase
```
Functions/Methods/Variables:
```
camelCase
```
Constants:
```
camelCase
```
or
```
UPPER_CASE
```
Enum members:
```
UPPER_CASE
```
Boolean variables: Must have prefix
```
is
```
,
```
should
```
,
```
has
```
,
```
can
```
,
```
did
```
, or
```
will
```
Private members:
```
camelCase
```
(no leading underscore)

Import Order

Framework imports (NestJS, React)
Third-party libraries
Shared libraries (
```
@darraghor/nest-backend-libs
```
)
Local imports (with
```
.js
```
extension for backend)

// Example backend import order
import { Injectable, Logger } from "@nestjs/common";
import { Repository } from "typeorm";
import { InjectRepository } from "@nestjs/typeorm";
import { RequestUser } from "@darraghor/nest-backend-libs";
import { MyEntity } from "../models/my-entity.entity.js";
import { HelperService } from "./helper-service.js";

Error Handling

Use NestJS built-in exceptions:

import { ForbiddenException, NotFoundException } from "@nestjs/common";

if (!hasPermission) {
    throw new ForbiddenException(
        "You do not have permission to perform this action",
    );
}

if (!entity) {
    throw new NotFoundException("Resource not found");
}

Use a Logger instance per service:

private readonly logger = new Logger(MyService.name);

Entity & DTO Patterns

@Entity()
export class MyEntity {
    @PrimaryGeneratedColumn()
    @ApiProperty()
    id!: number;

    @Column()
    @ApiProperty()
    name!: string;
}

export class CreateMyDto {
    @IsString()
    @ApiProperty()
    name!: string;

    @IsOptional()
    @IsUrl()
    @ApiPropertyOptional()
    url?: string;
}

Testing Patterns (Vitest)

describe("MyService", () => {
    const service = new MyService();

    describe("myMethod", () => {
        it("should return expected result", () => {
            expect(service.myMethod("input")).toBe("expected");
        });

        test.each([
            { input: "a", expected: "A" },
            { input: "b", expected: "B" },
        ])("should handle $input", ({ input, expected }) => {
            expect(service.myMethod(input)).toBe(expected);
        });
    });
});

Commit Messages

Uses Conventional Commits:

feat:

fix:

refactor:

docs:

test:

chore:

Technology Stack

Runtime: Node.js 24.12.0+
Package Manager: pnpm 10.27.0+
Backend: NestJS 11, TypeORM 0.3, PostgreSQL
Frontend: Next.js 14, React 19, Tailwind CSS 4
Testing: Vitest
Auth: Auth0
Payments: Stripe
State: React Query (TanStack Query)

AGENTS.md - Agentic Coding Guide

Instructions for AI coding agents working in this pnpm monorepo.

Project Structure

```
apps/backend
```
- NestJS 11 API (TypeORM, PostgreSQL, Auth0, Stripe)
```
apps/frontend
```
- Next.js 14 (React 19, Tailwind CSS 4, React Query)
```
apps/backend-e2e
```
- E2E tests for backend API
```
libs/project-setup
```
- Project initialization utilities

Build/Lint/Test Commands

Root Level

pnpm run build          # Build all packages (excludes backend-e2e, frontend)
pnpm run test           # Run tests across all packages
pnpm run lint           # Lint all packages
pnpm run mill:dev       # Start local dev (docker + backend + frontend)
pnpm run knip           # Check for unused code/dependencies

Backend (

apps/backend

)

pnpm run build          # Build the backend
pnpm run start          # Start in watch mode (development)
pnpm run lint           # Lint with auto-fix
pnpm run test           # Run all tests (Vitest)
pnpm run up             # Start Docker services (PostgreSQL, Redis)
pnpm run down           # Stop Docker services
pnpm run db:run         # Run database migrations
pnpm run db:gen         # Generate new migration

Running a Single Test

# Backend - run specific test file (Vitest)
cd apps/backend && pnpm run test src/course-files/services/file-scrambler.service.test.ts

# Backend - run tests matching pattern
cd apps/backend && pnpm run test --testNamePattern="partition"

# Backend E2E tests
cd apps/backend-e2e && pnpm run test:e

# Project setup tests (Vitest)
cd libs/project-setup && pnpm run test

Frontend (

apps/frontend

)

pnpm run build          # Build for production
pnpm run start          # Start development server
pnpm run lint           # Run Next.js linting

Code Style Guidelines

Formatting (Prettier)

Tab width: 4 spaces (no tabs), Semicolons: Always, Quotes: Double quotes only

TypeScript Strictness

All strict checks enabled:

strict

noImplicitAny

strictNullChecks

strictPropertyInitialization

noUnusedLocals

noImplicitReturns

ESM Module System

This project uses ESM (

"type": "module"

). Use

.js

extensions for local imports:

import { MyService } from "./my-service.js"; // Correct
import { MyService } from "./my-service"; // Incorrect

File Naming Conventions

Type	Pattern	Example
Entities	`kebab-case.entity.ts`	`org-github-user.entity.ts`
DTOs	`kebab-case.dto.ts`	`create-user.dto.ts`
Services	`kebab-case.service.ts`	`user-onboarding.service.ts`
Controllers	`kebab-case.controller.ts`	`payments.controller.ts`
Modules	`kebab-case.module.ts`	`payments.module.ts`
Unit tests	`*.test.ts`	`file-scrambler.service.test.ts`
E2E tests	`*.e2e-spec.ts`	`basic-security.e2e-spec.ts`
React components	`PascalCase.tsx`	`UserProfile.tsx`
React hooks	`useCamelCase.ts`	`useAuth.ts`

Code Naming Conventions

Classes/Types/Interfaces:
```
PascalCase
```
Functions/Methods/Variables:
```
camelCase
```
Constants:
```
camelCase
```
or
```
UPPER_CASE
```
Enum members:
```
UPPER_CASE
```
Boolean variables: Must have prefix
```
is
```
,
```
should
```
,
```
has
```
,
```
can
```
,
```
did
```
, or
```
will
```
Private members:
```
camelCase
```
(no leading underscore)

Import Order

Framework imports (NestJS, React)
Third-party libraries
Shared libraries (
```
@darraghor/nest-backend-libs
```
)
Local imports (with
```
.js
```
extension for backend)

// Example backend import order
import { Injectable, Logger } from "@nestjs/common";
import { Repository } from "typeorm";
import { InjectRepository } from "@nestjs/typeorm";
import { RequestUser } from "@darraghor/nest-backend-libs";
import { MyEntity } from "../models/my-entity.entity.js";
import { HelperService } from "./helper-service.js";

Error Handling

Use NestJS built-in exceptions:

import { ForbiddenException, NotFoundException } from "@nestjs/common";

if (!hasPermission) {
    throw new ForbiddenException(
        "You do not have permission to perform this action",
    );
}

if (!entity) {
    throw new NotFoundException("Resource not found");
}

Use a Logger instance per service:

private readonly logger = new Logger(MyService.name);

Entity & DTO Patterns

@Entity()
export class MyEntity {
    @PrimaryGeneratedColumn()
    @ApiProperty()
    id!: number;

    @Column()
    @ApiProperty()
    name!: string;
}

export class CreateMyDto {
    @IsString()
    @ApiProperty()
    name!: string;

    @IsOptional()
    @IsUrl()
    @ApiPropertyOptional()
    url?: string;
}

Testing Patterns (Vitest)

describe("MyService", () => {
    const service = new MyService();

    describe("myMethod", () => {
        it("should return expected result", () => {
            expect(service.myMethod("input")).toBe("expected");
        });

        test.each([
            { input: "a", expected: "A" },
            { input: "b", expected: "B" },
        ])("should handle $input", ({ input, expected }) => {
            expect(service.myMethod(input)).toBe(expected);
        });
    });
});

Commit Messages

Uses Conventional Commits:

feat:

fix:

refactor:

docs:

test:

chore:

Technology Stack

Runtime: Node.js 24.12.0+
Package Manager: pnpm 10.27.0+
Backend: NestJS 11, TypeORM 0.3, PostgreSQL
Frontend: Next.js 14, React 19, Tailwind CSS 4
Testing: Vitest
Auth: Auth0
Payments: Stripe
State: React Query (TanStack Query)

AGENTS.md - Agentic Coding Guide

Related Skills

Markdown Converter

Nano Banana Pro

1password