Foresight

AI revenue intelligence platform for boutique hotels. Combines events, weather, flights, and competitor pricing to recommend optimal room rates.

Prerequisites

• uv — Python package manager
• Docker — for PostgreSQL (and optional containerized backend)
• just — command runner

Quick Start

# Build the backend image
just build

# Start everything (db + backend with hot reload)
just dev

# Run migrations
just migrate

# View logs
just logs

# Stop everything
just destroy

The API will be available at http://localhost:8000
API docs at http://localhost:8000/docs

Re-run just build whenever you change backend dependencies or the Dockerfile — source code changes hot-reload automatically while just dev is running.

Database Migrations

# Create a new migration after changing models
just migrate-create "add_hotels_table"

# Run pending migrations
just migrate

# Rollback last migration
just migrate-down

Code Quality

# Lint
just lint

# Format
just format

# Fix lint issues + format
just fix

Pre-commit Hooks

# Install hooks (ruff formatting/linting + conventional commits)
just hooks

Commit messages must follow Conventional Commits:

• feat: add pricing endpoint
• fix: correct rate calculation
• docs: update README

Project Structure

foresight/
├── backend/
│   ├── foresight/               # Installable package (see pyproject.toml)
│   │   ├── main.py              # FastAPI app entrypoint (foresight.main:app)
│   │   ├── config.py            # Settings (pydantic-settings)
│   │   ├── routes/              # API route handlers
│   │   ├── schemas/             # Pydantic request/response models
│   │   ├── services/            # Business logic
│   │   │   ├── ml/              # ML models (regression, bayesian, ...)
│   │   │   └── parsers/         # Client data ingestion
│   │   ├── repository/          # Data-access layer
│   │   └── database/            # SQLAlchemy + Alembic
│   │       ├── base.py          # Declarative base
│   │       ├── session.py       # Async session factory
│   │       ├── models/          # SQLAlchemy models
│   │       └── migrations/      # Alembic migrations
│   ├── scripts/                 # Dev tooling (mock data, model comparison)
│   ├── tests/                   # Pytest suite
│   ├── alembic.ini
│   ├── pyproject.toml
│   └── Dockerfile
├── frontend/                    # TBD
├── docker-compose.yml
├── justfile
├── .env.example
└── .pre-commit-config.yaml