# Create a new NestJS project
npm install -g @nestjs/cli
nest new my-api
cd my-api
npm run start:dev  # Starts with hot reload

my-api/
├── src/
│   ├── app.controller.ts       # Root controller
│   ├── app.controller.spec.ts  # Root controller tests
│   ├── app.module.ts           # Root module
│   ├── app.service.ts          # Root service
│   └── main.ts                 # Entry point
├── test/
│   └── app.e2e-spec.ts         # End-to-end tests
├── nest-cli.json               # NestJS CLI configuration
├── package.json
└── tsconfig.json

# Generate a complete resource (CRUD)
nest generate resource articles
# Creates:
# src/articles/
#   ├── articles.module.ts
#   ├── articles.controller.ts
#   ├── articles.controller.spec.ts
#   ├── articles.service.ts
#   ├── articles.service.spec.ts
#   ├── dto/
#   │   ├── create-article.dto.ts
#   │   └── update-article.dto.ts
#   └── entities/
#       └── article.entity.ts

# Generate individual components
nest g controller articles
nest g service articles
nest g module articles
nest g guard auth
nest g middleware logger
nest g interceptor transform
nest g pipe validation

// src/main.ts
import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
import { AppModule } from "./app.module";

async function bootstrap() {
    const app = await NestFactory.create(AppModule);

    // Global prefix for all routes
    app.setGlobalPrefix("api/v1");

    // Enable CORS
    app.enableCors({
        origin: ["http://localhost:3000", "https://futuretechzone.in"],
        credentials: true
    });

    // Global validation pipe — validate all incoming DTOs
    app.useGlobalPipes(new ValidationPipe({
        whitelist: true,          // Strip properties not in DTO
        forbidNonWhitelisted: true,  // Throw error for extra properties
        transform: true           // Auto-transform types
    }));

    // Swagger API documentation
    const config = new DocumentBuilder()
        .setTitle("FutureTechZone API")
        .setDescription("The FutureTechZone REST API")
        .setVersion("1.0")
        .addBearerAuth()
        .build();
    const document = SwaggerModule.createDocument(app, config);
    SwaggerModule.setup("api/docs", app, document);

    await app.listen(3000);
    console.log("Application running on http://localhost:3000");
    console.log("API docs at http://localhost:3000/api/docs");
}

bootstrap();

// src/articles/articles.module.ts
import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { ArticlesController } from "./articles.controller";
import { ArticlesService } from "./articles.service";
import { Article } from "./entities/article.entity";
import { UsersModule } from "../users/users.module";

@Module({
    imports: [
        TypeOrmModule.forFeature([Article]),  // Register entity for this module
        UsersModule,                           // Import UsersModule for UserService
    ],
    controllers: [ArticlesController],         // HTTP request handlers
    providers: [ArticlesService],              // Business logic providers
    exports: [ArticlesService],                // Make service available to other modules
})
export class ArticlesModule {}

// src/app.module.ts — Root module
import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { ArticlesModule } from "./articles/articles.module";
import { UsersModule } from "./users/users.module";
import { AuthModule } from "./auth/auth.module";

@Module({
    imports: [
        // Configuration module (reads .env)
        ConfigModule.forRoot({
            isGlobal: true,     // Available everywhere without importing
            envFilePath: ".env"
        }),

        // Database connection
        TypeOrmModule.forRootAsync({
            imports: [ConfigModule],
            useFactory: (config: ConfigService) => ({
                type: "postgres",
                host: config.get("DB_HOST"),
                port: config.get<number>("DB_PORT"),
                username: config.get("DB_USER"),
                password: config.get("DB_PASSWORD"),
                database: config.get("DB_NAME"),
                entities: [__dirname + "/**/*.entity{.ts,.js}"],
                synchronize: config.get("NODE_ENV") === "development",
                logging: config.get("NODE_ENV") === "development",
            }),
            inject: [ConfigService],
        }),

        // Feature modules
        ArticlesModule,
        UsersModule,
        AuthModule,
    ],
})
export class AppModule {}

// src/articles/articles.controller.ts
import {
    Controller, Get, Post, Put, Patch, Delete, Param, Body,
    Query, UseGuards, ParseIntPipe, HttpCode, HttpStatus
} from "@nestjs/common";
import { ApiTags, ApiBearerAuth, ApiOperation, ApiResponse } from "@nestjs/swagger";
import { ArticlesService } from "./articles.service";
import { CreateArticleDto } from "./dto/create-article.dto";
import { UpdateArticleDto } from "./dto/update-article.dto";
import { ArticleQueryDto } from "./dto/article-query.dto";
import { JwtAuthGuard } from "../auth/guards/jwt-auth.guard";
import { CurrentUser } from "../auth/decorators/current-user.decorator";
import { User } from "../users/entities/user.entity";

@ApiTags("Articles")                    // Swagger tag grouping
@Controller("articles")                 // Base route: /api/v1/articles
export class ArticlesController {

    constructor(private readonly articlesService: ArticlesService) {}

