---
alwaysApply: true
---
# Dubai DLD Analytics API - Enterprise Cursor Rules

## Project Overview
Natural Language Processing API for Dubai real estate analytics with:
- NLP-powered query parsing using natural language
- Context-aware SQL generation for follow-up queries
- Chart.js-optimized data formatting
- MySQL database integration with pooling
- Express.js RESTful API with security middleware

## Architecture Patterns

### Service Layer Architecture
Services in `src/services/` contain pure business logic:
- `nlpService.js` - Natural language query parsing (DubaiRealEstateParser)
- `sqlGenerator.js` - Base SQL generation
- `contextAwareSQLGenerator.js` - Context-aware SQL with session management
- `chartFormatter.js` - Chart.js data transformation
- `queryTemplates.js` - Hardcoded SQL templates for 10 specific queries
- `contextManager.js` - Session-based context management for conversational queries

Routes orchestrate services, models handle database, middleware validates/errors, utils are pure helpers.

### Design Principles
1. Separation of concerns per service
2. Context management for multi-turn conversations
3. Template-based optimized SQL queries
4. Progressive enhancement: Basic → Context-aware → Template-based
5. Joi validation for type safety
6. Graceful error boundaries

## Code Style & Naming Conventions

### File Naming
- Services: `{purpose}Service.js` or `{purpose}.js`
- Use kebab-case: `context-aware-sql-generator.js` NOT `contextAwareSQLGenerator.js`

### Naming Conventions
- Classes: PascalCase (`DubaiRealEstateParser`, `ContextManager`)
- Variables/Functions: camelCase (`parsedQuery`, `getContext()`)
- Constants: UPPER_SNAKE_CASE (`DB_HOST`, `DEFAULT_TTL`)
- Database: snake_case (`area_en`, `prop_sub_type_en`)

### Code Organization Order
```javascript
// 1. External imports
// 2. Internal imports
// 3. Class declaration
// 4. Constructor
// 5. Public methods (logical flow)
// 6. Private/helper methods
// 7. Module exports
```

## Database Patterns

### Connection Management
- Single Database singleton from `src/models/database.js`
- Connection pooling via `mysql2/promise`
- Pool: 10 connections, 60s timeout
- Always parameterize queries to prevent SQL injection

### Query Patterns
```javascript
// ✅ GOOD: Parameterized
await database.query(
  'SELECT * FROM rents WHERE area_en = ? AND start_date >= ?',
  ['business bay', '2024-01-01']
);

// ❌ BAD: String concatenation
```

### SQL Template Pattern
- Define in `queryTemplates.js`
- Return `{ sql, params }`
- Use `WHERE 1=1` base for dynamic conditions

## NLP & Query Processing Flow

1. Parse: Extract intent, areas, dates, property types
2. Context Check: Detect follow-up via ContextManager
3. Generate SQL: Use ContextAwareSQLGenerator or fallback
4. Execute: Query database
5. Format: Transform for Chart.js via ChartFormatter
6. Store Context: Save for future follow-ups

### Intent Classification
Intent keywords in `nlpService.js`:
- `trend`: Time-series analysis
- `compare`: Comparative analysis  
- `average`: Statistical aggregation
- `summary`: Overview queries
- `count`: Quantitative queries
- `filter`: Refinement queries

### Dubai-Specific Patterns
- Areas: Use DB values (`'business bay'`, not `'Business Bay'`)
- Property types: Map to `prop_sub_type_en`
- Room types: `'3 b/r'` format (space-separated)
- Dates: `YYYY-MM-DD` for SQL, use `moment` for manipulation

## API Design

### Endpoint Structure