# Valwiki MarketMind Intelligence Platform

> Whitelabel real estate decision engine and predictive modeling suite across  France, Spain, and Portugal.

Valwiki provides institutional-grade regional real estate intelligence, evolving metrics across evolutionary vectors, and forecasting models. This file provides an outline of the system structure, routing paths, and API integrations for automated agents.

---

## Core System Architecture

Valwiki is structured as a **Unified Gateway API** that resolves and mounts regional sub-applications dynamically at startup.

*   **Unified Gateway Port**: `8012` (Production) / `8010` (Default)
*   **Web Dashboard Port**: `5174` (Production) / `5173` (Default)

### Regional Silos
*   **France (FR)**: Served at `/fr/api` (mounted from `backend_paris`). Focuses on DVF sales, ADEME DPE energy performance, and INSEE census grid blocks.
*   **Spain (ES)**: Served at `/es/api` and `/sp/api` (mounted from `backend_sp`). Focuses on Spanish district/barrio metrics and portal medians.
*   **Portugal (PT)**: Served at `/pt/api` (mounted from `backend_pt`). Focuses on concelhos and freguesias.

---

## 4-Tier Data Lifecycle

All data undergoes a strict promotion pipeline to ensure database integrity and model validation:

1.  **Staging Layer**: Raw input records from ETL scrapers land in staging tables (e.g. `app.staged_indicators`, `app.staged_transactions_dvf`).
2.  **Production Base**: An administrator reviews and promotes validated staging rows into production index tables (e.g. `app.transactions_dvf`, `app.locations`).
3.  **Intelligence Tables**: Downstream processes aggregate production records into unified, region-specific intelligence views (e.g. `app.quartier_intelligence`, `app.neighborhood_intelligence`).
4.  **Simulation & Projections**: Advanced predictive engines (ARIMA, Prophet, and ElasticNet Ensembles) run against historical baselines. High-uncertainty predictions fall back automatically to Monte Carlo (MC) simulations, stored as nested JSON (e.g. `mc_snapshots_json`, `ensemble_metadata_json`).

---

## Primary API Endpoints

### 1. Global Gateway
*   `GET /health`: Basic gateway health monitor.
*   `POST /api/discovery/global`: Query investment targets across all active regions.
*   `GET /api/market/resolve/{locationId}`: Resolve a given location ID to its regional sub-app prefix.
*   `POST /api/auth/login`: Issue HttpOnly session cookie for operations console access.

### 2. France Region (`/fr/api`)
*   `GET /fr/api/parity/stats`: High-level inventory and staging statistics.
*   `GET /fr/api/parity/staging`: List French transactions pending promotion.
*   `GET /fr/api/parity/validation/summary`: Fetch drift box-plots and deviation metrics.
*   `POST /fr/api/parity/validation/trigger`: Trigger regional updates and scrapes.

### 3. Spain Region (`/es/api`)
*   `GET /es/api/ops_spain/stats`: Spanish inventory, medians, and staging counts.
*   `GET /es/api/ops_spain/staging`: List Spanish records pending promotion.
*   `GET /es/api/ops_spain/ops_validation_sp/summary`: Aggregate Spanish market drift.
*   `POST /es/api/ops_spain/ops_validation_sp/trigger`: Trigger barrio-level validation.

---

## Crawler & Agent Policy

*   **Sitemap**: A canonical XML sitemap is dynamically generated at [/sitemap.xml](/sitemap.xml).
*   **Rate Limits**: Gateway requests are limited to `10/minute` for heavy generative AI endpoints, and `5/minute` for deep property analysis.
*   **Authentication**: Administrative operations require the `X-Ops-Key` header mapped to `VALWIKI_ADMIN_SECRET`.