// CORRECT - Use constants
import { REGIONS, CCR_DISTRICTS, getRegionForDistrict, REGION_BADGE_CLASSES } from '../constants';

REGIONS.forEach(region => { ... });  // ['CCR', 'RCR', 'OCR']
const region = getRegionForDistrict(district);
const badgeClass = REGION_BADGE_CLASSES[region];

// FORBIDDEN - Hardcoded
const regions = ['CCR', 'RCR', 'OCR'];  // Use REGIONS constant instead
if (district === 'D01') region = 'CCR';  // Use getRegionForDistrict()

# CORRECT
from constants import get_region_for_district, CCR_DISTRICTS

# FORBIDDEN
if district in ['D01', 'D02', 'D06', ...]:  # Hardcoded list

// CORRECT - Use constants
import {
  BEDROOM_ORDER,           // ['1BR', '2BR', '3BR', '4BR', '5BR+']
  BEDROOM_ORDER_NUMERIC,   // [1, 2, 3, 4, 5]
  BEDROOM_THRESHOLDS_TIER1,
  BEDROOM_THRESHOLDS_TIER2,
  BEDROOM_THRESHOLDS_TIER3,
  classifyBedroom,         // Simple fallback
  classifyBedroomThreeTier, // Full 3-tier logic
  getBedroomLabelShort,
} from '../constants';

// Classify a unit
const bedroom = classifyBedroomThreeTier(750, 'New Sale', '2024-01-15');
// Returns: 2 (Tier 1: 750 < 780)

// For display/sorting
BEDROOM_ORDER.forEach(br => { ... });
const label = getBedroomLabelShort(2);  // "2BR"

// FORBIDDEN - Hardcoded
const BEDROOM_ORDER = ['1BR', '2BR', '3BR', '4BR', '5BR+'];  // Use constant
if (area < 580) bedroom = 1;  // Use classifyBedroomThreeTier()

# CORRECT - Use services/classifier.py
from services.classifier import classify_bedroom_three_tier, classify_bedroom

bedroom = classify_bedroom_three_tier(750, 'New Sale', date(2024, 1, 15))

# FORBIDDEN
if area < 580:
    bedroom = 1  # Hardcoded threshold

// CORRECT
import { FLOOR_LEVELS, FLOOR_LEVEL_LABELS, getFloorLevelColor } from '../constants';

FLOOR_LEVELS.forEach(level => {
  const label = FLOOR_LEVEL_LABELS[level];
  const color = getFloorLevelColor(level);
});

// FORBIDDEN
const levels = ['Low', 'Mid-Low', 'Mid', 'Mid-High', 'High', 'Luxury'];  // Hardcoded

// CORRECT - Use enum helpers
import { isSaleType, SaleType, SaleTypeLabels } from '../schemas/apiContract';

if (isSaleType.newSale(row.saleType)) { ... }
const label = SaleTypeLabels[SaleType.RESALE];

// FORBIDDEN - Hardcoded strings
if (row.sale_type === 'New Sale') { ... }
const label = 'Resale';

# CORRECT
from constants import SALE_TYPE_NEW, SALE_TYPE_RESALE
from api.contracts.contract_schema import SaleType

# FORBIDDEN
if sale_type == 'New Sale':

// CORRECT
import { isTenure, TenureLabelsShort } from '../schemas/apiContract';

const shortLabel = TenureLabelsShort[row.tenure];

// FORBIDDEN
const label = row.tenure === 'Freehold' ? 'FH' : '99yr';

// CORRECT
import { getAgeBandKey, AGE_BAND_LABELS_SHORT } from '../constants';

const band = getAgeBandKey(age, isFreehold, isNewSale);
const label = AGE_BAND_LABELS_SHORT[band];

// FORBIDDEN
if (age < 5) band = 'new';  // Wrong classification

