Borbann - Real Estate Information Platform

AI-powered property valuation platform for Bangkok, Thailand. Provides intelligent site selection and price predictions using machine learning and graph neural networks.

Features

• AI Property Valuation - Get instant property valuations with ML-powered price predictions
• AI Chat Agent - Interactive assistant for property search and location analysis
• Property Price Prediction - Predict property values using AI models
• Site Analytics - Analyze locations with spatial intelligence
• Interactive Map - Explore properties and points of interest in Bangkok
• Location Intelligence - Transit scores, walkability, flood risk, and more
• Enterprise Authentication - Secure multi-tenant authentication with RBAC
• Organization & Team Management - Collaborative workspace with role-based permissions
• Multi-Model Support - Compare predictions from multiple ML models
  • LightGBM baseline with spatial features
  • Graph Neural Network (HGT) for complex relationships

Project Structure

borbann/
├── gis-server/         # FastAPI backend
│   ├── src/            # Source code
│   ├── scripts/        # Training scripts
│   ├── tests/          # Test suite
│   └── models/         # Trained ML models
└── frontend/           # React frontend

Getting Started

Quickstart (Full Stack)

# From repo root
make stack-up

This starts PostGIS, the FastAPI backend on http://localhost:8000, and the Vite frontend on http://localhost:3000.

Backend (gis-server)

cd gis-server

# Install dependencies
uv sync

# Set up database (first time only)
# See docs/DATABASE_SETUP.md for detailed instructions
uv run alembic upgrade head
uv run python src/scripts/seed_permissions.py

# Run development server
uv run uvicorn main:app --reload --port 8000

# Run tests
make test

Requirements:

• Python 3.13+
• PostgreSQL with PostGIS extension
• uv package manager

Documentation:

• Database Setup Guide - Database migrations and permissions

Frontend

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Useful Root Commands

make db-up        # Start PostGIS only
make stack-up     # Start app stack (db + backend + frontend)
make stack-up-all # Start app stack + MLflow services
make mlflow-up    # Start MLflow (Postgres backend) on http://localhost:5001
make prod-config  # Validate production compose configuration
make prod-up      # Start production compose stack using .env.production
make prod-down    # Stop production compose stack
make test         # Run backend + frontend tests
make lint         # Run backend + frontend lint
make dagger-ci    # Run Dagger pilot CI (backend + frontend)

Dagger pilot details: docs/DAGGER_PILOT.md

Requirements:

• Node.js 20+
• npm or yarn

Production Deployment

• Production deployment assets live in docker-compose.prod.yml, frontend/Dockerfile.prod, gis-server/Dockerfile.prod, and deploy/nginx/site-select-core.conf.
• Follow docs/production-deployment-runbook.md for the VPS hardening, Tailscale, Nginx, CI/CD, backup, and rollback flow.
• Minimum VPS for a single-node production pilot: 4 vCPU, 8 GB RAM, 160 GB SSD, plus 2 GB swap.
• Recommended VPS for safer headroom with PostGIS, Redis, MinIO, and runtime ML assets: 6 vCPU, 16 GB RAM, 250 GB SSD.

Git LFS (Required for Model/Data Files)

This repository stores large model and dataset artifacts with Git LFS.

# One-time setup on your machine
git lfs install

# After cloning or switching branches with large assets
git lfs pull

When adding new large artifacts, track them first and then commit:

git lfs track "gis-server/models/**/*.parquet"
git add .gitattributes <your-large-file>
git commit -m "track large artifacts with git lfs"

API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Machine Learning

Train Models

cd gis-server

# Train baseline models (LightGBM, Random Forest, Linear)
make train-baseline-all

# Train graph neural network
make train-hgt

# Start MLflow server/UI
make mlflow-up
make mlflow-ui

# Promote a run with strict auto-gate checks
make promote-baseline RUN_ID=<mlflow_run_id>
make promote-hgt RUN_ID=<mlflow_run_id>

# Export cross-experiment leaderboard (defaults: METRIC=cv_mape_mean MODE=min)
make mlflow-leaderboard METRIC=test_mape MODE=min

Model Architecture

1. Baseline Models - Traditional ML with spatial features

   • H3 hexagonal indexing for location features
   • POI (Points of Interest) aggregation
   • Distance to CBD and transit stations
   • Hex2Vec spatial embeddings

2. Graph Neural Network (HGT) - Heterogeneous graph learning

   • Property-POI-Location relationships
   • Attention mechanisms for feature importance
   • Cold-start property support

Technology Stack

Backend:

• FastAPI - Modern Python web framework
• PostgreSQL + PostGIS - Spatial database
• LightGBM - Gradient boosting models
• PyTorch Geometric - Graph neural networks
• MLflow - Experiment tracking
• H3 - Hexagonal hierarchical spatial indexing
• LangGraph - AI agent orchestration

Frontend:

• React 19 - UI framework
• Vite - Build tool
• Deck.gl - WebGL-powered map visualization
• TanStack Router - Type-safe routing

Environment Variables

Create .env file in gis-server/:

DATABASE_URL=postgresql://user:password@localhost:5432/dbname
SECRET_KEY=your-secret-key-for-jwt-signing
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
GOOGLE_MAPS_API_KEY=your_google_maps_api_key
GOOGLE_API_KEY=your_gemini_api_key  # For AI chat agent
MLFLOW_TRACKING_URI=http://localhost:5001
MLFLOW_REGISTRY_URI=http://localhost:5001
DATASET_VERSION=local-dev

Testing

cd gis-server

# Run all tests (23 tests)
make test

# Run with coverage
make test-cov

# Run specific test suites
make test-unit          # Unit tests only
make test-integration   # Integration tests only

Development

# Format code
make format

# Run linter
make lint

# Clean cache files
make clean

Data Sources

• Property transactions from public records
• OpenStreetMap for POIs and roads
• Bangkok GTFS data for transit information
• Administrative boundaries from government data

License

This project is for educational purposes.

Team

Developed by Kasetsart University students for the Borbann platform.