.cursorrules

# OrbitChat.io Development Guidelines

## Architecture Overview
- Backend: NestJS with TypeORM and PostgreSQL
- Frontend: Vue 3 with Nuxt 3
- Infrastructure: Docker-based development environment
- Local development managed through Makefile commands

## Backend Guidelines
1. Use NestJS with strict TypeScript configuration
2. Database:
   - PostgreSQL as primary database
   - TypeORM for database operations
   - All entities must have proper migrations
   - Implement repository pattern

3. API Design:
   - Follow REST principles strictly
   - Use proper HTTP methods (GET, POST, PUT, DELETE)
   - Implement versioning (v1, v2, etc.)
   - Use DTOs for request/response validation
   - Implement proper error handling

4. Authentication & Authorization:
   - Implement role-based access control (RBAC)
   - Feature flags system for all users
   - JWT-based authentication
   - Role-based middleware for route protection

## Frontend Guidelines
1. Vue 3 + Nuxt 3 Architecture:
   - Custom components only - no external UI libraries
   - Composition API usage
   - TypeScript for type safety

2. State Management:
   - Use Pinia for state management
   - Stores must handle all API communications
   - Components must never directly call API endpoints
   - Implement proper state hydration

3. Component Structure:
   - Atomic design principles
   - Self-contained components
   - Props validation
   - Emit typed events
   - Use composables for shared logic

4. API Integration:
   - Create dedicated API services
   - All API calls must go through Pinia stores
   - Implement proper error handling
   - Use TypeScript interfaces for API responses

## Development Workflow
1. Docker:
   - Containerized development environment
   - Separate containers for frontend, backend, and database
   - Production-ready Dockerfile configurations
   - Docker Compose for local development

2. Build Process:
   - All commands through Makefile
   - Consistent command structure
   - Development and production builds
   - Hot-reload for development

3. Code Quality:
   - ESLint + Prettier configuration
   - Strict TypeScript rules
   - Unit tests required
   - E2E tests for critical paths

4. Feature Flags:
   - Implement feature flag system
   - Role-based feature access
   - Easy toggle mechanism
   - Feature flag persistence

## Security Guidelines
1. Backend:
   - Input validation
   - Rate limiting
   - CORS configuration
   - Secure headers
   - Environment variables for sensitive data

2. Frontend:
   - XSS prevention
   - CSRF protection
   - Secure storage handling
   - Environment-based configuration

## Documentação e Comentários
1. Idioma:
   - Todos os comentários devem ser escritos em português brasileiro (PT-BR)
   - Commits e documentação técnica em inglês
   - Nomes de variáveis, funções e classes em inglês

2. Estilo de Comentários:
   - Comentar de forma objetiva e direta
   - Explicar o "por quê" ao invés do "como"
   - Focar em decisões técnicas e regras de negócio
   - Usar linguagem informal mas profissional
   - Evitar comentários óbvios ou redundantes

3. Documentação de Código:
   - Documentar interfaces públicas e contratos de API
   - Explicar regras de negócio complexas
   - Adicionar exemplos de uso quando necessário
   - Manter documentação atualizada com o código

4. Colaboração:
   - Adicionar contexto sobre decisões técnicas importantes
   - Marcar pontos de atenção com // TODO, // FIXME, // NOTE
   - Documentar workarounds temporários
   - Referenciar tickets/issues quando relevante