Architecture Overview

Housr runs as a set of interconnected services sharing a single MySQL database. This page maps how everything connects.

System Diagram


                                    ┌─────────────────────┐
                                    │   External Services │
                                    │  Firebase, Finix,   │
                                    │  RyftPay, HubSpot,  │
                                    │  Twilio, Mailgun,   │
                                    │  DocuSign, Mapbox,  │
                                    │  Sanity CMS         │
                                    └──────────┬──────────┘
                                               │
          ┌────────────────────────────────────┼────────────────────────────────────┐
          │                                    │                                    │
          ▼                                    ▼                                    ▼
┌──────────────────┐             ┌──────────────────────┐             ┌──────────────────┐
│   Housr-Webapp   │             │     Housr-App        │             │  Housr Portal    │
│   (Next.js )     │             │   (Expo / RN)        │             │     (Laravel)    │
│                  │             │                      │             │                  │
│  Marketing site  │             │  Student mobile app  │             │  Admin tool      │
│  Property search │             │  US + UK             │             │  Ops, agents,    │
│  US + UK         │             │                      │             │  landlords       │
└───────┬──────────┘             └──────┬───────────────┘             └───────┬──────────┘
        │                               │                                     │
        │  REST (mostly v2)             │  REST (v1 + v2)                     │  Direct DB
        │                               │                                     │ 
        │                               │                                     │
        ▼                               ▼                                     ▼
┌──────────────────┐         ┌──────────────────┐                   ┌──────────────────┐
│   Housr-API2     │         │   Housr-API      │                   │                  │
│   (Laravel v2)   │         │   (Laravel v1)   │                   │   Shared MySQL   │
│                  │         │                  │                   │   Database       │
│  New endpoints   │         │  Legacy endpoints│                   │                  │
│  Modular arch    │         │  Being phased out│                   │  Single source   │
└───────┬──────────┘         └───────┬──────────┘                   │  of truth for    │
        │                            │                              │  all data        │
        └────────────────────────────└─────────────────────────────▶︎│                  │
                                                                    └───────┬──────────┘
                                                                           ▲
                                                                           │
                                                                   ┌──────────────────┐
                                                                   │ Property Feeds   │
                                                                   │                  │
                                                                   │ Entrata (US)     │
                                                                   │ Jupix/BLM (UK)   │
                                                                   └──────────────────┘

How the Pieces Connect

Webapp to APIs

Housr-Webapp makes server-side API calls to API v2 (primary) and API v1 (legacy endpoints). The src/helpers/api.ts module provides get(), post(), and related helpers with ISR caching (revalidate: 3600 by default).

For property search, the Webapp also makes direct MySQL queries via a connection pool (src/lib/db.ts) for performance. This is read-only access.

App to APIs

Housr-App uses two axios instances (apiV1 and apiV2) to call both API versions:

API v2: Bearer JWT in Authorization header. Used for all new endpoints.
API v1: JWT sent as form field (jwt) or plain Authorization header. Used where v2 endpoints don’t exist yet.

Portal to Database

Housr Portal is a Laravel app that connects directly to the shared MySQL database via Eloquent. It does not call the APIs — it reads and writes the same tables that the APIs use. This means Portal changes are immediately visible to API consumers and vice versa.

Property Feeds to Database

Housr-Property-Feeds runs scheduled import jobs that pull property data from external sources (Entrata for US, Jupix/BLM for UK) and write it directly to the shared MySQL database.

Firebase

Firebase provides real-time features across the stack:

App: Push notifications, real-time chat via Firebase Realtime Database
API v1: Sends push notifications, writes to Firebase Realtime DB

The Shared Database

The single most important architectural decision: all PHP backends share one MySQL database. API v1, API v2, Portal, and Property Feeds all read/write the same tables. The Webapp has read-only access for search.

This means:

Schema changes affect all consumers
Migrations can live in API v1, API v2 (module-specific), or Portal
Data consistency is maintained at the database level, not via API contracts
Be careful with destructive migrations — test against all consumers