diff --git a/FIREPROPERTIES-BLUEPRINT-UPDATED.md b/FIREPROPERTIES-BLUEPRINT-UPDATED.md
new file mode 100644
index 0000000..5b1f974
--- /dev/null
+++ b/FIREPROPERTIES-BLUEPRINT-UPDATED.md
@@ -0,0 +1,1660 @@
+# FIREPROPERTIES.COM — Blueprint (SEO & AI-Optimized)
+
+> Generated by The Architect on 2026-05-28
+> Archetype: SaaS / Real Estate Marketplace
+> Strategy: Semantic URLs + Structured Data for SEO & Future AI Crawling
+
+---
+
+## 1. Project Overview
+
+### Vision
+FIREPROPERTIES is a next-generation luxury real estate marketplace for South Florida (Miami, Fort Lauderdale, Palm Beach). Unlike traditional platforms cluttered with noise, Fire delivers a premium, technology-first experience built on transparent data and superior service. The platform serves three distinct audiences: luxury home buyers seeking off-market deals, homeowners ready to sell with data-driven advantage, and professional investors analyzing ROI opportunities.
+
+The brand promise: "Exclusive opportunities in luxury homes, high-growth developments, and strategic real estate investments across South Florida." Aesthetic: minimalist, premium, trustworthy (black + white).
+
+### Goals
+- Build a searchable, map-based luxury property marketplace with AI-powered valuation tools
+- Capture all three user segments (buyers, sellers, investors) with dedicated experiences
+- **Dominate local SEO by city + property type** with semantic URL structure and schema.org markup:
+ - Rank top 3 for: "Miami luxury condos", "Miami new construction", "Miami luxury homes"
+ - Rank top 3 for: "Fort Lauderdale condos", "Fort Lauderdale waterfront", "Fort Lauderdale new construction"
+ - Rank top 3 for: "Palm Beach luxury real estate", "Palm Beach new construction condos"
+ - Rank top 3 for: "investment properties Miami", "sell home Miami"
+- Drive 500+ qualified leads in first 90 days through SEO + organic growth
+- Provide superior service UX vs miamiluxuryhomes (faster search, direct chat, transparency)
+- **Build AI-crawlable architecture**: semantic URLs, structured data (JSON-LD), clear hierarchy for future AI indexing
+
+### Success Metrics
+- Organic search traffic: 10k+ monthly sessions (6 months)
+- Lead conversion rate: 8%+ (contact form submissions)
+- Average time on site: 3+ minutes
+- Property view rate: 85%+ of visitors view at least one property detail
+- Mobile traffic: 60%+
+- Top 3 ranking for 20+ city + property type combinations
+
+---
+
+## 2. Tech Stack
+
+| Layer | Technology | Why |
+|-------|-----------|-----|
+| Framework | Next.js 15 (App Router) | Server Components for SEO, fast builds, Vercel deployment native |
+| Language | TypeScript | Type safety, team onboarding, fewer runtime errors |
+| Styling | Tailwind CSS v4 | Rapid iteration, design token control (black/white theme) |
+| Components | shadcn/ui + custom | Accessible base components, highly customizable |
+| Database | PostgreSQL (Supabase) | Relational data (properties, users, favorites), real-time subscriptions if needed |
+| ORM | Prisma | Type-safe queries, schema migrations, great DX |
+| Auth | NextAuth.js v5 | Self-hosted, email + OAuth, role-based access (admin, agent, user) |
+| Search | Algolia | Fast full-text search, facets (price, location, type), typeahead |
+| Maps | Mapbox | Beautiful maps, property clustering, geolocation |
+| AI/ML | OpenAI API | Property valuations, market insights, chat support |
+| Email | Resend + React Email | Transactional emails (contact confirmations, alerts) |
+| Analytics | Vercel Analytics + Posthog | SEO data, user behavior, heatmaps |
+| Hosting | Vercel | Serverless deployment, auto-scaling, edge caching |
+| Package Manager | pnpm | Fast, disk-efficient, monorepo support |
+
+---
+
+## 3. Directory Structure
+
+```
+fireproperties/
+├── src/
+│ ├── app/ # Next.js App Router pages (SEO-optimized)
+│ │ ├── layout.tsx # Root layout + metadata (structured data)
+│ │ ├── page.tsx # / - Homepage (hero + featured properties)
+│ │ ├── comprar/
+│ │ │ ├── page.tsx # /comprar - All properties (default view)
+│ │ │ ├── [city]/
+│ │ │ │ ├── page.tsx # /comprar/miami - Miami luxury homes
+│ │ │ │ └── [type]/
+│ │ │ │ └── page.tsx # /comprar/miami/condos - Miami luxury condos
+│ │ │ └── layout.tsx # Sidebar layout for filters
+│ │ ├── properties/
+│ │ │ └── [id]/
+│ │ │ └── page.tsx # /properties/[id] - Property detail
+│ │ ├── vender/
+│ │ │ ├── page.tsx # /vender - Seller onboarding
+│ │ │ └── estimador/
+│ │ │ └── page.tsx # /vender/estimador - Home valuation
+│ │ ├── invertir/
+│ │ │ ├── page.tsx # /invertir - Investment opportunities
+│ │ │ ├── [city]/
+│ │ │ │ └── page.tsx # /invertir/miami - Miami investment deals
+│ │ │ └── layout.tsx # Dashboard layout
+│ │ ├── mercado/
+│ │ │ ├── page.tsx # /mercado - Market insights + trends
+│ │ │ └── [city]/
+│ │ │ ├── page.tsx # /mercado/miami - Miami market data
+│ │ │ └── [type]/
+│ │ │ └── page.tsx # /mercado/miami/new-construction - Miami new construction market
+│ │ ├── mi-cuenta/
+│ │ │ ├── page.tsx # /mi-cuenta - User dashboard
+│ │ │ ├── favoritos/
+│ │ │ │ └── page.tsx # /mi-cuenta/favoritos - Saved properties
+│ │ │ └── alertas/
+│ │ │ └── page.tsx # /mi-cuenta/alertas - Price drop alerts
+│ │ ├── contacto/
+│ │ │ └── page.tsx # /contacto - Contact form + chat widget
+│ │ ├── api/
+│ │ │ ├── properties/
+│ │ │ │ ├── route.ts # GET /api/properties - List + search + filters
+│ │ │ │ ├── [id]/
+│ │ │ │ │ └── route.ts # GET /api/properties/[id]
+│ │ │ │ └── valuation/
+│ │ │ │ └── route.ts # POST /api/properties/valuation (AI)
+│ │ │ ├── favorites/
+│ │ │ │ └── route.ts # POST/DELETE favorites
+│ │ │ ├── contacts/
+│ │ │ │ └── route.ts # POST contact form
+│ │ │ ├── auth/
+│ │ │ │ └── [...nextauth]/route.ts # NextAuth endpoints
+│ │ │ └── search/
+│ │ │ └── route.ts # GET /api/search (Algolia)
+│ │ └── sitemap.xml.ts # Dynamic XML sitemap (SEO)
+│ ├── components/
+│ │ ├── layout/
+│ │ │ ├── Header.tsx # Navigation + logo
+│ │ │ ├── Footer.tsx # Footer with links
+│ │ │ └── Navigation.tsx # Main nav menu
+│ │ ├── home/
+│ │ │ ├── HeroSection.tsx # Hero with headline + subhead
+│ │ │ ├── FeaturedProperties.tsx
+│ │ │ ├── ValueProposition.tsx # Why Fire Properties
+│ │ │ ├── Testimonials.tsx
+│ │ │ └── CallToAction.tsx
+│ │ ├── properties/
+│ │ │ ├── PropertyCard.tsx # Reusable property listing card
+│ │ │ ├── PropertyGrid.tsx # Grid of properties
+│ │ │ ├── PropertyDetail.tsx # Full detail view
+│ │ │ ├── PropertyComparator.tsx # Compare 2-3 properties
+│ │ │ ├── PropertyMap.tsx # Mapbox integration
+│ │ │ └── PropertyFilters.tsx # Search filters (city, type, price, etc.)
+│ │ ├── seller/
+│ │ │ ├── HomeValuation.tsx # AI-powered valuation form
+│ │ │ ├── ValuationResult.tsx
+│ │ │ ├── SellingProcess.tsx # Step-by-step explainer
+│ │ │ └── ContactAgentForm.tsx
+│ │ ├── investor/
+│ │ │ ├── InvestmentCard.tsx
+│ │ │ ├── ROICalculator.tsx
+│ │ │ ├── MarketAnalysis.tsx
+│ │ │ └── DealComparator.tsx
+│ │ ├── market/
+│ │ │ ├── PriceTrends.tsx # Chart component
+│ │ │ ├── NeighborhoodStats.tsx
+│ │ │ └── MarketInsights.tsx
+│ │ ├── ui/
+│ │ │ ├── Button.tsx # shadcn base
+│ │ │ ├── Input.tsx
+│ │ │ ├── Select.tsx
+│ │ │ ├── Modal.tsx
+│ │ │ ├── Card.tsx
+│ │ │ ├── Badge.tsx
+│ │ │ └── Skeleton.tsx # Loading states
+│ │ ├── common/
+│ │ │ ├── ContactForm.tsx # Reusable contact form
+│ │ │ ├── ChatWidget.tsx # Live chat
+│ │ │ ├── SearchBar.tsx
+│ │ │ ├── Breadcrumbs.tsx # Navigation breadcrumbs (SEO)
+│ │ │ └── Pagination.tsx
+│ │ └── auth/
+│ │ ├── LoginForm.tsx
+│ │ ├── SignupForm.tsx
+│ │ └── ProtectedRoute.tsx
+│ ├── lib/
+│ │ ├── db.ts # Prisma client
+│ │ ├── auth.ts # NextAuth config
+│ │ ├── algolia.ts # Algolia client & helpers
+│ │ ├── mapbox.ts # Mapbox config
+│ │ ├── openai.ts # OpenAI valuation service
+│ │ ├── mail.ts # Email service (Resend)
+│ │ ├── seo.ts # SEO metadata generators
+│ │ ├── schema.ts # JSON-LD structured data generators (CRITICAL for AI)
+│ │ ├── utils.ts # General utilities (formatPrice, etc.)
+│ │ └── constants.ts # App-wide constants (cities, property types, neighborhoods)
+│ ├── types/
+│ │ ├── index.ts # Exported types from Prisma + custom
+│ │ ├── property.ts # Property type definitions
+│ │ ├── user.ts # User / auth types
+│ │ └── market.ts # Market data types
+│ ├── styles/
+│ │ └── globals.css # Tailwind imports + global styles
+│ └── middleware.ts # NextAuth auth middleware
+├── prisma/
+│ ├── schema.prisma # Database schema
+│ └── migrations/ # Auto-generated migrations
+├── public/
+│ ├── images/
+│ │ ├── logo.svg # Fire Properties logo
+│ │ ├── hero-bg.jpg # Hero background
+│ │ └── og-image.png # Open Graph image
+│ └── icons/ # SVG icons
+├── tests/
+│ ├── unit/
+│ │ └── lib/utils.test.ts
+│ ├── integration/
+│ │ └── api/properties.test.ts
+│ └── e2e/
+│ └── search.spec.ts # Playwright test
+├── .env.example # Template for env vars
+├── next.config.ts # Next.js config (optimization)
+├── tsconfig.json # TypeScript strict mode
+├── tailwind.config.ts # Tailwind theme (black/white)
+├── postcss.config.ts
+├── eslint.config.ts
+├── package.json
+└── README.md
+```
+
+---
+
+## 4. Data Model
+
+### Entities
+
+**Property**
+| Field | Type | Notes |
+|-------|------|-------|
+| id | UUID | Primary key |
+| address | String | Full address |
+| city | Enum | MIAMI, FORT_LAUDERDALE, PALM_BEACH |
+| zipCode | String | For targeting |
+| lat, lng | Float | For Mapbox |
+| type | Enum | CONDO, TOWNHOUSE, SINGLE_FAMILY, PENTHOUSE, WATERFRONT, VACANT_LAND, NEW_CONSTRUCTION |
+| bedrooms | Int | 1-10 |
+| bathrooms | Float | 1.0-10.0 |
+| sqft | Int | Building size |
+| yearBuilt | Int | 1900-2030 |
+| price | BigInt | In cents (for precision) |
+| listingStatus | Enum | ACTIVE, SOLD, PENDING, COMING_SOON |
+| isNewConstruction | Boolean | Flag for new construction (filters + SEO) |
+| description | Text | Rich text or markdown |
+| imageUrls | String[] | Array of image URLs |
+| amenities | String[] | Pool, Gym, Doorman, Parking, etc. |
+| iidxId | String | IDX integration ID |
+| createdAt | DateTime | Listing creation |
+| updatedAt | DateTime | Last update |
+| createdBy | UUID (FK User) | Agent who listed |
+| isFeatured | Boolean | Homepage feature |
+
+**User**
+| Field | Type | Notes |
+|-------|------|-------|
+| id | UUID | Primary key |
+| email | String | Unique |
+| name | String | Display name |
+| role | Enum | ADMIN, AGENT, BUYER, SELLER, INVESTOR, GUEST |
+| passwordHash | String | Bcrypt |
+| phone | String | Optional |
+| preferences | JSON | Search filters, alerts, etc. |
+| savedProperties | UUID[] | Relation to Property |
+| createdAt | DateTime | |
+| updatedAt | DateTime | |
+
+**Favorite**
+| Field | Type | Notes |
+|-------|------|-------|
+| id | UUID | |
+| userId | UUID (FK) | |
+| propertyId | UUID (FK) | |
+| createdAt | DateTime | |
+| unique constraint | (userId, propertyId) | |
+
+**ContactForm**
+| Field | Type | Notes |
+|-------|------|-------|
+| id | UUID | |
+| name | String | |
+| email | String | |
+| phone | String | |
+| message | Text | |
+| segment | Enum | BUYER, SELLER, INVESTOR, GENERAL |
+| propertyId | UUID (FK, nullable) | Property they're interested in |
+| status | Enum | NEW, RESPONDED, CLOSED |
+| createdAt | DateTime | |
+
+**MarketData** (for /mercado)
+| Field | Type | Notes |
+|-------|------|-------|
+| id | UUID | |
+| city | Enum | MIAMI, FORT_LAUDERDALE, PALM_BEACH |
+| propertyType | Enum | CONDO, SINGLE_FAMILY, NEW_CONSTRUCTION, etc. |
+| month | DateTime | Month aggregation |
+| avgPrice | BigInt | Average price |
+| medianPrice | BigInt | |
+| soldCount | Int | Properties sold |
+| activeListings | Int | Current active listings |
+| daysOnMarket | Int | Average |
+| pricePerSqft | BigInt | |
+| updatedAt | DateTime | |
+
+### Relationships
+```
+User (1) -> (many) Property [createdBy agent]
+User (1) -> (many) Favorite
+User (1) -> (many) ContactForm
+Property (1) -> (many) Favorite
+Property (1) -> (many) ContactForm
+```
+
+### Database Schema (Prisma)
+```prisma
+// prisma/schema.prisma
+generator client {
+ provider = "prisma-client-js"
+}
+
+datasource db {
+ provider = "postgresql"
+ url = env("DATABASE_URL")
+}
+
+enum UserRole {
+ ADMIN
+ AGENT
+ BUYER
+ SELLER
+ INVESTOR
+ GUEST
+}
+
+enum PropertyType {
+ CONDO
+ TOWNHOUSE
+ SINGLE_FAMILY
+ PENTHOUSE
+ WATERFRONT
+ VACANT_LAND
+ NEW_CONSTRUCTION
+}
+
+enum ListingStatus {
+ ACTIVE
+ SOLD
+ PENDING
+ COMING_SOON
+ OFF_MARKET
+}
+
+enum City {
+ MIAMI
+ FORT_LAUDERDALE
+ PALM_BEACH
+}
+
+enum ContactSegment {
+ BUYER
+ SELLER
+ INVESTOR
+ GENERAL
+}
+
+model User {
+ id String @id @default(cuid())
+ email String @unique
+ name String
+ role UserRole @default(GUEST)
+ passwordHash String?
+ phone String?
+ image String?
+ bio String?
+ preferences Json?
+ emailVerified DateTime?
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ properties Property[] @relation("CreatedBy")
+ favorites Favorite[]
+ contacts ContactForm[]
+
+ @@index([email])
+}
+
+model Property {
+ id String @id @default(cuid())
+ address String
+ city City
+ zipCode String
+ lat Float
+ lng Float
+ type PropertyType
+ isNewConstruction Boolean @default(false)
+ bedrooms Int
+ bathrooms Float
+ sqft Int
+ yearBuilt Int
+ price BigInt
+ listingStatus ListingStatus @default(ACTIVE)
+ description String? @db.Text
+ imageUrls String[] @default([])
+ amenities String[] @default([])
+ idxId String? @unique
+ isFeatured Boolean @default(false)
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ createdBy User? @relation("CreatedBy", fields: [createdById], references: [id], onDelete: SetNull)
+ createdById String?
+
+ favorites Favorite[]
+ contacts ContactForm[]
+
+ @@index([city])
+ @@index([type])
+ @@index([isNewConstruction])
+ @@index([listingStatus])
+ @@index([price])
+ @@index([lat, lng])
+ @@fulltext([address, description])
+}
+
+model Favorite {
+ id String @id @default(cuid())
+ userId String
+ propertyId String
+ createdAt DateTime @default(now())
+
+ user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+ property Property @relation(fields: [propertyId], references: [id], onDelete: Cascade)
+
+ @@unique([userId, propertyId])
+ @@index([userId])
+ @@index([propertyId])
+}
+
+model ContactForm {
+ id String @id @default(cuid())
+ name String
+ email String
+ phone String?
+ message String @db.Text
+ segment ContactSegment
+ propertyId String?
+ status String @default("NEW")
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ property Property? @relation(fields: [propertyId], references: [id], onDelete: SetNull)
+
+ @@index([status])
+ @@index([createdAt])
+}
+
+model MarketData {
+ id String @id @default(cuid())
+ city City
+ propertyType PropertyType
+ month DateTime
+ avgPrice BigInt
+ medianPrice BigInt
+ soldCount Int
+ activeListings Int
+ daysOnMarket Int
+ pricePerSqft BigInt
+ updatedAt DateTime @updatedAt
+
+ @@unique([city, propertyType, month])
+ @@index([city])
+ @@index([propertyType])
+}
+```
+
+---
+
+## 5. API Design
+
+### Routes Overview
+| Method | Path | Description | Auth | Cache |
+|--------|------|-------------|------|-------|
+| GET | /api/properties | List properties (paginated, filtered by city, type, price) | Public | 5min |
+| GET | /api/properties/[id] | Single property detail | Public | 10min |
+| POST | /api/properties/valuation | AI home valuation | Public | None |
+| GET | /api/search | Full-text + Algolia search | Public | 5min |
+| POST | /api/favorites | Save property | Auth | None |
+| DELETE | /api/favorites/[id] | Remove favorite | Auth | None |
+| GET | /api/favorites | List user's favorites | Auth | 2min |
+| POST | /api/contacts | Submit contact form | Public | None |
+| GET | /api/market/[city]/[type] | Market stats by city + type | Public | 24h |
+| GET | /api/health | Health check (for monitoring) | Public | 1min |
+
+### Key Endpoints Detail
+
+**GET /api/properties**
+```
+Query params:
+ - page: number (default 1)
+ - limit: number (default 20)
+ - city: enum (MIAMI, FORT_LAUDERDALE, PALM_BEACH)
+ - type: enum (CONDO, TOWNHOUSE, SINGLE_FAMILY, PENTHOUSE, WATERFRONT, NEW_CONSTRUCTION)
+ - isNewConstruction: boolean (filter for new construction)
+ - priceMin, priceMax: number (in cents)
+ - bedrooms: number
+ - bathrooms: number
+ - sort: string (price_asc, price_desc, newest, pricePerSqft)
+ - search: string (full-text)
+
+Response:
+{
+ "success": true,
+ "data": [
+ {
+ "id": "...",
+ "address": "...",
+ "city": "MIAMI",
+ "type": "CONDO",
+ "isNewConstruction": true,
+ "price": 450000000,
+ "bedrooms": 3,
+ "bathrooms": 2.5,
+ "imageUrls": [...],
+ "listingStatus": "ACTIVE",
+ "sqft": 1800
+ }
+ ],
+ "pagination": {
+ "page": 1,
+ "limit": 20,
+ "total": 523,
+ "pages": 27
+ }
+}
+```
+
+**POST /api/properties/valuation**
+```
+Body:
+{
+ "address": "123 Main St, Miami, FL 33101",
+ "bedrooms": 3,
+ "bathrooms": 2,
+ "sqft": 1800,
+ "yearBuilt": 2020,
+ "amenities": ["pool", "gym", "parking"],
+ "condition": "excellent"
+}
+
+Response:
+{
+ "success": true,
+ "data": {
+ "estimatedValue": 450000000,
+ "lowEstimate": 420000000,
+ "highEstimate": 480000000,
+ "pricePerSqft": 250000,
+ "reasoning": "Based on 12 recent comps in Brickell with similar specs...",
+ "updatedAt": "2026-05-28T10:00:00Z"
+ }
+}
+```
+
+**POST /api/contacts**
+```
+Body:
+{
+ "name": "John Doe",
+ "email": "john@example.com",
+ "phone": "+1-305-123-4567",
+ "message": "Interested in the Brickell condo...",
+ "segment": "BUYER",
+ "propertyId": "prop-123" (optional)
+}
+
+Response:
+{
+ "success": true,
+ "message": "Thank you! We'll contact you within 24 hours."
+}
+```
+
+---
+
+## 6. Frontend Architecture
+
+### Pages / Routes (Semantic URLs for SEO + AI)
+
+**Main Routes:**
+| Route | Component | Purpose | Auth | SEO Priority |
+|-------|-----------|---------|------|--------------|
+| / | HomePage | Hero + featured + CTA | Public | HIGH (H1) |
+| /comprar | SearchPage | All properties (filter by city/type) | Public | HIGH |
+| /comprar/[city] | CityPage | Miami/Fort Lauderdale/Palm Beach homes | Public | HIGH |
+| /comprar/[city]/[type] | CityTypePage | Miami condos, Fort Lauderdale new construction, etc. | Public | **HIGHEST** (semantic URL) |
+| /properties/[id] | PropertyDetail | Full property info + comparator | Public | HIGH |
+| /vender | SellerPage | Seller value prop + CTA | Public | MEDIUM |
+| /vender/estimador | Valuation | Home price estimator | Public | MEDIUM |
+| /invertir | InvestorPage | Investment opportunities | Public | MEDIUM |
+| /invertir/[city] | CityInvestments | Miami investment deals | Public | MEDIUM |
+| /mercado | MarketInsights | Market trends + stats | Public | MEDIUM |
+| /mercado/[city] | CityMarket | Miami market data | Public | MEDIUM |
+| /mercado/[city]/[type] | MarketByType | Miami new construction market | Public | **MEDIUM-HIGH** |
+| /contacto | ContactPage | Contact form + chat | Public | LOW |
+| /mi-cuenta | Dashboard | User account center | Auth | LOW |
+| /mi-cuenta/favoritos | Favorites | Saved properties | Auth | LOW |
+| /mi-cuenta/alertas | Alerts | Price drop notifications | Auth | LOW |
+
+**Cities:** MIAMI, FORT_LAUDERDALE, PALM_BEACH
+**Types:** CONDOS, CASAS (SINGLE_FAMILY), PENTHOUSES, WATERFRONT, NEW_CONSTRUCTION, TIERRA (VACANT_LAND)
+
+### Component Hierarchy (Example: /comprar/miami/condos)
+```
+CityTypeSearchPage
+├── Breadcrumbs (Comprar > Miami > Condos) — JSON-LD BreadcrumbList
+├── Header
+│ ├── H1: "Miami Luxury Condos | Fire Properties"
+│ ├── H2: "Exclusive luxury condos in Miami with expert agents"
+│ └── Filters (price, bedrooms, new construction toggle, etc.)
+├── PropertyGrid
+│ └── PropertyCard[] (image, price, bed/bath, "NEW CONSTRUCTION" badge if applicable)
+├── PropertyMap (Mapbox with clustering)
+├── PaginationFooter
+└── JSON-LD Schema (CollectionPage + BreadcrumbList + SearchAction)
+```
+
+### State Management
+- **Server Components by default** for all pages and data fetching
+- **Client Components only** for: search filters, map zoom, form submission, favorites toggle
+- **React Query** (useQuery) for data caching and refetching
+- **Next.js Image Optimization** for property photos
+- **Session stored in HTTP-only cookies** (NextAuth)
+- **Real-time favorites** using optimistic UI updates
+
+---
+
+## 7. Design System
+
+### Colors (Black & White Premium)
+| Role | Hex | Usage |
+|------|-----|-------|
+| Primary | #000000 | Headlines, buttons, accents, logo |
+| Secondary | #FFFFFF | Background, cards, contrast |
+| Muted | #666666 | Secondary text, borders |
+| Light | #F5F5F5 | Page background, subtle surfaces |
+| Accent | #FF6B35 | Fire orange (logo/highlights only) |
+| Success | #10B981 | Price increase, status positive |
+| Warning | #F59E0B | Market caution, alerts |
+| Error | #EF4444 | Errors, destructive actions |
+| NewConstruction | #FF6B35 | Highlight new construction badges |
+
+### Typography
+| Role | Font | Size | Weight |
+|------|------|------|--------|
+| H1 (Hero) | Inter | 48px | 700 (Bold) |
+| H2 (Sections) | Inter | 32px | 700 |
+| H3 (Subsections) | Inter | 24px | 600 |
+| Body | Inter | 16px | 400 |
+| Small | Inter | 14px | 400 |
+| Code | Monaco | 12px | 400 |
+
+### Spacing & Layout
+- **Spacing scale:** 4px base — 4, 8, 12, 16, 24, 32, 48, 64, 96px
+- **Border radius:** 8px (buttons, cards), 0px (minimalist approach)
+- **Max content width:** 1280px
+- **Breakpoints:** sm=640px, md=768px, lg=1024px, xl=1280px, 2xl=1536px
+- **Shadows:** Minimal (0 1px 3px rgba(0,0,0,0.1) on cards only)
+
+### Component Style
+- **Aesthetic:** Clean, minimal, premium (black & white)
+- **Spacing:** Generous, not cramped
+- **Rounded corners:** Minimal (8px max)
+- **Animations:** Subtle fade-ins, no flashy transitions
+- **Icons:** Feather Icons (simple, 24px)
+- **Badges:** Use for "NEW CONSTRUCTION", "FEATURED", etc.
+
+---
+
+## 8. Authentication & Authorization
+
+### Auth Flow
+1. User lands on homepage (public)
+2. Clicks "Guardar Favoritos" or "Mi Cuenta" → redirects to login
+3. Login form: email + password (or OAuth with Google)
+4. Email verification (if new signup)
+5. Onboarding: select role (Buyer, Seller, Investor)
+6. Redirect to dashboard or back to page where they clicked
+
+### Protected Routes
+```
+Public:
+ / /comprar /comprar/[city] /comprar/[city]/[type]
+ /properties/[id] /vender /vender/estimador
+ /invertir /invertir/[city] /mercado /mercado/[city] /mercado/[city]/[type]
+ /contacto
+
+Protected (Auth required):
+ /mi-cuenta /mi-cuenta/favoritos /mi-cuenta/alertas
+ /api/favorites (POST, DELETE, GET)
+
+Admin only:
+ /admin/properties /admin/contacts /admin/market-data
+```
+
+### Roles & Permissions
+| Role | Can Do | View |
+|------|--------|------|
+| GUEST | Browse, search, contact | Public pages only |
+| BUYER | Save favorites, set alerts, contact agents | Comprar + Mercado |
+| SELLER | List property, edit listing, view inquiries | Vender + own listings |
+| INVESTOR | Analyze deals, ROI calc, contact | Invertir + Mercado |
+| AGENT | Manage properties, respond to contacts, analytics | Admin dashboard |
+| ADMIN | Full access | Everything |
+
+### Session Management
+- **NextAuth.js v5** with JWT strategy
+- **Tokens stored in HTTP-only secure cookies** (not localStorage)
+- **Token refresh:** 30 days for remember-me, 7 days default
+- **Logout:** Clears session, revokes token server-side
+
+---
+
+## 9. Build Order
+
+**Step 1: Project Scaffolding & Setup**
+- Create Next.js 15 project with TypeScript
+- Install dependencies: Tailwind, shadcn/ui, Prisma, NextAuth, Algolia, Mapbox
+- Setup environment variables (.env.local)
+- Create Tailwind config with black/white theme
+- Setup Git + create initial commit
+- **Deliverable:** Project runs locally with `pnpm dev`
+
+```bash
+npx create-next-app@latest fireproperties --typescript --tailwind --app
+cd fireproperties
+pnpm add -D @types/node typescript
+pnpm add @prisma/client next-auth@5 algolia react-map-gl mapbox-gl openai resend zod
+npx shadcn-ui@latest init
+```
+
+**Step 2: Database Schema & Prisma Setup**
+- Create Prisma schema with Property.type enum including NEW_CONSTRUCTION
+- Add Property.isNewConstruction boolean flag
+- Add MarketData.propertyType enum field (for market data by type)
+- Setup PostgreSQL database (Supabase free tier or local)
+- Create initial migration
+- Seed database with 50 sample properties across Miami, Ft. Lauderdale, Palm Beach
+- Seed market data for all city + type combinations
+- **Deliverable:** `pnpm prisma db:push` succeeds, schema is in place
+
+**Step 3: Authentication System (NextAuth.js)**
+- Setup NextAuth middleware (protects /mi-cuenta routes)
+- Create login/signup pages (/auth/signin, /auth/signup)
+- Implement role-based access control
+- Setup email provider (Resend) for verification emails
+- Create user dashboard shell (/mi-cuenta)
+- **Deliverable:** Users can sign up, verify email, login, logout
+
+**Step 4: Root Layout & Navigation**
+- Create root layout.tsx with metadata (title, description, canonical)
+- Build Header component (logo, nav menu, user menu)
+- Build Footer component (links, CTA, social)
+- Create Mobile-responsive navigation menu
+- Add structured data (JSON-LD Organization schema)
+- Add Breadcrumbs component (for all filtered pages)
+- **Deliverable:** Navigation works on mobile + desktop, SEO tags present
+
+**Step 4.1: Open Graph & Twitter Card Tags (NEW — AI CRAWLING)**
+- Add dynamic og:title, og:description, og:image to all pages
+- Add og:type (website, article, etc.) per page
+- Add Twitter Card meta tags (twitter:card, twitter:title, twitter:description, twitter:image)
+- Create image generation strategy (og:image for city+type pages should include city name + property type)
+- Example for `/comprar/miami/condos`:
+ ```
+ og:title = "Miami Luxury Condos | FireProperties"
+ og:description = "Explore 47 luxury Miami condos. Average $1.2M. New construction available. Find your dream property."
+ og:image = "https://fireproperties.com/og/miami-condos.png" (dynamic, shows city name)
+ ```
+- Test with Facebook Debugger + Twitter Card Validator
+- **Deliverable:** All public pages have og: + twitter: tags, images render in social shares
+
+**Step 5: Homepage (/)**
+- Create Hero section with:
+ - H1: "Miami Luxury Real Estate & Future Investment Properties"
+ - H2 subheader
+ - Quick search bar (city, type, price range)
+ - 3 CTA buttons (Comprar, Vender, Invertir)
+- Add FeaturedProperties component (fetch 6 featured from DB, highlight new construction)
+- Add ValueProposition section (3 columns)
+- Add TestimonialSection
+- Add FAQ with JSON-LD schema
+- Add CTA footer section
+- Optimize images (Next.js Image component)
+- Add meta description: "Discover luxury real estate in Miami, Fort Lauderdale, and Palm Beach. Find condos, new construction, and investment properties. Exclusive off-market deals."
+- **Deliverable:** / page is complete, SEO tags in place (H1, meta description, og:image)
+
+**Step 6: Dynamic City + Type Pages (/comprar/[city]/[type])**
+- Create **dynamic route structure**: /comprar/[city] and /comprar/[city]/[type]
+- Generate page metadata dynamically:
+ - `/comprar/miami` → "Miami Luxury Homes"
+ - `/comprar/miami/condos` → "Miami Luxury Condos"
+ - `/comprar/fort-lauderdale/new-construction` → "New Construction Fort Lauderdale"
+- Each page has unique H1 with city + type keywords
+- Add JSON-LD BreadcrumbList for each page
+- Add JSON-LD CollectionPage + SearchAction schema
+- Use getStaticParams() to pre-render all city + type combinations
+- **Deliverable:** 15+ semantic URL pages generated automatically (3 cities × 5 types)
+
+**Step 6.5: AI Crawler Optimization & API Integration (NEW)**
+- Create `/api/ai/properties` endpoint that returns **pure JSON structured data** (no HTML parsing needed)
+- Response format for AI crawlers (Claude, ChatGPT, Perplexity):
+ ```json
+ {
+ "properties": [
+ {
+ "id": "prop-123",
+ "title": "Luxury Miami Condo",
+ "description": "Exclusive 3BR condo in Brickell",
+ "price": 1200000,
+ "location": { "city": "Miami", "type": "Condo" },
+ "bedrooms": 3,
+ "bathrooms": 2,
+ "sqft": 2100,
+ "images": ["url1", "url2"],
+ "url": "https://fireproperties.com/properties/prop-123"
+ }
+ ],
+ "pagination": { "total": 47, "page": 1, "pageSize": 10 },
+ "metadata": {
+ "city": "Miami",
+ "propertyType": "Condos",
+ "averagePrice": 1200000,
+ "priceRange": { "min": 800000, "max": 3500000 }
+ }
+ }
+ ```
+- Update `robots.txt` to allow AI crawlers with explicit allow lists:
+ ```
+ User-agent: GPTBot
+ Allow: /api/ai/properties
+ Allow: /comprar
+ Allow: /mercado
+ Allow: /properties
+
+ User-agent: CCBot
+ Allow: /api/ai/properties
+ Allow: /comprar
+ Allow: /mercado
+ Allow: /properties
+
+ User-agent: anthropic-ai
+ Allow: /api/ai/properties
+ Allow: /comprar
+ Allow: /mercado
+ Allow: /properties
+ ```
+- Add `X-Robots-Tag: noodp` and `X-Robots-Tag: noydir` headers (disable directory/ODP snippets)
+- Create `/sitemap-ai.xml` for AI crawlers with all city+type URLs
+- Document API in OpenAPI/Swagger format at `/api-docs`
+- **Deliverable:** AI crawlers can access structured property data directly via /api/ai/properties, robots.txt configured correctly
+
+**Step 7: Search & Map Infrastructure**
+- Setup Algolia index for properties (synced on creation/update)
+- Create PropertyFilters component (city, type, price, bedrooms, bathrooms, sort, isNewConstruction)
+- Build PropertyCard component (image, address, price, bed/bath, NEW CONSTRUCTION badge)
+- Create PropertyGrid component
+- Integrate Mapbox for property map view (clustering, pins, popup)
+- Create SearchPage layout with sidebar filters + map/grid toggle
+- **Deliverable:** /comprar page loads, search filters work, map renders, new construction highlighted
+
+**Step 8: Property Detail Pages (/properties/[id])**
+- Create Property detail page (/properties/[id])
+- Show full property info (images carousel, specs, description, amenities)
+- Highlight if NEW CONSTRUCTION with badge
+- Build PropertyComparator (side-by-side comparison with 1-2 other properties)
+- Add "Save to Favorites" button (with login redirect if needed)
+- Add "Contact Agent" form
+- Add similar properties section
+- Create JSON-LD schema for Property (name, price, address, images, type, etc.)
+- **Deliverable:** Property pages are SEO-optimized, comparator works, structured data validates
+
+**Step 9: Seller Segment (/vender)**
+- Create /vender homepage (value prop for sellers)
+- Build HomeValuation estimator form (/vender/estimador)
+- Integrate OpenAI API for property valuation
+- Show valuation result (estimated value, low/high range, price/sqft)
+- Add "List Your Property" CTA form
+- Create /api/properties/valuation endpoint
+- **Deliverable:** Sellers can get instant valuations, /vender copy is compelling
+
+**Step 10: Investor Segment (/invertir)**
+- Create /invertir homepage (investment opportunities)
+- Build deal listing with ROI calculator
+- Create /invertir/[city] for Miami, Fort Lauderdale, Palm Beach investment deals
+- Add MarketAnalysis component (price trends, cap rates)
+- Create /invertir/[id] deal detail page (investment metrics, cash flow, ROI)
+- Add comparison tool for multiple deals
+- **Deliverable:** Investors see compelling deals, ROI calculations work, city-specific pages live
+
+**Step 11: Market Insights (/mercado) — with city + type breakdown**
+- Create /mercado homepage (market trends)
+- Build /mercado/[city] pages (Miami market data, Fort Lauderdale data, etc.)
+- Build /mercado/[city]/[type] pages (Miami new construction market, condos market, etc.)
+- Show market stats by city + type: average price, median price, days on market, sold count, price per sqft
+- Add price trend charts (Chart.js or Recharts)
+- Create MarketData API endpoints (/api/market/[city]/[type])
+- Seed initial market data for all city + type combinations
+- **Deliverable:** Market data pages are data-driven, ranked for "Miami new construction market" etc.
+
+**Step 12: User Account & Favorites System**
+- Create /mi-cuenta dashboard
+- Build favorites page (/mi-cuenta/favoritos) — display all saved properties
+- Create alerts feature (/mi-cuenta/alertas) — price drop notifications
+- Implement POST/DELETE /api/favorites endpoints
+- Add "View Saved Properties" link in header (only when logged in)
+- **Deliverable:** Authenticated users can save & manage favorites
+
+**Step 13: Contact Forms & Lead Management**
+- Create /contacto page with contact form
+- Build ContactForm component (name, email, phone, message, segment)
+- Create POST /api/contacts endpoint
+- Setup Resend for email notifications (admin gets notified of new leads)
+- Add simple admin dashboard to view contacts (/admin/contacts, auth required)
+- **Deliverable:** Leads are captured, admins get email notifications
+
+**Step 14: SEO Optimization & Structured Data (CRITICAL FOR AI)**
+- Create sitemap.xml.ts (dynamic XML sitemap with all city + type pages)
+- Add robots.txt with AI crawler allow lists (Step 6.5)
+- Add meta descriptions to all pages (title, description, keywords)
+ - Homepage: "Discover luxury real estate in Miami, Fort Lauderdale, and Palm Beach. Find condos, new construction, and investment properties. Exclusive off-market deals."
+ - City pages: "Miami Luxury Homes | Fire Properties — Discover {totalCount} homes in Miami starting at ${minPrice}. Exclusive properties, expert agents."
+ - City + Type: "Miami Luxury Condos | Fire Properties — {totalCount} luxury condos in Miami. Average price ${avgPrice}. New construction available."
+- Create comprehensive JSON-LD schemas:
+
+ **1. Organization Schema (Homepage)** — complete identity:
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "Organization",
+ "name": "Fire Properties",
+ "url": "https://fireproperties.com",
+ "logo": "https://fireproperties.com/logo.png",
+ "description": "Luxury real estate marketplace for South Florida (Miami, Fort Lauderdale, Palm Beach)",
+ "telephone": "+1-XXX-XXX-XXXX",
+ "email": "info@fireproperties.com",
+ "address": {
+ "@type": "PostalAddress",
+ "streetAddress": "123 Main Street",
+ "addressLocality": "Miami",
+ "addressRegion": "FL",
+ "postalCode": "33101",
+ "addressCountry": "US"
+ },
+ "sameAs": [
+ "https://www.facebook.com/fireproperties",
+ "https://www.instagram.com/fireproperties",
+ "https://www.linkedin.com/company/fireproperties"
+ ],
+ "knowsAbout": ["Real Estate", "Luxury Homes", "Condominiums", "New Construction", "Investment Properties"],
+ "areaServed": [
+ {
+ "@type": "City",
+ "name": "Miami",
+ "addressRegion": "FL",
+ "addressCountry": "US"
+ },
+ {
+ "@type": "City",
+ "name": "Fort Lauderdale",
+ "addressRegion": "FL",
+ "addressCountry": "US"
+ },
+ {
+ "@type": "City",
+ "name": "Palm Beach",
+ "addressRegion": "FL",
+ "addressCountry": "US"
+ }
+ ]
+ }
+ ```
+
+ **2. LocalBusiness Schema (Per City)** — build on city pages (/comprar/[city]):
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "LocalBusiness",
+ "name": "Fire Properties - Miami",
+ "image": "https://fireproperties.com/og/miami.png",
+ "description": "Luxury real estate marketplace in Miami",
+ "url": "https://fireproperties.com/comprar/miami",
+ "telephone": "+1-XXX-XXX-XXXX",
+ "email": "miami@fireproperties.com",
+ "address": {
+ "@type": "PostalAddress",
+ "streetAddress": "123 Miami Office",
+ "addressLocality": "Miami",
+ "addressRegion": "FL",
+ "postalCode": "33101",
+ "addressCountry": "US"
+ },
+ "areaServed": "Miami, FL",
+ "serviceType": ["Real Estate Sales", "Home Valuation", "Investment Analysis"],
+ "priceRange": "$$$$",
+ "openingHoursSpecification": {
+ "@type": "OpeningHoursSpecification",
+ "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+ "opens": "09:00",
+ "closes": "18:00"
+ }
+ }
+ ```
+
+ **3. AggregateOffer Schema** — on city + type pages (/comprar/[city]/[type]):
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "AggregateOffer",
+ "priceCurrency": "USD",
+ "lowPrice": "800000",
+ "highPrice": "3500000",
+ "offerCount": "47",
+ "url": "https://fireproperties.com/comprar/miami/condos",
+ "availability": "https://schema.org/InStock"
+ }
+ ```
+
+ **4. Property Schema** — on individual property pages (/properties/[id]):
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "Property",
+ "name": "Luxury Miami Condo - 3BR/2BA",
+ "image": ["url1", "url2", "url3"],
+ "description": "Exclusive 3-bedroom luxury condo in prestigious Brickell area",
+ "address": {
+ "@type": "PostalAddress",
+ "streetAddress": "123 Brickell Ave",
+ "addressLocality": "Miami",
+ "addressRegion": "FL",
+ "postalCode": "33131",
+ "addressCountry": "US"
+ },
+ "geo": {
+ "@type": "GeoCoordinates",
+ "latitude": "25.7617",
+ "longitude": "-80.1918"
+ },
+ "offers": {
+ "@type": "Offer",
+ "price": "1200000",
+ "priceCurrency": "USD",
+ "availability": "https://schema.org/InStock",
+ "url": "https://fireproperties.com/properties/prop-123"
+ },
+ "numberOfRooms": "3",
+ "numberOfBathroomsTotal": "2",
+ "floorSize": {
+ "@type": "QuantitativeValue",
+ "unitCode": "FTK",
+ "value": "2100"
+ },
+ "propertyType": "Condo",
+ "url": "https://fireproperties.com/properties/prop-123"
+ }
+ ```
+
+ **5. BreadcrumbList** — on all filtered pages (CRITICAL FOR AI):
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "BreadcrumbList",
+ "itemListElement": [
+ {
+ "@type": "ListItem",
+ "position": 1,
+ "name": "Home",
+ "item": "https://fireproperties.com"
+ },
+ {
+ "@type": "ListItem",
+ "position": 2,
+ "name": "Buy",
+ "item": "https://fireproperties.com/comprar"
+ },
+ {
+ "@type": "ListItem",
+ "position": 3,
+ "name": "Miami",
+ "item": "https://fireproperties.com/comprar/miami"
+ },
+ {
+ "@type": "ListItem",
+ "position": 4,
+ "name": "Condos",
+ "item": "https://fireproperties.com/comprar/miami/condos"
+ }
+ ]
+ }
+ ```
+
+ **6. CollectionPage + SearchAction** — on city + type pages:
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "CollectionPage",
+ "name": "Miami Luxury Condos",
+ "description": "Browse {totalCount} luxury condos in Miami",
+ "url": "https://fireproperties.com/comprar/miami/condos",
+ "potentialAction": {
+ "@type": "SearchAction",
+ "target": {
+ "@type": "EntryPoint",
+ "urlTemplate": "https://fireproperties.com/api/search?city=miami&type=condos&q={search_term_string}"
+ },
+ "query-input": "required name=search_term_string"
+ }
+ }
+ ```
+
+ **7. Author/Expertise Schema** — on market insights pages (/mercado/[city]/[type]):
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "Article",
+ "headline": "Miami New Construction Market 2026",
+ "author": {
+ "@type": "Organization",
+ "name": "Fire Properties",
+ "expertise": ["Real Estate Analysis", "Miami Market Data", "New Construction Trends"],
+ "knownFor": "Luxury real estate expertise in South Florida",
+ "url": "https://fireproperties.com"
+ },
+ "datePublished": "2026-05-29",
+ "dateModified": "2026-05-29"
+ }
+ ```
+
+ **8. FAQ Schema** — on homepage and market pages (for featured snippets):
+ ```json
+ {
+ "@context": "https://schema.org",
+ "@type": "FAQPage",
+ "mainEntity": [
+ {
+ "@type": "Question",
+ "name": "How much do luxury condos cost in Miami?",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "Average prices range from $800K to $3.5M depending on location and amenities. Check our Miami Condos page for current listings."
+ }
+ },
+ {
+ "@type": "Question",
+ "name": "What new construction is available in Miami?",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "We feature 15+ new construction projects. Visit /comprar/miami/new-construction to browse available units."
+ }
+ }
+ ]
+ }
+ ```
+
+- Setup Open Graph tags (og:image, og:title, og:description) — completed in Step 4.1
+- Setup Twitter Card tags — completed in Step 4.1
+- Test with **Google Rich Results Test**, **Google Schema Markup Validator**, **JSON-LD Validator**
+- Verify breadcrumbs appear in Google Search Console
+- **Deliverable:** Site passes all Rich Results tests, breadcrumbs in SERP, AggregateOffer rich snippets appear, 100+ URLs in sitemap
+
+**Step 15: Testing & Quality Assurance**
+- Write unit tests for utility functions (formatPrice, generateMetadata, generateSchema)
+- Write integration tests for API endpoints (/api/properties, /api/contacts, /api/market/[city]/[type])
+- Write E2E tests for critical user flows:
+ - Search by city → view detail → favorite
+ - Contact form submission
+ - New construction filter
+- Test mobile responsiveness on actual devices
+- Test form validation and error handling
+- Test auth flows (login, logout, protected routes)
+- **Deliverable:** All tests pass, no console errors, SEO validation passes
+
+**Step 16: Performance & Deployment**
+- Optimize images (WebP, lazy loading)
+- Setup caching headers (5min for /api/properties, 24h for /mercado)
+- Enable gzip compression
+- Setup Vercel deployment (env vars, build command, preview deploys)
+- Configure custom domain (fireproperties.com)
+- Setup analytics (Vercel Analytics + PostHog) — track city + type page performance
+- Setup monitoring (Sentry for error tracking)
+- **Deliverable:** Site deploys to production, metrics dashboard visible, city + type pages ranking
+
+---
+
+## 9.5. Internal Linking Strategy (SEO + AI Crawlability)
+
+### Hierarchy & Link Equity Distribution
+
+```
+Homepage (/)
+├─ /comprar (hub page, distributes equity to city pages)
+│ ├─ /comprar/miami (distributes equity to type pages)
+│ │ ├─ /comprar/miami/condos (final destination)
+│ │ ├─ /comprar/miami/homes
+│ │ ├─ /comprar/miami/new-construction
+│ │ └─ /comprar/miami/waterfront
+│ ├─ /comprar/fort-lauderdale
+│ │ ├─ /comprar/fort-lauderdale/condos
+│ │ ├─ /comprar/fort-lauderdale/homes
+│ │ └─ /comprar/fort-lauderdale/new-construction
+│ └─ /comprar/palm-beach
+│ ├─ /comprar/palm-beach/new-construction-condos
+│ └─ /comprar/palm-beach/waterfront
+├─ /mercado (market data hub)
+│ ├─ /mercado/miami
+│ │ ├─ /mercado/miami/condos
+│ │ ├─ /mercado/miami/new-construction
+│ │ └─ /mercado/miami/homes
+│ └─ /mercado/fort-lauderdale
+│ └─ /mercado/fort-lauderdale/new-construction
+├─ /invertir (investment hub)
+│ ├─ /invertir/miami
+│ ├─ /invertir/fort-lauderdale
+│ └─ /invertir/palm-beach
+├─ /vender (seller hub)
+└─ /properties/[id] (individual property detail)
+```
+
+### Linking Patterns
+
+1. **Homepage links to hub pages** (`/comprar`, `/mercado`, `/invertir`, `/vender`):
+ - Anchor text: "Browse Luxury Homes in Miami", "Explore Investment Properties", "Get Home Valuation"
+ - Links are prominent (hero section, main navigation, footer)
+
+2. **Hub pages (/comprar) link to city pages**:
+ - `Miami Luxury Homes`
+ - `Fort Lauderdale Properties`
+ - Include all 3 cities
+
+3. **City pages link to type pages**:
+ - On `/comprar/miami`, include internal links:
+ - `Miami Condos`
+ - `Miami Homes`
+ - `Miami New Construction`
+
+4. **Type pages link to market data**:
+ - On `/comprar/miami/condos`, include: `Miami Condo Market Data`
+ - Provides context on pricing trends
+
+5. **Property detail pages link to similar properties**:
+ - Show 3-5 related properties at bottom: `Similar 3BR Condo in Brickell`
+ - Filter by: same city, same type, similar price range
+ - Helps AI crawlers discover property clusters
+
+6. **Market pages link back to buy pages**:
+ - On `/mercado/miami/new-construction`, include CTA: `Browse New Construction`
+ - Closes the loop for users/crawlers
+
+7. **Breadcrumbs as internal links** (HTML + JSON-LD):
+ - Every page has breadcrumbs: `Home > Buy > Miami > Condos`
+ - Each breadcrumb is a clickable link with anchor text matching the hierarchy
+
+8. **Search results link to properties**:
+ - `/comprar` and `/comprar/[city]/[type]` show property cards
+ - Each card links to `/properties/[id]` with anchor: `"View Details"` or property address
+
+### Link Equity Flow
+
+```
+Homepage (high authority)
+ ↓
+/comprar (distributes authority to 3 city pages)
+ ↓
+/comprar/[city] (distributes authority to 5 type pages)
+ ↓
+/comprar/[city]/[type] (property collection pages)
+ ↓
+/properties/[id] (individual property detail)
+```
+
+Each level amplifies focus on the next level. City pages rank for "Miami luxury homes", type pages rank for "Miami condos", individual properties serve long-tail searches.
+
+### AI Crawler Guidance
+
+- Breadcrumbs explicitly show hierarchy: AI crawlers follow the path Home → Buy → Miami → Condos
+- Similar properties links help crawlers discover property clusters by type
+- Market data links (type page → market page) show AI that price/trend data exists
+- Internal link anchor text is descriptive: `"Miami Luxury Condos"` not `"click here"`
+- No orphan pages: all pages reachable from homepage via semantic URL structure
+
+### Implementation in Code
+
+```tsx
+// Example: Breadcrumbs component
+
+
+// Example: Internal link with semantic anchor text
+
+ Miami Luxury Condos
+
+
+// Example: Property card internal link
+
+ {property.address}
+ ${property.price.toLocaleString()}
+ View Details →
+
+```
+
+---
+
+## 10. Environment Setup
+
+### Prerequisites
+- Node.js 18.17+ (use `nvm` to manage versions)
+- pnpm 8+ (install globally: `npm install -g pnpm`)
+- PostgreSQL 14+ (or Supabase account for cloud DB)
+- Mapbox account (free tier available)
+- Algolia account (free tier available)
+- OpenAI API key (for valuations)
+- Resend account (free tier for transactional emails)
+- Vercel account (for deployment)
+
+### Environment Variables
+| Variable | Description | Where to Get | Example |
+|----------|-------------|--------------|---------|
+| DATABASE_URL | PostgreSQL connection string | Supabase or local | postgresql://user:pass@localhost:5432/fireproperties |
+| NEXTAUTH_SECRET | Secret key for NextAuth tokens | Generate: `openssl rand -base64 32` | your-random-secret-here |
+| NEXTAUTH_URL | Site URL (dev + prod) | Your domain or localhost | http://localhost:3000 or https://fireproperties.com |
+| NEXT_PUBLIC_MAPBOX_TOKEN | Mapbox public token | Mapbox account settings | pk.eyJ1... |
+| NEXT_PUBLIC_ALGOLIA_APP_ID | Algolia app ID | Algolia dashboard | ALGOLIA_APP_ID_HERE |
+| NEXT_PUBLIC_ALGOLIA_SEARCH_KEY | Algolia search key | Algolia dashboard | ALGOLIA_SEARCH_KEY_HERE |
+| ALGOLIA_ADMIN_KEY | Algolia admin key (server-side only) | Algolia dashboard | ALGOLIA_ADMIN_KEY_HERE |
+| OPENAI_API_KEY | OpenAI API key for valuations | OpenAI account | sk-proj-... |
+| RESEND_API_KEY | Resend API key for emails | Resend dashboard | re_... |
+
+### Initial Setup Commands
+```bash
+# 1. Clone/create project
+git clone fireproperties
+cd fireproperties
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Setup environment
+cp .env.example .env.local
+# Edit .env.local with your actual keys
+
+# 4. Setup database
+pnpm prisma db:push
+
+# 5. Seed initial data (optional)
+pnpm prisma db:seed
+
+# 6. Start development server
+pnpm dev
+
+# 7. Open browser
+# Visit http://localhost:3000
+```
+
+---
+
+## 11. Dependencies
+
+### Core
+| Package | Purpose | Version |
+|---------|---------|---------|
+| next | React framework + SSR | ^15.0 |
+| react | UI library | ^19.0 |
+| typescript | Type safety | ^5.0 |
+| @prisma/client | Database ORM | ^5.x |
+| next-auth | Authentication | ^5.x |
+| tailwindcss | Styling framework | ^4.x |
+| algolia | Search engine | ^4.x |
+| react-map-gl | Mapbox wrapper | ^7.x |
+| mapbox-gl | Maps library | ^3.x |
+| openai | AI API client | ^4.x |
+| resend | Email service | ^3.x |
+| zod | Schema validation | ^3.x |
+| react-hook-form | Form handling | ^7.x |
+
+### Dev
+| Package | Purpose | Version |
+|---------|---------|---------|
+| @types/node | Node types | ^20.x |
+| @types/react | React types | ^18.x |
+| typescript | TypeScript compiler | ^5.x |
+| eslint | Code linter | ^8.x |
+| prettier | Code formatter | ^3.x |
+| vitest | Unit testing | ^1.x |
+| @testing-library/react | Component testing | ^14.x |
+| playwright | E2E testing | ^1.x |
+| shadcn-ui | Component library | ^0.x |
+
+---
+
+## 12. Deployment Strategy
+
+### Hosting
+**Vercel** (recommended for Next.js)
+- Auto-deploys on git push
+- Edge functions available (for API routes)
+- Built-in analytics and monitoring
+- Free tier supports unlimited deployments
+- Auto-scales with traffic
+- **ISR (Incremental Static Regeneration)** for city + type pages
+
+### CI/CD
+- **GitHub Actions** for automated tests on PR
+ - Run linter (eslint)
+ - Run unit tests (vitest)
+ - Run E2E tests (Playwright, only on main/production)
+- **Vercel Preview Deploys** for every PR
+ - Share live preview URL with team
+ - Check performance metrics before merging
+- **Production Deployment** on merge to main
+ - Automatic database migrations
+ - Zero-downtime deployments
+ - Regenerate semantic URL pages via ISR
+
+### Domain & DNS
+- Custom domain: fireproperties.com
+- DNS: Route53 (AWS) or Cloudflare
+- SSL certificate: Auto-provisioned by Vercel
+- Email: admin@fireproperties.com (Resend)
+
+### Environments
+| Env | Database | Vercel URL | Logging | Analytics |
+|-----|----------|-----------|---------|-----------|
+| Local | PostgreSQL localhost | - | Console | Off |
+| Development | Supabase staging | dev-fp.vercel.app | CloudWatch | PostHog dev |
+| Production | Supabase production | fireproperties.com | Sentry | PostHog prod |
+
+---
+
+## 13. Testing Strategy
+
+### Unit Tests (Vitest)
+Test utility functions, validation, helpers:
+- `lib/utils.test.ts` — formatPrice, parsePrice, calculateROI
+- `lib/seo.test.ts` — generateMetadata, generateSchema, generateBreadcrumbs (CRITICAL)
+- Location: `tests/unit/`
+
+### Integration Tests (Vitest + MSW)
+Test API endpoints with mocked database:
+- `tests/integration/api/properties.test.ts` — GET /api/properties with city + type filters
+- `tests/integration/api/valuation.test.ts` — POST /api/properties/valuation
+- `tests/integration/api/contacts.test.ts` — POST /api/contacts
+- `tests/integration/api/market.test.ts` — GET /api/market/[city]/[type]
+- Location: `tests/integration/`
+
+### E2E Tests (Playwright)
+Test critical user flows:
+- `tests/e2e/search-by-city-type.spec.ts` — Search /comprar/miami/condos, view detail, save favorite
+- `tests/e2e/valuation.spec.ts` — User enters home details, gets valuation estimate
+- `tests/e2e/contact.spec.ts` — User submits contact form, receives confirmation email
+- `tests/e2e/market-insights.spec.ts` — Navigate to /mercado/miami/new-construction, view stats
+- Location: `tests/e2e/`
+- Run before deploying to production
+
+**Testing Commands:**
+```bash
+pnpm test:unit # Vitest unit tests
+pnpm test:integration # Vitest integration tests
+pnpm test:e2e # Playwright E2E tests
+pnpm test:all # All tests
+```
+
+---
+
+## 14. Skills to Use During Build
+
+| Skill | When to Use | Why |
+|-------|-------------|-----|
+| `/ui-ux-pro-max` | Step 5 (Homepage design) | Define visual hierarchy, component styles, color usage, new construction badge design |
+| `/verify` | After each major step | Test functionality works as expected before moving on |
+| `/code-review` | Before Step 15 (testing) | Ensure code quality, SEO compliance, structured data correctness |
+| `/seo-audit` | After Step 14 | Verify all pages rank-able, sitemap complete, schema.org valid, breadcrumbs present |
+
+---
+
+## 15. CLAUDE.md for Target Project
+
+```markdown
+# FIREPROPERTIES.COM
+
+Luxury real estate marketplace for South Florida (Miami, Ft. Lauderdale, Palm Beach). Three user segments: buyers, sellers, investors. Premium black + white design. **SEO-first with semantic URL structure and AI-crawlable architecture.**
+
+## AI Crawling Optimization
+
+This project is built specifically for **AI crawler compatibility** (Claude, ChatGPT, Perplexity, GPTBot). Every page includes:
+- **Semantic URLs** encoding query intent: `/comprar/miami/condos` (not `/comprar?city=miami&type=condos`)
+- **JSON-LD structured data** on every public page: Organization, LocalBusiness, Property, BreadcrumbList, CollectionPage, SearchAction, AggregateOffer, Author, FAQ
+- **Breadcrumbs (HTML + JSON-LD)** on all filtered pages for hierarchy clarity
+- **robots.txt allow lists** for AI crawlers (GPTBot, CCBot, anthropic-ai)
+- **/api/ai/properties endpoint** returning pure JSON data (no HTML parsing needed)
+- **Proper heading hierarchy** (H1 per page with keywords, H2 for sections)
+- **Meta descriptions** that are unique per page and include keyword context
+- **Open Graph + Twitter Card tags** with dynamic og:image per page
+- **Internal linking strategy** that guides crawlers through the hierarchy
+
+## Commands
+
+- `pnpm dev` — Start development server (localhost:3000)
+- `pnpm build` — Production build
+- `pnpm lint` — Run ESLint
+- `pnpm test` — Run all tests (unit + integration + E2E)
+- `pnpm db:push` — Push Prisma schema to database
+- `pnpm db:seed` — Seed initial property data + market data
+- `pnpm prisma studio` — Open Prisma Studio (database UI)
+
+## Tech Stack
+
+Next.js 15 + React 19 + TypeScript + Tailwind CSS v4 + Prisma + PostgreSQL + NextAuth.js v5 + Algolia + Mapbox + OpenAI API + Resend
+
+## Architecture
+
+### Directory Structure
+- `src/app/` — Next.js App Router pages with semantic URL structure:
+ - `/comprar/[city]/[type]` — Dynamic city + property type pages (e.g., /comprar/miami/condos)
+ - `/mercado/[city]/[type]` — Market data by city + type
+ - `/properties/[id]` — Individual property details
+ - `/invertir/[city]` — Investment deals by city
+- `src/components/` — React components organized by feature (layout, home, properties, seller, investor, market, auth)
+- `src/lib/` — Utilities: db.ts (Prisma), auth.ts (NextAuth), algolia.ts, mapbox.ts, openai.ts, **seo.ts** (metadata generators), **schema.ts** (JSON-LD generators)
+- `src/types/` — TypeScript types exported from Prisma + custom types
+- `prisma/` — Database schema + migrations
+
+### Data Flow
+- **Server Components by default** for pages (fetch data server-side, better SEO)
+- **Client Components only for interaction** (search filters, map zoom, form submission, favorites toggle)
+- **API routes in src/app/api/** for backend logic (search, valuation, contacts, market data)
+- **Database queries through Prisma ORM** — no raw SQL
+- **Algolia for full-text search** — synced via API after property creation
+- **OpenAI for property valuations** — called from POST /api/properties/valuation
+- **Semantic URLs encode query intent** — /comprar/miami/condos is better than /comprar?city=miami&type=condos
+
+### Key Patterns
+1. **Server Components by default.** Add "use client" only for filters, maps, forms, interactive elements.
+2. **Fetch data in server components.** Use `async` server components, not useEffect + fetch.
+3. **API routes return consistent shape.** Always: `{ success: true, data: {...}, error?: string }`
+4. **Auth middleware protects /mi-cuenta.** NextAuth middleware.ts redirects to login if not authenticated.
+5. **All database queries use Prisma.** No raw SQL. Migrations auto-generated.
+6. **Dynamic pages with getStaticParams().** Pre-render all [city]/[type] combinations for fast SEO.
+7. **JSON-LD on every page.** BreadcrumbList, CollectionPage, SearchAction, Property schema.
+8. **Breadcrumbs in every filtered page.** HTML breadcrumbs + JSON-LD for AI crawlers.
+
+## Code Organization Rules
+
+1. **One component per file.** Max 300 lines. Extract sub-components if longer.
+2. **Path alias:** Use `@/` for `src/` imports (already configured in tsconfig.json).
+3. **No barrel exports.** Import directly: `import { PropertyCard } from '@/components/properties/PropertyCard'` (not from index.ts).
+4. **Server Components by default.** Only add "use client" when component needs interactivity (onClick, useState, hooks).
+5. **Colocate related files.** Keep page-specific components next to pages: `src/app/comprar/PropertyFilters.tsx` (used by /comprar page).
+6. **SEO metadata on every page.** Export `metadata` object from each page.tsx with title, description, canonical, og:image.
+7. **Breadcrumbs on filtered pages.** Every /comprar/[city]/[type] page has Breadcrumbs component + JSON-LD.
+
+## Design System
+
+### Colors (Black & White Premium)
+- Primary: `#000000` (black) — headlines, buttons, accents
+- Secondary: `#FFFFFF` (white) — backgrounds, contrast
+- Muted: `#666666` — secondary text, borders
+- Light: `#F5F5F5` — page background
+- Accent: `#FF6B35` — fire orange (logo/highlights only)
+- NewConstruction: `#FF6B35` — highlight new construction badges
+- Success: `#10B981` — positive indicators
+- Warning: `#F59E0B` — alerts
+- Error: `#EF4444` — errors, destructive
+
+### Typography
+- Headings: Inter font, weights 600-700 (48px H1, 32px H2, 24px H3)
+- Body: Inter font, 16px regular, 14px small
+- Code: Monaco, 12px
+
+### Style
+- Border radius: 8px for buttons/cards, minimal use
+- Shadows: 0 1px 3px rgba(0,0,0,0.1) on cards only (minimal shadows, premium feel)
+- Spacing: 4px base (scale: 4, 8, 12, 16, 24, 32, 48, 64, 96px)
+- Max width: 1280px content
+- Breakpoints: sm=640px, md=768px, lg=1024px, xl=1280px
+- Aesthetic: Clean, minimal, premium (black & white), generous spacing, no flashy animations
+- Badges: "NEW CONSTRUCTION" badge on property cards + detail pages
+
+## Environment Variables
+
+| Variable | Description | Get From |
+|----------|-------------|----------|
+| DATABASE_URL | PostgreSQL connection string | Supabase or local |
+| NEXTAUTH_SECRET | NextAuth secret token | `openssl rand -base64 32` |
+| NEXTAUTH_URL | Site URL | http://localhost:3000 (dev) or fireproperties.com (prod) |
+| NEXT_PUBLIC_MAPBOX_TOKEN | Mapbox API token | Mapbox account |
+| NEXT_PUBLIC_ALGOLIA_APP_ID | Algolia app ID | Algolia dashboard |
+| NEXT_PUBLIC_ALGOLIA_SEARCH_KEY | Algolia search-only key | Algolia dashboard |
+| ALGOLIA_ADMIN_KEY | Algolia admin key (server-side) | Algolia dashboard |
+| OPENAI_API_KEY | OpenAI API key | OpenAI account |
+| RESEND_API_KEY | Resend API key | Resend dashboard |
+
+## Semantic URL Structure (CRITICAL FOR SEO & AI)
+
+Routes are semantic to communicate query intent to AI crawlers:
+- `/comprar` — all properties
+- `/comprar/[city]` — Miami, Fort Lauderdale, Palm Beach properties
+- `/comprar/[city]/[type]` — Miami condos, Fort Lauderdale new construction, etc.
+- `/mercado/[city]/[type]` — market data by city + type
+- `/invertir/[city]` — investment deals by city
+- `/properties/[id]` — individual property detail
+
+Each city/type page:
+- Has unique H1 with keywords (e.g., "Miami Luxury Condos")
+- Includes JSON-LD BreadcrumbList for AI
+- Includes JSON-LD CollectionPage + SearchAction
+- Pre-rendered via getStaticParams() for fast SEO
+
+## Reglas No Negociables
+
+1. **TypeScript strict mode.** No `any` types. Use proper typing everywhere.
+2. **Mobile-first responsive design.** Design for mobile (375px) first, then scale up.
+3. **All forms validated with Zod.** Define schema, validate client + server side.
+4. **One component per file, max 300 lines.** Extract sub-components if longer.
+5. **No console.logs in production.** Remove all debug logs before pushing.
+6. **SEO tags on every page.** Export `metadata` object: title, description, canonical, og:image.
+7. **All API responses consistent shape.** `{ success: boolean, data?: any, error?: string }`
+8. **Protected routes use NextAuth middleware.** No scattered permission checks in components.
+9. **Images use Next.js Image component.** Never use raw `![]()
` (except SVGs).
+10. **Database operations through Prisma only.** No raw SQL queries.
+11. **Semantic URLs encode intent.** `/comprar/miami/condos` not `/comprar?city=miami&type=condos`. For AI crawlers.
+12. **JSON-LD schema MANDATORY on every public page.** Organization, LocalBusiness, Property, BreadcrumbList, CollectionPage, SearchAction, AggregateOffer, Author, FAQ.
+13. **Breadcrumbs on all filtered pages.** Both HTML (visible) + JSON-LD (for AI). Each breadcrumb is clickable internal link.
+14. **Meta descriptions unique per page.** Include relevant keywords and property context.
+15. **Open Graph + Twitter Card dynamic.** og:title, og:description, og:image, twitter:card per page.
+16. **AI crawler optimization.** /api/ai/properties endpoint, robots.txt allow lists (GPTBot, CCBot, anthropic-ai), proper heading hierarchy.
+17. **Internal linking strategy.** Follow hierarchy: Homepage → Hub → City → Type → Detail. Use descriptive anchor text.
+18. **Pre-render all city + type pages.** Use getStaticParams() for fast SEO.
+19. **isNewConstruction flag required.** All properties must have this boolean. Property enum includes NEW_CONSTRUCTION.
+```
+
+---
+
+## 16. Reglas No Negociables
+
+1. **TypeScript strict mode.** No `any` types. Proper typing on all functions, components, API responses.
+2. **Mobile-first responsive design.** Design for 375px mobile, then scale to desktop. Test on real devices.
+3. **SEO tags on EVERY page.** Each page.tsx must export metadata: title, description, canonical URL, og:image, og:type.
+4. **Zod validation for all forms.** Define schema, validate client-side and server-side.
+5. **One component per file, max 300 lines.** Extract sub-components if longer.
+6. **No `console.log` in production.** Remove all debug logs before pushing to main.
+7. **API responses have consistent shape.** Always return `{ success: boolean, data?: any, error?: string }`.
+8. **Protected routes use NextAuth middleware.** No scattered permission checks in components.
+9. **Images use Next.js Image component.** Never use raw `![]()
` (except SVGs).
+10. **Database operations only through Prisma.** No raw SQL, no direct driver queries.
+11. **No localStorage for sensitive data.** Use HTTP-only cookies (NextAuth handles this).
+12. **Test critical user flows before deployment.** E2E tests for search → favorite, contact form, valuation.
+13. **JSON-LD schema MANDATORY on EVERY public page.** Organization, LocalBusiness, Property, BreadcrumbList, CollectionPage, SearchAction, AggregateOffer, Author, FAQ — **CRITICAL FOR AI CRAWLERS**.
+14. **Semantic URLs encode intent.** `/comprar/miami/condos` not `/comprar?city=miami&type=condos`. Every URL tells AI what it's about.
+15. **Pre-render city + type pages.** Use getStaticParams() + ISR for fast indexing and AI discovery.
+16. **Breadcrumbs on all filtered pages.** Both HTML (visible) + JSON-LD (structured). Each breadcrumb is a clickable internal link.
+17. **Internal linking strategy enforced.** Follow hierarchy: Homepage → Hub (/comprar) → City (/comprar/miami) → Type (/comprar/miami/condos) → Detail. Anchor text is descriptive.
+18. **Meta descriptions unique per page.** Not generic. Include keywords, context, offer count if applicable.
+19. **Open Graph + Twitter Cards dynamic.** og:title, og:description, og:image (generated per page), twitter:card, twitter:image.
+20. **AI crawler optimization required.** /api/ai/properties endpoint for JSON data, robots.txt allow lists (GPTBot, CCBot, anthropic-ai), robots.txt no blocking.
+21. **New construction flag on all properties.** isNewConstruction boolean + Property type enum includes NEW_CONSTRUCTION. Surfaces in UI with orange badge.
+22. **Heading hierarchy strict.** One H1 per page with main keyword. H2 for sections. H3 for subsections. No skipped levels.
+23. **Image alt text descriptive.** Every property image has alt: "3BR condo in Miami Brickell, $1.2M" (not "image" or empty).
+24. **Sitemap + robots.txt complete.** Dynamic sitemap with 100+ URLs. robots.txt allows all crawlers including AI crawlers.