    // GET /api/v1/articles?page=1&limit=20&published=true
    @Get()
    @ApiOperation({ summary: "Get all published articles" })
    @ApiResponse({ status: 200, description: "List of articles" })
    findAll(@Query() query: ArticleQueryDto) {
        return this.articlesService.findAll(query);
    }

    // GET /api/v1/articles/trending
    @Get("trending")
    getTrending() {
        return this.articlesService.getTrending();
    }

    // GET /api/v1/articles/:id
    @Get(":id")
    findOne(@Param("id", ParseIntPipe) id: number) {
        // ParseIntPipe automatically converts and validates the id is a number
        return this.articlesService.findOne(id);
    }

    // GET /api/v1/articles/:id/comments
    @Get(":id/comments")
    getComments(@Param("id", ParseIntPipe) id: number) {
        return this.articlesService.getComments(id);
    }

    // POST /api/v1/articles (authenticated)
    @Post()
    @UseGuards(JwtAuthGuard)
    @ApiBearerAuth()
    @ApiOperation({ summary: "Create a new article" })
    @ApiResponse({ status: 201, description: "Article created" })
    create(
        @Body() createArticleDto: CreateArticleDto,
        @CurrentUser() user: User    // Custom decorator to get logged-in user
    ) {
        return this.articlesService.create(createArticleDto, user);
    }

    // PATCH /api/v1/articles/:id (authenticated)
    @Patch(":id")
    @UseGuards(JwtAuthGuard)
    @ApiBearerAuth()
    update(
        @Param("id", ParseIntPipe) id: number,
        @Body() updateArticleDto: UpdateArticleDto,
        @CurrentUser() user: User
    ) {
        return this.articlesService.update(id, updateArticleDto, user);
    }

    // DELETE /api/v1/articles/:id (authenticated)
    @Delete(":id")
    @UseGuards(JwtAuthGuard)
    @HttpCode(HttpStatus.NO_CONTENT)   // Returns 204 No Content
    remove(
        @Param("id", ParseIntPipe) id: number,
        @CurrentUser() user: User
    ) {
        return this.articlesService.remove(id, user);
    }
}

// src/articles/articles.service.ts
import {
    Injectable, NotFoundException, ForbiddenException, BadRequestException
} from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { Repository, FindManyOptions } from "typeorm";
import { Article } from "./entities/article.entity";
import { CreateArticleDto } from "./dto/create-article.dto";
import { UpdateArticleDto } from "./dto/update-article.dto";
import { User } from "../users/entities/user.entity";

@Injectable()
export class ArticlesService {

    constructor(
        @InjectRepository(Article)
        private readonly articleRepository: Repository<Article>,
    ) {}

    async findAll(query: { page: number; limit: number; published?: boolean }) {
        const { page = 1, limit = 20, published = true } = query;
        const [articles, total] = await this.articleRepository.findAndCount({
            where: published !== undefined ? { published } : {},
            relations: ["author", "tags"],
            order: { publishedAt: "DESC" },
            skip: (page - 1) * limit,
            take: limit,
        });

        return {
            data: articles,
            pagination: { page, limit, total, totalPages: Math.ceil(total / limit) }
        };
    }

    async findOne(id: number): Promise<Article> {
        const article = await this.articleRepository.findOne({
            where: { id },
            relations: ["author", "tags", "comments"]
        });

        if (!article) {
            throw new NotFoundException(`Article #${id} not found`);
        }

        // Increment view count atomically
        await this.articleRepository.increment({ id }, "views", 1);

        return article;
    }

    async create(createArticleDto: CreateArticleDto, author: User): Promise<Article> {
        const slug = this.generateSlug(createArticleDto.title);

        // Check for duplicate slug
        const existing = await this.articleRepository.findOne({ where: { slug } });
        if (existing) {
            throw new BadRequestException("An article with this title already exists");
        }

        const article = this.articleRepository.create({
            ...createArticleDto,
            slug,
            author,
        });

        return this.articleRepository.save(article);
    }

    async update(id: number, updateArticleDto: UpdateArticleDto, user: User): Promise<Article> {
        const article = await this.findOne(id);

        // Authorization: only author or admin can update
        if (article.author.id !== user.id && user.role !== "admin") {
            throw new ForbiddenException("You can only edit your own articles");
        }

        Object.assign(article, updateArticleDto);

        if (updateArticleDto.title && updateArticleDto.title !== article.title) {
            article.slug = this.generateSlug(updateArticleDto.title);
        }

        return this.articleRepository.save(article);
    }

    async remove(id: number, user: User): Promise<void> {
        const article = await this.findOne(id);

        if (article.author.id !== user.id && user.role !== "admin") {
            throw new ForbiddenException("You can only delete your own articles");
        }

        await this.articleRepository.remove(article);
    }

    private generateSlug(title: string): string {
        return title
            .toLowerCase()
            .replace(/[^a-z0-9]+/g, "-")
            .replace(/^-|-$/g, "");
    }
}