108 lines
3.4 KiB
Plaintext
108 lines
3.4 KiB
Plaintext
---
|
|
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 |