# Next.js Project Rules

## Language
- All code, comments, documentation, commits, and PRs MUST be written in English.

## Architecture

### Folder Structure
- `/app`: App router pages and API routes
  - Route-specific components should be placed in their respective route folders
- `/components`: Reusable UI components
  - `/ui`: Shadcn UI components and their derivatives
- `/contexts`: React Context providers
- `/hooks`: Custom React hooks
- `/lib`: Utility functions and configuration
- `/public`: Static assets
- `/services`: API service functions
- `/styles`: Global styles
- `/types`: TypeScript type definitions

### Component Guidelines
- Use functional components with TypeScript
- Use the `.tsx` extension for React components
- Follow a logical naming convention:
  - Complex components: Use PascalCase and create folders with an index.tsx file
  - Simple components: Single PascalCase named files

### State Management
- Use React Context for global state
- Use React hooks for local state
- Avoid prop drilling more than 2 levels deep

### API & Data Fetching
- Use API service modules in `/services` directory
- Implement proper error handling and loading states
- Use React Query or SWR for complex data fetching where appropriate

## Development Patterns

### Code Quality
- Maintain type safety - avoid using `any` type
- Write self-documenting code with descriptive names
- Keep components focused on a single responsibility
- Extract complex logic into custom hooks
- Follow DRY (Don't Repeat Yourself) principle

### CSS & Styling
- Use Tailwind CSS for styling
- Use Shadcn UI components as base building blocks
- Maintain consistent spacing and sizing

### Performance
- Avoid unnecessary re-renders
- Optimize images and assets
- Implement code splitting where appropriate
- Use dynamic imports for large components/pages

### Testing
- Write tests for critical business logic
- Test components in isolation
- Implement end-to-end tests for critical user flows

## Git Workflow

### Branch Naming
- Features: `feature/short-description`
- Bugfixes: `fix/short-description`
- Hotfixes: `hotfix/short-description`
- Releases: `release/version`

## Conventions
- Variable and function names in English
- Log and error messages in English
- Documentation in English
- User-facing content (emails, responses) in English
- Indentation with 4 spaces
- Maximum of 79 characters per line

## Commit Rules
- Use Conventional Commits format for all commit messages
- Format: `<type>(<scope>): <description>`
- Types:
  - `feat`: A new feature
  - `fix`: A bug fix
  - `docs`: Documentation changes
  - `style`: Changes that do not affect code meaning (formatting, etc.)
  - `refactor`: Code changes that neither fix a bug nor add a feature
  - `perf`: Performance improvements
  - `test`: Adding or modifying tests
  - `chore`: Changes to build process or auxiliary tools
- Scope is optional and should be the module or component affected
- Description should be concise, in the imperative mood, and not capitalized
- Use body for more detailed explanations if needed
- Reference issues in the footer with `Fixes #123` or `Relates to #123`
- Examples:
  - `feat(auth): add password reset functionality`
  - `fix(api): correct validation error in client registration`
  - `docs: update API documentation for new endpoints`
  - `refactor(services): improve error handling in authentication`

Format: `type(scope): subject`

Examples:
- `feat(auth): add login form validation`
- `fix(api): resolve user data fetching issue`
- `docs(readme): update installation instructions`
- `style(components): format according to style guide`

### Pull Requests
- Keep PRs focused on a single feature or fix
- Include descriptive titles and descriptions
- Reference related issues
- Request code reviews from appropriate team members
- Ensure CI checks pass before merging

## Code Review Guidelines
- Focus on code quality, architecture, and maintainability
- Provide constructive feedback
- Address all review comments before merging
- Maintain a respectful and collaborative tone