bot-with-admin-starter/CONTRIBUTING.md

Contributing Guide

This guide helps developers (and AI assistants) understand how to contribute to this project.

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd bot-with-admin-starter
   

2. Set up environment

   cp .env.example .env
   # Edit .env with your values
   

3. Start development environment

   docker compose -f compose.dev.yml up -d
   

4. Create super admin

   docker exec -it ${PROJECT_NAME}_back sh
   pnpm console admin create {username} {email}
   

5. Start frontend

   cd front
   npm install
   npm run dev
   

Code Style

TypeScript

• Use strict typing - avoid any
• Prefer interfaces over types
• Use enums for fixed sets
• Always define return types
• Add JSDoc for public APIs

NestJS Backend

• Follow module structure: Controller → Service → Repository
• Use DTOs with class-validator
• Services contain business logic, controllers handle HTTP
• Use dependency injection
• Use guards for auth
• Use interceptors for response transformation

React Frontend

• Functional components with hooks
• React Query for API calls
• Zod schemas for validation
• Mantine components consistently
• TypeScript paths (@/*) for imports

Adding a New Feature

Backend

1. Create entity

   # File: back/src/feature/entities/feature.entity.ts
   

   import { Entity, Column } from 'typeorm';
   import { AbstractEntity } from 'src/common/entities/abstract.entity';
   
   @Entity('features')
   export class Feature extends AbstractEntity {
     @Column()
     name: string;
   }
   

2. Create DTOs

   # Files: back/src/feature/dto/create-feature.dto.ts
   #        back/src/feature/dto/update-feature.dto.ts
   

3. Create service

   # File: back/src/feature/feature.service.ts
   

4. Create controller

   # File: back/src/feature/feature.controller.ts
   

5. Create module

   # File: back/src/feature/feature.module.ts
   

6. Register in AppModule

   // back/src/app.module.ts
   imports: [
     // ...
     FeatureModule,
   ]
   

7. Generate migration

   cd back
   pnpm migration:generate --name=create-feature
   

Frontend

1. Create Zod schemas

   # File: front/src/api/dtos/feature.ts
   

2. Create API hooks

   # File: front/src/hooks/api/feature.ts
   

3. Create page component

   # File: front/src/pages/feature/index.tsx
   

4. Add route

   // front/src/routes/index.tsx
   {
     path: '/feature',
     element: <FeaturePage />,
   }
   

Git Workflow

1. Create feature branch

   git checkout -b feature/my-feature
   

2. Make changes

   • Write code following style guide
   • Add tests if applicable
   • Update documentation

3. Commit changes

   git commit -m "feat: add new feature"
   

   Use conventional commits:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation
   • style: Formatting
   • refactor: Code refactoring
   • test: Tests
   • chore: Maintenance

4. Push and create PR

   git push origin feature/my-feature
   

Testing

Backend

cd back
pnpm test
pnpm test:e2e

Frontend

cd front
npm run test

Code Review Checklist

• Code follows style guide
• Tests pass
• Documentation updated
• No console.logs or debug code
• Environment variables documented
• Migration files created for schema changes
• JSDoc comments added for public APIs

Questions?

• Check .cursorrules for code conventions
• See AGENTS.md for architecture details
• See EXAMPLES.md for code examples