git:20251217.3f83b43 to git:20251217.f66687a
147 added, 74 removed. Audit A to A.
---
name: generic-fullstack-feature-developer
description: Guide feature development for full-stack applications with architecture focus. Covers Next.js App Router patterns, NestJS backend services, database models, data workflows, and seamless integration. Use when adding new features, refactoring existing code, or planning major changes.
---
# Fullstack Feature Developer
- Guide feature development with Next.js/NestJS architecture patterns.
+ Guide feature development for Next.js/NestJS full-stack applications.
- ## Architecture Overview
+ **Extends:** [Generic Feature Developer](../generic-feature-developer/SKILL.md) - Read base skill for development workflow, decision frameworks, data flow patterns, and error handling.
- ### Frontend (Next.js App Router)
+ ## Full-Stack Data Flow
```
- src/
- ├── app/ # App Router
- │ ├── layout.tsx # Root layout
- │ ├── page.tsx # Home page
- │ └── [route]/ # Route folders
- ├── components/
- │ ├── layout/ # Header, Footer
- │ └── ui/ # shadcn/ui
- └── lib/
- ├── theme.ts # Colors
- └── utils.ts # Utilities
+ User Action → Event Handler → API Call → NestJS Controller
+ ↓
+ UI Update ← Response ← Service ← Prisma ← Database
```
- **Best Practices:**
- - App Router conventions
- - Single source of truth (layout.tsx for Header/Footer)
- - shadcn/ui for components
- - Theme colors from lib/theme.ts
+ ### Request/Response Cycle
- ### Backend (NestJS)
+ ```typescript
+ // Frontend: Call API
+ const response = await fetch('/api/users', {
+ method: 'POST',
+ body: JSON.stringify(userData),
+ });
+ // Backend: Handle request
+ @Post()
+ @UseGuards(JwtAuthGuard)
+ async createUser(@Body() dto: CreateUserDto) {
+ return this.userService.create(dto);
+ }
```
- src/
- ├── auth/ # Authentication
- ├── [module]/ # Feature modules
- ├── prisma/ # Database service
- └── common/ # Shared utilities
+
+ ## Next.js App Router Patterns
+
+ ### File Conventions
+
+ | File | Purpose |
+ |------|---------|
+ | `page.tsx` | Route UI (server component by default) |
+ | `layout.tsx` | Shared UI wrapper |
+ | `loading.tsx` | Suspense loading UI |
+ | `error.tsx` | Error boundary |
+ | `route.ts` | API endpoint |
+
+ ### Server vs Client Components
+
+ ```typescript
+ // Server Component (default) - can fetch data
+ export default async function Page() {
+ const data = await getData(); // Direct DB/API call
+ return <div>{data.title}</div>;
+ }
+
+ // Client Component - needs 'use client'
+ 'use client';
+ export default function Interactive() {
+ const [state, setState] = useState();
+ return <button onClick={() => setState(...)}>Click</button>;
+ }
```
- **Best Practices:**
- - Auth guards for protected routes
- - Validate with class-validator DTOs
- - Keep services focused
- - `npx prisma generate` after schema changes
+ ## NestJS Module Pattern
- ## Feature Checklist
+ ```
+ Module → Controller → Service → Prisma
+ ```
- ### Before Starting
- - [ ] Read existing code in affected areas
- - [ ] Check for similar patterns
- - [ ] Plan data flow: UI → API → Database
+ ### Adding a Feature Module
- ### During Development
- - [ ] Follow design system
- - [ ] Add TypeScript types
- - [ ] Implement keyboard navigation
- - [ ] Add ARIA labels
- - [ ] Test dark mode
+ ```typescript
+ // 1. Module definition
+ @Module({
+ controllers: [UsersController],
+ providers: [UsersService],
+ exports: [UsersService],
+ })
+ export class UsersModule {}
- ### Before Completion
- - [ ] Write tests
- - [ ] Verify builds pass
- - [ ] Run linter
- - [ ] Update CLAUDE.md if new patterns
+ // 2. Controller with guards
+ @Controller('users')
+ @UseGuards(JwtAuthGuard)
+ export class UsersController {
+ @Post()
+ create(@Body() dto: CreateUserDto) {
+ return this.usersService.create(dto);
+ }
+ }
- ## Common Patterns
+ // 3. Service with Prisma
+ @Injectable()
+ export class UsersService {
+ constructor(private prisma: PrismaService) {}
- ### Adding API Endpoint
- 1. Create DTO in `src/[module]/dto/`
- 2. Add service method
- 3. Add controller route with auth guard
- 4. Add validation decorators
- 5. Write tests
+ create(dto: CreateUserDto) {
+ return this.prisma.user.create({ data: dto });
+ }
+ }
+ ```
- ### Adding Page (Frontend)
- 1. Create in `src/app/[route]/page.tsx`
- 2. Export metadata
- 3. Follow component patterns
- 4. Use theme colors
- 5. Test responsive behavior
+ ## Prisma Workflow
- ### Database Schema Changes
- 1. Edit `schema.prisma`
- 2. Run `npx prisma migrate dev`
- 3. Run `npx prisma generate`
- 4. Update affected services
- 5. Add tests
+ ### Schema Changes
- ## Performance Guidelines
+ ```bash
+ # 1. Edit schema.prisma
+ # 2. Create migration
+ npx prisma migrate dev --name add_user_role
- - Bundle size awareness
- - Lazy load non-essential code
- - GPU-accelerated animations
- - Use Next.js Image component
- - Memoize expensive calculations
+ # 3. Regenerate client
+ npx prisma generate
+ # 4. Update services to use new fields
+ ```
+
+ ### Type-Safe Queries
+
+ ```typescript
+ // ✓ Type-safe with generated types
+ const user = await this.prisma.user.findUnique({
+ where: { id },
+ include: { posts: true },
+ });
+
+ // ✗ Avoid raw SQL
+ await this.prisma.$queryRaw`SELECT * FROM users`; // No type safety
+ ```
+
+ ## Authentication Flow
+
+ ```
+ Login Request → Validate Credentials → Generate JWT → Set Cookie
+ ↓
+ Protected Route → JwtAuthGuard → Extract User → Inject to Controller
+ ```
+
+ ### Auth Integration Points
+
+ ```typescript
+ // Frontend: Include credentials
+ fetch('/api/protected', { credentials: 'include' });
+
+ // Backend: Guard + decorator
+ @UseGuards(JwtAuthGuard)
+ @Get('profile')
+ getProfile(@CurrentUser() user: User) {
+ return user;
+ }
+ ```
+
+ ## Feature Checklist (Fullstack)
+
+ ### Before Starting
+ - [ ] Plan data model (Prisma schema)
+ - [ ] Define API contract (DTOs)
+ - [ ] Identify auth requirements
+
+ ### During Development
+ - [ ] Create/update Prisma schema
+ - [ ] Run migrations
+ - [ ] Implement NestJS module (controller + service)
+ - [ ] Create frontend components
+ - [ ] Add loading/error states
+
+ ### Before Completion
+ - [ ] Add DTO validation decorators
+ - [ ] Write backend unit tests
+ - [ ] Write E2E tests for API
+ - [ ] Verify TypeScript types match
+
## See Also
- - [Code Review Standards](./../_shared/CODE_REVIEW_STANDARDS.md) - Quality requirements
- - [Design Patterns](./../_shared/DESIGN_PATTERNS.md) - UI patterns
- - Project `CLAUDE.md` - Workflow rules
+ - [Generic Feature Developer](../generic-feature-developer/SKILL.md) - Base methodology
+ - [Code Review Standards](../_shared/CODE_REVIEW_STANDARDS.md) - Quality requirements
+ - [Design Patterns](../_shared/DESIGN_PATTERNS.md) - UI patterns