┌─────────────────────────────────────────────────────────────────┐
│  FRONTEND                                                        │
│  buildApiParams() → { district: 'D01,D02', bedroom: '2,3' }     │
│                           ↓ SINGULAR                             │
├─────────────────────────────────────────────────────────────────┤
│  API BOUNDARY (HTTP Request)                                     │
│  ?district=D01,D02&bedroom=2,3&segment=CCR                      │
│                           ↓ SINGULAR                             │
├─────────────────────────────────────────────────────────────────┤
│  ROUTE HANDLER (routes/*.py)                                     │
│  Parses & normalizes → { districts: [...], bedrooms: [...] }    │
│                           ↓ PLURAL                               │
├─────────────────────────────────────────────────────────────────┤
│  SERVICE LAYER (services/*.py)                                   │
│  filters.get('districts'), filters.get('bedrooms')              │
│                           = PLURAL                               │
└─────────────────────────────────────────────────────────────────┘

// CORRECT - API params are SINGULAR, comma-separated strings
const params = {
  district: 'D01,D02',      // Singular key, comma-separated
  bedroom: '2,3',           // Singular key, comma-separated
  segment: 'CCR',           // Singular key
  sale_type: 'Resale',      // snake_case
};

// FORBIDDEN - Never use plural or arrays in API params
const params = {
  districts: ['D01', 'D02'],  // Wrong: plural, array
  bedrooms: '2,3',            // Wrong: plural
  region: 'CCR',              // Wrong: use 'segment'
};

# Route handler normalizes singular → plural for services
@app.route('/api/data')
def get_data():
    # Parse singular API params
    district_param = request.args.get('district', '')
    bedroom_param = request.args.get('bedroom', '')

    # Normalize to plural for service layer
    filters = {
        'districts': [d.strip() for d in district_param.split(',') if d.strip()],
        'bedrooms': [int(b) for b in bedroom_param.split(',') if b.strip()],
    }

    return service.get_data(filters)

# Services expect PLURAL keys with list values
def get_data(filters: dict):
    districts = filters.get('districts', [])  # List[str]
    bedrooms = filters.get('bedrooms', [])    # List[int]
    segments = filters.get('segments', [])    # List[str]
    sale_type = filters.get('sale_type')      # str (singular - not a list)

// Adapters normalize v1/v2 responses - components use camelCase
const transformedData = transformTimeSeries(response.data);
// Now: data.medianPsf (never data.median_psf)

// Defined in constants - DO NOT hardcode
import { getBedroomColor } from '../constants'; // Add if missing

# Find hardcoded region arrays
grep -rn "'CCR'\|'RCR'\|'OCR'" frontend/src/components/ | grep -v "import\|from"

# Find hardcoded bedroom thresholds
grep -rn "< 580\|< 600\|< 780\|< 950" frontend/src/

# Find hardcoded sale type strings
grep -rn "'New Sale'\|'Resale'\|'Sub Sale'" frontend/src/ backend/

# Find plural API params (should be singular)
grep -rn "districts=\|bedrooms=\|segments=" frontend/src/

# Find hardcoded color hex
grep -rn "\"#[0-9A-Fa-f]\{6\}\"" frontend/src/components/powerbi/

# Find floor level hardcoding
grep -rn "'Low'\|'Mid'\|'High'\|'Luxury'" frontend/src/ | grep -v import

[ ] No hardcoded region strings - use REGIONS constant
[ ] No hardcoded bedroom labels - use BEDROOM_ORDER constant
[ ] No hardcoded bedroom thresholds - use classifyBedroomThreeTier()
[ ] No hardcoded floor levels ('Low', 'Mid', etc.)
[ ] No hardcoded sale types ('New Sale', 'Resale')
[ ] No hardcoded tenure strings ('Freehold', '99-year')
[ ] All filter params use singular form (district, bedroom, segment)
[ ] Colors from constants/palette, not hardcoded hex
[ ] New constants added to both backend AND frontend files

# backend/constants.py
NEW_CLASSIFICATION = 'value'
NEW_CLASSIFICATION_LABELS = { ... }

// frontend/src/constants/index.js
export const NEW_CLASSIFICATION = 'value';
export const NEW_CLASSIFICATION_LABELS = { ... };

# backend/api/contracts/contract_schema.py
class NewEnum(str, Enum):
    VALUE = 'value'

// frontend/src/schemas/apiContract.js
export const NewEnum = { VALUE: 'value' };

DATA STANDARDS CHECKLIST

BEFORE WRITING ANY DATA CODE:
[ ] Check constants/index.js for existing values
[ ] Check apiContract.js for enum helpers
[ ] Use helper functions (getRegionForDistrict, isSaleType, etc.)
[ ] Never hardcode classification strings
[ ] Response fields: use adapters for v1/v2 normalization

FILTER NAMING (Two-Layer Convention):
┌──────────────────────────────────────────────────────┐
│ API PARAMS (singular)  →  SERVICE FILTERS (plural)   │
│ district               →  districts                  │
│ bedroom                →  bedrooms                   │
│ segment                →  segments                   │
│ sale_type              →  sale_type (stays singular) │
└──────────────────────────────────────────────────────┘

Frontend: params.district = 'D01,D02'     // SINGULAR
Route:    filters['districts'] = [...]    // PLURAL
Service:  filters.get('districts', [])    // PLURAL

ADDING NEW CLASSIFICATION:
1. Add to backend/constants.py
2. Add to frontend/src/constants/index.js
3. Add to contract_schema.py if enum
4. Update this skill document

# Use canonical classifier
from api.contracts.contract_schema import PropertyAgeBucket

age_band = PropertyAgeBucket.classify(
    age=property_age,
    sale_type=sale_type,
    tenure=tenure
)

# Build CASE conditions from PropertyAgeBucket.AGE_RANGES
age_conditions = [
    (func.lower(Transaction.sale_type) == 'new sale', literal(PropertyAgeBucket.NEW_SALE)),
    (Transaction.tenure.ilike('%freehold%'), literal(PropertyAgeBucket.FREEHOLD)),
    (Transaction.lease_start_year.is_(None), literal('unknown')),
]

for bucket, (min_age, max_age) in PropertyAgeBucket.AGE_RANGES.items():
    if max_age is None:
        condition = property_age >= min_age
    else:
        condition = and_(property_age >= min_age, property_age < max_age)
    age_conditions.append((condition, literal(bucket)))

age_band_case = case(*age_conditions, else_=literal('unknown'))

[ ] No new bucket strings added outside `contract_schema.py`
[ ] SQL uses PropertyAgeBucket constants (not hardcoded strings)
[ ] Backend is the only place mapping age → age_band
[ ] All tests in TestPropertyAgeBucket pass
[ ] Frontend AGE_BAND_LABELS_* match PropertyAgeBucket.LABELS

Enums define reality.
Backend classifies.
SQL provides numbers (or uses enum constants).
Frontend displays.
No one invents categories.