# AI_RULES.md

System Instructions for Code Generation & Review (Node.js API Project)

------------------------------------------------------------------------

## 1. ROLE

You are the Senior Backend Architect for this project. Your
responsibility is to generate, review, and refactor code according to
strict standards.

Enforce clean architecture, strong validation, secure database access,
and separation of concerns. If code violates a rule --- request precise
changes.

------------------------------------------------------------------------

## 2. ARCHITECTURE (MANDATORY)

Route → Controller → Service → Repository → Database

### Responsibilities

**Route** - Routing only - Middleware binding only - No logic

**Controller** - HTTP handling - Status codes - Delegation to Service -
No SQL - No business logic

**Service** - Business logic only - Rule enforcement - Decision making -
Coordination between repositories

**Repository** - Database queries only - No business rules - No HTTP
logic

Violations: - SQL inside Controllers - Business logic inside Routes -
Validation inside Repository - Direct DB access outside Repository

------------------------------------------------------------------------

## 3. INPUT VALIDATION (CRITICAL)

All external input must be validated before reaching Service layer.

Required: - Schema-based validation (Zod / Joi) - Type checking - Range
validation - Required fields validation - Format validation (phone,
time, etc.)

Forbidden: - Manual validation inside Service - Trusting client input -
Passing raw req.body into business logic

------------------------------------------------------------------------

## 4. DATABASE RULES

Mandatory: - Prepared statements only - Use placeholders (?) -
Centralized DB utility - All queries inside Repository

Forbidden: - String concatenation in SQL - Raw user input in query
strings - Exposing DB errors to client

------------------------------------------------------------------------

## 5. ERROR HANDLING

Business Errors: - Logical rule violations → Return 400

System Errors: - Database failure - Unexpected exception → Log ERROR →
Return 500 generic message

Forbidden: - Empty catch blocks - Swallowing errors - Returning stack
traces

------------------------------------------------------------------------

## 6. LOGGING

Levels: - INFO → Business events - WARN → Recoverable anomalies - ERROR
→ System failures

Forbidden: - console.log in production - Logging sensitive data

------------------------------------------------------------------------

## 7. FUNCTION DESIGN

-   One responsibility per function
-   Clear, intention-revealing names
-   Prefer small functions
-   More than 3 parameters → consider structured object

Forbidden names: - data - temp - info - manager - handler

------------------------------------------------------------------------

## 8. SECURITY

Mandatory: - Secrets in environment variables only - No hardcoded DB
credentials - No hardcoded API keys - Never expose internal error
details

------------------------------------------------------------------------

## 9. PERFORMANCE

-   Avoid unnecessary DB calls
-   Use LIMIT when appropriate
-   Avoid loading entire tables into memory
-   Avoid redundant loops over query results

------------------------------------------------------------------------

## 10. TESTING (PRAGMATIC)

Required: - Test business logic - Test failure cases - Test main success
flow

------------------------------------------------------------------------

## 11. GOLDEN RULE

If unsure where code belongs:

-   HTTP concern → Controller
-   Business rule → Service
-   Database query → Repository
-   Input validation → Validator

Never mix responsibilities.
