Imported from arremata/leilao-br (frontend/AGENTS.md). Install upstream with npx skills add arremata/leilao-br --skill frontend. Copyright stays with the author.

Frontend — Arremate React SPA

Overview

React 19 SPA (Vite) for browsing and analyzing Brazilian real estate auctions. Demo-ready with 3 real auction properties, real photos, and real market comparables. Responsive PWA with watchlist and history. Deployed to Vercel.

Commands

npm run dev        # dev server with HMR (localhost:5173)
npm run build      # production build to dist/
npm run lint       # eslint
npm run preview    # preview production build

Architecture

Four-Screen SPA

Navigation via go(screen, prop) in App.jsx. Screen and watchlist persist to localStorage.

Files

API Integration

• GET /api/properties → array of AuctionPropertyResult (proxied to :8000/properties)
• POST /api/analyze → run pipeline on URL, return AuctionPropertyResult (proxied to :8000/analyze)
• Vite proxy config in vite.config.js: /api/* → http://localhost:8000/* (strips /api prefix)
• App loads properties from API on mount; falls back to fixture data if API is empty/unavailable

Data Model

Each property matches the AuctionPropertyResult shape from the backend (backend/graph/contracts.py):

{
  id, score,           // 0-100
  photoLabel, title, address, type, neighborhood, city,
  auctionType, auctioneer, court,
  discount,            // percentage (negative = above market)
  minBid, market,      // raw BRL numbers — format with fmtBRL()
  roi,                 // projected ROI % (negative = loss)
  area, beds, baths, parking, floor,
  endsAt,              // ISO 8601 string — convert with getEndsAtMs()
  occupancy,           // "desocupado" | "ocupado" | "disputado"
  risk: { j, f, l, o }, // "good" | "warn" | "bad"
  photoUrl,            // "/photos/auction1.jpg" — real property photo
  auctionUrl,          // original auction listing URL
  marketDetail: {
    confidenceLevel,   // "low" | "medium" | "high"; numeric score stays internal
    indicators, comparables
  },
  matricula,           // official property registration number, when published
  editalUrl,           // official auction notice PDF
  matriculaUrl,        // official property registration PDF
  editalData           // structured official auction/property/payment facts
}

Important: market is the estimated market value based on real comparable sales (not the official auction appraisal). discount = (market - minBid) / market × 100. Can be negative when bid exceeds market value.

Key Conventions

• ES module imports/exports — no window globals
• Named exports for all components
• Monetary values: raw BRL numbers from backend; fmtBRL() formats at render time
• Dates: getEndsAtMs() converts endsAt (ISO string or epoch ms) to epoch ms for Countdown
• Colors: oklch with CSS custom properties — --good/--warn/--bad for risk, --accent for primary actions
• Styling: mostly inline style objects; styles.css handles layout primitives, typography, reusable patterns
• Language: Brazilian Portuguese (pt-BR) throughout the UI
• No router: screen state managed in App.jsx, persisted to localStorage (arremate_screen)