Project Structure

This guide explains the organization of a generated NestJS project and where to add your custom code.

Directory Layout


my-api/
├── src/
│   ├── entities/               # Generated: TypeORM entities
│   ├── modules/                # Generated: NestJS modules
│   ├── extensions/             # Your code: Custom additions
│   ├── common/                 # Generated: Shared utilities
│   ├── config/                 # Configuration files
│   ├── migrations/             # Database migrations
│   ├── app.module.ts           # Root module
│   └── main.ts                 # Application entry point
├── test/                       # Test files
├── .apsorc                     # APSO schema definition
└── package.json

Generated Code

Entities (`src/entities/`)

TypeORM entity definitions:


// src/entities/project.entity.ts
import { Entity, Column, PrimaryGeneratedColumn, OneToMany } from 'typeorm';
import { Task } from './task.entity';
 
@Entity('projects')
export class Project {
  @PrimaryGeneratedColumn('uuid')
  id: string;
 
  @Column()
  name: string;
 
  @Column({ nullable: true })
  description: string;
 
  @Column()
  organizationId: string;
 
  @OneToMany(() => Task, task => task.project)
  tasks: Task[];
 
  @Column({ type: 'timestamp', default: () => 'CURRENT_TIMESTAMP' })
  createdAt: Date;
 
  @Column({ type: 'timestamp', default: () => 'CURRENT_TIMESTAMP' })
  updatedAt: Date;
}

Modules (`src/modules/`)

Each entity gets its own module:


src/modules/projects/
├── projects.module.ts      # Module definition
├── projects.controller.ts  # HTTP endpoints
├── projects.service.ts     # Business logic
└── dto/
    ├── create-project.dto.ts
    └── update-project.dto.ts

Controller Example


// src/modules/projects/projects.controller.ts
@Controller('projects')
@UseGuards(AuthGuard)
export class ProjectsController {
  constructor(private readonly projectsService: ProjectsService) {}
 
  @Get()
  @ApiOperation({ summary: 'Get all projects' })
  findAll(
    @Query() query: FindAllQuery,
    @CurrentUser() user: User,
  ) {
    return this.projectsService.findAll(query, user);
  }
 
  @Post()
  @ApiOperation({ summary: 'Create a project' })
  create(
    @Body() dto: CreateProjectDto,
    @CurrentUser() user: User,
  ) {
    return this.projectsService.create(dto, user);
  }
}

Service Example


// src/modules/projects/projects.service.ts
@Injectable()
export class ProjectsService {
  constructor(
    @InjectRepository(Project)
    private readonly repository: Repository<Project>,
  ) {}
 
  async findAll(query: FindAllQuery, user: User) {
    return this.repository.find({
      where: { organizationId: user.organizationId },
      take: query.limit,
      skip: query.offset,
    });
  }
 
  async create(dto: CreateProjectDto, user: User) {
    const project = this.repository.create({
      ...dto,
      organizationId: user.organizationId,
    });
    return this.repository.save(project);
  }
}

Common (`src/common/`)

Shared utilities and decorators:


src/common/
├── decorators/
│   ├── current-user.decorator.ts
│   └── organization.decorator.ts
├── guards/
│   ├── auth.guard.ts
│   └── organization.guard.ts
├── interceptors/
│   └── transform.interceptor.ts
└── filters/
    └── http-exception.filter.ts

Extension Points

Extensions Directory (`src/extensions/`)

Add your custom code here. It won’t be overwritten during regeneration.


src/extensions/
├── controllers/          # Custom endpoints
│   └── reports.controller.ts
├── services/             # Custom services
│   └── email.service.ts
├── modules/              # Complete modules
│   └── analytics/
└── index.ts              # Exports

Adding Custom Endpoints


// src/extensions/controllers/reports.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthGuard } from '../../common/guards/auth.guard';
 
@Controller('reports')
@UseGuards(AuthGuard)
export class ReportsController {
  @Get('summary')
  async getSummary() {
    // Your custom logic
    return { total: 100, active: 75 };
  }
}


// src/extensions/index.ts
import { Module } from '@nestjs/common';
import { ReportsController } from './controllers/reports.controller';
 
@Module({
  controllers: [ReportsController],
  providers: [],
})
export class ExtensionsModule {}

Configuration Files

Root Module


// src/app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot(),
    TypeOrmModule.forRoot(databaseConfig),
    ProjectsModule,
    TasksModule,
    ExtensionsModule,  // Your custom module
  ],
})
export class AppModule {}

Main Entry Point


// src/main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
 
  app.setGlobalPrefix('api/v1');
  app.enableCors();
 
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setVersion('1.0')
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document);
 
  await app.listen(process.env.PORT || 3001);
}
bootstrap();

File Naming Conventions

Type	Pattern	Example
Entity	`{name}.entity.ts`	`project.entity.ts`
Module	`{name}.module.ts`	`projects.module.ts`
Controller	`{name}.controller.ts`	`projects.controller.ts`
Service	`{name}.service.ts`	`projects.service.ts`
DTO	`{action}-{name}.dto.ts`	`create-project.dto.ts`
Guard	`{name}.guard.ts`	`auth.guard.ts`
Decorator	`{name}.decorator.ts`	`current-user.decorator.ts`