# Development Rules

## General Principles (Clean Code)

### Constants Over Magic Numbers
- Replace hard-coded values with named constants.
- Use descriptive constant names that explain the value's purpose.
- Keep constants at the top of the file or in a dedicated constants file.

### Meaningful Names
- Variables, functions, and types should reveal their purpose.
- Names should explain *why* something exists and *how* it's used.
- Avoid abbreviations unless they're universally understood.
- **Go Specific:** Use `PascalCase` for exported identifiers and `camelCase` for unexported ones.

### Smart Comments
- Don't comment on *what* the code does - make the code self-documenting.
- Use comments to explain *why* something is done a certain way (decision documentation).
- Document APIs, complex algorithms, and non-obvious side effects.

### Single Responsibility & DRY
- Each function should do exactly one thing and be small and focused.
- Extract repeated code into reusable functions.
- Maintain single sources of truth.

### Encapsulation
- Hide implementation details.
- Expose clear interfaces.
- Move nested conditionals into well-named functions.

## Go Development Rules

### Error Handling
- **Always check errors:** `if err != nil { ... }`.
- Return errors to the caller rather than panicking (except during initialization).
- Use custom error types when beneficial for the caller.
- Wrap errors with context when propagating them (e.g., `fmt.Errorf("failed to process item: %w", err)`).

### Concurrency
- Utilize Go's built-in concurrency features (goroutines, channels) when beneficial for performance, but avoid over-engineering.
- Always manage goroutine lifecycles (use `context` for cancellation).
- Use `sync.Mutex` or `sync.RWMutex` to protect shared state.

### Dependency Management
- Use Go Modules.
- Group imports: Standard library, Third-party, Internal project imports.

## Backend & API Development

### API Structure (REST/Gin)
- Follow RESTful API design principles.
- Use appropriate HTTP status codes (200 OK, 201 Created, 400 Bad Request, 500 Internal Server Error).
- Format JSON responses consistently.
- Implement input validation for all API endpoints.

### Security & Best Practices
- **Input Validation:** Validate all incoming data.
- **SQL Injection:** Use prepared statements or ORM features that handle parameterization safely.
- **Authentication/Authorization:** Implement proper checks (middleware) before processing sensitive requests.
- **Logging:** Use structured logging (`logrus`) for errors and important events. Do not log sensitive data (passwords, tokens).
- **Rate Limiting:** Implement rate limiting to protect API resources.

### Database Interaction
- Use connection pooling to improve performance.
- Close database connections/rows when they are no longer needed (defer `rows.Close()`).
- Handle database errors gracefully.
- Consider using an ORM for complex queries and data modeling.

## Scalability & Performance
- Consider caching strategies for read-heavy operations.
- Optimize database queries (indexing, avoiding N+1 problems).
- Design for horizontal scalability (stateless services where possible).

## Version Control (Git)
- Write clear, imperative commit messages (e.g., "Add user login endpoint" not "Added user login endpoint").
- Make small, focused commits.
- Review code for cleanliness and adherence to these rules before committing.

# Go ServeMux REST API Rules (Cursor Rules)

## General Guidelines
- You are an expert AI programming assistant specializing in building APIs with Go, using the standard library's net/http package and the new ServeMux introduced in Go 1.22.
- Always use the latest stable version of Go (1.22 or newer) and be familiar with RESTful API design principles, best practices, and Go idioms.
- Follow the user's requirements carefully & to the letter.
- **Planning:** First think step-by-step - describe your plan for the API structure, endpoints, and data flow in pseudocode, written out in great detail. Confirm the plan, then write code!
- Write correct, up-to-date, bug-free, fully functional, secure, and efficient Go code for APIs.
- Leverage the power and simplicity of Go's standard library to create efficient and idiomatic APIs.

## Implementation Details
- **Error Handling:** Implement proper error handling, including custom error types when beneficial.
- **Response Formatting:** Use appropriate status codes and format JSON responses correctly.
- **Validation:** Implement input validation for API endpoints.
- **Concurrency:** Utilize Go's built-in concurrency features when beneficial for API performance.
- **Logging:** Implement proper logging using the standard library's log package or a simple custom logger.
- **Middleware:** Consider implementing middleware for cross-cutting concerns (e.g., logging, authentication).
- **Security:** Implement rate limiting and authentication/authorization when appropriate. Always prioritize security, scalability, and maintainability.
- **Completeness:** Leave NO todos, placeholders, or missing pieces in the API implementation.
- **Comments:** Be concise in explanations, but provide brief comments for complex logic or Go-specific idioms.
- **Testing:** Offer suggestions for testing the API endpoints using Go's testing package.

# Go Backend Scalability Rules

## General Expertise
- Consider scalability, reliability, maintainability, and security in all recommendations.
- Key areas: Database Management, API Development (REST, gRPC), Performance Optimization, Caching Strategies, Data Infrastructure (Kafka, Redis), and Containerization.

## gRPC & Protocol Buffers
- **Proto Files:** Define clear messages/services. Use proper types/naming. Ensure `go_package` is correct.
- **Implementation:** Generate code with `protoc`. Handle errors/validation properly.
- **Database:** Connect using `database/sql` or ORM (e.g. GORM). Use prepared statements.

# Node.js and Express.js Best Practices

## Project Structure
- Use proper directory structure.
- Implement proper module organization.
- Keep routes organized by domain.
- Implement proper error handling.

## Express Setup
- Use proper middleware setup.
- Implement proper routing.
- Configure proper security middleware (CORS, Helmet).
- Implement proper validation.

## Database & Auth
- Use proper ORM/ODM (Mongoose/Sequelize/Prisma).
- Implement proper migrations.
- Implement proper JWT handling and password hashing.
- Handle auth errors properly.

## Performance & Security
- Implement proper caching and async operations.
- Implement proper rate limiting and input validation.
- Use proper security headers.
- Handle high traffic properly.

## Testing & Deployment
- Write proper unit and integration tests.
- Use proper Docker setup and environment variables.
- Implement proper CI/CD.