Architecture

File-Based Routing

Housr API v1 uses flat PHP files as endpoints. There is no framework router. Each .php file in the api/ directory is a directly accessible HTTP endpoint.

URL mapping: A request to https://api.uk.housr.com/api/login.php maps to the file api/login.php.

Nginx is configured to pass all .php requests to PHP-FPM. The key Nginx directive that makes the bootstrap work:

fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/api/include/bootstrap.php";

This means api/include/bootstrap.php is automatically executed before every PHP file, providing database connections, environment variables, Sentry init, and global variables like $link, $billsLink, $key, $USA, etc.

Request Flow

Client Request
    |
    v
Nginx (port 80)
    |
    v
PHP-FPM (port 9000)
    |
    v
auto_prepend: api/include/bootstrap.php
    |-- loads .env via configdb.php
    |-- sets up DB connections ($link, $billsLink)
    |-- sets global JWT vars ($key, $issued_at, $issuer)
    |-- sets $USA flag from $_ENV['USA']
    |-- initializes Sentry
    |
    v
Endpoint file (e.g., api/login.php)
    |-- sets CORS headers
    |-- includes JWT libs
    |-- includes utility files as needed
    |-- reads $_POST / $_GET / $_SERVER['HTTP_AUTHORIZATION']
    |-- performs business logic (DB queries, API calls)
    |-- echoes JSON response

Bootstrap Chain

1. api/include/bootstrap.php - Entry point. Loads composer autoloader, then configdb.php, core.php, and exceptionHandler.php. Initializes Sentry.
2. api/include/configdb.php - Parses .env file into $_ENV. Defines DB constants (DB_SERVER, DB_USERNAME, DB_PASSWORD, DB_NAME). Creates $link (main DB) and $billsLink (bills DB, UK only) connections via db_connect().
3. api/include/core.php - Sets timezone to UTC. Defines JWT variables ($key, $issued_at, $issuer). Sets $USA and $database globals.
4. api/include/dbcon.php - Alternative bootstrap that sets up Firebase (Realtime DB + Cloud Messaging) via Kreait SDK. Used by notification-related endpoints.

Utility Pattern

Shared logic lives in api/utils/. Endpoint files include utilities with include_once or require_once:

include_once './utils/jwtUtils.php';
include_once './utils/sendEmail.php';
include_once './utils/hubspotUtils.php';

Key utility files:

Authentication Methods

Endpoints use two patterns for receiving JWTs:

1. POST body (legacy, most endpoints): $jwt = $_POST["jwt"]
2. Authorization header (newer endpoints): $jwt = $_SERVER['HTTP_AUTHORIZATION']

Some endpoints also support API key auth via apiKeyChecker.php for external/portal access.

External Endpoints

The api/external/ directory contains endpoints meant for external consumers (the Housr website, brand portal). These are routed via Nginx rewrites:

location /api/external/ {
    rewrite ^/api/external/(.*)$ /api/external/$1.php last;
}

The Entrata subdirectory has its own routing:

location /api/external/entrata/ {
    try_files $uri $uri/ /api/external/entrata/index.php$is_args$args;
}

Subdirectories