Housr API v1 (Legacy)

Legacy flat-PHP API powering the Housr mobile app and web platform. This API serves both the UK and US markets with region-specific logic controlled by a $USA environment flag.

Status: Legacy. New features should target Housr-API2 (Laravel-based API v2). This codebase is maintained for existing endpoints that have not yet been migrated.

Stack

Runtime: PHP 8.2 (FPM)
Web Server: Nginx (reverse proxy to PHP-FPM)
Database: MySQL (dual databases: main + bills)
Container: Docker (deployed via AWS Copilot / App Runner)
Error Tracking: Sentry
Auth: JWT (HS256, custom implementation using firebase/php-jwt)

Quick Start


# Clone and start
git clone <repo-url>
cp .env.example .env   # Fill in database credentials and service keys
docker compose up --build
 
# API is available at http://localhost/api/

The Docker setup runs Nginx + PHP-FPM in a single container. The deploy/run script starts both services.

Project Structure


Housr-API/
  api/                    # All endpoint files (flat PHP, file-based routing)
    include/              # Bootstrap, DB config, Firebase, email templates
    utils/                # Shared utility functions (JWT, notifications, bills, HubSpot, etc.)
    libs/                 # Vendored libraries (php-jwt, AWS SDK)
    external/             # External-facing endpoints (Finix, Entrata, perks)
    roomie/               # Roomie feature endpoints
    propertyFeed/         # Property feed integrations (Jupix, BLM, Aspasia, RTDF, Veco)
    us/                   # US-specific endpoints (moderation, landlord reviews)
    websiteEnquiries/     # Website enquiry handling
    PHPMailer/            # PHPMailer library
  deploy/                 # Nginx config, PHP-FPM config, entrypoint script
  copilot/                # AWS Copilot service definitions and environment configs
  saml/                   # SimpleSAMLphp config for SSO (US university auth)
  docker/                 # Docker-specific config (xdebug)
  vendor/                 # Composer dependencies
  composer.json
  Dockerfile
  docker-compose.yml

Documentation Index

Document	Description
Architecture	File-based routing, request flow, utility pattern
Setup	Docker setup, environment variables, local development
Auth	JWT implementation, token structure, auth guards
Database	Dual DB setup, connection patterns, key tables
Regional Logic	UK vs US branching via `$USA` flag
Deployment	Docker, AWS Copilot, Nginx configuration
Endpoints
Auth Endpoints	Login, signup, SSO, OTP, social auth
Houses Endpoints	Property listing, search, details, likes
Viewings Endpoints	Viewing requests, cancellation, ratings
Chat Endpoints	Chat rooms, messaging
Bills Endpoints	Quotes, signup, meters, direct debit
Perks Endpoints	Perk categories, redemption, tokens
Roomie Endpoints	Profile CRUD, matching, requests
Rideshare Endpoints	Rides, booking, chat
Users Endpoints	Profile, friends, groups, referrals
Notifications Endpoints	FCM tokens, push, reminders
Moderation Endpoints	US moderation, ratings, disputes
Integrations
Firebase	Realtime DB, Cloud Messaging
HubSpot	CRM contacts, leads, deals
Finix	Payment processing
Entrata	Property management (US)
Property Feeds	Jupix, BLM, Aspasia, RTDF, Veco
Twilio	SMS delivery
Mailgun	Email delivery

Key Dependencies (composer.json)

Package	Purpose
`kreait/laravel-firebase`	Firebase Admin SDK (FCM, Realtime DB)
`firebase/php-jwt` (vendored in libs/)	JWT encoding/decoding
`twilio/sdk`	SMS via Twilio
`mailgun/mailgun-php`	Email via Mailgun
`hubspot/api-client`	HubSpot CRM integration
`aws/aws-sdk-php`	S3 uploads, Secrets Manager
`guzzlehttp/guzzle`	HTTP client
`sentry/sentry`	Error tracking
`dompdf/dompdf`	PDF generation
`mailchimp/marketing`	Mailchimp integration (US SSO signup)
`verifalia/sdk`	Email verification
`google/apiclient`	Google Sign-In verification