trackgo-be/.agents/skills/project-guidelines-example/SKILL.md

---
name: project-guidelines-example
description: NestJS modular TDD project guidelines with Drizzle and PostgreSQL. Use when scaffolding features, reviewing structure, or aligning code with this repo's conventions.
---

# Project Guidelines

Project skill for this NestJS API. Contains architecture, file structure, code patterns, testing, and deployment conventions.

## When to Use

Reference this skill when working on this project. It contains:

- Architecture overview
- File structure
- Code patterns
- Testing requirements
- Deployment workflow

---

## Architecture Overview

**Tech Stack:**

- **Backend**: NestJS
- **Database**: PostgreSQL using Drizzle ORM
- **Testing**: NestJS TestingModule (unit) and Supertest (E2E)

---

## File Structure

```
project/
├── src/
│   ├── main.ts                          # Application bootstrap
│   ├── app.module.ts                    # Root module
│   ├── common/                          # Shared cross-cutting concerns
│   │   ├── decorators/
│   │   ├── filters/
│   │   ├── guards/
│   │   ├── interceptors/
│   │   └── pipes/
│   ├── config/                          # Env and database config
│   └── modules/                         # Feature modules (one folder per domain)
│       ├── auth/
│       │   ├── auth.module.ts
│       │   ├── auth.controller.ts
│       │   ├── auth.controller.spec.ts  # Unit tests (colocated)
│       │   ├── auth.service.ts
│       │   ├── auth.service.spec.ts
│       │   ├── dto/
│       │   └── strategies/
│       └── users/
│           ├── users.module.ts
│           ├── users.controller.ts
│           ├── users.controller.spec.ts
│           ├── users.service.ts
│           ├── users.service.spec.ts
│           └── dto/
├── test/                                # E2E tests (NestJS convention)
│   ├── jest-e2e.json
│   ├── app.e2e-spec.ts
│   ├── auth.e2e-spec.ts
│   └── users.e2e-spec.ts
├── drizzle/                             # Schema and migrations
│   ├── schema.ts
│   └── migrations/
├── drizzle.config.ts                    # Drizzle Kit config
├── deploy/                              # Deployment configs
├── docs/                                # Documentation
└── scripts/                             # Utility scripts
```

---

## Code Patterns

### Controller + DTO

```typescript
export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  password: string;
}

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}
```

### Drizzle Repository

```typescript
@Injectable()
export class UsersRepository {
  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}

  findById(id: string) {
    return this.db.query.users.findFirst({
      where: eq(users.id, id),
    });
  }

  create(data: typeof users.$inferInsert) {
    return this.db.insert(users).values(data).returning();
  }
}
```

---

## Testing Requirements

```bash
# Unit tests
npm test

# Coverage
npm run test:cov

# E2E
npm run test:e2e
```

**Unit test (colocated `*.spec.ts`):**

```typescript
const moduleRef = await Test.createTestingModule({
  providers: [
    UsersService,
    { provide: UsersRepository, useValue: { findById: jest.fn() } },
  ],
}).compile();

const service = moduleRef.get(UsersService);
```

**E2E test (`test/*.e2e-spec.ts`):**

```typescript
describe('UsersController (e2e)', () => {
  it('/users (POST)', () => {
    return request(app.getHttpServer())
      .post('/users')
      .send({ email: 'ada@example.com', password: 'secret123' })
      .expect(201);
  });
});
```

---

## Deployment Workflow

### Pre-Deployment Checklist

- [ ] All tests passing locally
- [ ] `npm run build` succeeds
- [ ] `npm run test:e2e` passes
- [ ] No hardcoded secrets
- [ ] Environment variables documented
- [ ] Drizzle migrations applied

### Deployment Commands

```bash
npm run build
npx drizzle-kit migrate
# deploy the NestJS API (Cloud Run, Fly, or similar)
```

### Environment Variables

```bash
DATABASE_URL=postgresql://user:pass@host:5432/tracking
PORT=3000
JWT_SECRET=...
```

---

## Critical Rules

1. **No emojis** in code, comments, or documentation
2. **Immutability** - never mutate objects or arrays
3. **TDD** - write tests before implementation
4. **80% coverage** minimum
5. **Many small files** - 200-400 lines typical, 800 max
6. **No console.log** in production code
7. **Exception filters** for HTTP errors, not raw try/catch in controllers
8. **Input validation** with class-validator DTOs

---

## Related Skills

- `.agents/skills/coding-standards/` - General coding best practices
- `.agents/skills/backend-patterns/` - API and database patterns
- `.agents/skills/nestjs-best-practices/` - NestJS architecture and security
- `.agents/skills/tdd-workflow/` - Test-driven development methodology